autocode-mcp 0.8.0

MCP Server for competitive programming problem creation, based on AutoCode paper

AutoCode MCP Server

基于论文《AutoCode: LLMs as Problem Setters for Competitive Programming》实现的竞赛编程出题辅助 MCP Server。

AutoCode MCP Server 提供 15 个原子工具，让 AI 助手能够创建、验证和测试竞赛编程题目。它负责编译、执行、压力测试和测试数据生成——让 AI 专注于题目设计和解法逻辑。

特性

• Validator-Generator-Checker 框架 — 基于论文实现输入正确性自动验证、多策略测试生成和输出验证
• 15 个原子工具 — 文件操作、解法构建、压力测试、校验器/生成器/检查器构建等
• testlib.h 支持 — 完整集成竞赛编程标准库，用于校验器、生成器和检查器
• 多策略生成 — 四种生成策略：tiny（穷举）、random（随机）、extreme（边界情况）、tle（诱导超时）
• 压力测试 — 自动比较最优解和暴力解，可配置测试轮数
• MCP 协议 — 原生支持 Claude Code、Cursor 等 MCP 兼容的 AI 工具
• 执行控制 — 超时控制、内存限制（Linux）、临时目录隔离（仅限本地可信环境）
• Polygon 打包 — 导出为 Polygon 格式，适用于 Codeforces 等平台

安装

1. Claude Code 市场安装（推荐）

本仓库已经按官方 Claude Code plugin 结构组织：

• .claude-plugin/plugin.json
• settings.json
• agents/autocode-workflow.md
• hooks/hooks.json
• scripts/workflow_guard.py
• .mcp.json

这个插件不只是暴露 MCP server，还会一起安装：

• 默认工作流 agent
• AutoCode 工作流 skill
• 用于阻止跳步的 hooks

推荐通过 Claude Code marketplace 安装，这样会同时安装 plugin manifest、agent、skills 和 workflow hooks。

claude plugin marketplace add https://github.com/SummerOneTwo/autocode-marketplace.git
claude plugin install autocode@autocode-marketplace

注意：marketplace 默认从 https://github.com/SummerOneTwo/AutoCode.git 远程安装，所以测试远程安装前需要先把插件改动 push 到 GitHub。

2. 从 PyPI 安装

pip install autocode-mcp

3. 其它通用安装方式

使用 uv 安装

uv tool install autocode-mcp

从源码安装

git clone https://github.com/SummerOneTwo/AutoCode.git
cd AutoCode
uv sync

前置要求

• Python 3.10+
• g++ 编译器，支持 C++20（推荐 GCC 10+）
• testlib.h（已内置在 src/autocode_mcp/templates/）

验证安装：

# 检查 Python 版本
python --version

# 检查 g++ 版本
g++ --version

# 运行测试
uv run pytest tests/ -v

快速开始

1. 安装插件

推荐直接通过 Claude Code marketplace 安装：

claude plugin marketplace add https://github.com/SummerOneTwo/autocode-marketplace.git
claude plugin install autocode@autocode-marketplace

如果你只是想把 MCP server 作为通用组件使用，再选择 PyPI、uv 或源码安装。

2. 创建你的第一个题目

在 Claude Code 中，只需说：

"创建一道竞赛编程题目：给定两个整数 A 和 B，输出它们的和。"

Claude 将使用 AutoCode 工具：

1. 生成题目描述
2. 实现解法（最优解 + 暴力解）
3. 构建校验器和生成器
4. 运行压力测试
5. 生成最终测试数据

客户端配置

传输层与兼容性

推荐方式：直接作为 Claude Code plugin 安装。

当前支持：仅支持本地 stdio 传输。服务器通过标准输入/输出流通信，适用于本地可信环境。

客户端
Claude Code
Cursor
OpenCode

不支持：HTTP/SSE 传输、远程连接或多租户环境。

Claude Code Plugin

推荐的插件文件：

• .claude-plugin/plugin.json
• settings.json
• agents/autocode-workflow.md
• hooks/hooks.json
• scripts/workflow_guard.py

其他 MCP 客户端

同一个 MCP server 也可用于其他本地 MCP 客户端，但工作流强制约束的 agent 和 hooks 是 Claude Code plugin 能力。

Cursor

添加到 Cursor 设置（Settings → MCP）：

{
  "mcp": {
    "servers": {
      "autocode": {
        "command": "autocode-mcp"
      }
    }
  }
}

OpenCode

编辑 ~/.config/opencode/opencode.json：

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "autocode": {
      "type": "local",
      "command": ["uvx", "autocode-mcp"],
      "enabled": true
    }
  }
}

验证安装

配置完成后，重启 MCP 客户端并检查工具是否可用。你应该能看到 15 个工具，包括 solution_build、validator_build、generator_build 等。

工具参考

AutoCode 提供 15 个原子工具，分为 7 组。所有工具返回统一格式：

{
  "success": true,
  "error": null,
  "data": { ... }
}

文件操作

工具	描述	关键参数
file_save	保存内容到文件	path, content
file_read	读取文件内容	path

解法工具

工具	描述	关键参数
solution_build	编译解法代码	problem_dir, solution_type ("sol"/"brute"), code
solution_run	执行已编译的解法	problem_dir, solution_type, input_data, timeout

校验器工具

工具	描述	关键参数
validator_build	构建并测试校验器	problem_dir, code, test_cases
validator_select	从候选中选择最佳校验器	candidates

生成器工具

工具	描述	关键参数
generator_build	编译生成器	problem_dir, code
generator_run	生成测试输入	problem_dir, strategies, test_count, validator_path

检查器工具

工具	描述	关键参数
checker_build	构建输出检查器	problem_dir, code, test_scenarios

交互器工具

工具	描述	关键参数
interactor_build	构建交互题的交互器	problem_dir, code, reference_solution_path, mutant_solutions

压力测试

工具	描述	关键参数
stress_test_run	比较 sol 和 brute 输出	problem_dir, trials, n_max, timeout

题目管理

工具	描述	关键参数
problem_create	初始化题目目录	problem_dir, problem_name
problem_generate_tests	生成最终测试数据（最终数据集中 extreme/tle 至少占一半，候选不足时尽量满足）	problem_dir, test_count
problem_verify_tests	验证测试数据质量（含 extreme/tle 占比硬校验）	problem_dir, tests_dir, verify_types
problem_pack_polygon	打包为 Polygon 格式	problem_dir, time_limit, memory_limit

工作流教程：A+B 问题

本教程演示如何使用 AutoCode 工具创建一道简单的 A+B 问题。

步骤 1：初始化题目

problem_create(
    problem_dir="problems/ab",
    problem_name="A + B"
)

步骤 2：实现解法

最优解（sol.cpp）：

#include <iostream>
int main() {
    int a, b;
    std::cin >> a >> b;
    std::cout << a + b << std::endl;
    return 0;
}

暴力解（brute.cpp）：

#include <iostream>
int main() {
    int a, b;
    std::cin >> a >> b;
    // 对于 A+B 问题与最优解相同，但复杂问题可能更慢
    std::cout << a + b << std::endl;
    return 0;
}

构建两个解法：

solution_build(problem_dir="problems/ab", solution_type="sol", code="...")
solution_build(problem_dir="problems/ab", solution_type="brute", code="...")

步骤 3：构建校验器

#include "testlib.h"
int main(int argc, char* argv[]) {
    registerValidation(argc, argv);
    int a = inf.readInt(-1000, 1000, "a");
    inf.readSpace();
    int b = inf.readInt(-1000, 1000, "b");
    inf.readEoln();
    inf.readEof();
    return 0;
}

构建并测试：

validator_build(
    problem_dir="problems/ab",
    code="...",
    test_cases=[
        {"input": "1 2\n", "expected_valid": True},
        {"input": "0 0\n", "expected_valid": True},
        {"input": "-1000 1000\n", "expected_valid": True},
        {"input": "1001 0\n", "expected_valid": False},  # 超出范围
        {"input": "1 2 3\n", "expected_valid": False},   # 多余数字
    ]
)

步骤 4：构建生成器

#include "testlib.h"
#include <iostream>
int main(int argc, char* argv[]) {
    registerGen(argc, argv, 1);
    int seed = atoi(argv[1]);
    int type = atoi(argv[2]);
    rnd.setSeed(seed);
    
    int a = rnd.next(-1000, 1000);
    int b = rnd.next(-1000, 1000);
    std::cout << a << " " << b << std::endl;
    return 0;
}

构建并运行：

generator_build(problem_dir="problems/ab", code="...")

generator_run(
    problem_dir="problems/ab",
    strategies=["random", "extreme"],
    test_count=20,
    validator_path="problems/ab/val.exe"
)

步骤 5：压力测试

stress_test_run(
    problem_dir="problems/ab",
    trials=1000,
    n_max=100,
    timeout=30
)

预期输出：

All 1000 rounds passed

步骤 6：生成最终测试

problem_generate_tests(
    problem_dir="problems/ab",
    test_count=50
)

说明：最终写入的测试中，extreme（type=3）与 tle（type=4）合计不少于一半；若候选里极限类不足，则会在可用候选范围内尽量满足并返回对应统计字段。

步骤 7：打包为 Polygon 格式

problem_pack_polygon(
    problem_dir="problems/ab",
    time_limit=1,
    memory_limit=256
)

架构

Validator-Generator-Checker 框架

┌─────────────────┐
│   题面设计      │
└────────┬────────┘
         │
         ▼
┌─────────────────┐     ┌──────────────┐
│  解法构建       │────►│  Validator   │ 验证输入约束
│  (sol + brute)  │     └──────────────┘
└────────┬────────┘
         │
         ▼
┌─────────────────┐     ┌──────────────┐
│  Generator      │────►│  Stress Test │ 比较 sol 和 brute
│  多策略生成     │     └──────────────┘
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  Checker        │ 验证输出正确性
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  Polygon 打包   │ 导出为平台格式
└─────────────────┘

设计原则

1. 纯工具模式，无 LLM — Server 提供编译、执行和验证。所有代码生成由客户端 LLM 完成。

2. 无状态设计 — 每次工具调用独立。状态通过 problem_dir 参数管理。

3. 统一返回格式 — 所有工具返回 {success, error, data}，便于一致的错误处理。

4. 安全执行 — 超时控制、内存限制（Linux 通过 prlimit）、临时目录隔离。

安全边界

⚠️ 重要提示：本工具仅适用于本地可信环境

文件操作

• 指定 problem_dir 参数时：file_read 和 file_save 限制在指定目录内访问
• 不指定 problem_dir 参数时：这些工具可以读写任意路径的文件
• 建议：调用文件操作时始终指定 problem_dir 以限制访问范围

代码执行

• 编译并执行 AI 生成的 C++ 代码，仅提供时间/内存限制
• 无沙箱隔离（Linux 上仅通过 prlimit 限制内存）
• 风险：畸形或恶意代码可能影响系统

适用场景

✅ 适用于：

• 本地开发机器
• 竞赛编程出题
• 可信环境下的 AI 辅助编程
• 有定期备份的个人工作站

❌ 不适用于：

• 多租户环境
• 不可信代码执行
• 生产级代码运行平台
• 无隔离的共享服务器

安全加固建议

如需更强的安全隔离，建议：

• 在 Docker 容器中运行
• 使用虚拟机
• 在操作系统层面限制文件系统权限
• 以非特权用户身份运行

生成策略

策略	类型码	用途
tiny	1	小数据穷举测试（N ≤ 10）
random	2	约束范围内的随机数据
extreme	3	边界情况：溢出、精度、hash 碰撞
tle	4	诱导 TLE 的性能测试数据

problem_generate_tests 的默认采样策略会优先保证最终测试集中 extreme + tle 至少占 50%，剩余名额再按配置平衡分配（或按确定性顺序填充）。

文件结构

problems/your-problem/
├── files/
│   ├── testlib.h       # 竞赛编程标准库
│   ├── gen.cpp         # 测试生成器
│   ├── val.cpp         # 输入校验器
│   ├── checker.cpp     # 输出检查器（可选）
│   └── interactor.cpp  # 交互器（交互题）
├── solutions/
│   ├── sol.cpp         # 最优解
│   └── brute.cpp       # 暴力解（用于验证）
├── statements/
│   └── README.md       # 题目描述
├── tests/
│   ├── 01.in           # 测试输入
│   ├── 01.ans          # 期望输出
│   └── ...
└── problem.xml         # Polygon 配置

开发

环境搭建

git clone https://github.com/SummerOneTwo/AutoCode.git
cd AutoCode
uv sync

运行测试

# 运行所有测试
uv run pytest tests/ -v

# 运行并生成覆盖率报告
uv run pytest tests/ --cov=src/autocode_mcp --cov-report=html

# 运行特定测试文件
uv run pytest tests/test_compiler.py -v

代码质量

# Lint 检查
uv run ruff check .

# 类型检查
uv run mypy src/

# 格式化
uv run ruff format .

项目结构

autocode-mcp/
├── src/autocode_mcp/
│   ├── tools/           # MCP 工具实现
│   │   ├── base.py      # 工具基类
│   │   ├── solution.py  # 解法工具
│   │   ├── validator.py # 校验器工具
│   │   ├── generator.py # 生成器工具
│   │   ├── checker.py   # 检查器工具
│   │   ├── stress_test.py
│   │   └── ...
│   ├── utils/
│   │   ├── compiler.py  # C++ 编译工具
│   │   └── platform.py  # 平台相关辅助函数
│   ├── prompts/         # 工作流提示词模板
│   ├── resources/       # 模板资源
│   └── server.py        # MCP server 入口
├── tests/               # 测试套件
└── pyproject.toml

添加新工具

1. 在 src/autocode_mcp/tools/ 创建新文件
2. 继承 Tool 基类
3. 实现 name、description、input_schema 和 execute()
4. 在 server.py 中注册
5. 在 tests/ 中添加测试

贡献

查看 CONTRIBUTING.md 了解贡献指南。

故障排查

查看 TROUBLESHOOTING.md 了解常见问题和解决方案。

许可证

MIT License - 详见 LICENSE。

致谢

• 基于论文 "AutoCode: LLMs as Problem Setters for Competitive Programming"
• 使用 testlib.h 竞赛编程工具库
• 基于 Model Context Protocol 构建

链接

• 文档
• PyPI
• GitHub
• Issue Tracker