gangtise-mcp

基于 Gangtise OpenAPI 的 MCP（Model Context Protocol）服务，让 Workbuddy, OpenClaw, Hermes, Cherry Studio, Cursor, Claude, Codex 等 AI 助手直接访问 Gangtise 投研平台数据。

Changelog

0.1.42 (2026-07-06)

• 质量护栏与内部重构（无对外行为变化，除并发负值修正）：

  • 新增 spec↔ENDPOINTS 交叉校验测试——遍历所有 spec 驱动工具，钉住每个 endpointKey 存在于 ENDPOINTS、json/download 种类匹配、paginated 与端点 pagination.enabled 双向一致、工具名唯一且 gangtise_ 前缀；另一条 spec-liveness 测试启动整个 server 断言每个 spec 都真实注册（自适应，取代集成测试里需手工维护的工具名单）。挡住跟 gangtise-openapi-cli 同步时易引入的 endpoint/参数错配类 bug

  • GANGTISE_PAGE_CONCURRENCY 收口到 config.ts——原先 client.ts（分页扇出）与 quoteSharding.ts（分片扇出）各自在模块加载期读一次 env，现统一为 config.ts 的 PAGE_CONCURRENCY（经可测的 resolvePageConcurrency，与 INLINE_MAX_BYTES 同款）；顺带修掉旧 Number(x)||5 放行负数并发的潜在 bug（0/负/NaN 回退默认、小数向下取整）

  • gangtise_fund_flow 市场校验复用 assertMarketMatch——去掉内联重复的后缀→市场检查（assertMarketMatch 加可选 sentinel/message），保留其「资金流向仅支持 A 股」专属提示与 aShares 哨兵

  • gangtise_read_response 分页提示文案修正——_note 里过期的「256KB」改为动态引用实际 INLINE_MAX_BYTES（0.1.40 起默认 64KB、可 env 覆盖）

  • 删除 gangtise_security_clue_list / gangtise_hot_topic spec 里冗余的 from 字段（分页工具的 from/size/fetchAll 由注册器统一注入）

• 测试 265 → 272

0.1.41 (2026-07-06)

• 同步 gangtise-openapi-cli v0.23：

  • 默认 API 域名迁移 open.gangtise.com → openapi.gangtise.com（新旧域名多接口实测等价、旧域名仍可用；固定旧域名设 GANGTISE_BASE_URL=https://open.gangtise.com）

  • 新增 gangtise_fund_flow（A 股个股日资金流向，沪深北）——含小/中/大/特大单流入流出金额及占比、主力净流入等字段；免费。security 传单/多只代码（仅 A 股沪深北，传港/美股代码本地即报错，不静默返空），或 'aShares' 配合 startDate/endDate 拉全市场（自动按 1 天/片分片合并，缺日期本地报错）

  • 新增 gangtise_institution_search（机构 ID 搜索）——按机构名/简称返回 institutionId 及 usageScopes（标明用于哪个接口的哪个参数），覆盖内资券商/外资/牵头/观点/外资观点机构，供各 list 工具 institutionList/brokerList 等参数使用；免费

  • gangtise_my_conference_list 新增 sourceList——按录制来源筛选（1=企微会议助理 | 2=会议服务微信群，可多选）

  • gangtise_wechat_chatroom_list 适配服务端改版——上游改返 {total, list}（原 chatRoomList 且无 total），改为标准分页端点按 total 并发翻页（旧的 chatRoomList 串行翻页对新结构会漏读）；省略 size 拉全部群、传 size 取前 N 条，roomName 多值仍以逗号拼接为标量下发

  • 行情截断防静默——无翻页行情端点（gangtise_fund_flow / gangtise_minute_kline / 显式多标的日 K〔A/港/美〕/ 指数日 K）单次请求返回行数达到 limit（默认 6000 / 上限 10000）时标 _partial（limit_truncated）；默认 limit=6000 现显式写入请求体，令截断判定不受服务端默认值漂移影响（分钟 K limit 描述笔误 5000→6000 一并修正）。security='all' 全市场分片路径同样在分片失败或单片撞行数上限时标 _partial（failed_shards / limit_truncated），不再只标失败。混用 'all'/'aShares' 与具体代码本地即报错（避免落到无 limit 注入/不标截断的裸请求）

• 对齐 CLI v0.23 源码：清理 normalize.ts 已失效的 chatRoomList 分支（服务端改返 list）；各 list 工具的 broker/institution ID 参数描述改为优先引导 gangtise_institution_search，并按接口标注对应机构分类（内资研报=domesticBroker / 外资研报=foreignInstitution / 内资观点=opinionInstitution / 外资观点=foreignOpinionInstitution / 纪要·路演·调研·策略=leadInstitution），模型可直接带 categoryList 精确搜；本地静态表仅作全量枚举兜底

• 测试 250 → 265

0.1.40 (2026-07-05)

• 对抗式审查 batch 3 收尾（健壮性 / 参数一致性 / 描述路由 / 工具注解，逐条单独核实）：

  • 健壮性修复（3 个真行为 bug）：

    • token 缓存写失败不再连累当前请求（#35）——token 已在内存中有效、落盘仅是跨进程缓存优化；此前只读 home / ENOSPC 写盘抛错会让触发刷新的在途请求（及并发等待者）一起失败，现在吞掉写错误（verbose 记日志）、请求照常返回数据

    • 超大截断预览收缩为样本而非清空（#33）——20 行预览本身超内联预算时（大行如公告全文），此前整份 list 被丢、模型拿到零示例行无从得知字段；现在样本逐级减半（20→10→5→2→1）直到装下、保留几行真数据，单行都装不下才退回 metadata-only 并以 _first_item_keys 暴露首行字段名（落盘文件不变，has_more/next_offset 指向样本之后供续读）

    • async _check 终态失败带出原因（#36）——410111（失败）分支此前只返回 {status,dataId} 丢了 reason，模型无从判断为何失败或是否该重提；现补 error（错误码 + 可操作提示），与 submit 路径一致

  • K 线/实时字段参数统一为 fieldList（#32）：quote 工具原用 field，而 13 个基本面工具及上游 body key 都用 fieldList；zod v3 strip 静默丢弃未知 key，习惯性给 K 线/实时工具传 fieldList 会被无声丢弃、拿回未过滤全字段数据。跨 commonKlineSchema / 分钟线 / 实时 / buildKlineBody / 美股默认字段回退统一改名，不设别名（两个同义词只会误导模型）

  • 内联阈值可配置，默认 256KB → 64KB（#16）：INLINE_MAX_BYTES 原在 registry.ts + response.ts 硬编码两处，统一到 config.ts 单一来源、env 可覆盖 GANGTISE_INLINE_MAX_BYTES（下限 8KB）。降到 64KB（约 15-20K token）——单个结果落入客户端典型显示预算内，且落盘结果总留可分页预览指针，64-256KB 响应从「整块 dump 无分页退路」变为可经 gangtise_read_response 续读（批量导出会话可调高）

  • 工具描述 / 路由指引：

    • 重叠工具补「何时用我 vs 另一个」路由指引（#28）——gangtise_knowledge_batch / gangtise_edb_search / gangtise_indicator_search（语义搜索 vs 结构化 *_list；EDB 宏观/行业 vs EDE 证券级）

    • async submit describe 警告任务计费且非幂等（用返回的 dataId 配 *_check、勿重提），_check describe 说明 dataId 来源及 pending=继续轮询（#29）

    • gangtise_securities_search category z.string()→z.enum（stock/dr/index/fund）非法值边界拒绝、不再静默 no-op；补 research_list rankType（1=综合默认 | 2=时间倒序）、top gains .max(10) 等 X5 schema 收紧漏网 describe（#30/#31）

  • 全工具声明 openWorldHint: false（#37）：每个工具只触达单一封闭域 API（Gangtise）或纯本地数据、从不触达开放世界，MCP 把缺失的 openWorldHint 当 true，故 26 个工具注解全部显式置 false（async submit 保持 readOnlyHint:false，其余 readOnlyHint:true），集成测试钉住该不变式

• 测试 246 → 250

0.1.39 (2026-07-03)

• 对抗式审查后续（性能 / 健壮性 / 可用性，逐条单独核实实现）：

  • 响应 JSON 改紧凑序列化：去掉模型可见输出与落盘文件的 2 空格缩进——实测日 K 载荷 -38% 字节（59KB→36.8KB），纯 token 节省；256KB 内联阈值 / 落盘 / gangtise_read_response 分页字节预算全部按紧凑字节统一度量，更多数据得以内联、减少续读往返（context.ts 小日期载荷与 auth.ts 令牌缓存保留原格式）

  • 异步 AI 默认等待 180s→55s：原 180s 超过 MCP 客户端约 60s 请求超时，客户端在服务端返回 {dataId, status:"timeout"} 前即断开，计费任务的 dataId 丢失、无从 *_check 续查；55s 让超时响应及时返回。GANGTISE_MCP_ASYNC_TIMEOUT_MS 语义不变（可调高，或按调用传 waitSeconds 最大 180）

  • K 线市场/工具错配预校验：.HK/.O 代码传给 A 股 gangtise_day_kline（或 A 股代码传 _hk/_us）此前打到上游返回静默空列表、与「区间无数据」难辨；现在明显跨市场错配在请求前抛错并点名正确工具、不花 API（跳过 security:'all' 与未知后缀防误伤；指数 / 分钟 / 实时接口不校验）

  • 429 限流退避尊重 Retry-After：429 此前与 5xx 共用 400ms/4s 退避且丢弃 Retry-After 头（狂敲已限流的接口）；现 429 走更狠的 2s 基 / 15s 顶退避，服务端 Retry-After（429 或 503）更长时采纳并封顶 15s（防超大/恶意值卡死），JSON 与下载两条请求路径均覆盖；5xx / 网络退避逐字节不变，重试次数仍为 2

• 测试 234 → 246

0.1.38 (2026-07-03)

• 对抗式审查（6 维度并行 + 逐条对抗核实）后的工具描述 / schema 收紧：

  • 枚举收紧防静默 no-op：gangtise_summary_list 会议纪要类别修正为实测有效的 9 值集（删无效的 expertInterview/fieldResearch/industryConference——上游对未知值静默忽略过滤、返回全量 17 万条）；gangtise_research_list / gangtise_foreign_report_list 修正 quantitative→quant 并补齐 15 值集；连同 fundamental / ai / vault / indicator 共 18 组闭集参数（报告期、报表类型、拆分、股东类型、估值指标、查询模式、管理层讨论维度、内容类型、币种、量纲、日历类型等）从宽松 string 收紧为 z.enum——非法值在 MCP schema 层即拒绝，不再打到上游得静默 no-op 或不透明错误（取值全部对 CLI 文档闭集核实）

  • 错误可诊断：未知上游错误码始终带出「（错误码 X）」，补 999994（vault 权限/配额）、0000001008（令牌失效/被顶号）提示；下载失败带 HTTP 状态码 + 响应体片段（区分 404 失效 ID / 403 权限）

  • 选对工具/参数：server instructions 补证券代码后缀约定（.SH/.SZ/.BJ=A股 / .HK=港股 / .O/.N/.A=美股）与「只知名称先 gangtise_securities_search」；4 个日程工具与会议纪要工具双向消歧；补港/美股 securityCode 格式示例、港股/指数 K 线 'all' 全市场能力、period 标注修正（h2=下半年报，原误标年报）、conceptList/institutionList/brokerList ID 来源、外资研报评级枚举、hot_topic 布尔参数、分页 from/size/fetchAll 说明

  • 空结果 / 续读：空列表结果附 _hint 区分「真无数据」与「参数不匹配」（漏交易所后缀等）；截断预览补 next_offset 对齐 gangtise_read_response 续读契约，不再重复拉取预览项

  • gangtise_earnings_review 的 period 加正则校验（计费且不可重试的提交，防畸形格式白扣一次费）

• 测试 227 → 234

0.1.37 (2026-07-02)

• Schema 全面收紧（原审查搁置项 X5）：畸形日期/时间在本地 schema 层快速失败，不再透传给上游被静默改写（JS Date 会把 2026-02-30 滚成 2026-03-02）或返回不透明错误

  • dateString（YYYY-MM-DD + 日历 round-trip 校验，原 quote.ts 私有实现）与新增 dateTimeString（YYYY-MM-DD HH:mm:ss，时分秒范围 + 日历校验）、quarterEndDate（季末报告期）提取至 dateContext.ts 统一导出

  • 覆盖全部日期/时间参数：fundamental（三大报表 startDate/endDate）、alternative（EDB）、indicator（截面 date / 时序 startDate/endDate）、insight（日程类 4 组 startTime/endTime）、vault（云盘/录音/会议/微信 4 组 startTime/endTime）、ai（线索 startTime/endTime、热点 startDate/endDate、主题跟踪 date、管理层讨论 reportDate——后者按接口限定 中报/年报 或 四季末）、quote（分钟线 startTime/endTime）

  • gangtise_stock_pool_stocks 的 poolIdList 拒绝空数组（实测上游对 [] 返回空列表而非文档承诺的"所有池"默认值，静默错答案）——查所有池请省略该参数

• 测试 210 → 227（schema 边界单元测试 + 工具级拒绝/通过用例；已对真实 API 冒烟验证合法值不受影响）

0.1.36 (2026-07-02)

• 对抗式审查第三批（工程加固）+ 补测试时发现的真 bug：

  • 修复 indicator（EDE）内层失败信封漏判：失败信封不带 data 键（{code,status:false,msg}）时，unwrapIndicatorData 因判定条件要求 data 存在而原样放行，三个 indicator 工具把权限/配额错误当"成功数据"返回。现按 code/status 判定失败（补齐信封证据守卫防误伤）。注：同门 CLI 同款实现有同样问题，待同步

  • 全市场 K 线分片合并后 total 重算为合并行数，不再泄漏第一个分片的 total（此前 total=单日行数 + 全量 list，误导完整性判断）

  • token 缓存目录以 0700 创建（对齐文件 0600 策略；此前按 umask 落成 755，同机其他用户可列目录）

• CI/发布链加固：

  • ci.yml 增加 permissions: contents: read（此前默认 token 权限暴露给依赖安装脚本）+ npm audit --omit=dev 步骤（CI 走官方 registry，本地 npmmirror 无法 audit）

  • 两个 workflow 的 actions/checkout、actions/setup-node pin 到 commit SHA；npm ci --ignore-scripts（发布 job 持有 OIDC id-token，不给依赖生命周期脚本执行机会）

  • 移除 workflow_dispatch 触发器——手动触发会跳过 tag↔版本一致性校验、从分支直接发版

• 测试补盲区（210 个）：token 刷新 single-flight 并发去重、gangtise_read_response 拒绝他进程创建的同前缀目录（钉住 0.1.28 的进程隔离语义）、港股 2 天/片分片边界（无重叠无缺日+尾片截断）、indicator 内层失败信封 → isError（上述真 bug 即由此测试暴露）

• README 修正：大响应章节改为真实路径与 gangtise_read_response 续读指引（此前写 /tmp/... 且教直接读文件，无文件能力的客户端走不通）、字段表补 _read_with、前置要求改 Node ≥ 20.18.1（对齐 engines）

Related MCP server: financial-research-agent

功能覆盖

前置要求

• Node.js ≥ 20.18.1（undici 7.27+ 的要求，见 package.json#engines）

• Gangtise 开放平台账号（申请地址），获取 accessKey / secretKey

快速开始

Claude Code

claude mcp add gangtise \
  -e GANGTISE_ACCESS_KEY=your_access_key \
  -e GANGTISE_SECRET_KEY=your_secret_key \
  -- npx -y gangtise-mcp@latest

Claude Desktop

编辑配置文件（根据系统选择路径）：

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json

• Windows：%APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "gangtise": {
      "command": "npx",
      "args": ["-y", "gangtise-mcp@latest"],
      "env": {
        "GANGTISE_ACCESS_KEY": "your_access_key",
        "GANGTISE_SECRET_KEY": "your_secret_key"
      }
    }
  }
}

修改后重启 Claude Desktop 生效。

Cursor

编辑 ~/.cursor/mcp.json（全局）或项目根目录下 .cursor/mcp.json：

{
  "mcpServers": {
    "gangtise": {
      "command": "npx",
      "args": ["-y", "gangtise-mcp@latest"],
      "env": {
        "GANGTISE_ACCESS_KEY": "your_access_key",
        "GANGTISE_SECRET_KEY": "your_secret_key"
      }
    }
  }
}

Windsurf

编辑 ~/.codeium/windsurf/mcp_config.json：

{
  "mcpServers": {
    "gangtise": {
      "command": "npx",
      "args": ["-y", "gangtise-mcp@latest"],
      "env": {
        "GANGTISE_ACCESS_KEY": "your_access_key",
        "GANGTISE_SECRET_KEY": "your_secret_key"
      }
    }
  }
}

Cline（VS Code 插件）

打开 VS Code → Cline 插件面板 → MCP Servers → Edit MCP Settings，加入：

{
  "gangtise": {
    "command": "npx",
    "args": ["-y", "gangtise-mcp@latest"],
    "env": {
      "GANGTISE_ACCESS_KEY": "your_access_key",
      "GANGTISE_SECRET_KEY": "your_secret_key"
    }
  }
}

其他支持 MCP 的客户端

配置格式通用，只需在对应客户端的 MCP 配置文件中加入：

{
  "command": "npx",
  "args": ["-y", "gangtise-mcp@latest"],
  "env": {
    "GANGTISE_ACCESS_KEY": "your_access_key",
    "GANGTISE_SECRET_KEY": "your_secret_key"
  }
}

升级到最新版本

npx -y gangtise-mcp 不会每次都去 registry 拉最新版——npx 会把已下载的版本缓存到 ~/.npm/_npx/<hash>/ 下，后续启动直接复用。npm 发布了新版本但客户端工具列表没出现新工具时，多半就是这个原因。

任选其一：

方法 1：配置里钉版本（推荐） —— 把 args 改成 ["-y", "gangtise-mcp@latest"] 或具体版本 ["-y", "gangtise-mcp@0.x.x"]，重启 MCP 客户端即可强制拉新。

方法 2：清 npx 缓存

# macOS / Linux
rm -rf ~/.npm/_npx
# Windows (PowerShell)
Remove-Item -Recurse -Force $env:LOCALAPPDATA\npm-cache\_npx

清完缓存后，在 MCP 客户端里关掉再打开 gangtise 服务（或重启客户端），npx 会重新下载最新版。

怎么确认当前跑的是哪个版本？查 ~/.npm/_npx/*/node_modules/gangtise-mcp/package.json 的 version 字段。

环境变量

认证优先级：GANGTISE_TOKEN > Token 缓存文件 > GANGTISE_ACCESS_KEY + GANGTISE_SECRET_KEY（自动换取并缓存 Token）。

大响应处理

当单次工具调用返回超过 256 KB 时，完整数据会写入系统临时目录下的 gangtise-mcp-* 目录（macOS 实际在 /var/folders/.../T/ 下；JSON 数据为 response.json，文本类为 response.md），MCP 响应改为内联返回前 20 条预览及元数据：

续读完整数据请调用 gangtise_read_response 工具（传 _saved_to 路径，按 offset/limit 分页；单页同样受 256KB 字节预算约束）——不要依赖客户端直接读文件，Claude Desktop 等无文件读取能力的客户端只能走该工具。若单条内容过大导致 20 条预览本身也超过阈值，则只返回元数据，_preview_count 为 0（此时 has_more: true 表示数据全部在文件中）。

开发

git clone https://github.com/gangtiser/gangtise-mcp
cd gangtise-mcp
npm install
npm run dev      # 直接运行源码（tsx，无需 build）
npm run build    # 编译 TypeScript → dist/
npm test         # 运行测试

发布维护

本包默认通过 GitHub Actions + npm Trusted Publisher 发布，不在本地执行 npm publish，也不需要长期 npm token。发布前确保 npm 包设置已信任本仓库的 .github/workflows/npm-publish.yml workflow；该 workflow 已配置 permissions: id-token: write，推送 v* tag 后会通过 OIDC 发布到 npm。

标准流程：

npm version patch --no-git-tag-version
# 更新 README Changelog，并完成代码/测试修改
npm test
npx tsc --noEmit
npm run build
git add .
git commit -m "fix: <message>"
git push origin main
git tag v0.1.x
git push origin v0.1.x

发布完成后确认：

gh run list --workflow npm-publish.yml --limit 1
npm view gangtise-mcp version

如果 GitHub Actions 的 publish 步骤提示 OIDC/trusted publisher 失败，应先检查 npm 包的 Publishing access 设置是否绑定到 gangtiser/gangtise-mcp 和 .github/workflows/npm-publish.yml，不要改回本地 token 发布。

License

MIT