deAPI MCP Server

deAPI MCP 服务

面向 deAPI REST API 的生产级 Model Context Protocol (MCP) 服务。此服务将 deAPI 的所有 AI 能力封装为 MCP 工具，使大模型能够执行音频转录、图像生成、OCR、视频生成、文本转语音等操作。

deAPI v2 — 此服务面向 deAPI v2 客户端 API（/api/v2/* 下与 OpenAI 对齐的名词路径）。如果需要使用旧版 v1 端点，请设置 DEAPI_API_VERSION=v1。

功能

• 完整的 API 覆盖范围：通过 MCP 暴露 39 个 deAPI 工具，涵盖每个 v2 客户端端点
• 智能自适应轮询：根据任务类型使用优化的间隔自动轮询异步任务
• OAuth 2.0 身份验证：通过 OAuth Authorization Code 流程和 PKCE 安全交换令牌
• 错误恢复：使用指数退避的自动重试逻辑
• 进度报告：向 MCP 客户端实时更新进度
• 类型安全：完整的 Pydantic 模式验证
• 生产就绪：基于 FastMCP 框架构建，确保可靠性

可用工具

音频工具

• audio_transcription - 使用 Whisper 模型将音频文件转录为文本
• audio_transcription_price - 计算转录费用
• text_to_audio - 将文本转换为自然语音（TTS）
• text_to_audio_price - 计算 TTS 费用
• text_to_music - 根据文本描述和歌词生成音乐
• text_to_music_price - 计算音乐生成费用
• audio_url_transcription - 转录已完成的 Twitter Spaces 音频链接
• audio_url_transcription_price - 计算 Twitter Spaces 转录费用

视频转录工具

• video_file_transcription - 将视频文件转录为文本
• video_file_transcription_price - 计算视频文件转录费用
• video_url_transcription - 转录视频链接（YouTube、Twitter/X、Twitch、Kick）
• video_url_transcription_price - 计算视频链接转录费用

图像工具

• text_to_image - 根据文本提示生成图像
• image_to_image - 根据文本指导转换图像
• image_to_text - 从图像中提取文本（OCR）
• image_remove_background - 移除图像背景
• image_upscale - 将图像放大到更高分辨率
• text_to_image_price - 计算图像生成费用
• image_to_image_price - 计算图像转换费用
• image_to_text_price - 计算 OCR 费用
• image_remove_background_price - 计算背景移除费用
• image_upscale_price - 计算图像放大费用

视频工具

• text_to_video - 根据文本提示生成视频
• image_to_video - 将静态图像制作成动画视频
• audio_to_video - 根据音频内容生成视频
• video_replace - 将视频中的人物替换为参考图像中的角色
• video_remove_background - 移除视频背景
• video_upscale - 将视频放大到更高分辨率
• text_to_video_price - 计算文本生成视频的费用
• image_to_video_price - 计算图像生成视频的费用
• audio_to_video_price - 计算音频生成视频的费用
• video_replace_price - 计算视频角色替换费用
• video_remove_background_price - 计算视频背景移除费用
• video_upscale_price - 计算视频放大费用

嵌入工具

• text_to_embedding - 生成用于语义搜索的文本嵌入
• text_to_embedding_price - 计算嵌入费用

提示词工具

• prompt_booster - 使用 AI 指南增强适用于任何 deAPI 推理类型的提示词（同步执行，直接返回优化后的提示词）
• prompt_booster_price - 计算提示词增强费用

实用工具

• get_balance - 查看账户余额
• get_available_models - 列出可用的 AI 模型及其规格
• check_job_status - 按 ID 查询异步任务状态

安装

前置条件

运行 MCP 服务所需：

• Python 3.10 或更高版本
• 用于包管理的 uv、pip 或 conda

deAPI 账户所需：

• 在 deapi.ai 注册并获取 API 令牌

设置

1. 克隆仓库：

git clone https://github.com/deapi-ai/mcp-server-deapi.git
cd mcp-server-deapi

2. 选择 Python 环境设置方式：

选项 A：使用 uv（推荐 — 速度最快）

uv pip install -e .

选项 B：使用 pip

pip install -e .

选项 C：使用 conda

# Create conda environment
conda create -n mcp-server-deapi python=3.11
conda activate mcp-server-deapi

# Install dependencies
pip install -e .

3. （可选）创建 .env 文件进行配置：

# Copy the example file
cp .env.example .env

# Edit with your preferences (optional - defaults work fine)
# DEAPI_API_BASE_URL=https://api.deapi.ai
# DEAPI_HTTP_TIMEOUT=30.0
# DEAPI_MAX_RETRIES=3

使用方法

运行服务

服务可以通过两种模式运行：

本地模式（用于在同一台机器上搭配 Claude Desktop 使用）：

python -m src.server_remote

服务默认会在 http://localhost:8000 启动。

远程模式（用于部署到远程服务）：

# Set host to accept external connections
MCP_HOST=0.0.0.0 MCP_PORT=8000 python -m src.server_remote

生产环境部署选项请参阅远程部署部分。

从 Claude Desktop / Claude.ai 连接

选项 1：添加连接器（推荐）

Claude Desktop 和 Claude.ai 均支持内置 OAuth 身份验证的 MCP 连接器。

1. 从 deapi.ai 获取 deAPI 令牌
2. 在 Claude Desktop 或 Claude.ai 中，前往 设置 → 连接器 → 添加连接器
3. 填写连接器详细信息：

Name:              deAPI
Remote MCP server: https://your-server-domain:8000/mcp

▼ Advanced settings
OAuth Client ID:     deapi-mcp
OAuth Client Secret: YOUR_DEAPI_TOKEN

4. 点击添加——Claude 将通过 OAuth 自动完成身份验证并发现所有工具。

有关 OAuth 流程的详情，请参阅 AUTH.md。

---

选项 2：使用 Bearer 令牌的配置文件（本地开发）

适用场景： 服务运行在同一台机器上，无需 OAuth 即可快速设置。

编辑 Claude Desktop 配置文件：

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Windows：%APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "deapi": {
      "url": "http://localhost:8000/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_DEAPI_TOKEN"
      }
    }
  }
}

将 YOUR_DEAPI_TOKEN 替换为你实际的 deAPI 令牌。保存文件并重启 Claude Desktop。

使用工具

身份验证在连接级别处理，而非针对每次工具调用。工具不接受 deapi_api_token 参数。

以下是一个工作流示例：

1. 获取可用模型：

Use get_available_models to see available models

2. 查看余额：

Use get_balance to check remaining credits

3. 生成图像：

Use text_to_image with:
- prompt: "A beautiful sunset over mountains"
- model: "Flux1schnell"

4. 转录音频：

Use audio_transcription with:
- audio: "base64-encoded-audio-or-url"
- include_ts: true

注意：通过 Claude Desktop 或 MCP SDK 调用工具时，身份验证会通过服务连接（OAuth 或 HTTP 标头）自动处理。有关 OAuth 设置的详细信息，请参阅 AUTH.md。

架构

核心组件

• DeapiClient（src/deapi_client.py）：支持身份验证转发和重试逻辑的 HTTP 客户端
• PollingManager（src/polling_manager.py）：针对异步任务的智能自适应轮询
• Schemas（src/schemas.py）：用于类型安全的 Pydantic 模型
• Tools（src/tools/）：分类组织的工具实现
  • audio.py - 音频转录、TTS 和音乐生成工具
  • image.py - 图像生成、转换、OCR、背景移除和放大工具
  • video.py - 视频生成、音频转视频和视频替换工具
  • embedding.py - 文本嵌入工具
  • utility.py - 余额、模型和状态工具

智能自适应轮询

服务会根据任务类型采用不同的轮询策略：

任务类型	初始延迟	最大延迟	超时
音频	1s	5s	5 min
图像	2s	8s	5 min
视频	5s	30s	15 min

轮询使用带可配置乘数（默认值：1.5x）的指数退避策略。

错误处理

• HTTP 错误：自动重试（3 次），并采用指数退避策略
• 超时：妥善处理并提供清晰的错误消息
• 任务失败：检测失败并向客户端报告
• API 错误：返回格式规范的错误响应

配置

可通过环境变量设置配置（变量名前缀为 DEAPI_）：

# API Configuration
DEAPI_API_BASE_URL=https://api.deapi.ai
DEAPI_API_VERSION=v2

# HTTP Client
DEAPI_HTTP_TIMEOUT=30.0
DEAPI_MAX_RETRIES=3
DEAPI_RETRY_BACKOFF_FACTOR=2.0

# Polling Configuration (override defaults)
DEAPI_POLLING_AUDIO__INITIAL_DELAY=1.0
DEAPI_POLLING_AUDIO__MAX_DELAY=5.0
DEAPI_POLLING_AUDIO__TIMEOUT=300.0

开发

项目结构

mcp-server-deapi/
├── src/
│   ├── server_remote.py       # Streamable-HTTP MCP server
│   ├── deapi_client.py        # HTTP client with auth forwarding
│   ├── polling_manager.py     # Smart adaptive polling logic
│   ├── schemas.py             # Pydantic models
│   ├── config.py              # Configuration management
│   ├── auth.py                # Authentication middleware
│   ├── fastmcp_auth.py        # FastMCP OAuth provider
│   ├── oauth_endpoints.py     # OAuth 2.0 endpoints
│   └── tools/                 # Tool implementations
│       ├── audio.py           # Audio transcription, TTS & music generation
│       ├── image.py           # Image generation, OCR & processing
│       ├── video.py           # Video generation, audio-to-video & video replace
│       ├── embedding.py       # Text embeddings
│       ├── utility.py         # Balance, models, status
│       └── _price_helpers.py  # Price calculation helpers
├── tests/                     # Test suite
│   ├── __init__.py
│   └── conftest.py           # Pytest fixtures
├── pyproject.toml             # Dependencies
├── Dockerfile                 # Container build
├── docker-compose.yml         # Container orchestration
├── .env.example              # Environment config template
├── README.md                  # This file
├── DEPLOYMENT.md              # Deployment guide
├── AUTH.md                    # OAuth authentication setup
└── CLAUDE.md                  # Claude Code guidance

运行测试

安装开发依赖：

uv pip install -e ".[dev]"

运行测试：

pytest

运行冒烟测试（需要服务器正在运行）：

python tests/smoke_test.py

代码格式化

使用 Black 格式化代码：

black src/

使用 Ruff 执行代码检查：

ruff check src/

API 令牌安全

重要提示：MCP 服务不会存储 API 令牌。身份验证方式如下：

1. 远程 HTTP 服务：通过 OAuth 2.0（使用 PKCE 的授权码模式）或 HTTP 标头（Authorization: Bearer token）进行身份验证
2. 令牌转发：服务器会针对每个请求将身份验证信息转发给 deAPI API
3. 不持久化：令牌仅用于特定请求，绝不会持久化或记录
4. 按连接身份验证：工具不接受 deapi_api_token 参数——身份验证在连接级别进行管理

请始终妥善保管 API 令牌，切勿将其提交到版本控制系统。OAuth 设置详情请参阅 AUTH.md。

远程部署

对于生产环境，或希望在远程计算机上托管 MCP 服务的情况，请使用远程服务模式。

使用 Docker 快速开始

1. 使用 Docker 构建并运行：

docker build -t mcp-server-deapi .
docker run -d -p 8000:8000 --name mcp-server-deapi mcp-server-deapi

2. 或者使用 Docker Compose：

docker-compose up -d

3. 配置 Claude Desktop 以连接：

{
  "mcpServers": {
    "deapi": {
      "url": "http://your-server-ip:8000/mcp"
    }
  }
}

手动远程部署

1. 在远程服务上：

git clone https://github.com/deapi-ai/mcp-server-deapi.git
cd mcp-server-deapi
pip install -e .
python -m src.server_remote

2. 使用 systemd 进行生产部署：

# Create /etc/systemd/system/mcp-server-deapi.service
sudo systemctl enable mcp-server-deapi
sudo systemctl start mcp-server-deapi

3. 通过反向代理（nginx + SSL）：

server {
    listen 443 ssl http2;
    server_name mcp.yourdomain.com;

    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;

    location / {
        proxy_pass http://localhost:8000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_buffering off;
        proxy_cache off;
        proxy_read_timeout 86400;
    }
}

云部署选项

• Railway.app：推送到 GitHub，连接仓库并自动部署
• Fly.io：fly launch && fly deploy
• Heroku：heroku create && git push heroku main
• DigitalOcean：使用 App Platform 或搭配 Docker 的 Droplets
• AWS/GCP/Azure：使用容器服务部署（ECS、Cloud Run、Container Instances）

详细的部署说明、安全注意事项、监控和故障排除，请参阅 DEPLOYMENT.md。

故障排除

连接问题

如果服务器无法连接：

1. 检查 API 令牌是否有效
2. 确认网络可以连接到 api.deapi.ai
3. 检查日志中的具体错误信息
4. 对于远程服务：确认防火墙规则正确，且端口 8000 可访问

任务超时

如果任务超时：

1. 使用 get_balance 检查余额
2. 确认任务类型的超时时间设置合理
3. 使用 check_job_status 检查任务是否仍在处理中

未找到模型

如果出现模型错误：

1. 使用 get_available_models 查看可用模型
2. 确保使用了正确的模型名称
3. 检查模型是否支持所请求的操作

远程连接问题

如果远程 MCP 连接失败：

1. 测试端点：curl -N http://your-server:8000/mcp
2. 查看服务器日志：docker logs mcp-server-deapi 或 journalctl -u mcp-server-deapi
3. 确认防火墙规则和 SSL 证书正确（如果使用 HTTPS）
4. 确保客户端可以访问 MCP 端点

许可证

本项目采用 MIT License 许可，详情请参阅 LICENSE 文件。

支持

有关以下内容的问题：

• 此 MCP 服务：提交问题
• deAPI Platform：访问 docs.deapi.ai
• MCP Protocol：访问 modelcontextprotocol.io