deAPI MCP Server

deAPI MCP Server

deAPI REST API 用の本番環境対応 Model Context Protocol（MCP）サーバーです。このサーバーは、deAPI のすべての AI 機能を MCP ツールとして公開し、LLM による音声の文字起こし、画像生成、OCR、動画生成、テキスト読み上げなどを可能にします。

deAPI v2 — このサーバーは deAPI v2 クライアント API（/api/v2/* 以下の OpenAI に準拠した名詞パス）を対象としています。従来の v1 エンドポイントを指定する必要がある場合は、DEAPI_API_VERSION=v1 を設定してください。

特長

• 完全な API カバレッジ：すべての v2 クライアントエンドポイントを網羅する 39 個の deAPI ツールを MCP 経由で公開
• スマートな適応型ポーリング：ジョブの種類に応じて最適化された間隔で、非同期ジョブを自動的にポーリング
• OAuth 2.0 認証：PKCE を使用した OAuth Authorization Code フローによる安全なトークン交換
• エラーリカバリー：指数バックオフによる自動再試行ロジック
• 進捗レポート：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 の URL から音声を文字起こし
• audio_url_transcription_price - Twitter Spaces の文字起こし料金を計算

動画文字起こしツール

• video_file_transcription - 動画ファイルをテキストに文字起こし
• video_file_transcription_price - 動画ファイルの文字起こし料金を計算
• video_url_transcription - URL（YouTube、Twitter/X、Twitch、Kick）から動画を文字起こし
• video_url_transcription_price - 動画 URL の文字起こし料金を計算

画像ツール

• 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

使い方

サーバーの実行

サーバーは 2 つのモードで実行できます：

ローカルモード（同じマシン上の 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：ベアラートークンを使用した設定ファイル（ローカル開発）

最適な用途： 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（Authorization Code with 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 をご覧ください