hanjialeGit

@apocdata-info/mcp-server

ApocData の MCP（Model Context Protocol）サーバーです。46 個の A 株データ API を MCP ツールとしてラップしており、Claude Desktop／Cursor／Cline／Continue など、任意の MCP クライアントから直接呼び出せます。

• データソース：https://www.apocdata.com/api/blade-dataplatform/open/data/*
• 無料お試し枠：登録不要で呼び出せます。登録すると、より大きな枠とさらに多くのデータ機能を利用できます
• X-Tdc-* メタデータヘッダーを自動的に転送します（残りのレート制限枠／切り詰めフラグ／エラーコード／キャッシュポリシー）
• 46 個のツールが対応する分野：相場、バリュエーション、財務、株主、資金フロー、ストップ高・ストップ安、セクター、公告、マクロ、ファクター、総合プロファイル

---

インストール

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

クライアントの設定に npx -y @apocdata-info/mcp-server を直接記述すれば、手動で install する必要はありません。

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

npm install -g @apocdata-info/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-info/mcp-server"]
    }
  }
}

Cursor

~/.cursor/mcp.json：

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

Cline / Continue / その他の stdio MCP クライアント

同様に、command=npx, args=["-y","@apocdata-info/mcp-server"] を渡せば利用できます。

CLI フラグ

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-info/mcp-server"],
      "env": { "APOCDATA_DEBUG": "1" }
    }
  }
}

BASE URL のカスタマイズ

環境変数 APOCDATA_BASE_URL で、社内ネットワーク／プライベート環境のデプロイ先を指定できます。

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

タイムアウトと再試行

環境変数	デフォルト	説明
APOCDATA_TIMEOUT_MS	30000	1 回のリクエストのタイムアウト（ミリ秒）。時間になると AbortController が中断します
APOCDATA_MAX_RETRIES	2	5xx またはネットワークエラーの再試行回数（初回を除く）。指数バックオフは 500→1000→2000ms です

4xx は再試行しません（業務エラーを再試行しても意味がありません）。再試行を使い切ると、最後の 5xx 応答を返すか、NetworkError（ネットワーク異常）をスローします。

---

ツール一覧（46 個）

カテゴリー	ツール
A. 相場とバリュエーション（10）	quote quotes daily stock stocks st ranking indexes index-daily hot-rank
B. 財務と株主（8）	financial express dividend holders holder-number share-float repurchase block-trade
C. 資金フロー（8）	moneyflow hsgt hk-hold hk-daily margin dragon-tiger hot-money hot-money-detail
D. ストップ高・ストップ安とセクター（4）	limit-list limit-step sector-flow cyq-perf
E. 公告／調査（2）	announcements survey
F. セクター構成銘柄（4）	concepts concept-stocks ths-boards ths-board-stocks
G. 転換社債（2）	convertible-bonds cb-price-chg
H. ファクター（2）	factors tech-factor
I. マクロ（3）	macro macro-latest macro-definition
J. カレンダー（1）	calendar
K. 総合（2）	profile-full factor-categories

各ツールの入力／出力／デフォルト値は、MCP プロトコル層で JSON Schema として公開され、クライアントに自動表示されます。

MCP リソース

ツールに加えて、3 つの Markdown ドキュメントも公開しています。エージェントは resources/list と resources/read を通じて取得できます。

URI	内容
apocdata://guide	全般的な利用ガイド：46 個のツールの分類、symbol の形式、遅延／レート制限／エラープロトコル、メタデータヘッダーの説明
apocdata://scenarios	シナリオ別クイックリファレンス：よくあるユーザーの意図とツールの組み合わせの対応、およびアンチパターン（8 個の API を連続して呼び出すのを避ける方法）
apocdata://limits	limit／fields／compact クイックリファレンス：各ツールのデフォルト値／上限／フィールド絞り込みの対応状況

---

使用例（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 で残りの枠を転送します）
• キャッシュポリシー：取引時間中のリアルタイムデータは 5s、取引終了後の日次データは 5min、メタデータは 1h（Cache-Control ヘッダーが自動で付与されます）
• limit パラメーターの上限は 50 です。上限を超えると通知なしに切り詰められます（応答ヘッダー X-Tdc-Truncated を確認してください）
• 大量のデータには、列指向出力の format=compact を推奨します。token を 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 つ追加して、再度 build するだけです。ほかのコードを変更する必要はありません。

テスト

npm test                 # build + 6 类测试全跑（需在 apocdata-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 種類の検証を行います。

スクリプト	検証
client-unit-test.mjs	クライアントの 4xx では再試行しないこと、5xx が成功または上限まで再試行されること、タイムアウトの正規化、meta ヘッダーの抽出、URL の構築（fetch をモック）
contract-test.mjs	46 個すべてのエンドポイントについて、パラメーター名／必須項目がバックエンドの @RequestParam と一致すること、および正常系の呼び出しがすべて 200 を返すこと
error-path-test.mjs	不正なパラメーター／存在しないリソースに対して、HTTP 400 + success=false + X-Tdc-Error-Code が返されること
coverage-test.mjs	レート制限ヘッダー／切り詰めヘッダーが転送されること。すべての enum ツール（ranking / limit-list / sector-flow / hot-rank / margin / macro）の有効値をすべて検証
mcp-e2e-test.mjs	MCP プロトコルが正しいこと：tools/list が 46 個であること、HTTP 4xx と success=false の両方で isError が正しくマークされること、compact モードが列指向で出力されること
integration-test.mjs	実際の backoff の所要時間、実際にタイムアウトが発生すること、CLI の --version / --help、アイドル状態での SIGTERM による即時終了、処理中のリクエスト完了を待ってから SIGTERM で終了すること

プライベート環境にデプロイする場合：APOCDATA_BASE_URL=http://your.host/path npm test

生产契约基线

当前 www.apocdata.com 已提供并由测试套件持续验证：

• ranking / macro / macro/latest / macro/definition / sector-flow / hot-rank / margin 的非法 enum 校验
• X-Tdc-Error-Code 响应头
• X-Tdc-RateLimit-Remaining 响应头（限流剩余配额）
• X-Tdc-Truncated 响应头（limit 超上限通知）
• format=compact 列式输出
• /profile/full 和 /factor-categories 两个端点本身

---

License

Apache-2.0