Servicio MCP TdxQuant

Encapsulación MCP (Model Context Protocol) basada en el tqcenter.py local (interfaz de estrategia de TdxQuant / 通达信). Los clientes de IA (como Cursor) pueden invocar herramientas a través de stdio o HTTP/SSE para obtener datos de mercado, financieros, de sectores, fórmulas, etc.

Nombre del paquete Python: tdxquant-mcp (ver pyproject.toml).

Acceso MCP: docs/mcp-configuration.md Uso del Agente (orden de llamada, correspondencia de intenciones, seguridad en el trading): docs/agent-usage.md Introducción a la plataforma TdxQuant (ayuda oficial organizada + explicación de herramientas MCP): docs/tdxquant-intro.md Paquete de habilidades del Agente (Claude Code / OpenClaw / Hermes + configuración SSE): docs/agent-skills.md · skills/tdxquant-mcp/

Paquete de habilidades del Agente

Orientado a Claude Code, OpenClaw, Hermes Agent, etc.: se puede copiar el directorio skills/tdxquant-mcp/ (contiene SKILL.md / skill.md y fragmentos de configuración SSE en references/, además de flujos de trabajo simplificados). Junto con el tdx_mcp.main_http ya iniciado, el cliente se conecta a http://<MCP_HOST>:<MCP_PORT>/sse. Consulte la instalación y las rutas del host en docs/agent-skills.md.

Resumen de funciones

Las herramientas se dividen en 9 categorías (coherentes con tools_catalog / tool_metadata):

Sugerencia: Primero llame a la herramienta tools_catalog (sin parámetros), que devuelve la lista de categorías y herramientas, y luego llame a la herramienta específica según sea necesario. Formato de código de valores: Para Shanghái/Shenzhen, generalmente es 600519.SH, 000001.SZ (sufijo de mercado en mayúsculas).

Estructura del repositorio (relacionada con este proyecto)

user/
├── tqcenter.py              # TdxQuant Python 接口（依赖 TPythClient.dll 等）
├── tdxdata_test.py          # 直连 tq 的脚本示例（非 MCP）
├── skills/tdxquant-mcp/     # Agent Skill（SSE工作流 + 各宿主 MCP 片段）
├── tdx_mcp/                 # MCP 可安装包
│   ├── main_stdio.py        # stdio 入口（Cursor本地 MCP 推荐）
│   ├── main_http.py         # HTTP/SSE入口
│   ├── config.py            # 环境变量：TQ_PATH 等
│   ├── service/tdx_service.py
│   └── server/              # 各工具注册模块
├── tests/                   # pytest（含可选集成测试）
├── pyproject.toml
├── .env.example
├── docs/
│   ├── mcp-configuration.md # MCP 配置（Cursor / Claude / SSE）
│   ├── agent-usage.md       # Agent 使用说明（工作流、意图对照、交易）
│   ├── agent-skills.md      # Skill 包安装（Claude Code / OpenClaw / Hermes）
│   ├── tdxquant-intro.md    # TdxQuant 简介索引（正文见包内 resources）
│   └── mirror-tdx-quant-help/  # 运行 sync脚本后：官方帮助镜像 Markdown（可选）
└── .cursor/mcp.json         # Cursor 项目级 MCP 示例（可选）

Requisitos previos para la ejecución

1. El terminal TdxQuant / 通达信 (incluyendo capacidades de estrategia) puede ejecutarse normalmente en la máquina local y la ruta de la estrategia se ha configurado según las instrucciones oficiales.

2. El archivo tqcenter.py en el directorio del proyecto debe poder importarse (coincide con la ruta de TPythClient.dll, etc., ver documentación de TdxQuant).

3. Se ha configurado TQ_PATH (apunta a la ruta del script de estrategia, coherente con los requisitos de tq.initialize).

4. Se recomienda utilizar uv para gestionar dependencias y comandos de ejecución.

Instalación

uv sync

El modo HTTP/SSE requiere dependencias ASGI:

uv sync --extra http

Desarrollo y pruebas:

uv sync --extra dev

Espejo de ayuda en línea de TdxQuant (rastreo de páginas bajo help.tdx.com.cn/quant/docs/, generación de Markdown local, opcional):

uv sync --extra sync-docs
python scripts/sync_tdx_help_docs.py

El directorio de salida es por defecto docs/mirror-tdx-quant-help/ (contiene pages/, _manifest.json, README.md). Consulte las instrucciones dentro de ese directorio; los derechos de autor del texto pertenecen a TdxQuant, por favor tome la versión en línea como referencia.

Variables de entorno

Copie .env.example a .env y modifique:

Al iniciar el proceso MCP, se cargará get_settings(), la falta de TQ_PATH provocará un error directo.

Configurar MCP en Cursor (stdio)

El proyecto ya proporciona un ejemplo .cursor/mcp.json (uv + envFile). Después de abrir la raíz del repositorio en Cursor, habilite tdxquant en Configuración → MCP.

Para obtener instrucciones más completas (incluyendo Claude Desktop, env en línea, HTTP/SSE, resolución de problemas), consulte docs/mcp-configuration.md.

Métodos de inicio

stdio (Recomendado: Cursor, Claude Desktop, etc.)

uv run python -m tdx_mcp.main_stdio

HTTP / SSE (Proceso independiente, para clientes que admiten MCP remoto)

uv run python -m tdx_mcp.main_http

La dirección y el puerto de escucha están determinados por MCP_HOST / MCP_PORT (ver .env).

Nombres de herramientas y ejemplos de llamada

Los siguientes nombres son exactamente iguales a @mcp.tool(name="...") en el código. En diferentes clientes, los campos JSON pueden ser tool / name / toolName, consulte la documentación del cliente que utilice.

Obtener catálogo de herramientas

{
  "tool": "tools_catalog",
  "arguments": {}
}

Mercado: Últimas 60 velas diarias

{
  "tool": "market_get_kline",
  "arguments": {
    "stock_list": ["600519.SH"],
    "period": "1d",
    "count": 60,
    "dividend_type": "none"
  }
}

Información bursátil: Información extendida

{
  "tool": "stock_get_more_info",
  "arguments": {
    "stock_code": "600519.SH"
  }
}

Sectores: Acciones constituyentes

{
  "tool": "sector_stocks",
  "arguments": {
    "block_code": "BK0475",
    "block_type": 0,
    "list_type": 0
  }
}

Finanzas: Por período de informe

{
  "tool": "financial_get_report_by_date",
  "arguments": {
    "stock_list": ["600519.SH"],
    "year": 2024,
    "mmdd": 1231
  }
}

Trading: Vista previa de orden (dry-run, por defecto)

Para realizar una orden real, debe establecer dry_run en false y asumir los riesgos por su cuenta; account_id generalmente se obtiene mediante trade_get_account_id.

{
  "tool": "trade_order_stock",
  "arguments": {
    "account_id": 1001,
    "stock_code": "600519.SH",
    "order_type": 0,
    "order_volume": 100,
    "price_type": 0,
    "price": 1500.0,
    "dry_run": true
  }
}

Herramientas: Ejecutar fórmulas de TdxQuant

La entrada principal es utility_formula_run; también existe el alias formula_run, con el mismo comportamiento.

{
  "tool": "utility_formula_run",
  "arguments": {
    "formula_name": "KDJ",
    "formula_arg": "9,3,3",
    "mode": "zb"
  }
}

Pruebas

Pruebas unitarias (sin conexión al cliente)

uv run pytest tests/ -q

Cuando no se configuran las variables de entorno para la integración, los casos de integración se omitirán, ejecutando solo pruebas unitarias de parámetros, directorios, etc.

Pruebas de integración (requiere haber iniciado sesión en TdxQuant)

CMD:

set TDX_INTEGRATION=1
set TDX_STRICT_DATA=1
uv run pytest tests/test_tools_integration_tdxdata.py -m integration

PowerShell:

$env:TDX_INTEGRATION = "1"
$env:TDX_STRICT_DATA = "1"
uv run pytest tests/test_tools_integration_tdxdata.py -m integration

• TDX_STRICT_DATA: Opcional, falla si los datos están vacíos (por defecto permite dict vacío para facilitar la resolución de problemas de conexión).

• TDX_TRADE_ACCOUNT: Opcional, cadena de cuenta para llamadas de integración de trading.

Ejemplo de script (no MCP)

tdxdata_test.py demuestra la llamada directa a tqcenter.tq, utilizada para comparar el comportamiento de la interfaz; es independiente del proceso MCP.

Solución de problemas

Licencia y upstream

El comportamiento y el formato de los datos se basan en TdxQuant / 通达信 y tqcenter.py; este repositorio es solo para encapsulación MCP y organización de documentación.