docs(mcp): 新增 MCP 协议规范——规定如何通过 MCP 操作 TPV 与 TPC

- MCP/README.md：总览、目录、快速接入与命令速查 - MCP/protocol.md：14 个工具定义（tpc_/tpv_/tp_ 前缀）、执行约定、输出格式、安全约束、错误码 - MCP/tools/tools.json：可被客户端直接加载的工具 schema 集合
2026-08-21 14:00:43 +08:00
1 parent ff7c0457ad
commit e412885a3e
@@ -0,0 +1,67 @@
+# TransPyC / TransPyV MCP 工具集
+
+通过 **MCP（Model Context Protocol）** 操作 Viper 编译器生态的工具协议与接入说明。
+
+本目录定义了一套标准化的 MCP 工具集，让 AI 助手/客户端能够：
+
+- 编译 **TPC**（TransPyC，CPython 实现的编译器）管辖的 Viper 工程与单文件
+- 构建并驱动 **TPV**（TransPyV，Viper 自举编译器）及自举链验证
+- 运行回归测试、读取日志 / AST / SHA1 映射等诊断信息
+
+## 目录
+
+| 文件 | 说明 |
+|------|------|
+| `README.md` | 本文件：总览与快速接入 |
+| `protocol.md` | MCP 协议规范：工具定义、执行约定、输出格式、安全约束 |
+| `tools/` | 各工具的 JSON schema（可选生成，供客户端加载） |
+
+## 快速接入
+
+MCP 服务器（`transpyc-tools`）以 stdio 方式运行于项目根目录：
+
+```json
+{
+  "mcpServers": {
+    "transpyc-tools": {
+      "command": "python",
+      "args": ["-m", "transpyc_mcp.server"],
+      "cwd": "D:\\Users\\TermiNexus\\Desktop\\TransPyC"
+    }
+  }
+}
+```
+
+实现规范见 [protocol.md](protocol.md)。工具命名空间前缀约定：
+
+| 前缀 | 作用对象 |
+|------|----------|
+| `tpc_` | TPC（TransPyC 编译器 / Projectrans 工程体系） |
+| `tpv_` | TPV（TransPyV 自举编译器 / 自举链） |
+| `tp_` | 只读诊断（AST / 日志 / SHA1 映射） |
+
+## 常用命令速查（协议映射）
+
+| 目标 | 协议工具 | 底层命令 |
+|------|----------|----------|
+| 编译单个测试 | `tpc_run_test` | `python Projectrans.py --project Test/<Name>/project.json --clean --run` |
+| 编译任意工程 | `tpc_build` | `python Projectrans.py --project <project.json> [--clean] [--run] ...` |
+| 单文件转 LLVM IR | `tpc_build_file` | `python TransPyC.py -f <in.vp> -o <out.ll>` |
+| 全量回归 | `tpc_run_regression` | `python Test/regression_test.py` |
+| 清理工程产物 | `tpc_clean_project` | `python Projectrans.py --project <p> --clean` |
+| 清全局缓存 | `tpc_clear_cache` | `python Projectrans.py --project <p> --clear-cache` |
+| 重建 includes | `tpc_rebuild_includes` | `python Projectrans.py --project <p> --rebuild-includes` |
+| 构建 TPV | `tpv_build` | `python Projectrans.py --project TransPyV/project.json --clean` |
+| 自举链验证 | `tpv_bootstrap` | Phase A/B/C（TPC 编译 TPV → tpv.exe → tpv2 → tpv3） |
+| TPV 编译工程 | `tpv_compile_project` | `TransPyV\output\TransPyV.exe --project <p> --clean` |
+| 解析 AST | `tp_read_ast` | `python -c "import vast; ..."`（内部调用 vast） |
+| 读日志 | `tp_read_log` | 读取项目内日志文件末尾 N 行 |
+| 读 SHA1 映射 | `tp_sha1_map` | 读取 `temp/_sha1_map.txt` |
+
+## 关键约束（摘自 protocol.md）
+
+- 一律不手动删除文件；清理用 `--clean` / `--rebuild-includes` / `--clear-cache`
+- 编译输出仅返回**末尾 N 行**（默认 50），避免长日志污染上下文
+- 同一工程目录禁止并行编译（temp/output 冲突）
+- TPC 编译错误 **fail-fast**：立即返回错误，不静默兜底
+- 修改 TPV `.vp` 源码后必须清缓存 + Phase A 全量重建才生效（SHA1 缓存复用旧 .ll）
@@ -0,0 +1,436 @@
+# TransPyC / TransPyV MCP 协议规范
+
+版本：2026-08（v1） · 适用根目录：`D:\Users\TermiNexus\Desktop\TransPyC`
+
+---
+
+## 1. 概述
+
+本协议定义通过 MCP 操作 Viper 编译器生态的**工具集、执行约定与安全约束**，
+覆盖两大编译器：
+
+| 名称 | 实现 | 入口 | 说明 |
+|------|------|------|------|
+| **TPC** | CPython | `TransPyC.py`（单文件）/ `Projectrans.py`（工程级） | 主路径编译器，所有 `Test/` 依赖它 |
+| **TPV** | Viper（自举） | `TransPyV\output\TransPyV.exe` | Viper 语言自写编译器，由 TPC 编译产出 |
+
+客户端（AI 助手等）通过 MCP 服务器的工具调用完成：编译、构建、回归测试、诊断。
+
+---
+
+## 2. 服务器信息
+
+| 字段 | 值 |
+|------|-----|
+| name | `transpyc-tools` |
+| description | TransPyC/TransPyV Viper 编译器控制服务器 |
+| transport | stdio |
+| protocol | MCP 2025-03-26 / 2024-11-05 兼容 |
+| cwd | `D:\Users\TermiNexus\Desktop\TransPyC` |
+
+工具命名空间前缀：`tpc_`（TPC 操作）、`tpv_`（TPV/自举操作）、`tp_`（只读诊断）。
+
+---
+
+## 3. 术语与路径约定
+
+- **project.json**：工程配置，位于 `<工程>/project.json`；`Test/` 下每个子目录即一个测试工程
+- **工程编译**：`Projectrans.py --project <path>` 两阶段（Phase1 声明生成 + Phase2 翻译/编译/链接）
+- **单文件编译**：`TransPyC.py -f <in.vp> -o <out.ll>`，生成 LLVM IR（可再 `-cc`/`-run` 链接运行）
+- **TPV 产物**：`TransPyV\output\TransPyV.exe`（根目录 `TransPyV.exe` 可能为旧版，验证必须用 output 新版）
+- **自举链**：Phase A（TPC 编译 TransPyV → tpv.exe）→ Phase B（tpv.exe 编译自身 → tpv2）→ Phase C（tpv2 → tpv3）
+- **缓存目录**：工程 `temp/`、`output/`、`.tpv_build/`；全局 `.transpyc_cache/`（含 `.vpi` / `.stub.ll` / `.doc.json`）
+- **SHA1 映射**：`<工程>/temp/_sha1_map.txt`，记录源码 SHA1 → 中间产物
+
+路径参数一律使用**相对根目录**或根目录内绝对路径；禁止指向根目录之外。
+
+---
+
+## 4. 工具清单（总览）
+
+| # | 工具 | 分类 | 作用 |
+|---|------|------|------|
+| 1 | `tpc_build` | TPC 工程 | 编译任意 Viper 工程（两阶段 + 可选清理/运行/重建） |
+| 2 | `tpc_build_file` | TPC 单文件 | 单文件 .vp → LLVM IR（可选链接运行） |
+| 3 | `tpc_run_test` | TPC 测试 | 编译并运行单个 `Test/<Name>` 工程 |
+| 4 | `tpc_run_regression` | TPC 测试 | 全量回归（遍历 `Test/*` 编译 + 运行判定） |
+| 5 | `tpc_clean_project` | TPC 维护 | 清理工程 `output/` 与 `temp/`（--clean） |
+| 6 | `tpc_clear_cache` | TPC 维护 | 清除全局 `.transpyc_cache`（--clear-cache） |
+| 7 | `tpc_rebuild_includes` | TPC 维护 | 删除 includes.binary 并重编译所有 includes |
+| 8 | `tpv_build` | TPV 构建 | TPC 编译 TransPyV → `TransPyV\output\TransPyV.exe` |
+| 9 | `tpv_bootstrap` | TPV 自举 | 执行自举链 Phase A/B/C 并对比产物 |
+| 10 | `tpv_compile_project` | TPV 编译 | 用 TPV.exe 编译任意工程（参数同 `tpc_build`） |
+| 11 | `tpv_run_test` | TPV 测试 | 运行 `TransPyV/Test` 自测（含 NegativeTest/Sha1Test） |
+| 12 | `tp_read_ast` | 诊断 | 解析 .vp 源码输出 AST dump（vast） |
+| 13 | `tp_read_log` | 诊断 | 读取项目内日志/输出文件末尾 N 行 |
+| 14 | `tp_sha1_map` | 诊断 | 读取工程 SHA1 映射（_sha1_map.txt） |
+
+---
+
+## 5. 执行约定
+
+### 5.1 工作目录
+所有命令在 `D:\Users\TermiNexus\Desktop\TransPyC`（根目录）执行；路径参数先规范化（`resolve`）再校验。
+
+### 5.2 Python 解释器
+统一使用 `python`（**Python 3.12**）。禁止使用系统内置 3.10。
+约定：`t.py` / `c.py` 为语言基础模块，**不参与编译**。
+
+### 5.3 清理策略
+**禁止手动删除文件**。清理一律通过工具参数映射到命令行选项：
+- `--clean`：清理 `output/` 与 `temp/`
+- `--rebuild-includes`：删除 includes.binary 预编译缓存并重编译 includes
+- `--clear-cache`：清除 `.transpyc_cache` 全局缓存
+
+### 5.4 串行与并发
+- **同一工程目录禁止并行编译**（temp/output 共享，冲突会损坏产物）
+- 服务端维护按工程路径的锁；客户端不应并发发起同一工程的两个 build
+- TPC 并行 worker 数由编译器按可用内存自动限制（`_PickWorkerCount`），服务端不干预
+
+### 5.5 缓存与重建
+- `.vp` 源码 SHA1 未变时，缓存命中会复用旧 `.ll`/`.vpi`
+- **修改 TPC 的 `.py` 编译逻辑后**：需 `--clear-cache` + `--rebuild-includes` 才彻底生效
+- **修改 TPV 的 `.vp` 源码后**：必须 `tpv_build`（内含 `--clean`）做 Phase A 全量重建，否则新逻辑不生效
+- 编译器（TPC 侧）输出内容不可靠时（如 `bitcast i8* null t` 类垃圾 IR），应 `--clear-cache` 后重编
+
+### 5.6 fail-fast
+TPC 编译错误必须立即终止并原样返回错误（traceback 风格），**不兜底、不静默发明值**。
+工具返回值中的 `ok=false` + `exit_code!=0` 即表示失败，客户端应停止后续依赖操作。
+
+### 5.7 环境依赖
+- `llc`（LLVM 静态编译器）、`clang++`（mingw-w64 链接器）须在 PATH
+- TPV 运行时需 **≥ 1 GiB 空闲内存**（启动时 `malloc(1<<30)` 内存池）
+- ASan 模式（`--asan`）需 clang64 环境
+---
+
+## 6. 工具详细定义
+
+> 每个工具给出：`name` / `description` / `inputSchema`（JSON Schema）/ `command`（底层执行）/ `output`（返回结构）。
+> 所有 `command` 均以工作目录为根，路径参数经规范化与**根目录白名单校验**后方可拼接。
+
+### 6.1 tpc_build — 编译 Viper 工程（两阶段）
+
+- description：用 TransPyC 编译任意工程，对应 `Projectrans.py --project`。支持清理、运行、阶段选择、缓存维护。
+- inputSchema：
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "project":       {"type": "string", "description": "project.json 路径（相对根），如 Test/CoroTest/project.json"},
+    "clean":         {"type": "boolean", "default": false, "description": "先清理 output/temp 再编译"},
+    "run":           {"type": "boolean", "default": false, "description": "编译成功后立即运行产物"},
+    "phase":         {"type": "string", "enum": ["1", "2", "all"], "default": "all", "description": "阶段：1=声明生成，2=翻译+编译，all=全部"},
+    "rebuild_includes": {"type": "boolean", "default": false, "description": "删除 includes.binary 并重编译 includes"},
+    "clear_cache":   {"type": "boolean", "default": false, "description": "清除全局 .transpyc_cache"},
+    "asan":          {"type": "boolean", "default": false, "description": "ASan 插桩模式"},
+    "nowarn_register": {"type": "boolean", "default": false, "description": "抑制外部函数返回类型未登记 WARN"},
+    "src":           {"type": "string", "description": "覆盖 source_dir"},
+    "temp":          {"type": "string", "description": "覆盖 temp_dir"},
+    "output":        {"type": "string", "description": "覆盖 output_dir"},
+    "cc":            {"type": "string", "description": "覆盖 LLVM 编译器命令"}
+  },
+  "required": ["project"]
+}
+```
+
+- command：
+
+```powershell
+python Projectrans.py --project <project> [--clean] [--run] [--phase <1|2|all>] [--rebuild-includes] [--clear-cache] [--asan] [--nowarn-register] [--src <src>] [--temp <temp>] [--output <output>] [--cc <cc>]
+```
+
+- output：见 §7；`artifacts.exe` 取 `output_dir` 下新生成的可执行文件路径（依 project.json 的 `linker.output`）。
+
+### 6.2 tpc_build_file — 单文件编译
+
+- description：单文件 `.vp` → LLVM IR（`TransPyC.py -f`），可选 `-cc` 链接 + `-run` 运行。
+- inputSchema：
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "input":  {"type": "string", "description": "输入 .vp 路径（相对根）"},
+    "output": {"type": "string", "description": "输出 .ll 路径（相对根）"},
+    "run":    {"type": "boolean", "default": false, "description": "链接并运行"},
+    "args":   {"type": "string", "description": "运行时参数（空格分隔）"},
+    "level":  {"type": "string", "description": "切片级别，数字或 s"},
+    "encoding": {"type": "string", "default": "utf-8"},
+    "cc":     {"type": "string", "description": "覆盖编译命令（默认见 lib/constants/config）"},
+    "cflags": {"type": "string", "description": "覆盖编译标志"}
+  },
+  "required": ["input", "output"]
+}
+```
+
+- command：
+
+```powershell
+python TransPyC.py -f <input> -o <output> [-cc <cc>] [-cflags <cflags>] [-run] [-args <args>] [-level <level>] [-e <encoding>]
+```
+
+### 6.3 tpc_run_test — 编译并运行单个测试
+
+- description：对 `Test/<Name>` 执行 `--clean --run`（等价手工验证单测试）。
+- inputSchema：
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "name": {"type": "string", "description": "测试名，即 Test/ 下子目录名，如 CoroTest"},
+    "rebuild_includes": {"type": "boolean", "default": false},
+    "clear_cache": {"type": "boolean", "default": false},
+    "asan": {"type": "boolean", "default": false}
+  },
+  "required": ["name"]
+}
+```
+
+- command：
+
+```powershell
+python Projectrans.py --project Test/<name>/project.json --clean --run [--rebuild-includes] [--clear-cache] [--asan]
+```
+
+- 说明：测试工程无 `linker.output` 时产物为 `Test/<name>/output/<name>.exe`（由 project.json 决定）。
+
+### 6.4 tpc_run_regression — 全量回归
+
+- description：运行 `Test/regression_test.py`（遍历所有含 project.json 的测试，编译 + 运行 + 关键词判定）。
+- inputSchema：
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "name": {"type": "string", "description": "可选：只跑匹配名字的测试（按需实现过滤）"},
+    "timeout": {"type": "integer", "default": 300, "description": "单测试编译超时秒数"}
+  },
+  "required": []
+}
+```
+
+- command：
+
+```powershell
+python Test/regression_test.py
+```
+
+- 说明：默认全量耗时较长；客户端应按需使用 `name` 过滤或分片调用。
+
+### 6.5 tpc_clean_project — 清理工程产物
+
+- description：清理工程 `output/` 与 `temp/`（`Projectrans.py --clean`）。
+- inputSchema：`{ "project": {"type":"string"} }`，required: ["project"]。
+- command：`python Projectrans.py --project <project> --clean`
+
+### 6.6 tpc_clear_cache — 清除全局缓存
+
+- description：清除 `.transpyc_cache`（`.vpi` / `.stub.ll` / `.doc.json`），解决缓存腐化。
+- inputSchema：`{ "project": {"type":"string"} }`，required: ["project"]。
+- command：`python Projectrans.py --project <project> --clear-cache`
+- 说明：腐化典型症状——`(1<<N)` 被求值为 1、类型推断退化导致指针截断、`bitcast i8* null t` 垃圾 IR。
+
+### 6.7 tpc_rebuild_includes — 重建 includes 预编译缓存
+
+- description：删除 includes.binary 并重编译所有 includes。
+- inputSchema：`{ "project": {"type":"string"} }`，required: ["project"]。
+- command：`python Projectrans.py --project <project> --rebuild-includes`
+- 说明：修改 `includes/` 下基础模块后必须执行，否则旧符号表残留。### 6.8 tpv_build — 构建 TransPyV
+
+- description：用 TPC 编译 TransPyV（自举第一阶段），产物 `TransPyV\output\TransPyV.exe`。
+- inputSchema：
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "clean": {"type": "boolean", "default": true, "description": "默认全量清理重建（TPV 源码改动必须清缓存）"},
+    "rebuild_includes": {"type": "boolean", "default": true, "description": "TPC 侧 includes 改动时置 true"},
+    "clear_cache": {"type": "boolean", "default": true, "description": "TPC 侧编译器逻辑改动时置 true"}
+  },
+  "required": []
+}
+```
+
+- command：
+
+```powershell
+python Projectrans.py --project TransPyV/project.json --clean [--rebuild-includes] [--clear-cache]
+```
+
+- output：`artifacts.exe = TransPyV/output/TransPyV.exe`
+- 注意：**验证 TPV 行为必须用 `TransPyV\output\TransPyV.exe`**；根目录 `TransPyV.exe` 可能为旧版。TPV 源码 `.vp` SHA1 不变时不清缓存会复用旧 `.ll`，新逻辑不生效。
+
+### 6.9 tpv_bootstrap — 自举链验证
+
+- description：执行 Phase A/B/C 自举，验证 TPV 能编译自身（B/C 阶段由 tpv.exe 驱动）。
+- inputSchema：
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "phases": {"type": "array", "items": {"type": "string", "enum": ["A", "B", "C"]}, "description": "默认 [A,B,C]"},
+    "compare": {"type": "boolean", "default": true, "description": "对比相邻阶段产物（如 tpv vs tpv2 的 sha1）"}
+  },
+  "required": []
+}
+```
+
+- command（示意）：
+
+```powershell
+# Phase A：TPC 编译 TransPyV → tpv.exe
+python Projectrans.py --project TransPyV/project.json --clean
+# Phase B：tpv.exe 编译自身 → tpv2
+TransPyV\output\TransPyV.exe --project TransPyV/project.json --clean --output TransPyV/output2
+# Phase C：tpv2 编译自身 → tpv3
+TransPyV\output\tpv2.exe --project TransPyV/project.json --clean --output TransPyV/output3
+```
+
+- 说明：B/C 阶段的 `--project` 参数与 TPC `Projectrans.py` 一致；产物命名/目录按实现约定。服务器应返回各阶段 exit_code 与产物路径，供客户端对比。
+
+### 6.10 tpv_compile_project — 用 TPV 编译工程
+
+- description：用 `TransPyV\output\TransPyV.exe` 编译任意工程（参数同 `tpc_build`）。
+- inputSchema：同 `tpc_build`（project/clean/run/phase/...）。
+- command：
+
+```powershell
+TransPyV\output\TransPyV.exe --project <project> [--clean] [--run] [--phase <1|2|all>] [--rebuild-includes] [--clear-cache]
+```
+
+- 说明：用于验证 TPV 对既有工程的兼容性；TPV 运行需 ≥ 1 GiB 空闲内存。
+
+### 6.11 tpv_run_test — 运行 TPV 自测
+
+- description：运行 `TransPyV/Test` 下编译器自测（App 用例 + NegativeTest + Sha1Test）。
+- inputSchema：
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "suite": {"type": "string", "enum": ["App", "NegativeTest", "Sha1Test", "all"], "default": "all"},
+    "filter": {"type": "string", "description": "按名字过滤（可选）"}
+  },
+  "required": []
+}
+```
+
+- command（示意）：`TransPyV\output\TransPyV.exe --project TransPyV/Test/project.vpj --clean --run`（或按 suite 分目录调用）。
+- 说明：Test 工程配置在 `TransPyV/Test/project.vpj`，参数透传方式与 `tpv_compile_project` 一致。
+
+### 6.12 tp_read_ast — 解析 AST
+
+- description：解析指定 `.vp` 源码，返回 vast AST dump（compact）与符号级信息。
+- inputSchema：
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "file": {"type": "string", "description": ".vp 源文件路径（相对根）"},
+    "dump": {"type": "string", "enum": ["compact", "full"], "default": "compact"}
+  },
+  "required": ["file"]
+}
+```
+
+- command（示意）：`python -c "import vast as ast,io; print(ast.dump(ast.parse(open(r'<file>',encoding='utf-8').read())))"`
+- 用途：定位 AST 形态（如 `-> None` 是 Constant(CONST_NONE)、`await` 节点位置、extern/export 软关键字标志）。
+
+### 6.13 tp_read_log — 读取日志
+
+- description：读取项目内文本文件（1.log、deps.json、stub.ll 等）末尾 N 行或按正则过滤。
+- inputSchema：
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "file": {"type": "string", "description": "文件路径（相对根），如 1.log"},
+    "lines": {"type": "integer", "default": 50, "description": "返回末尾行数"},
+    "pattern": {"type": "string", "description": "正则过滤（可选）"}
+  },
+  "required": ["file"]
+}
+```
+
+- 说明：用于崩溃栈定位、输出核对；避免整文件灌入上下文。
+
+### 6.14 tp_sha1_map — 读取 SHA1 映射
+
+- description：读取工程 `temp/_sha1_map.txt`，确认哪些源码命中缓存（诊断缓存腐化）。
+- inputSchema：
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "project": {"type": "string", "description": "工程目录（相对根），如 Test/CoroTest"},
+    "filter": {"type": "string", "description": "按文件名过滤（可选）"}
+  },
+  "required": ["project"]
+}
+```
+
+- command：读取 `<project>/temp/_sha1_map.txt`（不存在则返回 `ok=false, error="sha1 map not found"`）。
+---
+
+## 7. 输出格式
+
+所有工具返回统一 JSON 结构：
+
+```json
+{
+  "ok": true,
+  "exit_code": 0,
+  "stdout": "…编译末尾 50 行…",
+  "stderr": "…错误末尾 50 行…",
+  "artifacts": {
+    "exe": "Test/CoroTest/output/CoroTest.exe",
+    "ir": "…",
+    "logs": ["Test/CoroTest/output/…"]
+  },
+  "elapsed_ms": 12345
+}
+```
+
+约定：
+
+- `ok=false` 且 `exit_code!=0` 即失败；`stderr` 原样保留（traceback 风格），**禁止改写/兜底**
+- `stdout`/`stderr` 默认截断为**末尾 50 行**（`tp_read_log` 可通过 `lines` 调整），防止长日志污染上下文
+- `artifacts` 为可选；无产物时省略该字段
+- 运行超时：编译 300s、程序运行 30s（与 `Test/regression_test.py` 对齐）；超时返回 `ok=false, error="timeout"`
+
+## 8. 安全约束
+
+1. **路径白名单**：所有 `file`/`project`/`src`/`temp`/`output` 参数必须先规范化，且必须位于根目录 `D:\Users\TermiNexus\Desktop\TransPyC` 内；越界即拒绝（`ok=false, error="path outside root"`）
+2. **命令白名单**：工具只拼接本协议 §6 中列出的固定命令模板与参数；参数值经 shell 分隔（`shlex.split`）传入，**禁止拼接任意 shell**
+3. **不手动删文件**：清理仅通过 `--clean` / `--rebuild-includes` / `--clear-cache`
+4. **不执行任意代码**：`tp_read_ast` 只解析不执行；编译类工具只跑编译器
+5. **串行锁**：同一工程路径并发 build 会被拒绝（`error="project busy"`）
+6. **内存保护**：TPV 相关工具调用前检查可用内存 ≥ 1 GiB，不足则拒绝并提示
+
+## 9. 错误码
+
+| code | 含义 |
+|------|------|
+| 0 | 成功 |
+| 1 | 编译/运行失败（stdout/stderr 携带详情） |
+| 2 | 参数错误（缺 required / 非法 enum） |
+| 3 | 路径越界（安全约束 §8.1） |
+| 4 | 文件不存在（如 project.json / sha1_map） |
+| 5 | 工程忙（并发冲突，§5.4/§8.5） |
+| 6 | 超时（编译 > 300s / 运行 > 30s） |
+| 7 | 内存不足（TPV 需 ≥ 1 GiB） |
+
+## 10. 扩展
+
+- **工具演进**：新增工具沿用前缀约定与 §6 模板；破坏性变更 bump 协议版本号
+- **只读优先**：诊断类（`tp_`）保持纯只读，可被客户端安全探测
+- **推荐工作流**：改 TPC/TPV 源码 → `tpc_clear_cache`/`tpv_build`（全量重建）→ 目标测试 `tpc_run_test` → 必要时 `tp_read_ast`/`tp_sha1_map` 定位根因 → `tp_read_log` 核对
@@ -0,0 +1,351 @@
+[
+  {
+    "name": "tpc_build",
+    "description": "用 TransPyC 编译任意 Viper 工程（Projectrans.py --project，两阶段）",
+    "inputSchema": {
+      "type": "object",
+      "properties": {
+        "type": "string",
+        "description": "project.json 路径（相对根），如 Test/CoroTest/project.json",
+        "clean": {
+          "type": "boolean",
+          "default": false
+        },
+        "run": {
+          "type": "boolean",
+          "default": false
+        },
+        "phase": {
+          "type": "string",
+          "enum": [
+            "1",
+            "2",
+            "all"
+          ],
+          "default": "all"
+        },
+        "rebuild_includes": {
+          "type": "boolean",
+          "default": false
+        },
+        "clear_cache": {
+          "type": "boolean",
+          "default": false
+        },
+        "asan": {
+          "type": "boolean",
+          "default": false
+        },
+        "nowarn_register": {
+          "type": "boolean",
+          "default": false
+        },
+        "src": {
+          "type": "string"
+        },
+        "temp": {
+          "type": "string"
+        },
+        "output": {
+          "type": "string"
+        },
+        "cc": {
+          "type": "string"
+        }
+      },
+      "required": [
+        "project"
+      ]
+    }
+  },
+  {
+    "name": "tpc_build_file",
+    "description": "单文件 .vp → LLVM IR（TransPyC.py -f），可选链接运行",
+    "inputSchema": {
+      "type": "object",
+      "properties": {
+        "input": {
+          "type": "string",
+          "description": "输入 .vp 路径（相对根）"
+        },
+        "output": {
+          "type": "string",
+          "description": "输出 .ll 路径"
+        },
+        "run": {
+          "type": "boolean",
+          "default": false
+        },
+        "args": {
+          "type": "string"
+        },
+        "level": {
+          "type": "string"
+        },
+        "encoding": {
+          "type": "string",
+          "default": "utf-8"
+        },
+        "cc": {
+          "type": "string"
+        },
+        "cflags": {
+          "type": "string"
+        }
+      },
+      "required": [
+        "input",
+        "output"
+      ]
+    }
+  },
+  {
+    "name": "tpc_run_test",
+    "description": "编译并运行单个 Test/<Name>（--clean --run）",
+    "inputSchema": {
+      "type": "object",
+      "properties": {
+        "name": {
+          "type": "string",
+          "description": "Test/ 下子目录名，如 CoroTest"
+        },
+        "rebuild_includes": {
+          "type": "boolean",
+          "default": false
+        },
+        "clear_cache": {
+          "type": "boolean",
+          "default": false
+        },
+        "asan": {
+          "type": "boolean",
+          "default": false
+        }
+      },
+      "required": [
+        "name"
+      ]
+    }
+  },
+  {
+    "name": "tpc_run_regression",
+    "description": "全量回归（Test/regression_test.py）",
+    "inputSchema": {
+      "type": "object",
+      "properties": {
+        "name": {
+          "type": "string",
+          "description": "可选过滤测试名"
+        },
+        "timeout": {
+          "type": "integer",
+          "default": 300
+        }
+      },
+      "required": []
+    }
+  },
+  {
+    "name": "tpc_clean_project",
+    "description": "清理工程 output/temp（--clean）",
+    "inputSchema": {
+      "type": "object",
+      "properties": {
+        "type": "string",
+        "description": "project.json 路径（相对根），如 Test/CoroTest/project.json"
+      },
+      "required": [
+        "project"
+      ]
+    }
+  },
+  {
+    "name": "tpc_clear_cache",
+    "description": "清除全局 .transpyc_cache（--clear-cache）",
+    "inputSchema": {
+      "type": "object",
+      "properties": {
+        "type": "string",
+        "description": "project.json 路径（相对根），如 Test/CoroTest/project.json"
+      },
+      "required": [
+        "project"
+      ]
+    }
+  },
+  {
+    "name": "tpc_rebuild_includes",
+    "description": "重建 includes.binary 预编译缓存（--rebuild-includes）",
+    "inputSchema": {
+      "type": "object",
+      "properties": {
+        "type": "string",
+        "description": "project.json 路径（相对根），如 Test/CoroTest/project.json"
+      },
+      "required": [
+        "project"
+      ]
+    }
+  },
+  {
+    "name": "tpv_build",
+    "description": "TPC 编译 TransPyV → TransPyV/output/TransPyV.exe（Phase A）",
+    "inputSchema": {
+      "type": "object",
+      "properties": {
+        "clean": {
+          "type": "boolean",
+          "default": true
+        },
+        "rebuild_includes": {
+          "type": "boolean",
+          "default": true
+        },
+        "clear_cache": {
+          "type": "boolean",
+          "default": true
+        }
+      },
+      "required": []
+    }
+  },
+  {
+    "name": "tpv_bootstrap",
+    "description": "自举链 Phase A/B/C 验证并对比产物",
+    "inputSchema": {
+      "type": "object",
+      "properties": {
+        "phases": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "enum": [
+              "A",
+              "B",
+              "C"
+            ]
+          },
+          "default": [
+            "A",
+            "B",
+            "C"
+          ]
+        },
+        "compare": {
+          "type": "boolean",
+          "default": true
+        }
+      },
+      "required": []
+    }
+  },
+  {
+    "name": "tpv_compile_project",
+    "description": "用 TransPyV/output/TransPyV.exe 编译工程（参数同 tpc_build）",
+    "inputSchema": {
+      "type": "object",
+      "properties": {
+        "name": {
+          "type": "string",
+          "description": "可选过滤测试名"
+        },
+        "timeout": {
+          "type": "integer",
+          "default": 300
+        }
+      },
+      "required": [
+        "project"
+      ]
+    }
+  },
+  {
+    "name": "tpv_run_test",
+    "description": "运行 TransPyV/Test 自测（App/NegativeTest/Sha1Test）",
+    "inputSchema": {
+      "type": "object",
+      "properties": {
+        "suite": {
+          "type": "string",
+          "enum": [
+            "App",
+            "NegativeTest",
+            "Sha1Test",
+            "all"
+          ],
+          "default": "all"
+        },
+        "filter": {
+          "type": "string"
+        }
+      },
+      "required": []
+    }
+  },
+  {
+    "name": "tp_read_ast",
+    "description": "解析 .vp 源码输出 vast AST dump",
+    "inputSchema": {
+      "type": "object",
+      "properties": {
+        "file": {
+          "type": "string",
+          "description": ".vp 源文件路径（相对根）"
+        },
+        "dump": {
+          "type": "string",
+          "enum": [
+            "compact",
+            "full"
+          ],
+          "default": "compact"
+        }
+      },
+      "required": [
+        "file"
+      ]
+    }
+  },
+  {
+    "name": "tp_read_log",
+    "description": "读取项目内文本文件末尾 N 行或正则过滤",
+    "inputSchema": {
+      "type": "object",
+      "properties": {
+        "file": {
+          "type": "string",
+          "description": "文件路径（相对根），如 1.log"
+        },
+        "lines": {
+          "type": "integer",
+          "default": 50
+        },
+        "pattern": {
+          "type": "string"
+        }
+      },
+      "required": [
+        "file"
+      ]
+    }
+  },
+  {
+    "name": "tp_sha1_map",
+    "description": "读取工程 temp/_sha1_map.txt（诊断缓存命中）",
+    "inputSchema": {
+      "type": "object",
+      "properties": {
+        "project": {
+          "type": "string",
+          "description": "工程目录（相对根），如 Test/CoroTest"
+        },
+        "filter": {
+          "type": "string"
+        }
+      },
+      "required": [
+        "project"
+      ]
+    }
+  }
+]