@apocdata/mcp-server

天启至数 ApocData の MCP（Model Context Protocol）Server。46 個の認証不要な A 株データ API を MCP tools としてラップし、Claude Desktop / Cursor / Cline / Continue などの任意の MCP client から直接呼び出せます。

• データソース：https://data.tianqis.com/api/blade-dataplatform/open/data/*

• API Key 不要、登録不要（ゲートウェイは /open/** を認証不要に設定済み）

• X-Tdc-* メタ情報ヘッダーを自動透過（レート制限残量/切り詰めフラグ/エラーコード/キャッシュポリシー）

• 46 ツールをカバー：相場、バリュエーション、財務、株主、資金フロー、値幅制限、セクター、公告、マクロ、ファクター、総合プロフィール

インストール

方法 A：npx（推奨、インストール不要）

client 設定に npx -y @apocdata/mcp-server を直接記述します。手動インストールは不要です。

方法 B：グローバルインストール

npm install -g @apocdata/mcp-server
apocdata-mcp   # 可执行命令

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json（macOS）または %APPDATA%\Claude\claude_desktop_config.json（Windows）を編集：

{
  "mcpServers": {
    "apocdata": {
      "command": "npx",
      "args": ["-y", "@apocdata/mcp-server"]
    }
  }
}

Cursor

~/.cursor/mcp.json：

{
  "mcpServers": {
    "apocdata": {
      "command": "npx",
      "args": ["-y", "@apocdata/mcp-server"]
    }
  }
}

Cline / Continue / その他の stdio MCP client

同上、command=npx, args=["-y","@apocdata/mcp-server"] を渡すだけです。

CLI flags

apocdata-mcp --version    # 打印版本号
apocdata-mcp --help       # 显示完整用法

シグナル

• SIGTERM / SIGINT：グレースフル終了。進行中のリクエストの完了を待って（最大 5 秒）、transport を閉じて終了します。

デバッグモード

環境変数 APOCDATA_DEBUG=1 を設定すると、各 HTTP 呼び出しの path/status/meta が stderr に出力されます：

{
  "mcpServers": {
    "apocdata": {
      "command": "npx",
      "args": ["-y", "@apocdata/mcp-server"],
      "env": { "APOCDATA_DEBUG": "1" }
    }
  }
}

カスタム BASE URL

環境変数 APOCDATA_BASE_URL で内部ネットワーク/プライベートデプロイを指定できます：

"env": { "APOCDATA_BASE_URL": "https://intranet.example.com/api/blade-dataplatform/open/data" }

タイムアウトとリトライ

4xx はリトライしません（業務エラーのリトライは無意味）。リトライを使い切った後は最後の 5xx レスポンスを返すか、NetworkError（ネットワーク例外）をスローします。

Related MCP server: sfc-data-mcp

ツール一覧（46 個）

各 tool の入出力パラメータ/デフォルト値は MCP プロトコル層で JSON Schema として公開され、client が自動表示します。

MCP Resources

ツール以外に 3 つの markdown ドキュメントを公開しています。Agent は resources/list と resources/read で取得します：

使用例（Claude で直接質問）

> 帮我看下贵州茅台最近 5 天行情
（Claude 调用 daily(symbol="600519", limit=5)）

> 现在涨幅榜前 10 是哪些股票？
（Claude 调用 ranking(type="gainers", limit=10)）

> 整理一下平安银行的综合画像
（Claude 调用 profile-full(symbol="000001")）

> CPI 最近一次数据是多少？
（Claude 调用 macro-latest(type="cpi")）

パフォーマンスとレート制限

• 単一 IP レート制限：60 req/min（レスポンスヘッダー X-Tdc-RateLimit-Remaining で残りクォータを透過）

• キャッシュポリシー：日中リアルタイムデータ 5 秒、引け後日次更新 5 分、メタデータ 1 時間（Cache-Control ヘッダーを自動付与）

• limit パラメータの上限は 50。超えるとサイレントに切り詰め（レスポンスヘッダー X-Tdc-Truncated を参照）

• 大量データは format=compact の列形式出力を推奨。トークンを 60〜70% 節約

• フィールドが多い API（financial、announcements など）は fields=... での絞り込みに対応

詳細な挙動はメイン SKILL ドキュメントを参照：https://github.com/ApocData/ApocData-skill

開発

git clone https://github.com/ApocData/ApocData-skill.git
cd ApocData-skill/mcp-server
npm install
npm run build
npm start

ソースコード構造：

src/
  index.ts     # MCP server 入口，stdio transport
  client.ts    # HTTP client，BASE_URL 调用 + meta 头提取
  tools.ts     # 46 个工具的配置表（声明式）

新しい API を追加するには：tools.ts の対応するグループに ToolDef を 1 件追加して、再ビルドするだけです。他のコードを変更する必要はありません。

テスト

npm test                 # build + 6 类测试全跑（需在 tianqi-mcp 目录执行）
npm run test:unit        # client 单测：超时/重试/URL 构造，不打外网
npm run test:contract    # 46 工具逐个真实 HTTP 调用（happy path）
npm run test:errors      # 错误路径：非法参数 / 不存在 symbol / 日期格式
npm run test:coverage    # 限流头/截断头/所有枚举值遍历
npm run test:e2e         # MCP 协议层：stdio JSON-RPC + isError + compact
npm run test:integration # 集成：mock HTTP + 子进程 server，验证 retries / timeout / --version / SIGTERM

6 つのスクリプトが 6 種類の検証に対応：

プライベートデプロイ：APOCDATA_BASE_URL=http://your.host/path npm test

既知の LAG（本番未反映）

以下の能力はソースコードで実装済み（ロードマップ §2.1 / §5.1 / §5.3）ですが、data.tianqis.com に現在デプロイされているバージョンではまだ有効になっていません。バックエンドを再デプロイすれば MCP server を変更する必要はなく、動作は自動的に復旧します：

• ranking / macro / macro/latest / macro/definition / sector-flow / hot-rank / margin の不正 enum バリデーション

• X-Tdc-Error-Code レスポンスヘッダー

• X-Tdc-RateLimit-Remaining レスポンスヘッダー（レート制限の残りクォータ）

• X-Tdc-Truncated レスポンスヘッダー（limit 上限超過通知；controller 内の safeLimit による切り詰め自体は有効済みで、ヘッダー通知がないだけ）

• format=compact 列形式出力

• /profile/full と /factor-categories の 2 つのエンドポイント自体

License

Apache-2.0