文档 / MCP

MCP

MCP Server 是开放 REST API 的薄封装：stdio 传输、三个工具、与 REST 共用同一把 Key 与订阅额度，不直连后端、不复制检索逻辑。实现目录 mcp/（Node ≥ 20 + 官方 @modelcontextprotocol/sdk）。

当前发布状态：npm 包 @tmglobal/mcp 尚未发布（Q3 待确认）。本阶段请在客户端用本地 node 路径启动；npx -y @tmglobal/mcp 仅在发布后可用，现在配置了会失败。

环境变量

变量	必填	说明
`TM_KEY`	是	开放平台 Key；缺失时进程启动即退出（exit 2），不会静默匿名调用
`TM_BASE_URL`	否	默认 `http://127.0.0.1:8000`；https 任意，http 仅本机（防明文泄 Key）
`TM_TIMEOUT_SEARCH_MS` / `_DETAIL_MS` / `_IMAGE_MS`	否	分工具超时：默认 30000 / 10000 / 120000
`TM_MAX_RETRIES`	否	可重试错误的最大重试次数（默认 2）

客户端配置（本地未发布阶段）

jsonclaude_desktop_config.json

{
  "mcpServers": {
    "tm-global": {
      "command": "node",
      "args": ["/Volumes/ZT/PycharmProjects/sdm-tm/TMOnline/mcp/src/index.js"],
      "env": {
        "TM_KEY": "<YOUR_TM_KEY>",
        "TM_BASE_URL": "http://127.0.0.1:8000"
      }
    }
  }
}

Claude Code：claude mcp add tm-global --env TM_KEY="$TM_KEY" --env TM_BASE_URL="http://127.0.0.1:8000" -- node /abs/path/mcp/src/index.js；Cursor/Cline/Zed 用同一 JSON 结构。

工具

工具	对应端点	默认超时	说明
`search_trademark`	POST /api/trademark/search	30s	文字检索：17 种模式、局/分类/状态过滤、分页排序；mark 必填（空值本地拒绝，不做 match-all）
`get_trademark_detail`	GET /api/trademark/data/detail	10s	著录详情：需 `appNum` + `ipOffice`（来自检索结果）；部分局未开放详情（10035）
`image_similarity`	POST /api/image/search	120s	图形近似：`image_url`（白名单图床）或 `image_base64`（≤3MB）；当前仅 AU 索引

结果口径（重要）

totalHits：近似模式为上限（smart 等 10000、contains/match/phrase 1000），MCP 输出 totalsAreCapped 与 totalHitsNote；精确计数请用 mode=exact。
score：文字检索为后端相关性原始分（scoreKind=backend_relevance），不是 0–100 相似度；图搜为 0–1 融合分（scoreKind=image_similarity_0_1）。
官方链接：officialPage（上游字段 officalPage 的修正名）；appDateISO 为 ISO 日期。
体积保护：单次结果 ≤96KB，超出会截断并标注 resultTruncated。

错误映射

工具执行错误返回 isError:true + 结构化 JSON：{error:{code, retryable, upstreamCode, httpStatus, hint, details}}；仅 schema/参数结构错误使用 JSON-RPC -32602。

上游	MCP code	retryable
10006	`PAGINATION_OUT_OF_RANGE`	否
10007 / 10010 / 400	`INVALID_ARGUMENT`	否
410	`NOT_FOUND`	否
10035	`DETAIL_NOT_SUPPORTED`	否
10005 / 500 / 5xx	`UPSTREAM_ERROR`	是（退避）
网络错误	`UPSTREAM_UNAVAILABLE`	是
超时	`UPSTREAM_TIMEOUT`	是
图搜 400 无法识别 / 413 / 502–504	`IMAGE_UNRECOGNIZED` / `IMAGE_TOO_LARGE` / `IMAGE_SERVICE_UNAVAILABLE`	否 / 否 / 是

客户端

Claude Desktop · Claude Code · Cursor · Cline · Zed · 任意支持 stdio 的 MCP 客户端。

自检：客户端重启后 tools/list 应返回 3 个工具（名称精确）；search_trademark {"mark":"HUAWEI","size":3} 返回 ok:true；缺 TM_KEY 时客户端显示 server failed（stderr 含 startup_failed），而不是静默空结果。计费口径（商业服务实测）：search 20 credits / detail 2 / image_search 200（订阅配额以定价页为准，Q2 待确认）。

← REST API 鉴权与 Key →