@apocdata/mcp-server

The MCP (Model Context Protocol) server for 天启至数 ApocData. It wraps 46 authentication-free A-share data endpoints into MCP tools, ready to be called directly from any MCP client such as Claude Desktop / Cursor / Cline / Continue.

• Data source: https://data.tianqis.com/api/blade-dataplatform/open/data/*

• No API Key, no registration required (the gateway has /open/** configured as authentication-free)

• Automatically passes through X-Tdc-* metadata headers (rate-limit remaining / truncation flag / error code / cache policy)

• 46 tools cover: quotes, valuation, financials, shareholders, money flow, limit up/down, sectors, announcements, macro, factors, and composite profiles

Installation

Method A: npx (recommended, zero installation)

Simply write npx -y @apocdata/mcp-server in the client configuration; no manual install is needed.

Method B: Global installation

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

Related MCP server: sfc-data-mcp

Client configuration examples

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %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 / other stdio MCP clients

Same as above; pass command=npx, args=["-y","@apocdata/mcp-server"].

CLI flags

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

Signals

• SIGTERM / SIGINT: graceful shutdown. Wait for in-flight requests to complete (up to 5 seconds), then close the transport and exit.

Debug mode

The environment variable APOCDATA_DEBUG=1 writes the path/status/meta of every HTTP call to stderr:

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

Custom BASE URL

The environment variable APOCDATA_BASE_URL can point to an intranet/private deployment:

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

Timeout and retry

4xx is not retried (retrying business errors is pointless). When retries are exhausted, return the last 5xx response, or throw NetworkError (network anomaly).

Tool list (46)

Each tool's inputs/outputs/defaults are exposed via JSON Schema at the MCP protocol layer; the client displays them automatically.

MCP Resources

In addition to tools, 3 markdown documents are exposed. Agents fetch them through resources/list and resources/read:

Usage examples (ask Claude directly)

> 帮我看下贵州茅台最近 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")）

Performance and rate limiting

• Per-IP rate limit: 60 req/min (the X-Tdc-RateLimit-Remaining response header reports the remaining quota)

• Cache policy: intraday realtime data 5s, post-close daily updates 5min, metadata 1h (the Cache-Control header is set automatically)

• The limit parameter cap is 50; exceeding it is silently truncated (see the X-Tdc-Truncated response header)

• For large data batches, use format=compact columnar output to save 60-70% tokens

• Interfaces with many fields (e.g., financial, announcements) support fields=... filtering

For detailed behavior, see the main SKILL document: https://github.com/ApocData/ApocData-skill

Development

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

Source tree:

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

To add a new endpoint, add a ToolDef to the corresponding group in tools.ts and rebuild; no other code changes are needed.

Testing

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

The six scripts correspond to six types of verification:

Private deployment: APOCDATA_BASE_URL=http://your.host/path npm test

Known LAG (pending online release)

The following capabilities are already implemented in the source (roadmap §2.1 / §5.1 / §5.3), but the version currently deployed on data.tianqis.com is not yet effective. After the backend is redeployed, no changes to the MCP server are needed and the behavior automatically recovers:

• Invalid enum validation for ranking / macro / macro/latest / macro/definition / sector-flow / hot-rank / margin

• X-Tdc-Error-Code response header

• X-Tdc-RateLimit-Remaining response header (remaining rate-limit quota)

• X-Tdc-Truncated response header (notification when limit exceeds the cap; note the safeLimit truncation inside the controller is already active, only the header notification is missing)

• format=compact columnar output

• The /profile/full and /factor-categories endpoints themselves

License

Apache-2.0