# gangtise-mcp

基于 [Gangtise OpenAPI](https://open.gangtise.com) 的 MCP（Model Context Protocol）服务，让 Workbuddy, OpenClaw, Hermes, Cherry Studio, Cursor, Claude, Codex 等 AI 助手直接访问 Gangtise 投研平台数据。

## Changelog

README 仅列最近 5 个版本的一行摘要，完整明细见 [CHANGELOG.md](CHANGELOG.md)：

- **0.3.4 — 2026-10-07**：`gangtise_drive_manage` 新增 `copy_folder`，跨空间（我的云盘 ↔ 租户云盘）复制整个文件夹，连同子文件夹与文件。下载文件名优先用 UTF-8 文件名；`GANGTISE_BASE_URL` 用明文 http 指向非本机地址时在 stderr 提示一次。说明更正：债券公告按日期查询时有代码的行都带后缀、部分行代码为空；债券行情 / 估值的数据起点可能晚于账号窗口，取长序列时核对首行日期；场内基金按 6 位代码或场内简称换代码；分钟 K 的可查历史是随日期滚动的短窗口。依赖 `@modelcontextprotocol/sdk` 升至 1.32.1（安全更新）。
- **0.3.3 — 2026-09-30**：新增公募基金 18 个工具（组名 `fund`，默认列出；0.4 积分/次，代码查不到返回空、不报错）：资料、费率、经理、净值、规模、持有人、资产配置与持仓、ETF 申赎与份额。`gangtise_earning_forecast` 日期省略时取近一年，区间预估超过积分预估保护须 `confirmCost: true`。资金流多只长区间自动按只分组（此前撞 6000 行上限截断）；多证券日 K / 分钟 K 的重复代码先去重（此前会出重复行）；财报日历日期区间的 `fetchAll` 改由积分预估保护把关；若干参数说明更正。
- **0.3.2 — 2026-09-27**：默认列出全部 96 个工具（`GANGTISE_MCP_TOOLS=core` 为精简的 89 个），云盘管理与上传、文件解析、债券发行明细 / 发行计划 / 行权安排改为默认可见。债券评级超过 10 只自动分批，债券公告支持 `fetchAll`；三个评级接口的积分标签改为 0.4/条、0.4/只、0.4/发行人。观点正文某批返回异常时保留同批已计费的正文；证券级指标漏传 `fiscalYear` 的说明更正为按默认年度取数。
- **0.3.1 — 2026-09-27**：🔴 修正 legacy 港美股日 K 多只长区间、`fieldList` 不含 `securityCode` 时整组丢数据（0.3.0 引入，用 `core,legacy` 的请升级后重查）。新增文件解析（`gangtise_file_parse` / `_check`，点名加载，0.8 积分/页）；显式多证券行情拆出的请求数超过单次调用上限 180 时本地拒绝；估值分析响应不是列表结构时报错。
- **0.3.0 — 2026-09-27**：默认工具面重组，**含破坏性变更，见下方「从 0.2.x 升级」**。三张财报表、公告列表按代码后缀选市场，15 个下载工具合为 `gangtise_download`，被合并的 27 个旧工具进 legacy 档（`GANGTISE_MCP_TOOLS=core,legacy` 可用，0.4.0 删除）。观点、题材默认走低价档（1 积分/条、50 积分/次）；按条计费的多页拉取超过 `GANGTISE_MCP_COST_LIMIT`（默认 1000）须 `confirmCost: true`。新增债券 12 个、会议线索、联网搜索与云盘管理。多证券日 K 按行数上限合批，全市场日 K 须同时给起止日期，多只时 `fieldList` 自动补身份列；行情首行晚于起点时以 `_note` 提示。

### 历史里程碑

- **0.2.11**：新增可选环境变量 `GANGTISE_MCP_TOOLS`（按工具组或工具名选择、禁用工具）与 `GANGTISE_MCP_GLOBAL_CONCURRENCY`（跨调用的在飞请求总数上限）；内部重构，列式行情结果整理与落盘提速约四分之一。
- **0.2.10**：🔴 翻页结果去掉跨页重复行并标 `duplicate_rows` / `changed_rows`；`valuation_analysis` 显式下发 `limit`，撞满标 `limit_truncated`；新增 `gangtise_opinion_detail` 与观点 / 题材的低价档开关。
- **0.2.9**：🔴 并发下载不再被临时目录回收误删；异步生成（`earnings_review` / `viewpoint_debate`）等待到期后不再重发请求，`dataId` 仍可用 `*_check` 取回。
- **0.2.8**：新增 5 个自选股池写工具（删池须显式确认）；🔴 token 缓存改为绑定凭证，换过 `GANGTISE_ACCESS_KEY` 的请复核换号前后取到的数据；`indicator_time_series` 不传 `calendarType` 时按指标类型自动选轴。
- **0.2.6**：修六处静默错数（`valuation_analysis` 的 `skipNull`+`fieldList` 会把正常数据全过滤成 0 行、全市场分片按位置合并可致开收盘价互换等）；行情 `fieldList` 只返回点名的列、缺列标 `missingFields`；`volume` 的单位是「股」不是「手」。
- **0.2.4**：三处静默丢数据（分页空页、首包裸数组、全市场分片缺 `list`）改为归一或显式标记；发布的 `inputSchema` 改为自包含（客户端无需解引用）。输入校验收紧：空白值、空列表、重复 `fieldList`、冲突参数、倒置日期区间改为本地拒绝。
- **0.2.0**：同步 CLI v0.33.0–v0.34.1。🔴 破坏性：日 K 全市场关键字由 `all` 改为 `aShares`/`hkStocks`/`usStocks`（须单独传）；三大报表时点对齐改用 `earliestAnncDate`。
- **0.1.52**：打包与文案表述统一，无取数逻辑或参数契约变更——`dist/` 不再输出源码注释（体积约 −24%）。
- **0.1.51**：修复财报日历日期筛选完全失效（发错字段名，静默返回全库切片而非排期且按条计费）；同步 CLI v0.32.0，新增帕米尔专家纪要工具；`searchType` / `rankType` 收成闭集。
- **0.1.50**：同步 CLI v0.30.0–v0.31.0，适配 EDE 取数契约重构（`universe` 改名、截面矩阵转置、日期下沉到每个指标），修正复权参数名 `adjustType`，新增条件选股工具，整行/整列丢数据标成 `_partial`。
- **0.1.49**：新增财报日历工具，取数护栏改按实际请求行数判定，`fieldList` 收成闭集以拦截静默错列。
- **0.1.48**：修复无效字段名导致的静默错列（数据污染），并把单票总市值路由到 EDE `qte_mkt_cptl`。
- **0.1.46**：取数路由调整，多证券财务/估值批量优先走 EDE 截面/时序接口。
- **0.1.45**：同步 CLI v0.28.0，适配新版错误码三层重排、日期严格校验与 traceId 透出。
- **0.1.44**：`server.instructions` 重写为路由层，建立 92 工具积分目录与自动计费标签，大响应支持字段投影与 `_available_fields`。
- **0.1.36–0.1.43**：计费端点 `no-replay`、429 退避与 `Retry-After`、异步任务截止时间与 `dataId` 保全、紧凑 JSON，以及 OIDC 发布链 verify/publish 拆分。
- **0.1.33–0.1.35**：确立 loud-partial 契约（分页与分片失败均标记 `_partial` 而非静默空洞），token 缓存改原子写并与 CLI 共享自愈。
- **0.1.31–0.1.32**：接入 EDE 证券级数据指标，补齐美股财报与公告、个股看点、首席搜索；全量工具端到端联调。
- **0.1.28–0.1.30**：新增产业公众号资讯，token 服务端失效自愈，CI 加 Node 20/22/24 矩阵与 npm provenance 发布。
- **0.1.24–0.1.27**：日程类工具按 API spec 各自收窄字段，本地静态表迁移到服务端常量/题材/板块接口。
- **0.1.14–0.1.23**：确立大响应截断与 `gangtise_read_response` 续读契约，全工具声明 `readOnlyHint`，日期指引上收到 server instructions。
- **0.1.3–0.1.13**：铺开基础工具面——港美股行情与三大报表、EDB 另类数据、自选股池，并落地全市场 K 线分片与超 256KB 落盘预览。

> 完整更新明细及更早版本见 [CHANGELOG.md](CHANGELOG.md)。

## 功能覆盖

默认列出 114 个工具（`GANGTISE_MCP_TOOLS=core` 为精简的 96 个，见下方「工具分档与选择」）。会改动账号数据的只有自选股池的 5 个与云盘管理、上传；业绩点评、观点辩证与文件解析的提交每次都会新建一个计费任务，也标为非只读；其余全部只读。完整清单与每个参数的语义由 `tools/list` 提供，此处只列范围。

| 类别 | 覆盖 |
|---|---|
| 上下文 | 运行时当前日期、年份、时间与时区（用于换算「今天 / 最近 / 今年」） |
| 检索与 ID 解析 | 证券搜索；行业 / 城市 / 公告分类 / 区域 / 债券与基金分类等常量；题材与板块成分股；首席分析师、机构、公众号 ID |
| 观点与研报 | 国内首席观点与外资观点（可按 ID 取全文）、会议纪要、会议线索（核心要点信息流）、帕米尔专家纪要（独立库，需单独购买）、券商研报、外资研报、独立观点、A/港/美股公告、产业公众号资讯、投资者问答、研报图表；研报、纪要、公告、独立观点、公众号文章与研报图表的原文用 `gangtise_download` 下载，机构观点正文用 `gangtise_opinion_detail` 按 ID 取 |
| 会议日程 | 路演、调研、策略会、论坛（日程；正文走会议纪要） |
| 财报日历 | 业绩预告 / 快报 / 公告的发布排期（含未来已排期）与原文 PDF |
| 行情 | A/港/美股日 K 与实时快照、分钟 K、指数日 K、A 股个股资金流向；日 K / 实时 / 分钟 K 另覆盖沪深 ETF 与 20 个全球指数 |
| 基本面 | A/港/美股三大报表（按代码后缀选市场，A 股可取单季）、主营业务、估值、股东、盈利预测 |
| 债券 | 基本资料、日行情（交易所 + 银行间）、上清所估值、现金流、评级一览与评级变动（超过 10 只自动分批）、公告（可自动翻页）、发行人资料、发行明细、利率债发行计划、行权安排 |
| 公募基金 | 基本资料、费率、基金经理（按姓名）与历任经理、净值（含复权与货币基金收益）、份额与规模、持有人结构、前十大持有人、资产配置、股票 / 债券 / 基金持仓与行业 / 券种 / 基金类型分布、ETF 申赎清单与份额变动 |
| 数据指标（EDE） | 证券级指标搜索；截面与时序（二维矩阵展平为宽表）；条件选股（变量绑指标 + 表达式筛选） |
| 另类数据 | EDB 宏观与行业经济指标；题材指数基本信息与成分股 |
| AI 能力 | 知识库检索、个股看点、一页通、投资逻辑、同业对比、投研线索、主题跟踪、业绩点评、观点辩证、管理层讨论 |
| 联网搜索与文件解析 | 投研定向的公开网页检索（信源分级、转载去重、可取正文）；本机 PDF 解析成 Markdown 正文与图片 |
| 云盘与语音 | 网盘文件与文件夹（含新建 / 改名 / 移动 / 复制 / 删除与上传）、录音转写、我的会议、微信群消息、自选股池（含建池 / 改名 / 加股 / 移除 / 删池） |

## 工具分档与选择

工具分三档：**core**（96 个：股票投研主流程与各品种入口）、**extended**（18 个：债券发行明细、发行计划、行权安排，云盘管理与上传，文件解析与取结果，基金费率、规模、持有人、债券与基金持仓、ETF 申赎与份额等 11 个）、**legacy**（0.3.0 合并掉的 27 个旧工具，0.4.0 删除）。默认列出 core 与 extended 共 114 个。用环境变量 `GANGTISE_MCP_TOOLS` 选择，逗号分隔取并集：

| 写法 | 列出的工具 |
|---|---|
| 不设置 / `all` | core + extended（默认） |
| `core` | 只列 core，上下文更省 |
| `all,legacy` | 默认 + 旧工具（升级过渡用） |
| `core,bond` | core + 债券全部 12 个 |
| `core,fund` | core + 基金全部 18 个 |
| `-vault` | 默认去掉云盘、录音、会议、群消息与自选股池 |

组名：`context` `lookup` `reference` `insight` `quote` `fundamental` `bond` `fund` `ai` `vault` `download` `alternative` `indicator` `tool` `response`，也可写单个工具名；前加 `-` 禁用。被禁用的工具既不列出也调不到。`gangtise_download` 属于 `download` 组，只选部分组时把 `download` 一并写上（如 `insight,download`）；禁用某一组或某个列表工具后（如 `-vault`），它也不下载对应的资源。`gangtise_current_date`、`gangtise_read_response`、`gangtise_securities_search` 始终启用。

工具定义每次会话都会进入模型上下文，工具越多占用越大。只做股票投研、想省上下文时设 `core`（约少 17KB）。**Claude Code** 默认开启 MCP tool search，按需加载工具定义；设 `ENABLE_TOOL_SEARCH=false` 可关闭。`ANTHROPIC_BASE_URL` 指向非官方主机时默认不启用，代理支持 `tool_reference` 时可设 `ENABLE_TOOL_SEARCH=true` 开启（据 Claude Code 官方文档，核对于 2026-09-27）。

### 从 0.2.x 升级

| 0.2.x | 0.3.0 |
|---|---|
| `gangtise_income_statement_hk` / `_us`、`gangtise_balance_sheet_hk` / `_us`、`gangtise_cash_flow_hk` / `_us` | 同名去掉后缀的工具，按 `securityCode` 的后缀选市场 |
| `gangtise_income_statement_quarterly`、`gangtise_cash_flow_quarterly` | `gangtise_income_statement` / `gangtise_cash_flow` 传 `quarterly: true`（仅 A 股） |
| `gangtise_announcement_hk_list` / `_us_list` | `gangtise_announcement_list`，按 `securityList` 的后缀选市场；不传证券时传 `market`（`aShares` / `hkStocks` / `usStocks`） |
| `gangtise_announcement_list` 不传证券查 A 股全量 | 须传 `market: "aShares"` |
| `gangtise_<资源>_download`（15 个） | `gangtise_download`：`kind` 为原工具名中间那段（如 `research`、`announcement_hk`、`knowledge_resource`、`record`），原 ID 参数统一传 `id`，`fileType` / `contentType` / `resourceType` 不变。只选部分组的配置要加上 `download` 组 |
| `gangtise_day_kline_hk` / `_us`（`security: 'all'`） | `gangtise_day_kline`（`'hkStocks'` / `'usStocks'`） |
| 观点列表缺省带正文（30 积分/条） | 缺省只回标题与 200 字摘要（1 积分/条）；要正文传 `withContent: true`，或用 `gangtise_opinion_detail` |
| 题材画像与成分股缺省为完整版（500 积分/次） | 缺省 50 积分/次；要催化事件、重点标记与纳入理由传 `full: true` |
| `fetchAll` 或大 `size` 直接拉取；`gangtise_opinion_detail` 一次传很多 ID | 按条计费的多页拉取与按 ID 批量取观点正文，预估超过 `GANGTISE_MCP_COST_LIMIT`（默认 1000）时报错并给出估算，确认后传 `confirmCost: true` |
| 全市场日 K 可只给一个日期 | 须同时给 `startDate` 与 `endDate` |
| 多只 / 全市场时 `fieldList` 只返回点名的列 | 自动在最前补上身份列：日 K、指数日 K 补 `securityCode` / `tradeDate`，分钟 K 补 `securityCode` / `tradeTime`，实时行情只补 `securityCode`（旧日 K 工具不补） |

暂时不改调用的，设 `GANGTISE_MCP_TOOLS=all,legacy` 即可继续使用旧工具名；旧工具同样受积分预估保护与全市场双日期约束。

## 前置要求

- Node.js ≥ 20.18.1（undici 7.27+ 的要求，见 `package.json#engines`）
- Gangtise 开放平台账号（[申请地址](https://open.gangtise.com)），获取 `accessKey` / `secretKey`

## 快速开始

### Claude Code

```bash
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`

```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`：

```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`：

```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**，加入：

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

### 其他支持 MCP 的客户端

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

```json
{
  "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 缓存**

```bash
# macOS / Linux —— 只删本包的缓存条目，不动其他工具的
grep -rl '"gangtise-mcp"' ~/.npm/_npx/*/package.json 2>/dev/null | xargs -r dirname | xargs -r rm -rf
# Windows (PowerShell)
Get-ChildItem "$env:LOCALAPPDATA\npm-cache\_npx" -Recurse -Filter package.json |
  Select-String -Pattern 'gangtise-mcp' | ForEach-Object { Remove-Item -Recurse -Force $_.Path.Substring(0, $_.Path.LastIndexOf('\')) }
```

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

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

## 环境变量

| 变量 | 默认值 | 说明 |
|---|---|---|
| `GANGTISE_ACCESS_KEY` | — | 开放平台 Access Key（与 SECRET_KEY 配对使用） |
| `GANGTISE_SECRET_KEY` | — | 开放平台 Secret Key |
| `GANGTISE_TOKEN` | — | 直接传 Bearer Token（优先于 Key/Secret，适合临时使用） |
| `GANGTISE_BASE_URL` | `https://openapi.gangtise.com` | API 基础地址（旧域名 `https://open.gangtise.com` 仍可用）；用 `http://` 指向非本机地址时在 stderr 提示一次（AK / SK / token 会明文传输） |
| `GANGTISE_TIMEOUT_MS` | `30000` | 单次请求超时，十进制整数毫秒（1000–3600000）；无效值回退默认、超上限夹到上限，未按原值生效时在 stderr 提示一次 |
| `GANGTISE_MCP_ASYNC_TIMEOUT_MS` | `55000` | 异步 AI 任务默认等待超时（毫秒）；保持在 MCP 客户端请求超时（约 60s）以下，超时返回 dataId 供 `*_check` 续查。需更长等待可调高本值或按调用传 `waitSeconds`（最大 180） |
| `GANGTISE_TOKEN_CACHE_PATH` | `~/.config/gangtise/token.json` | Token 缓存文件路径 |
| `GANGTISE_PAGE_CONCURRENCY` | `5` | 分页、全市场分片与逐只请求的并发数（1–32）；连接池随之放大，至少 16 |
| `GANGTISE_MCP_GLOBAL_CONCURRENCY` | `max(16, 分页并发)` | 同时在飞的请求总数上限，跨所有调用共享，查询与传输（下载、上传）各自计数、各用各的连接（1–64）；默认与连接池同大，单次调用不受影响，只在多个调用同时分页 / 分片时封顶总量 |
| `GANGTISE_INLINE_MAX_BYTES` | `65536` | 工具结果内联字节上限；超过则落盘为临时文件并返回可翻页的预览指针。默认 64KB（约 1.5–2 万 token）控制单次响应体积；批量导出可调大（最低 8192） |
| `GANGTISE_MAX_DOWNLOAD_BYTES` | `1073741824` | 单个下载文件的字节上限（默认 1 GiB）。超出时在落盘前拒绝（有 `Content-Length`）或流式中止（无该头），避免一次超大下载占满临时磁盘。`/tmp` 较小的部署可调低（最低 1 MB） |
| `GANGTISE_MCP_TOOLS` | `all` | 列出并启用哪些工具，逗号分隔取并集：`all` / `core` / `legacy`、工具组名或工具名；前加 `-` 禁用该组或该工具（不列出，也调不到），如 `-vault`；只写禁用项时以 `all` 为底。写法与组名见「工具分档与选择」。选了异步提交工具时其 `*_check` 一并启用；写错名字、禁用基础工具时启动即报错 |
| `GANGTISE_MCP_COST_LIMIT` | `1000` | 积分预估保护的阈值：按条计费的多页拉取（`fetchAll`，或 `size` 超过单页上限）、按 ID 批量取观点正文与长日期区间的盈利预测，预估超过它时先报错给出估算，确认后传 `confirmCost: true`。`0` 关闭；非法值回退默认。单页请求不在保护范围内 |
| `GANGTISE_VERBOSE` | — | 设为 `1` 开启请求耗时日志（输出到 stderr） |

变量设成空串（或只有空白）按未设置处理，MCP 配置里留空的可选项不会生效。

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

## 结果不完整时的标记

客户端检测到请求结果可能不完整时，会带 `_partial: true` 与 `_partial_reason`（逗号分隔的多个原因）。看到它就说明这份结果不能当全集用；没有该标记也不保证服务端数据完整，例如接口可能保留行列但返回 `null`。

| 原因 | 含义 | 按情况附带的详情字段 |
|---|---|---|
| `missing_fields` | 请求的某几列没回来（字段名写错或已下线）。行情类接口对不认识的字段名是名和值一起丢，不报错 | `missingFields` |
| `dropped_columns` | 合并多份响应时，后一份多出来的列放不下——合并结果的列集合取自第一份 | `_dropped_columns` |
| `limit_truncated` | 返回行数达到单次请求上限，结果可能在窗口内被截断 | 分片 / 逐只合并时为 `_truncated_shards` / `_truncated_securities`；估值分析附 `_hint`（缺的是区间开头）；其他单次请求可能只有原因标记 |
| `failed_shards` / `failed_securities` / `failed_pages` | 分片、逐只或分页请求中有一部分失败 | `_failed_shards` / `_failed_securities` / `_failed_pages`，逐条记出区间 / 证券 / 页与错误 |
| `failed_items` | 自选股池的批量写操作（加股 / 移除 / 删池）里有单条失败，其余照常生效 | `failedItems`，逐条点名并附原因 |
| `malformed_shards` / `malformed_securities` | 某一份响应里没有可合并的行，或列结构对不上 | `_malformed_shards` / `_malformed_securities` |
| `part_partial` | 合并多份响应时，其中一份自带不完整标记但没有写原因 | — |
| `short_page` / `page_cap` / `total_drift` / `total_capped` | 翻页没取满、撞到页数上限、翻页期间数据集变了、`total` 是上限值而非真实计数（含 `total` 触及接口偏移窗口、越过 `total` 的那一行被接口拒绝） | `page_cap` / `total_capped` 分别附带 `_page_cap` / `_total_capped`；其他原因不保证有独立详情字段 |
| `duplicate_rows` / `changed_rows` | 翻页排序键不唯一，同一行在相邻两页各出现一次（重复的已去掉，同样多的行没有取回）；同一 ID 在后面的页上内容变了（两版都保留） | `_duplicate_rows` / `_changed_rows` |
| `window_cut` | 请求的行越过了接口的偏移窗口（`from + size` 上限），窗口外的没有取回 | `_window_cut` |
| `missing_ids` / `unfetched_ids` | 按 ID 取观点全文时，有的 ID 没有正文（被跳过、不报错）；某一批请求失败，后面的 ID 没有取 | `missingIds` / `unfetchedIds` + `unfetchedError` |
| `unexpected_page_shape` | 分页端点的首个响应不是 `{total, list}` 结构，翻页没有发生 | `_unexpected_page_shape` |
| `omitted_indicators` / `omitted_securities` | 证券级指标（EDE）请求里的某些代码没有出现在返回矩阵中 | `omittedIndicators` / `omittedSecurities` |
| `security_only_row_cap` | 财报日历只按 `securityList` 筛选时最多取 1000 行；取满且 `total` 显示还有剩余，说明该筛选可能没有生效 | `_hint` |

拿到 `_partial` 后的常规处置：按标记指出的那几天 / 那几只 / 那几列缩小范围重拉，而不是把结果当完整集继续算。

另有两个说明字段，不属于不完整标记：`_note`（如行情的最早一行晚于请求起点、没有返回任何行的代码、`fieldList` 自动补了哪几列）与 `_cost_probe`（为估算积分先取的那 1 条在正式拉取时又计了一次）。

## 大响应处理

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

| 字段 | 说明 |
|---|---|
| `_truncated` | `true` — 表示响应已截断 |
| `_saved_to` | 完整数据的临时文件路径 |
| `_total_bytes` | 完整响应的 UTF-8 字节数 |
| `_total_items` | 文件中的总条数 |
| `_preview_count` | 本次内联返回的条数（最多 20） |
| `_read_with` | 续读工具名（固定为 `gangtise_read_response`） |
| `has_more` | 文件中是否还有未返回的条目 |
| `next_offset` | 下一页的起点，传给 `gangtise_read_response` 的 `offset`；没有更多时为 `null` |
| `_preview` / `_total_chars` / `_preview_chars` | 仅文本类（Markdown 等）：开头一段的预览、全文字符数、预览字符数；这类文件续读的 `offset` 按字符计 |
| `_local_hint` | 本地处理建议（server 与客户端共享文件系统时适用） |
| `_available_fields` / `_available_fields_sampled` | 采样前 20 行得到的顶层字段名，及实际扫描行数；供 `gangtise_read_response` 的 `fields` 参考 |
| `_available_fields_truncated` | 仅当顶层字段超 50 个时出现（`true`）：`_available_fields` 已截断至前 50 个 |

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

宽表可用 `fields` 只取所需列（如 `fields: ["tradeDate","close"]`）——投影在字节预算之前完成，因此每页能装下更多行。部分字段名拼错会以 `_unknown_fields` 回显并照常返回其余字段，全部拼错才报错并回列可用字段。

`gangtise_read_response` 每页也受同一字节预算约束：当「信封 + 最小一行」仍超预算（或列表为空但非列表兄弟字段本身超预算）时，仍返回该内容并标 `_oversized: true`——此时单页已无法再缩小，但 `next_offset` 照常推进，翻页不会卡死。

`_local_hint` 仅在 **server 与客户端共享文件系统、且客户端获准访问该路径**时可用：此时可在本地直接投影/过滤/聚合该文件，只把结果读进上下文。**远程 MCP、容器隔离、以及无文件读取能力的客户端（如 Claude Desktop）必须继续走 `gangtise_read_response`。** 注意本地直读不受 MCP 侧 owned-temp-path 校验保护，其安全性取决于客户端自身的文件权限。

## 开发

```bash
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         # 运行测试（含 tools/list 快照、逐工具请求契约与响应形状 fixture）
npm run coverage # 覆盖率（发布流水线按阈值把关）
npm run lint
npm run build && npm run check:release   # 发版门禁：对外措辞、dist 无注释、上下文预算
node --expose-gc --import tsx scripts/bench/run.ts   # 性能基线（本机假服务端，不进 CI）
node scripts/upstream-diff.mjs   # 与 gangtise-openapi-cli 的端点契约对比（先 build；同一比对也在 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。

标准流程：

```bash
npm version patch --no-git-tag-version
# 完整明细写进 CHANGELOG.md；README 的 Changelog 顶部加一行摘要、删掉第 6 行
npm run lint
npm test
npm run coverage                    # 发布流水线有覆盖率阈值，本地先跑
npx tsc --noEmit
npm run build && npm run check:release
git add .
git commit -m "fix: <message>"
git tag -a v0.x.y -m v0.x.y          # 必须是 annotated tag
git push origin main v0.x.y
git ls-remote --tags origin v0.x.y   # 有输出才说明 tag 已推上去、发布流水线会触发
```

tag 名须与 `package.json` 的 `version` 一致，被打 tag 的提交须已在 `main` 上。发布完成后确认：

```bash
gh run list --workflow npm-publish.yml --limit 1
npm view gangtise-mcp version        # 可能滞后几分钟，以 Actions 日志里的「+ gangtise-mcp@版本号」为准
```

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

## 数据、凭据与授权

**MIT 只覆盖本连接器的代码。** Gangtise OpenAPI 本身、经由它取得的行情/研报/纪要/公告等数据与内容，均按你与 Gangtise 的服务协议授权，不随本包一并授予。是否可再分发、可否用于对外产品，以该协议为准。

**云盘上传与文件解析会把本机文件发送到 Gangtise 平台处理。**

**取到的数据会进入你配置的 AI 客户端。** 本服务是一条管道：云盘文件、语音转写、我的会议、微信群消息、研报全文等**私域内容**，一旦被工具取回，就会进入你所连接的模型上下文，并按该客户端自己的策略被处理或留存。把这些工具接给第三方客户端前，请先确认对方的数据处理条款。

**凭据不要外传。** `GANGTISE_ACCESS_KEY` / `GANGTISE_SECRET_KEY` / `GANGTISE_TOKEN` 与 token 缓存文件（默认 `~/.config/gangtise/token.json`）等同于账号本身。提 issue、贴日志前先把它们去掉；`GANGTISE_VERBOSE=1` 的 stderr 输出不含凭据，但请求 URL 里可能带有你的查询内容。

**联网搜索返回的是公开网页内容**，不是 Gangtise 平台数据；可靠性按结果里的信源等级 `tier` 与内容标记 `flags` 判断。

**计费口径。** 工具描述里的【积分】标签是发布时的单价快照，用于让模型在调用前估算成本；**实际扣费以你的账户权限与平台当时的计费规则为准**。标注为免费的工具同样受账户数据权限约束。

## 客户端兼容性

已实际联调：Claude Code、Claude Desktop、Cursor、Cherry Studio。

其余任何支持 stdio 传输的 MCP 客户端理论上都可接入——本服务只用标准的 `tools/list` + `tools/call`，不依赖 MCP 的可选能力。但未联调过的客户端可能在两处有差异：一是是否把 server `instructions` 注入模型上下文（不注入时，跨工具的通用参数语义会缺失），二是超大响应的处理方式。遇到问题请提 issue 并附上客户端名称与版本。

## 支持与反馈

- 用法与缺陷：在 [GitHub Issues](https://github.com/gangtiser/gangtise-mcp/issues) 提，附上工具名、入参（去掉凭据）与返回中的 `traceId`。
- 数据权限、计费额度、账号问题：联系你的 Gangtise 客户经理，本连接器不参与这些环节。

## License

MIT（仅本连接器代码，见上方「数据、凭据与授权」）