Sounio Compiler

Sounio MCP 服务

sounio-mcp-server 通过本地 Model Context Protocol stdio 传输，将经过检查的 Sounio 编译器开放给 Agent 工具使用。它特意限定为仅在本地运行：不支持 HTTP 传输、OAuth、令牌处理，也没有远程执行路径。

安装

pip install -e tools/mcp
python -m sounio_mcp.server --transport stdio

Claude Code：

claude --mcp-server sounio=python:-m:sounio_mcp.server

服务通过 scripts/lib/resolve_souc.sh 解析 souc；在此检出版本中，该脚本会解析到经过检查的自托管启动器（在支持的主机上为 bin/souc）。服务会拒绝 /workspace/sounio 之外的源文件路径。

工具调用会同时返回 MCP 文本内容和 structuredContent。文本内容让提示词中的 shell 示例保持简洁；structuredContent 则让有类型的 MCP 客户端能够直接使用结果，无需重新解析 JSON 文本。

工具

sounio_check

对 .sio 文件进行类型检查，并返回根据 souc check --json 规范化的诊断信息。

示例：

{
  "source_path": "tests/fixtures/broken_dose.sio"
}

响应包含两种诊断视图：

• diagnostics：便于 Agent 使用的记录，包含字符串类型的严重程度、从 1 开始计数的 line/column、范围、相关备注和警告。
• diagnostic_envelope：CC-1/CC-2 共享的 sounio.diagnostic.v1 信封，并根据 tools/shared/diagnostic_schema.json 进行验证。

sounio_compile

运行 sounio_check，然后将有效文件编译为本地制品。

示例：

{
  "source_path": "examples/hello.sio",
  "target": "elf",
  "optimization": "default"
}

支持的目标包括 elf、macho、ptx、metal 或 wasm。当前经过检查的启动器对主机原生 ELF 的支持最完善；其他目标会传递给编译器的目标标志，如果不受支持则会如实报告。

sounio_run

运行 souc run，捕获 stdout/stderr/退出代码，并报告 compile_error、runtime_error、timeout 或 ok。

示例：

{
  "source_path": "examples/hello.sio",
  "args": [],
  "timeout_sec": 30
}

环境变量覆盖仅允许用于非敏感键。包含令牌、秘密、凭据、代理或身份验证材料的键会被拒绝。

sounio_test

使用经过检查的编译器，以编程方式运行 Sounio 测试目录或文件。

示例：

{
  "test_pattern": "tests/run-pass",
  "test_filter": "hello"
}

测试运行器能够识别现有的 //@ run-pass、//@ compile-fail、//@ check-only、//@ expect-stdout、//@ expect-stdout-contains、//@ error-pattern 和 //@ ignore 注解。

资源

• sounio://stdlib/{module} 返回标准库 README/源代码上下文。
• sounio://errors/{error_code} 返回编译器错误说明，内容依据当前编译器源码或已提交的编译失败证据追溯。

示例：

sounio://stdlib/stats
sounio://stdlib/clinical
sounio://errors/E070

错误 -> 修复循环

该循环刻意保持精简：

1. Agent 编写或编辑 .sio 文件。
2. Agent 调用 sounio_check。
3. 诊断信息会注入下一条提示词。
4. Agent 修改文件。
5. Agent 重复此流程，直到诊断信息为空或达到迭代次数上限。

可复现的本地演示：

PYTHONPATH=tools/mcp python3 tools/mcp/examples/llmloop_recipe.py \
  --fixtures 'tests/fixtures/broken/*.sio' \
  --max-iter 10 \
  --seed 1729

当前基准测试样例：

• 样例：20
• Agent 模型：deterministic-fixture-agent-v0.1
• 随机种子：1729
• 收敛率：1.0
• 平均迭代次数：1.0

这是 LLMloop 模式的一种本地用法示例，并非对托管模型的性能声明。它旨在让 Claude Code、Cursor、通过 MCP 使用的 ChatGPT，以及 CLI Agent 使用真实的 Sounio 编译器完成相同的检查/修复/重新检查循环。

跨 Agent 使用

• CC-1 维护 tools/shared/diagnostic_schema.json；MCP 使用相同的 souc check --json 数据结构，并保留与 LSP 兼容的 range 字段。
• Cx-1 应使用 sounio_check 作为验证生成的数据集样例的标准方法。
• 生成翻译后的 .sio 文件后，Cx-2 可以使用 sounio_run 作为 HumanEval/MultiPL-E 执行框架。

质量说明

• 不会修改编译器二进制文件。
• 未实现远程 MCP 传输。
• 错误目录中的条目均有跟踪记录作为依据；对于未知代码，会返回明确标注为“尚未推广”的资源，而不是编造解释。
• 经检查的启动器的 compile 兼容模式即使未生成制品，也可能以零状态码退出，因此 sounio_compile 会验证输出是否存在。
• 精简的 Python 测试门禁涵盖直接工具、架构验证、单次 JSON-RPC，以及通过标准输入输出建立的真实 mcp Python SDK 客户端会话。