@apocdata/mcp-server

Servidor MCP (Model Context Protocol) de 天启至数 ApocData. Envuelve 46 interfaces de datos de acciones A sin autenticación como MCP tools, que se pueden llamar directamente en cualquier cliente MCP como Claude Desktop / Cursor / Cline / Continue.

• Fuente de datos: https://data.tianqis.com/api/blade-dataplatform/open/data/*

• No se necesita API Key, no requiere registro (la puerta de enlace ya está configurada con /open/** sin autenticación)

• Transmite automáticamente los metadatos de la cabecera X-Tdc-* (restante del límite de velocidad / indicador de truncamiento / código de error / política de caché)

• 46 tools cubren: cotizaciones, valoración, finanzas, accionistas, flujo de fondos, límites de subida/bajada, sectores, anuncios, macro, factores, perfil integral

Instalación

Método A: npx (recomendado, sin instalación)

En la configuración del cliente, escribe npx -y @apocdata/mcp-server directamente, no es necesario instalar manualmente.

Método B: Instalación global

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

Related MCP server: sfc-data-mcp

Ejemplo de configuración del cliente

Claude Desktop

Edita ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) o %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 / otros clientes MCP stdio

Igual que arriba, pasa command=npx, args=["-y","@apocdata/mcp-server"].

CLI flags

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

Señales

• SIGTERM / SIGINT: salida elegante. Espera a que las solicitudes en curso terminen (máximo 5 segundos), luego cierra el transport y sale.

Modo de depuración

La variable de entorno APOCDATA_DEBUG=1 imprime el path/status/meta de cada llamada HTTP a stderr:

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

URL BASE personalizada

La variable de entorno APOCDATA_BASE_URL puede apuntar a una intranet/despliegue privado:

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

Timeout y reintentos

Los 4xx no se reintentan (los errores de negocio no tienen sentido de reintentar). Cuando se agotan los reintentos, se devuelve la última respuesta 5xx, o se lanza NetworkError (excepción de red).

Lista de tools (46)

Los parámetros de entrada/salida y valores predeterminados de cada tool se exponen mediante JSON Schema en la capa de protocolo MCP, y el cliente los muestra automáticamente.

MCP Resources

Además de las tools, también se exponen 3 documentos markdown, que el Agent puede obtener mediante resources/list y resources/read:

Ejemplo de uso (pregunta directamente en 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")）

Rendimiento y límite de velocidad

• Límite de velocidad por IP: 60 req/min (la cabecera de respuesta X-Tdc-RateLimit-Remaining transmite la cuota restante)

• Política de caché: datos en tiempo real durante la sesión 5s, datos diarios después del cierre 5min, metadatos 1h (la cabecera Cache-Control se proporciona automáticamente)

• El parámetro limit tiene un máximo de 50, si se excede se trunca silenciosamente (ver la cabecera de respuesta X-Tdc-Truncated)

• Para grandes volúmenes de datos se recomienda usar format=compact con salida en columnas, ahorrando 60-70% de tokens

• Las interfaces con muchos campos (como financial, announcements) admiten recorte con fields=...

Consulta el documento principal de SKILL para más detalles: https://github.com/ApocData/ApocData-skill

Desarrollo

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

Estructura del código fuente:

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

Para añadir una nueva interfaz: agrega una ToolDef en el grupo correspondiente en tools.ts, y reconstruye; no es necesario modificar otro código.

Pruebas

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

Los seis scripts corresponden a seis tipos de verificación:

Despliegue privado: APOCDATA_BASE_URL=http://your.host/path npm test

LAG conocido (pendiente de lanzamiento en línea)

Las siguientes capacidades ya están implementadas en el código fuente (hoja de ruta §2.1 / §5.1 / §5.3), pero la versión actualmente desplegada en data.tianqis.com aún no está activa. Después del redeploy del backend, no es necesario modificar el servidor MCP; el comportamiento se restaura automáticamente:

• Validación de enum ilegal para ranking / macro / macro/latest / macro/definition / sector-flow / hot-rank / margin

• Cabecera de respuesta X-Tdc-Error-Code

• Cabecera de respuesta X-Tdc-RateLimit-Remaining (cuota restante del límite de velocidad)

• Cabecera de respuesta X-Tdc-Truncated (notificación de que limit superó el máximo; nota: el truncamiento safeLimit dentro del controller ya está activo, solo falta la notificación por cabecera)

• Salida en columnas con format=compact

• Los dos endpoints /profile/full y /factor-categories en sí mismos

License

Apache-2.0