TermiNexus
44124b2f2f
- git mv .mcp.json → MCP/.mcp.json（cwd 保持项目根，args 相对项目根解析） - README 更新 .mcp.json 位置说明
69 lines
3.5 KiB
Markdown
69 lines
3.5 KiB
Markdown
# 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（可选生成，供客户端加载） |
|
||
| `transpyc_mcp/` | MCP 服务器实现（stdio，零依赖） |
|
||
|
||
## 快速接入
|
||
|
||
MCP 目录下已创建 `.mcp.json`（位于 `MCP/.mcp.json`），客户端（IDE/工具）按其中 cwd+args 自动注册 MCP 服务器 `transpyc-tools`（服务器代码位于 `MCP/transpyc_mcp/`，stdio 零依赖，也可手动 `python MCP/transpyc_mcp/server.py` 启动）：
|
||
|
||
```json
|
||
{
|
||
"mcpServers": {
|
||
"transpyc-tools": {
|
||
"command": "python",
|
||
"args": ["MCP/transpyc_mcp/server.py"],
|
||
"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）
|
||
- 非生产环境默认推荐 `--asan`；ASan/非 ASan 切换必须 `--rebuild-includes` 重建 includes.binary 缓存 |