onv-mcp

@onvcodes/mcp-server

ONV プラットフォームの MCP (Model Context Protocol) サーバーです。 プラットフォームの市場データ、公開エージェント／戦略、バックテスト、サブスクリプション、AI 生成などの機能を MCP ツールとして公開し、 Claude Desktop / Cursor / Cline などの AI エージェントから呼び出せるようにします。

アーキテクチャ：プラットフォームツールの薄いプロキシ

MCP サーバーではツールをローカルにハードコードしません（プラットフォーム側と定義が二重になり、ずれが生じるのを防ぐため）。実行時に動的に検出します。

MCP Client (Claude / Cursor …)
   │  Streamable HTTP（远程，推荐）/ SSE（兼容）/ stdio（本地）
   ▼
mcp-server（本包）
   │ ① 启动/会话时   GET {baseUrl}/api/mcp/platform/tools   → 发现工具清单（JSON Schema）
   │ ② 客户端调用工具 POST {baseUrl}/api/mcp/platform/{tool} body { args }
   │    凭证按会话透传：Authorization: Bearer > X-Api-Key > 匿名（仅公开工具）
   ▼
onv-backend（平台 /api/mcp/platform/*，3 通道鉴权：X-Api-Key / ?at= / Bearer JWT）

• ツール一覧と実行エンドポイントは onv-backend が一元管理します（backend/routes/platform-mcp.ts）。 本サービスはプラットフォームツールを MCP プロトコルに変換するだけです（zod スキーマの登録と呼び出しの転送）。
• プラットフォームに到達できない場合、API Key が未設定の場合、またはツールエンドポイントが 404 を返す場合は、読み取り専用の __platform_health フォールバックツールを登録して状態を報告します（tools/list が空にならないため、問題の調査に役立ちます）。正常時はプラットフォームの全ツールを登録します。

プラットフォームツール（現在 41 個）

tools/list は、権限別に分類され、4 グループ（market / strategy / portfolio / account）に分けて表示される 41 個のプラットフォームツールを返します。

権限レベル	数	説明
L0 公開読み取り（認証不要）	10	market_* · symbol_search · quick_analysis · list_agents · get_agent · plans · wallet_balance
L1 ユーザー読み取り（API Key／ログインユーザーとの紐付けが必要）	15	my_strategies · backtest_* · subscription_* · user_* · account_overview · positions · trade_history · credentials · risk_config · factory_runs · dex_quote
L2 書き込み操作（認可 scope が必要）	16	run_backtest · manage_strategy · publish_strategy · subscribe_* · ai_generate · ai_optimize · place_order · cancel_order · close_position · flat_all · set_risk_config · set_breaker · reset_breaker · dex_swap · factory_run · close_preview

各ツールには MCP annotations が含まれます：title（中国語の短い名称）、readOnlyHint（読み取りの場合は true）、 destructiveHint（書き込みの場合は true）——Claude Connectors ディレクトリの必須要件を満たします。 表示メタデータは backend/services/platform-tools/tool-meta.ts に集約されています。

ツール定義はプラットフォームの進化に合わせて自動更新されます。変更は backend の PLATFORM_TOOL_DEFS のみで行い、MCP サーバーのリリースは不要です。 backend では ENABLE_PLATFORM_TOOLS=true によりツールエンドポイントを有効にします（本番環境では有効化済みです）。

クイックスタート（本番環境、Streamable HTTP を推奨）

本番環境の MCP サーバーは onv.codes の統合スタックにデプロイ済みです（コンテナ onv-mcp、nginx で /mcp と /mcp/ をリバースプロキシ）：

• Streamable HTTP エンドポイント（推奨）：https://onv.codes/mcp
• SSE エンドポイント（互換）：https://onv.codes/mcp/sse
• 認証（セッションごとに転送）：
  • Authorization: Bearer <token>（OAuth／プラットフォーム JWT）
  • または X-Api-Key: ah_… / ahk_…（プラットフォーム／Agent Key）
  • どちらも指定されていない場合は匿名として扱われ、公開ツール（市場データ／公開エージェント／プランなど）のみ使用できます； HTTP エントリーポイントではサーバー側 env Key によるフォールバックを受け付けません。匿名の呼び出し元が実際のアカウント ID を引き継ぐのを防ぐためです。

Claude Desktop

Claude Desktop → Settings → Developer → Edit Config → claude_desktop_config.json：

{
  "mcpServers": {
    "onv": {
      "type": "http",
      "url": "https://onv.codes/mcp",
      "headers": {
        "X-Api-Key": "ah_你的平台APIKey"
      }
    }
  }
}

保存後、Claude Desktop を再起動すると、会話で platform_market_quote、platform_list_agents、 platform_run_backtest、platform_ai_generate などのツールを使用できます。

Cursor

Cursor → Settings → MCP → Add new MCP server：

• Type：HTTP（リモート、推奨）
• Name：onv
• URL：https://onv.codes/mcp
• Headers：X-Api-Key: ah_あなたのプラットフォームAPIKey

HTTP タイプに対応していない旧バージョンの Cursor では、SSE に切り替えてください：https://onv.codes/mcp/sse。

その他の MCP クライアント

「Streamable HTTP + カスタム header」に対応するクライアントでは、https://onv.codes/mcp と X-Api-Key を設定します； SSE のみ対応するクライアントでは、https://onv.codes/mcp/sse を設定します。どちらも同じツールと認証方式を使用します。

ローカル開発

依存要件：Node ≥ 18。

cd mcp-server
npm install
npm run build   # tsup 打包 ESM + CJS + dts 到 dist/
npm test        # vitest（工具 schema / 注册测试）

起動：

# stdio 模式（默认，供 Claude Desktop / Cursor 本地拉起）
ONV_API_KEY=ah_xxx node dist/server.js

# HTTP 模式（本地 :3002，同时提供 /mcp 与 /sse）
ONV_API_KEY=ah_xxx node dist/server.js --http
# => HTTP server listening on http://localhost:3002 (mcp + sse)

環境変数

変数	必須	デフォルト値	説明
ONV_API_KEY	-	-	サーバー側のフォールバック Key（ah_ / ahk_ プレフィックス）。クライアントが独自の認証情報を持つ場合は、クライアントの認証情報が優先されます；どちらも設定されていない場合は公開ツールのみ使用できます
ONV_BASE_URL	-	https://onv.codes	プラットフォーム API のルートアドレス（内部ネットワークでの接続テストには http://localhost:3100 を指定できます）
PORT	-	3002	HTTP モードのリッスンポート
MCP_MESSAGE_PATH	-	/message	SSE ハンドシェイクイベントのメッセージ配信パス；nginx のリバースプロキシ経由の場合に設定します（本番環境では /mcp/message）

Claude Desktop / Cursor のローカル stdio 設定

{
  "mcpServers": {
    "onv": {
      "command": "node",
      "args": ["/absolute/path/to/onv/mcp-server/dist/server.js"],
      "env": {
        "ONV_API_KEY": "ah_你的平台APIKey",
        "ONV_BASE_URL": "https://onv.codes"
      }
    }
  }
}

API Key と権限

Key	プレフィックス	用途	書き込み権限
プラットフォーム API Key	ah_	外部アプリ／MCP 呼び出し。ユーザーと権限に紐付け	permissions にツール scope（例：backtest:run / agents:write）または admin が含まれる場合に限り、書き込みツールを直接実行できます
Agent API Key	ahk_	Agent ID による直接呼び出し	scopes に write / admin が含まれる場合に限り、書き込みツールを直接実行できます

• 読み取りツール（L0）は認証なしで呼び出せます（公開データを返します）。
• ユーザー読み取り（L1）と書き込み（L2）ツールには、有効なユーザーに解決できる X-Api-Key が必要です（無効または取り消し済みの場合は 401 を返します）。
• 書き込みツール（L2）は、key に対応する scope がある場合、直接実行して監査記録を残します；scope がない場合は 403 を返します。
• 会話での操作（?at= HMAC token）による書き込みは pending 状態にのみ記録され、フロントエンドの操作カードで確認後に実行されます。

本番環境へのデプロイ（onv.codes 統合スタック）

• compose サービス：apps/onv-core/deploy/docker-compose.onv.yml の mcp（:3002、 ビルドコンテキスト apps/onv、dockerfile mcp-server/Dockerfile）。
• nginx：location = /mcp / location /mcp/ は mcp:3002 にリバースプロキシします（Streamable HTTP のバッファリングを無効化し、読み取りタイムアウトを 3600s に設定）； location /api/mcp/ は onv-backend:3100 にリバースプロキシします（ツールの検出／呼び出しエンドポイント）。
• 認証情報：セッションごとに引き継ぎ、サーバー側の Key は設定しません（MCP_API_KEY は compose から削除済みです）。 MCP_BASE_URL のデフォルトは https://onv.codes です。
• バックエンドのフラグ：ENABLE_PLATFORM_TOOLS=true（platform-tools.ts の段階的リリース用ゲート。production ではすでに true に設定されています）。

複数セッションについて

MCP SDK の Server インスタンスは、同時に 1 つの transport のみ接続できます（そうでない場合は Already connected がスローされます）。 本サービスではセッションごと（Streamable HTTP session / SSE transport）に独立した McpServer インスタンスを作成します （毎回ツール一覧を再検出します）。複数のクライアントによる同時接続や再接続が互いに影響することはなく、認証情報もセッションごとに分離されます。

トラブルシューティング

現象	原因と対処
tools/list に __platform_health しか表示されない	ツールの検出に失敗しています。ONV_BASE_URL への接続性、backend の ENABLE_PLATFORM_TOOLS=true、nginx の /api/mcp/ リバースプロキシを確認してください
呼び出しで invalid or revoked api key が返される	クライアントが送信した X-Api-Key / Bearer が無効、または取り消されています（ah_/ahk_ のプレフィックスが必要です）。匿名でユーザーレベルのツールを呼び出した場合も、このメッセージが表示されます
呼び出しで 404 unknown platform tool が返される	ツール一覧とエンドポイントのバージョンが同期していません（検出後にプラットフォーム側で名前が変更されています）。mcp-server イメージを更新して再接続してください
POST /message が 502 になる	多くの場合、SSE セッションが確立されていない、または切断済みの状態で配信しようとしています（sessionId が期限切れです）。クライアントは再接続してハンドシェイクをやり直してください

ライセンス

Apache-2.0