# 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）