TransPyC/MCP/README.md

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 方式运行于项目根目录：

{
  "mcpServers": {
    "transpyc-tools": {
      "command": "python",
      "args": ["-m", "transpyc_mcp.server"],
      "cwd": "D:\\Users\\TermiNexus\\Desktop\\TransPyC"
    }
  }
}

实现规范见 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）