MCP データゲートウェイ

ステータス: 開発初期段階。 プロジェクトの基盤（設定、依存関係、ドキュメント）は整っています。src/ 配下のソースコードはまだ実装されていません。現在の進捗状況については 開発ロードマップ を参照してください。実装計画は docs/plan.md にあります。

統合データゲートウェイとして機能する Python ベースの Model Context Protocol (MCP) サーバーです。Claude（およびその他の MCP クライアント）が、単一の安全なインターフェースを通じて複数の外部 API との間でデータを送受信できるようにします。

概要

この MCP サーバーは以下を提供します：

• 複数のデータ型に対する汎用的なデータ処理

• あらゆる REST または GraphQL エンドポイントをサポートする汎用 API ゲートウェイ

• ブラウザベースの自動ログインフローを備えた OAuth 2.0 認証

• システムキーリングを使用した安全な認証情報の保存

• 将来的な MCP アプリ進化のための基盤

機能

アーキテクチャ

MCP/
├── src/
│   ├── server.py              # MCP server entry point
│   ├── auth/
│   │   ├── __init__.py
│   │   ├── oauth.py           # OAuth 2.0 flow handler with popup
│   │   └── credentials.py     # Secure credential storage (keyring)
│   ├── gateway/
│   │   ├── __init__.py
│   │   ├── api_client.py      # Generic REST/GraphQL HTTP client
│   │   └── handlers.py        # Request/response transformation
│   ├── models/
│   │   ├── __init__.py
│   │   └── data_models.py     # Generic Pydantic data models
│   └── tools/
│       ├── __init__.py
│       └── mcp_tools.py       # MCP tool definitions for Claude
├── config/
│   └── api_configs.json       # API service configurations
├── tests/                     # Unit and integration tests
├── .env.example               # Environment variables template
├── .gitignore                 # Excludes secrets and build artifacts
├── requirements.txt           # Python dependencies
└── README.md                  # This file

モジュールの役割

コア MCP サーバー (src/server.py)

• Python mcp SDK を使用して MCP サーバーを初期化

• ツール (fetch_data, send_data, execute_graphql など) を登録

• ツールの実行ライフサイクルとエラー応答を処理

認証 (src/auth/)

• oauth.py: ブラウザの自動ポップアップを備えた OAuth 2.0 認可コードフロー。ローカル HTTP コールバックサーバーを起動して認可コードを受信。複数のプロバイダー (Google, GitHub, カスタム) をサポート。

• credentials.py: システムキーリングを介したアクセストークン/リフレッシュトークンの安全な保存。トークンの検証と有効期限を処理。

API ゲートウェイ (src/gateway/)

• api_client.py: REST (GET/POST/PUT/DELETE) および GraphQL (クエリ/ミューテーション) をサポートする汎用非同期 HTTP クライアント。Bearer トークン、API キー、Basic 認証を処理。

• handlers.py: 異なる API 間で応答を正規化し、GraphQL エラーを HTTP エラーとは別に解析。

MCP ツール (src/tools/mcp_tools.py)

認証フロー

Claude が認証を必要とするツールを呼び出すと：

1. Claude invokes tool (e.g., fetch_data)
        ↓
2. MCP checks credentials in keyring
        ↓
3a. Valid token  →  Proceed with API call
3b. Missing/Expired  →  Open browser popup for OAuth
        ↓
4. User logs in via browser
        ↓
5. Local callback server receives auth code
        ↓
6. Exchange auth code for access token
        ↓
7. Store token in keyring
        ↓
8. Resume original tool call

技術スタック

• Python 3.10+

• mcp — Model Context Protocol Python SDK

• httpx — 非同期 HTTP クライアント (REST + GraphQL)

• keyring — クロスプラットフォームの安全な認証情報ストレージ

• pydantic — データ検証およびモデリング

• python-dotenv — 環境変数管理

セットアップ

前提条件

• Python 3.10 以上

• pip または uv (推奨)

インストール

# Clone the repository
cd /Users/chawengwit/Documents/MCP

# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Copy environment template
cp .env.example .env
# Edit .env with your OAuth credentials and API settings

設定

1. 環境変数 (.env)

# OAuth credentials (per provider)
OAUTH_CLIENT_ID=your_client_id
OAUTH_CLIENT_SECRET=your_client_secret
OAUTH_REDIRECT_URI=http://localhost:8765/callback

# Server settings
MCP_LOG_LEVEL=INFO              # DEBUG | INFO | WARN | ERROR
MCP_LOG_FILE=                   # Optional path to log file (default: stderr only)
MCP_DEBUG=false                 # Enable verbose request tracing
MCP_MAX_RESPONSE_BYTES=1048576  # Response size cap (1 MB default)
OAUTH_CALLBACK_PORT=8765

2. API 設定 (config/api_configs.json)

{
  "apis": {
    "example_api": {
      "base_url": "https://api.example.com",
      "type": "rest",
      "auth": {
        "method": "oauth2",
        "provider": "custom",
        "authorize_url": "https://auth.example.com/oauth/authorize",
        "token_url": "https://auth.example.com/oauth/token",
        "scopes": ["read", "write"]
      },
      "endpoints": {
        "get_users": {"method": "GET", "path": "/users"},
        "create_user": {"method": "POST", "path": "/users"}
      }
    }
  }
}

使用方法

MCP サーバーの実行

python -m src.server

Claude Code への接続

Claude Code の MCP 設定に以下の設定を追加してください：

{
  "mcpServers": {
    "data-gateway": {
      "command": "python",
      "args": ["-m", "src.server"],
      "cwd": "/Users/chawengwit/Documents/MCP"
    }
  }
}

対話例

接続後、Claude は以下のような操作が可能です：

• 設定済み API の一覧表示: "利用可能な API サービスを表示して"

• データの取得: "example_api からユーザーリストを取得して"

• データの送信: "このデータを使って example_api に新しいレコードを作成して..."

• GraphQL の実行: "私の API に対してこの GraphQL クエリを実行して..."

認証が必要なツールを Claude が初めて使用する際、OAuth ログインのためにブラウザが自動的に開きます。

応答形式

すべての MCP ツールは、一貫した解析のために構造化された JSON を返します。

成功:

{
  "data": <api response>,
  "metadata": { "source": "...", "endpoint": "...", "timestamp": "...", "duration_ms": 142 }
}

エラー:

{
  "error": { "code": "AUTH_REQUIRED", "message": "...", "details": { ... } }
}

標準エラーコード: AUTH_REQUIRED, AUTH_FAILED, API_NOT_CONFIGURED, ENDPOINT_NOT_FOUND, RATE_LIMITED, UPSTREAM_ERROR, VALIDATION_ERROR, RESPONSE_TOO_LARGE。

MCP_MAX_RESPONSE_BYTES を超える JSON/テキスト応答は、metadata.truncated: true とページネーションカーソルが付与され、切り捨てられた状態で成功として返されます。バイナリまたはストリーミングペイロードのみが RESPONSE_TOO_LARGE を出力します（これらは安全に切り捨てることができないため）。バイナリデータは content_type メタデータと共に base64 エンコードされます。GraphQL 応答は data と errors の両方を表示するため、部分的な成功は引き続き利用可能です。

詳細は CLAUDE.md を参照してください。

デバッグ

クイック診断

デバッグモードの有効化

MCP_DEBUG=true MCP_LOG_LEVEL=DEBUG python -m src.server

これにより、完全な HTTP 交換（シークレットは編集済み）が stderr にダンプされます。stdout には絶対に出力しないでください。stdout は MCP JSON-RPC プロトコルストリームを運ぶためです。

ログに関する注意

• すべてのログは stderr (またはオプションの MCP_LOG_FILE) に出力されます。

• トークン、API キー、Authorization ヘッダー、および認証情報は、ログ記録前に自動的に編集されます。

• ログは jq で簡単に解析できるように、構造化された JSON (1 行に 1 イベント) になっています。

デバッグ戦略の詳細は CLAUDE.md を参照してください。

開発ロードマップ

フェーズ 1: プロジェクトセットアップ

• [x] 依存関係を固定した requirements.txt

• [x] シークレットとキャッシュ用の .gitignore

• [x] 環境変数を文書化した .env.example

• [ ] src/ パッケージ構造の初期化

• [ ] 初期 config/api_configs.json テンプレート

フェーズ 2: コア MCP サーバー

• [ ] MCP サーバーの初期化

• [ ] ツールスキーマの定義

• [ ] ログ記録とエラー処理

フェーズ 3: 認証

• [ ] OAuth 2.0 認可コードフロー

• [ ] ローカルコールバック HTTP サーバー

• [ ] キーリングベースのトークンストレージ

• [ ] トークン更新ロジック

フェーズ 4: API ゲートウェイ

• [ ] 汎用 REST クライアント

• [ ] GraphQL クエリ/ミューテーションサポート

• [ ] マルチ認証方式サポート

• [ ] リクエスト/応答ハンドラー

フェーズ 5: ツールと統合

• [ ] fetch_data ツールの実装

• [ ] send_data ツールの実装

• [ ] execute_graphql ツールの実装

• [ ] list_apis および get_status ツールの実装

フェーズ 6: テストと洗練

• [ ] モジュールごとのユニットテスト

• [ ] モック API を使用した統合テスト

• [ ] 設定例

• [ ] ユーザー向けドキュメント

今後の拡張機能

• MCP アプリ: このゲートウェイの上位層としてのスタンドアロン Web インターフェース

• 永続ストレージ: データ履歴と監査ログのための SQLite/PostgreSQL

• レート制限: API ごとのレート制限とリクエストキューイング

• キャッシュ: 設定可能な TTL を持つ応答キャッシュ

• マルチテナント: 個別の認証情報ストアを持つ複数のユーザーのサポート

• Webhooks: 受信 Webhook を介したデータ受信

• データ変換パイプライン: API 間での変換チェーン

セキュリティ

• すべての認証情報は OS レベルの安全なキーリングに保存 (macOS は Keychain、Windows は Credential Manager、Linux は Secret Service)

• .env ファイルは .gitignore を介してバージョン管理から除外

• OAuth は標準の認可コードフローを使用 (暗黙的付与は使用しない)

• トークンはログに記録されたり、エラーメッセージに露出したりすることはない

• ローカルコールバックサーバーは localhost でのみリッスンし、OAuth フロー中のみ動作

ライセンス

未定

貢献

このプロジェクトは開発初期段階です。コア実装が安定した時点で貢献ガイドラインを追加します。