行情数据接入 MCP：Claude Code / Cursor 工具描述怎么写才不踩坑

摘要

在 Claude Code、Cursor 等 AI 编码环境中通过 MCP 接入行情数据时，决定调用准确率的关键因素之一是工具描述和参数 schema 的质量 。描述模糊、参数缺少约束、错误码未暴露，模型就容易选错工具或填入无效参数。本文以 TickDB 的 MCP 行情工具为设计参照，拆解 description、inputSchema 的编写原则，给出 MCP/REST/CLI 命名空间对照、好坏描述对比及发布前自检清单。配置片段仅供思路参考，部署前请以当前官方文档为准。

正文

1. 一个越来越常见的场景

你在 Claude Code 里说：

"帮我查一下贵州茅台和宁德时代的最新价，判断哪一个今天涨跌幅更大。"

模型开始思考，调用了一个叫 get_current_price 的工具，参数填了 symbols=["茅台", "300750"]。结果一个无效，一个只返回了最新价却没有涨跌幅字段，模型又调了一次，来回三次才勉强拿到数据。

问题出在哪儿？不是 MCP 传输层有问题，也不是行情接口挂了，而是工具描述没有教会模型"怎么正确使用这个工具"。

本文聚焦被很多人忽略的一环：为行情工具编写高质量的 description 和参数 schema。安装步骤一笔带过，重心放在"描述什么、怎么描述、模型才会对"。

2. 先厘清命名空间：MCP / REST / CLI 各司其职

在 AI 编码环境中获取行情数据，有三条常见路径。混用概念会让模型选择错误的入口。

路径	典型形式	在 Claude Code / Cursor 中的位置	适用场景
MCP 工具	JSON-RPC 工具调用，由 MCP Server 暴露	模型自动发现并调用，无需手写 HTTP	对话式查询、多步推理中的行情获取
REST API	`requests.get()` 代码执行	模型在沙箱/终端中执行 Python	脚本化批量拉取、离线回测
CLI 命令	终端中执行 `curl` 或自定义 CLI	模型通过终端工具执行	临时查询、管道处理
统一接入层	同一数据源同时提供 MCP / REST 双入口	MCP 工具 + 代码执行均可	对话中查行情，脚本中跑回测，字段名保持一致

关键区分：MCP 工具调用不等于 REST 封装。MCP Server 内部可能对接 REST，但模型眼中它是一个带有明确 contract 的函数签名------只关心参数和返回值结构，不关心底层是 HTTP 还是 WebSocket。当 MCP 工具和 REST 脚本背后是同一数据源时，symbol 格式、字段名的统一会降低模型在两种模式间切换的出错率。

四类 MCP 行情工具的边界 ：设计工具描述前，先要明确不同工具各自能做什么。以 TickDB 的 MCP 服务（端点 https://mcp.tickdb.ai/）为例，其行情工具分为四类，每类有严格的适用边界：

工具名	用途	不适用场景
`get_ticker`	查询实时行情快照，返回最新价、涨跌幅、成交量等	历史 K 线、盘口深度、成交明细
`get_kline`	查询历史 K 线数据	实时快照、盘口、成交明细
`get_order_book`	查询盘口 bids/asks	快照、K 线、成交明细
`get_recent_trades`	查询最近成交序列	快照、K 线、盘口深度

工具描述必须让模型能区分这四类工具。如果 get_ticker 的描述写得含糊，模型可能用它去查历史数据，反复调用直到超限。TickDB 的 get_ticker、get_kline 等工具已在统一代码仓 https://github.com/TickDB/tickdb-unified-realtime-marketdata-api 中提供 schema 定义，设计自己的 MCP 工具时可作为字段命名的参照。

3. 工具描述是重要防线

模型选择工具并调用的流程：

读取工具列表（含 name、description、inputSchema）
根据用户意图匹配工具
按照 inputSchema 的约束生成参数
调用工具，解析返回，决定下一步

description 和 inputSchema 是影响第 2、3 步准确率的重要因素，但不能保证模型一定选对。 模型的工具选择还受上下文、用户措辞、温度参数等多重变量影响。但一份精确的描述能显著降低选错和填错参数的概率。描述不够精确的常见后果：模型选错工具、填入非法参数、对返回字段产生幻觉。

坏 description / schema	后果	好 description / schema（示意写法，发布前按官方文档复核）
"获取股票行情数据"	模型不知道是快照还是历史，选错工具	"获取指定品种的实时行情快照，返回最新价、涨跌幅、成交量等。不支持历史 K 线，历史数据请用 `get_kline`。"
`symbols` 参数无格式示例	模型传入 `"茅台"` 或 `"600519"` 等无效值	`symbols` 描述中注明"每项格式为 `CODE.EXCHANGE`，示例：`600519.SH`、`AAPL.US`"
不声明错误码	模型收到错误后无法自我修正，反复重试	在返回结构中列出 `code` 含义：`0` 成功、`3001` 限流需读 `Retry-After`、`1001` 鉴权失败
价格字段无类型提示	模型用 float 直接计算，精度丢失	描述中标注"`last_price` 为字符串，调用方需用 Decimal 处理"

核心原则：描述要明确"能做什么"和"不能做什么"。否定边界比泛泛的功能列表更有价值。

4. 参数 schema 的四个设计要点

inputSchema 使用 JSON Schema 格式。以下四个要点对行情工具尤其关键：

① 枚举优于自由文本

参数只有少数合法值时，用 enum 约束。

json 复制代码

"market": {
  "type": "string",
  "enum": ["A", "HK", "US"],
  "description": "市场代码：A 股为 A，港股为 HK，美股为 US"
}

示意写法，enum 取值以官方文档为准，发布前复核。

② 示例值放在描述里

并非所有 MCP Client 都支持解析 examples 字段，最稳妥的做法是把示例直接写入 description。

json 复制代码

"symbols": {
  "type": "string",
  "description": "品种代码列表，逗号分隔，格式为 CODE.EXCHANGE。示例：600519.SH,300750.SZ,700.HK,AAPL.US。数量上限以接口文档为准。"
}

示意写法，参数类型和数量上限以官方文档为准，发布前复核。

③ 返回结构要在描述中预告

模型拿到返回结果前对数据结构一无所知。在工具描述中预告关键字段及其含义，能明显提升模型解读结果的准确率。

示例描述片段：

"返回 data 数组，每项含 symbol、last_price（字符串，建议用 Decimal 处理）、timestamp（时间戳，具体精度以接口文档为准）等字段。"

④ 错误路径要提前约定

不要让模型从错误中自行归纳。描述中给出错误码含义和处理建议，模型遇到 3001 时知道等待而非连续重试。

5. 一个设计参照：TickDB 的 MCP 行情工具

以下不是完整可运行的配置文件，而是一份设计思路的参照，展示工具描述和参数 schema 可以到达的精确程度。

工具定义概览（示意写法，以官方文档和实测为准）：

name：get_ticker
description：
"获取指定品种的实时行情快照。返回最新价、涨跌幅、成交量、最高/最低价等字段。仅限单次查询，不支持历史 K 线。交易时段和返回数据情况以各市场实际交易时间为准。"

参数 schema 要点：

symbols：品种代码列表，格式 CODE.EXCHANGE，示例 ["600519.SH","300750.SZ"]。分隔方式和数量限制以接口文档为准。
无 interval、start_date 等 K 线参数------向模型明确这是快照接口。

返回结构描述要点：

顶层 code（0 成功）、data 数组
data[].last_price：字符串，调用方需转为高精度数值
data[].timestamp：时间戳，具体精度以接口文档为准
错误码：1001 Key 无效，3001 限流需读 Retry-After

⚠️ 以上字段和参数以 TickDB 当前 MCP 文档及代码仓 https://github.com/TickDB/tickdb-unified-realtime-marketdata-api 为准，发布前请用 MCP 工具实测复核。不同数据源的字段名和错误码体系存在差异，设计自己的工具时不要直接照搬。

TickDB 的设计思路是把 REST 层的字段命名与 MCP 工具的 schema 保持统一------这让开发者在对话和脚本两种模式间切换时，同一套 symbol 格式和字段名可以复用。对 Claude Code 用户来说，工具描述中约定的 symbol 格式和 last_price 类型提示，无论模型走 MCP 调用还是生成 REST 代码，都能保持一致。MCP 接入细节见 docs.tickdb.ai。

📡 本文行情数据及 MCP 工具示例由 TickDB.ai 提供

⚠️ 本文为技术教程，不构成任何投资建议

互动：你在 Claude Code 或 Cursor 中接入 MCP 工具时，遇到过因为描述不清晰导致模型反复调用失败的情况吗？你是怎么排查出是 schema 的问题的？欢迎分享你的调试过程。

标签

Claude Code、Cursor、MCP、行情数据接入、TickDB、Python

参考文档

https://docs.tickdb.ai（MCP 工具描述与字段文档）
https://mcp.tickdb.ai/（TickDB MCP 端点）
https://github.com/TickDB/tickdb-unified-realtime-marketdata-api（统一代码仓）