mcp-server-gamenumerics 0.1.1 → 0.1.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (4) hide show
  1. package/HOST-VERIFICATION.md +11 -0
  2. package/README.md +250 -223
  3. package/dist/index.js +31215 -95347
  4. package/package.json +53 -41
package/HOST-VERIFICATION.md CHANGED
@@ -72,3 +72,14 @@
72
72
  | F7 | 宿主进程模型差异：Claude Code 每次 `-p` 独立 server 子进程（无状态），ZCode 长会话常驻 | 预期行为（宿主语义），两种形态 server 均健康（EOF 干净退出 3/3 已验） | 记档即可 |
73
73
 
74
74
  **验证金字塔收官判定**：两宿主（ZCode + Claude Code）真机全绿 + 用户裁决跳过 Cursor——**发布决策输入齐备，npm publish 解禁**。
75
+
76
+ ## 七、npm 发布记录（2026-09-12，两宿主全绿后用户拍板）
77
+
78
+ | 步骤 | 结果 |
79
+ |------|------|
80
+ | 发布前置 | 包名核查可用 / files 白名单收敛（误含 41KB 测试文件、漏 dist——修正后 4 文件）/ bin shebang 修复（esbuild CLI banner 不解析转义 + Windows cmd 换行截断双坑，改走 JS API）/ README 反转「发布待定」为 npx 主推形态 |
81
+ | **0.1.0 发布事故** | 首发成坏包：仓库根 `private:true` 拦 publish（npm 向上应用 monorepo 根标记）→ 改独立临时目录发布时把 `dist/index.js` 拷为根级 `index.js`，files 白名单命中 `dist` 目录——**包内无 bin 目标，npx 必崩**；unpublish 403（granular token 无 unpublish 权限） |
82
+ | 0.1.1 修复版 | 版本号推进 + 正确 dist/ 结构发布成功；`npm deprecate` 标记 0.1.0 引导升级；`latest` tag 指向 0.1.1 |
83
+ | **发布后真机冒烟** | ✓ registry 真实拉包：`npx -y mcp-server-gamenumerics` → initialize 响应 + **17 工具**——发布链完整闭环 |
84
+
85
+ **教训**：发布验收不能止于 `npm pack --dry-run` 看清单——必须在**发布后从 registry 重新安装**并起 server 冒烟（本次 dry-run 两误：白名单误含测试文件、临时目录结构错误均在 dry-run 可见而未核）；granular token 默认无 unpublish 权限，首发事故只能版本推进兜底（unpublish 72h 窗口需账号级操作）。
package/README.md CHANGED
@@ -1,223 +1,250 @@
1
- # mcp-server-gamenumerics
2
-
3
- 游戏数值设计 Agent 工作站的 MCP（Model Context Protocol）形态——**read/算/审计面**的 stdio server。
4
-
5
- 把本项目 agent harness 的 20+ 个零依赖纯函数数值引擎，以 **14 个只读数值工具 + 3 个会话 meta 工具**（共 17 个）带给任意 MCP 宿主（Claude Code / Cursor / ZCode 等）：在开发者自己的 AI 编辑器里直接说「检查这份 HeroGrowth.xlsx 的数值曲线」，宿主 LLM 即可完成导入 → 查表 → 曲线审计的完整链路。
6
-
7
- 核心叙事一句话：**LLM 负责理解、编排、解释；确定性引擎负责数值正确性**——所有数值结论都出自确定性纯函数，不依赖 LLM 心算。
8
-
9
- ## 安装与启动
10
-
11
- 前置：Node.js 18+。
12
-
13
- **方式一：npx 免安装直跑（推荐，宿主配置推荐写法）**
14
-
15
- ```bash
16
- npx -y mcp-server-gamenumerics
17
- ```
18
-
19
- **方式二：全局安装**
20
-
21
- ```bash
22
- npm install -g mcp-server-gamenumerics
23
- gnd-mcp # 本包配置了 bin: gnd-mcp，全局安装后直接以该命令启动
24
- ```
25
-
26
- **方式三：从源码运行（开发者路径）**
27
-
28
- ```bash
29
- # 在 mcp-server/ 目录内
30
- npm install # 安装 @modelcontextprotocol/server
31
- npm run build # esbuild bundle 出单文件 dist/index.js
32
- node dist/index.js # 即 stdio server（stdin/stdout 通信，直接运行会等待输入，属正常）
33
- ```
34
-
35
- `npx .`（在 mcp-server/ 目录内）与 `node dist/index.js` 等价可用。
36
-
37
- ## 环境变量
38
-
39
- | 变量 | 说明 | 缺省 |
40
- |------|------|------|
41
- | `GND_WORKSPACES_DIR` | 工作区根目录（**建议绝对路径**；相对值按用户主目录解析，不依赖进程 cwd）——import_xlsx 装配产物落于此，写侧严格限于该目录内 | `~/.gamenumerics/workspaces` |
42
-
43
- MCP 用户机器上无本仓库源码，工作区绝不落到仓库 `workspaces/` 目录。`import_xlsx` 只接受本地磁盘路径（UNC/网络路径 `//server/...` 前置拒绝——网络解析可能长时间阻塞进程）。
44
-
45
- ## 宿主配置
46
-
47
- 以下配置提供两种接入形态：`npx` 形式直接使用 npm 包（推荐，无需本仓库源码）；本地路径形式供源码开发者使用，其中的 `<仓库绝对路径>` 替换为本仓库实际路径（Windows 路径正反斜杠均可）。
48
-
49
- ### Claude Code
50
-
51
- npx 形式（推荐）：
52
-
53
- ```bash
54
- claude mcp add gamenumerics --env GND_WORKSPACES_DIR=D:/mcp-workspaces -- npx -y mcp-server-gamenumerics
55
- ```
56
-
57
- 本地路径形式（源码开发者用）：
58
-
59
- ```bash
60
- claude mcp add gamenumerics -- node <仓库绝对路径>/mcp-server/dist/index.js
61
- ```
62
-
63
- 可选指定工作区根（本地路径形式；npx 形式同样加 `--env` 即可）：
64
-
65
- ```bash
66
- claude mcp add gamenumerics --env GND_WORKSPACES_DIR=D:/mcp-workspaces -- node <仓库绝对路径>/mcp-server/dist/index.js
67
- ```
68
-
69
- ### Cursor
70
-
71
- 项目级 `.cursor/mcp.json`（或用户级全局配置）。
72
-
73
- npx 形式（推荐）：
74
-
75
- ```json
76
- {
77
- "mcpServers": {
78
- "gamenumerics": {
79
- "command": "npx",
80
- "args": ["-y", "mcp-server-gamenumerics"],
81
- "env": { "GND_WORKSPACES_DIR": "D:/mcp-workspaces" }
82
- }
83
- }
84
- }
85
- ```
86
-
87
- 本地路径形式（源码开发者用）：
88
-
89
- ```json
90
- {
91
- "mcpServers": {
92
- "gamenumerics": {
93
- "command": "node",
94
- "args": ["<仓库绝对路径>/mcp-server/dist/index.js"],
95
- "env": { "GND_WORKSPACES_DIR": "D:/mcp-workspaces" }
96
- }
97
- }
98
- }
99
- ```
100
-
101
- ### ZCode
102
-
103
- 在 ZCode 的 MCP 配置（项目级 `.zcode/mcp.json` 或用户级配置文件，以所用版本文档为准）中加入同形态的 `mcpServers` 条目——`npx` 形式与本地 `node` 路径形式皆可。
104
-
105
- npx 形式（推荐）：
106
-
107
- ```json
108
- {
109
- "mcpServers": {
110
- "gamenumerics": {
111
- "command": "npx",
112
- "args": ["-y", "mcp-server-gamenumerics"],
113
- "env": { "GND_WORKSPACES_DIR": "D:/mcp-workspaces" }
114
- }
115
- }
116
- }
117
- ```
118
-
119
- 本地路径形式（源码开发者用）：
120
-
121
- ```json
122
- {
123
- "mcpServers": {
124
- "gamenumerics": {
125
- "command": "node",
126
- "args": ["<仓库绝对路径>/mcp-server/dist/index.js"],
127
- "env": { "GND_WORKSPACES_DIR": "D:/mcp-workspaces" }
128
- }
129
- }
130
- }
131
- ```
132
-
133
- 配置后重启宿主，工具列表中出现 `import_xlsx` / `list_tables` 等 17 个工具即接入成功。
134
-
135
- ## 性能基线
136
-
137
- | 指标 | 数值 |
138
- |------|------|
139
- | 冷启动（spawn → initialize → tools/list 全链） | ~150ms |
140
- | 空闲内存（握手完成后单进程） | ~79MB |
141
- | 工具面 | 17 个（14 映射 + 3 meta） |
142
- | stdin 关闭 | 干净退出，无残留进程 |
143
-
144
- 测量条件：Windows 11 / Node v24 / 单进程空闲态——数字随环境浮动。复现命令（仓库根目录）：`npx tsx scripts/mcp-benchmark.ts`（3 轮独立子进程取中位）。
145
-
146
- 内存大头是 Node.js 运行时基线（空进程 ~48MB），本包从 34 工具 registry 到 17 工具面的全链业务增量克制在 ~30MB——在「MCP server 动辄 100-200MB」是社区普遍抱怨的背景下，这是选型上的差异点。
147
-
148
- ## 工具面清单（17 = 14 映射 + 3 meta）
149
-
150
- ### 会话 meta 工具（3）
151
-
152
- | 工具 | 职责 |
153
- |------|------|
154
- | `import_xlsx` | 从本地 xlsx（绝对路径）导入并创建工作区：双行表头合并「父.子」列名、数值列自动识别等差/等比/常数模式，成功后设为当前工作区 |
155
- | `list_workspaces` | 列出工作区根下全部可用工作区 |
156
- | `set_workspace` | 按名切换当前工作区（后续全部数值工具作用于它） |
157
-
158
- ### 工作区读取（2）
159
-
160
- | 工具 | 职责 |
161
- |------|------|
162
- | `list_tables` | 列出当前工作区全部数值表清单（表名/模块/行数/列名） |
163
- | `read_table` | 读取指定表的数据行（支持列选择/条件过滤/分页） |
164
-
165
- ### 数值计算与审计（8）
166
-
167
- | 工具 | 职责 |
168
- |------|------|
169
- | `battle_simulate` | 战斗模拟（属性/伤害数值计算） |
170
- | `simulate_gacha` | 抽卡概率计算 + Monte Carlo 模拟 |
171
- | `compute_power` | 属性 → 战力（EHP×EDPS 解析式单源计算） |
172
- | `power_curve` | 批量战力曲线（多属性组对比） |
173
- | `eval_formula` | 求值数值公式表达式 |
174
- | `audit_column` | 列对账：实际值 vs 生成规则期望值的偏离点审计 |
175
- | `infer_column_rule` | 列规则逆向推断（Theil-Sen 稳健拟合等差/等比/幂律） |
176
- | `infer_table_relation` | 列间派生关系推断（还原「各列 = 基准 × 系数」生成结构） |
177
-
178
- ### 结构分析（3）
179
-
180
- | 工具 | 职责 |
181
- |------|------|
182
- | `grade_workspace` | 工作区数值质量评分 |
183
- | `profile_table` | 单表结构画像 |
184
- | `infer_foreign_keys` | 表间外键关系推断 |
185
-
186
- ### 记忆（1）
187
-
188
- | 工具 | 职责 |
189
- |------|------|
190
- | `read_memory` | 读工作区记忆文件（PROFILE/facts，缺省回落公共 facts） |
191
-
192
- > 面边界说明：本 MCP 形态只暴露只读面——写表/规划/问卷/交付导出等依赖人在回路确认面板、登录身份或前端 UI 载荷的工具不在 stdio 面提供。
193
-
194
- ## 使用示例
195
-
196
- 对话示例（任意 MCP 宿主中）：
197
-
198
- > **用户**：检查这份 D:/data/HeroGrowth.xlsx 的数值曲线
199
-
200
- 宿主 LLM 的典型编排（工具调用链）：
201
-
202
- 1. `import_xlsx` `{ "xlsxPath": "D:/data/HeroGrowth.xlsx" }`
203
- → 返回摘要：工作区 `HeroGrowth`、1 张表 `import/HeroGrowth`（3 行，双行表头探测 headerRows=2，`成长` 列为等比 1.1）
204
- 2. `read_table` `{ "table": "import/HeroGrowth" }` → 读回行数据确认口径
205
- 3. `infer_column_rule` 对 `成长` 列逆向拟合生成规则
206
- 4. `audit_column` `{ "table": "import/HeroGrowth", "column": "成长", "rule": "<上一步推断的表达式>" }` → 对账偏离点（疑似手调值）
207
-
208
- 若 headerRows 启发式探测失误（摘要回显可疑列名），在 `import_xlsx` 显式传 `"sheets": [{ "sheet": "HeroGrowth", "headerRows": 1 }]` 重试即可。
209
-
210
- ## 开发
211
-
212
- ```bash
213
- # 类型检查（mcp-server 自带独立 tsconfig，根 tsc exclude 本目录）
214
- npm run check
215
-
216
- # 单测（经根仓库 vitest 收集：npm test，文件级 @vitest-environment node）
217
- cd .. && npx vitest run mcp-server/__tests__/
218
-
219
- # 真机冒烟（stdio 子进程拉起 dist/index.js 全链路，不进 CI；上一行 cd .. 后即处于仓库根目录）
220
- npx tsx scripts/mcp-smoke.ts
221
- ```
222
-
223
- 架构一页纸见仓库 `docs/agent-harness-architecture.md`；本包 Spec 见 `docs/specs/v9-w2-mcp-server-spec.md`。
1
+ # mcp-server-gamenumerics
2
+
3
+ > **MCP server for game numerical design & balance auditing.** 20 deterministic tools that let your AI coding agent (Claude Code, Cursor, ZCode, or any MCP host) import xlsx config tables, audit growth curves, run battle/gacha simulations, and reverse-engineer the formulas behind game spreadsheets — every numeric answer comes from deterministic pure-function engines, zero LLM guessing.
4
+
5
+ **Who it's for**: game designers and solo/small teams doing roguelike / deckbuilder balance work, spreadsheet-driven numerical design, or live-ops tuning audits — no engine integration required, just an xlsx export of your config tables.
6
+
7
+ **What you get — 20 tools**: `import_xlsx` (dual-row header merge + column-pattern detection) · `list_tables` / `read_table` (workspace read, filter & paginate) · `battle_simulate` / `simulate_gacha` (Monte Carlo) / `compute_power` (EHP×EDPS) / `power_curve` / `eval_formula` / `audit_column` (expected-vs-actual reconciliation) / `infer_column_rule` (Theil-Sen robust fitting) / `infer_table_relation` (base×coefficient structures) · `grade_workspace` / `profile_table` / `infer_foreign_keys` (structure analysis) · `list_workspaces` / `set_workspace` / `read_memory` (session meta) · `export_table` (lua/json export, W3) · `recon_diff` (L3 cross-table reconciliation, W4) · `suggest_refs` (referential-integrity candidate discovery, W5). Read-only surface — write tools stay behind the web workbench's human-in-the-loop confirm flow.
8
+
9
+ **Quick start** (Node.js 18+):
10
+
11
+ ```bash
12
+ npx -y mcp-server-gamenumerics
13
+ ```
14
+
15
+ ```json
16
+ { "mcpServers": { "gamenumerics": { "command": "npx", "args": ["-y", "mcp-server-gamenumerics"] } } }
17
+ ```
18
+
19
+ **Performance**: ~150ms cold start (spawn → initialize → tools/list) · ~79MB idle memory · 20 tools · clean exit on stdin close.
20
+
21
+ **Verified hosts**: ZCode ✓ · Claude Code ✓ — per-host config snippets below; host-verification log in [HOST-VERIFICATION.md](HOST-VERIFICATION.md).
22
+
23
+ ---
24
+
25
+ 以下为中文详细文档。
26
+
27
+ 游戏数值设计 Agent 工作站的 MCP（Model Context Protocol）形态——**read/算/审计面**的 stdio server。
28
+
29
+ 把本项目 agent harness 的 20+ 个零依赖纯函数数值引擎，以 **14 个只读数值工具 + 6 个会话 meta 工具**（共 20 个）带给任意 MCP 宿主（Claude Code / Cursor / ZCode 等）：在开发者自己的 AI 编辑器里直接说「检查这份 HeroGrowth.xlsx 的数值曲线」，宿主 LLM 即可完成导入 → 查表 → 曲线审计的完整链路。
30
+
31
+ 核心叙事一句话：**LLM 负责理解、编排、解释；确定性引擎负责数值正确性**——所有数值结论都出自确定性纯函数，不依赖 LLM 心算。
32
+
33
+ ## 安装与启动
34
+
35
+ 前置：Node.js 18+。
36
+
37
+ **方式一：npx 免安装直跑（推荐，宿主配置推荐写法）**
38
+
39
+ ```bash
40
+ npx -y mcp-server-gamenumerics
41
+ ```
42
+
43
+ **方式二：全局安装**
44
+
45
+ ```bash
46
+ npm install -g mcp-server-gamenumerics
47
+ gnd-mcp # 本包配置了 bin: gnd-mcp，全局安装后直接以该命令启动
48
+ ```
49
+
50
+ **方式三：从源码运行（开发者路径）**
51
+
52
+ ```bash
53
+ # 在 mcp-server/ 目录内
54
+ npm install # 安装 @modelcontextprotocol/server
55
+ npm run build # esbuild bundle 出单文件 dist/index.js
56
+ node dist/index.js # 即 stdio server（stdin/stdout 通信，直接运行会等待输入，属正常）
57
+ ```
58
+
59
+ `npx .`（在 mcp-server/ 目录内）与 `node dist/index.js` 等价可用。
60
+
61
+ ## 环境变量
62
+
63
+ | 变量 | 说明 | 缺省 |
64
+ |------|------|------|
65
+ | `GND_WORKSPACES_DIR` | 工作区根目录（**建议绝对路径**；相对值按用户主目录解析，不依赖进程 cwd）——import_xlsx 装配产物落于此，写侧严格限于该目录内 | `~/.gamenumerics/workspaces` |
66
+
67
+ MCP 用户机器上无本仓库源码，工作区绝不落到仓库 `workspaces/` 目录。`import_xlsx` 只接受本地磁盘路径（UNC/网络路径 `//server/...` 前置拒绝——网络解析可能长时间阻塞进程）。
68
+
69
+ ## 宿主配置
70
+
71
+ 以下配置提供两种接入形态：`npx` 形式直接使用 npm 包（推荐，无需本仓库源码）；本地路径形式供源码开发者使用，其中的 `<仓库绝对路径>` 替换为本仓库实际路径（Windows 路径正反斜杠均可）。
72
+
73
+ ### Claude Code
74
+
75
+ npx 形式（推荐）：
76
+
77
+ ```bash
78
+ claude mcp add gamenumerics --env GND_WORKSPACES_DIR=D:/mcp-workspaces -- npx -y mcp-server-gamenumerics
79
+ ```
80
+
81
+ 本地路径形式（源码开发者用）：
82
+
83
+ ```bash
84
+ claude mcp add gamenumerics -- node <仓库绝对路径>/mcp-server/dist/index.js
85
+ ```
86
+
87
+ 可选指定工作区根（本地路径形式；npx 形式同样加 `--env` 即可）：
88
+
89
+ ```bash
90
+ claude mcp add gamenumerics --env GND_WORKSPACES_DIR=D:/mcp-workspaces -- node <仓库绝对路径>/mcp-server/dist/index.js
91
+ ```
92
+
93
+ ### Cursor
94
+
95
+ 项目级 `.cursor/mcp.json`（或用户级全局配置）。
96
+
97
+ npx 形式（推荐）：
98
+
99
+ ```json
100
+ {
101
+ "mcpServers": {
102
+ "gamenumerics": {
103
+ "command": "npx",
104
+ "args": ["-y", "mcp-server-gamenumerics"],
105
+ "env": { "GND_WORKSPACES_DIR": "D:/mcp-workspaces" }
106
+ }
107
+ }
108
+ }
109
+ ```
110
+
111
+ 本地路径形式（源码开发者用）：
112
+
113
+ ```json
114
+ {
115
+ "mcpServers": {
116
+ "gamenumerics": {
117
+ "command": "node",
118
+ "args": ["<仓库绝对路径>/mcp-server/dist/index.js"],
119
+ "env": { "GND_WORKSPACES_DIR": "D:/mcp-workspaces" }
120
+ }
121
+ }
122
+ }
123
+ ```
124
+
125
+ ### ZCode
126
+
127
+ 在 ZCode 的 MCP 配置（项目级 `.zcode/mcp.json` 或用户级配置文件，以所用版本文档为准）中加入同形态的 `mcpServers` 条目——`npx` 形式与本地 `node` 路径形式皆可。
128
+
129
+ npx 形式（推荐）：
130
+
131
+ ```json
132
+ {
133
+ "mcpServers": {
134
+ "gamenumerics": {
135
+ "command": "npx",
136
+ "args": ["-y", "mcp-server-gamenumerics"],
137
+ "env": { "GND_WORKSPACES_DIR": "D:/mcp-workspaces" }
138
+ }
139
+ }
140
+ }
141
+ ```
142
+
143
+ 本地路径形式（源码开发者用）：
144
+
145
+ ```json
146
+ {
147
+ "mcpServers": {
148
+ "gamenumerics": {
149
+ "command": "node",
150
+ "args": ["<仓库绝对路径>/mcp-server/dist/index.js"],
151
+ "env": { "GND_WORKSPACES_DIR": "D:/mcp-workspaces" }
152
+ }
153
+ }
154
+ }
155
+ ```
156
+
157
+ 配置后重启宿主，工具列表中出现 `import_xlsx` / `list_tables` 等 20 个工具即接入成功。
158
+
159
+ ## 性能基线
160
+
161
+ | 指标 | 数值 |
162
+ |------|------|
163
+ | 冷启动（spawn → initialize → tools/list 全链） | ~150ms |
164
+ | 空闲内存（握手完成后单进程） | ~79MB |
165
+ | 工具面 | 20 个（14 映射 + 6 meta） |
166
+ | stdin 关闭 | 干净退出，无残留进程 |
167
+
168
+ 测量条件：Windows 11 / Node v24 / 单进程空闲态——数字随环境浮动。复现命令（仓库根目录）：`npx tsx scripts/mcp-benchmark.ts`（3 轮独立子进程取中位）。
169
+
170
+ 内存大头是 Node.js 运行时基线（空进程 ~48MB），本包从 34 工具 registry 到 20 工具面的全链业务增量克制在 ~30MB——在「MCP server 动辄 100-200MB」是社区普遍抱怨的背景下，这是选型上的差异点。
171
+
172
+ ## 工具面清单（20 = 14 映射 + 6 meta）
173
+
174
+ ### 会话 meta 工具（6）
175
+
176
+ | 工具 | 职责 |
177
+ |------|------|
178
+ | `import_xlsx` | 从本地 xlsx（绝对路径）导入并创建工作区：双行表头合并「父.子」列名、数值列自动识别等差/等比/常数模式，成功后设为当前工作区 |
179
+ | `list_workspaces` | 列出工作区根下全部可用工作区 |
180
+ | `set_workspace` | 按名切换当前工作区（后续全部数值工具作用于它） |
181
+ | `export_table` | 导出当前工作区表为 lua record 数组模块或 JSON（columns 可收窄，超 1MB 拒绝） |
182
+ | `recon_diff` | 跨表对账（L3）：两张表按声明键列对齐、值列逐格比对（誊抄/倍率誊抄/外键断链，容差=绝对半格+相对 1e-9） |
183
+ | `suggest_refs` | 引用完整性候选发现（W5）：全表扫描「A 列疑似引用 B 表键列」的候选映射（值域包含+剪枝），确认后经 recon_diff 执行断链扫描 |
184
+
185
+ ### 工作区读取（2）
186
+
187
+ | 工具 | 职责 |
188
+ |------|------|
189
+ | `list_tables` | 列出当前工作区全部数值表清单（表名/模块/行数/列名） |
190
+ | `read_table` | 读取指定表的数据行（支持列选择/条件过滤/分页） |
191
+
192
+ ### 数值计算与审计（8）
193
+
194
+ | 工具 | 职责 |
195
+ |------|------|
196
+ | `battle_simulate` | 战斗模拟（属性/伤害数值计算） |
197
+ | `simulate_gacha` | 抽卡概率计算 + Monte Carlo 模拟 |
198
+ | `compute_power` | 属性 → 战力（EHP×EDPS 解析式单源计算） |
199
+ | `power_curve` | 批量战力曲线（多属性组对比） |
200
+ | `eval_formula` | 求值数值公式表达式 |
201
+ | `audit_column` | 列对账：实际值 vs 生成规则期望值的偏离点审计 |
202
+ | `infer_column_rule` | 列规则逆向推断（Theil-Sen 稳健拟合等差/等比/幂律） |
203
+ | `infer_table_relation` | 列间派生关系推断（还原「各列 = 基准 × 系数」生成结构） |
204
+
205
+ ### 结构分析（3）
206
+
207
+ | 工具 | 职责 |
208
+ |------|------|
209
+ | `grade_workspace` | 工作区数值质量评分 |
210
+ | `profile_table` | 单表结构画像 |
211
+ | `infer_foreign_keys` | 表间外键关系推断 |
212
+
213
+ ### 记忆（1）
214
+
215
+ | 工具 | 职责 |
216
+ |------|------|
217
+ | `read_memory` | 读工作区记忆文件（PROFILE/facts，缺省回落公共 facts） |
218
+
219
+ > 面边界说明：本 MCP 形态只暴露只读面——写表/规划/问卷/交付导出等依赖人在回路确认面板、登录身份或前端 UI 载荷的工具不在 stdio 面提供。
220
+
221
+ ## 使用示例
222
+
223
+ 对话示例（任意 MCP 宿主中）：
224
+
225
+ > **用户**：检查这份 D:/data/HeroGrowth.xlsx 的数值曲线
226
+
227
+ 宿主 LLM 的典型编排（工具调用链）：
228
+
229
+ 1. `import_xlsx` `{ "xlsxPath": "D:/data/HeroGrowth.xlsx" }`
230
+ → 返回摘要：工作区 `HeroGrowth`、1 张表 `import/HeroGrowth`（3 行，双行表头探测 headerRows=2，`成长` 列为等比 1.1）
231
+ 2. `read_table` `{ "table": "import/HeroGrowth" }` → 读回行数据确认口径
232
+ 3. `infer_column_rule` 对 `成长` 列逆向拟合生成规则
233
+ 4. `audit_column` `{ "table": "import/HeroGrowth", "column": "成长", "rule": "<上一步推断的表达式>" }` → 对账偏离点（疑似手调值）
234
+
235
+ 若 headerRows 启发式探测失误（摘要回显可疑列名），在 `import_xlsx` 显式传 `"sheets": [{ "sheet": "HeroGrowth", "headerRows": 1 }]` 重试即可。
236
+
237
+ ## 开发
238
+
239
+ ```bash
240
+ # 类型检查（mcp-server 自带独立 tsconfig，根 tsc exclude 本目录）
241
+ npm run check
242
+
243
+ # 单测（经根仓库 vitest 收集：npm test，文件级 @vitest-environment node）
244
+ cd .. && npx vitest run mcp-server/__tests__/
245
+
246
+ # 真机冒烟（stdio 子进程拉起 dist/index.js 全链路，不进 CI；上一行 cd .. 后即处于仓库根目录）
247
+ npx tsx scripts/mcp-smoke.ts
248
+ ```
249
+
250
+ 架构一页纸见仓库 `docs/agent-harness-architecture.md`；本包 Spec 见 `docs/specs/v9-w2-mcp-server-spec.md`。