@apocdata/mcp-server

MCP-Server (Model Context Protocol) von 天启至数 ApocData. Er verpackt 46 authentifizierungsfreie A-Aktien-Datenschnittstellen als MCP-Tools, die in jedem beliebigen MCP-Client wie Claude Desktop / Cursor / Cline / Continue direkt aufgerufen werden können.

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

• Kein API-Key, keine Registrierung erforderlich (das Gateway hat /open/** bereits ohne Authentifizierung freigeschaltet)

• Leitet automatisch die X-Tdc-* Metainformations-Header durch (Rate-Limit-Rest/Truncation-Flag/Fehlercode/Cache-Strategie)

• 46 Tools decken ab: Markt, Bewertung, Finanzen, Aktionäre, Kapitalflüsse, Limit Up/Down, Sektoren, Bekanntmachungen, Makro, Faktoren, umfassendes Profil

Installation

Methode A: npx (empfohlen, keine Installation)

Schreiben Sie direkt in der Client-Konfiguration npx -y @apocdata/mcp-server – kein manuelles Installieren nötig.

Methode B: Globale Installation

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

Related MCP server: sfc-data-mcp

Beispiel für die Client-Konfiguration

Claude Desktop

Bearbeiten Sie ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) oder %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 / andere stdio-MCP-Clients

Wie oben, übertragen Sie command=npx, args=["-y","@apocdata/mcp-server"].

CLI-Flags

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

Signale

• SIGTERM / SIGINT: Sauberes Beenden. Warten Sie, bis laufende Anfragen abgeschlossen sind (maximal 5 Sekunden), schließen Sie dann den Transport und beenden Sie den Prozess.

Debug-Modus

Die Umgebungsvariable APOCDATA_DEBUG=1 schreibt Pfad/Status/Meta jedes HTTP-Aufrufs nach stderr:

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

Benutzerdefinierte Basis-URL

Die Umgebungsvariable APOCDATA_BASE_URL kann auf ein Intranet/eine private Bereitstellung zeigen:

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

Zeitüberschreitung und Wiederholung

4xx wird nicht wiederholt (das Wiederholen von Geschäftsfehlern ist sinnlos). Nach erschöpften Wiederholungen wird die letzte 5xx-Antwort zurückgegeben oder ein NetworkError (Netzwerkfehler) geworfen.

Werkzeugliste (46 Tools)

Die Ein-/Ausgabeparameter und Standardwerte jedes Tools werden auf der MCP-Protokollebene per JSON Schema offengelegt; der Client zeigt sie automatisch an.

MCP-Ressourcen

Zusätzlich zu den Tools werden 3 Markdown-Dokumente bereitgestellt, die der Agent über resources/list und resources/read abrufen kann:

Anwendungsbeispiel (direkt in Claude fragen)

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

Leistung und Rate-Limiting

• Rate-Limit pro IP: 60 req/min (der Antwortheader X-Tdc-RateLimit-Remaining gibt das verbleibende Kontingent weiter)

• Cache-Strategie: Intraday-Echtzeitdaten 5s, Tagesaktualisierung nach Börsenschluss 5min, Metadaten 1h (Cache-Control-Header wird automatisch gesetzt)

• Der limit-Parameter ist auf 50 begrenzt; eine Überschreitung wird still gekürzt (siehe Antwortheader X-Tdc-Truncated)

• Für große Datenmengen wird format=compact Spaltenausgabe empfohlen, das 60-70 % Tokens spart

• Schnittstellen mit vielen Feldern (z. B. financial, announcements) unterstützen die Reduktion mit fields=...

Detailliertes Verhalten siehe Haupt-SKILL-Dokument: https://github.com/ApocData/ApocData-skill

Entwicklung

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

Quellcode-Struktur:

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

Um eine neue Schnittstelle hinzuzufügen: Fügen Sie in der entsprechenden Gruppe in tools.ts eine ToolDef hinzu und bauen Sie neu – kein anderer Code muss geändert werden.

Tests

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

Sechs Skripte entsprechen sechs Arten der Verifizierung:

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

Bekannte LAG (Online-Version ausstehend)

Die folgenden Fähigkeiten sind im Quellcode implementiert (Roadmap §2.1 / §5.1 / §5.3), aber in der aktuell auf data.tianqis.com bereitgestellten Version noch nicht wirksam. Nach einem Backend-Redeploy sind keine Änderungen am MCP-Server nötig; das Verhalten stellt sich automatisch wieder her:

• Validierung ungültiger Enum-Werte für ranking / macro / macro/latest / macro/definition / sector-flow / hot-rank / margin

• Antwortheader X-Tdc-Error-Code

• Antwortheader X-Tdc-RateLimit-Remaining (verbleibendes Rate-Limit-Kontingent)

• Antwortheader X-Tdc-Truncated (Hinweis bei Überschreitung des Limit-Höchstwerts; beachten Sie: die safeLimit-Kürzung im Controller ist bereits aktiv, nur ohne Header-Hinweis)

• format=compact Spaltenausgabe

• Die beiden Endpunkte /profile/full und /factor-categories selbst

Lizenz

Apache-2.0