Catobot Autoexperiment MCP

CatoBot自动实验MCP服务器

用于自主实验的域无关MCP服务器

文档地图

• 核心用法和设置：此README
• 示例目录： example_experiments/README.md
• 实验设计指南： example_experiments/Autoexperiment_Design_Guide.md
• 贡献指南： CONTRIBUTING.md
• 安全策略： SECURITY.md
• 支持渠道： SUPPORT.md
• 许可证和通知： LICENSE, NOTICE

示例实验

• 仅限壳牌使用CatoBot自动实验MCP进行实验： example_experiments/shell/

模式

modify something → run it → measure a result → keep or discard → repeat

服务器将此循环作为一组标准的MCP工具公开。这 领域 （修改的内容、运行方式以及测量的内容）完全在JSON配置文件中定义。无论域如何，代理端逻辑都保持不变。

建筑

┌─────────────────────────────────────────────────────┐
│  AI Agent (Claude Code, Codex, etc.)                │
│                                                     │
│  Reads status → plans change → edits file →         │
│  runs experiment → checks result → keeps/discards   │
└──────────────┬──────────────────────────────────────┘
               │ MCP (stdio)
┌──────────────▼──────────────────────────────────────┐
│  autoexperiment MCP server                                 │
│                                                     │
│  Tools:                                             │
│    autoexp_get_status          — session overview    │
│    autoexp_read_file           — read allowed file   │
│    autoexp_update_file         — full file replace   │
│    autoexp_patch_file          — targeted find/repl  │
│    autoexp_run_experiment      — execute + measure   │
│    autoexp_begin_experiment    — open pending record │
│    autoexp_complete_experiment — close with metric   │
│    autoexp_set_baseline        — mark as baseline    │
│    autoexp_rollback            — revert to last good │
│    autoexp_get_history         — review past runs    │
│    autoexp_run_setup           — one-time setup      │
│                                                     │
│  Resources:                                         │
│    autoexp://status        — session status (JSON)   │
│    autoexp://history       — experiment history      │
│    autoexp://file/{path}   — read allowed files      │
│                                                     │
│  Config:  autoexperiment.json  (domain adapter)     │
│  Ledger:  .autoexperiment_ledger.json (state)       │
└──────────────┬──────────────────────────────────────┘
               │ subprocess / external MCP server
┌──────────────▼──────────────────────────────────────┐
│  Your domain                                        │
│  (training script, benchmark, simulation, etc.)     │
└─────────────────────────────────────────────────────┘

代码结构

服务器被实现为Python包(autoexperiment_mcp/)与薄 server.py 入口点：

autoexperiment-mcp-server/
├── server.py                         # Entry point: imports mcp, calls mcp.run()
└── autoexperiment_mcp/
    ├── models.py                     # Pydantic models (DomainConfig, ExperimentRecord, …)
    ├── utils.py                      # Pure utilities (git, hash, path, regex, time, coercion)
    ├── store.py                      # State I/O, snapshot management, TSV logging, query helpers
    ├── experiment.py                 # Core lifecycle: begin/complete experiment, keep decision
    ├── lifespan.py                   # Startup validation, app_lifespan context manager
    ├── app.py                        # mcp = FastMCP("autoexperiment_mcp", lifespan=…)
    ├── tools.py                      # All 11 @mcp.tool() registrations
    ├── resources.py                  # All 3 @mcp.resource() registrations
    └── __init__.py                   # Imports app + triggers tool/resource registration

安装

先决条件

• python 3.12 或更高
• uv 包管理器

安装 uv

macOS/Linux

curl -LsSf https://astral.sh/uv/install.sh | sh

Windows（PowerShell）

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

了解更多： 星光散射/紫外线

克隆存储库

git clone https://github.com/IamCatoBot/catobot-autoexperiment-mcp.git
cd catobot-autoexperiment-mcp

安装依赖项

uv sync

快速开始

1.准备你的实验文件夹

您的实验文件夹需要一个工作基线、一个评估脚本和一个配置文件：

my-experiment/
├── autoexperiment.json     ← config (you write this)
├── solution.py             ← editable (agent modifies this)
├── benchmark.py            ← evaluation (read-only)
└── data.csv                ← test data (read-only)

2.创建autoexperiment.json

{
  "project_name": "My Experiment",
  "description": "What you're trying to optimise",
  "workspace_dir": "/absolute/path/to/my-experiment",
  "editable_files": ["solution.py"],
  "read_only_files": ["benchmark.py", "data.csv"],
  "run_command": "python benchmark.py 2>&1",
  "timeout_seconds": 60,
  "metric_name": "rmse",
  "metric_regex": "^rmse:\\s*([\\d.]+)",
  "metric_direction": "lower",
  "use_git": true
}

3.在实验文件夹中初始化git

默认情况下启用Git跟踪(use_git: true).实验文件夹 必须 成为一个git存储库，在服务器启动之前进行初始提交。

cd /path/to/my-experiment
git init
git add -A
git commit -m "initial baseline"

4.验证run命令是否有效

手动运行您的实验命令，并检查输出是否包含预期格式的指标：

cd /path/to/my-experiment
python benchmark.py
# Should print something like:  rmse: 12.345678

5.注册MCP服务器

推荐：通过 AUTOEXPERIMENT_CONFIG 指向您的配置文件。MCP主机可能会从不同的工作目录启动服务器进程，因此显式路径是最安全的默认路径。

克劳德代码 (-e 对于env变量）：

claude mcp add autoexperiment \
  -e AUTOEXPERIMENT_CONFIG=/path/to/my-experiment/autoexperiment.json \
  -- uv run \
  --project PATH_TO_AUTOEXPERIMENT_MCP_SERVER \
  python PATH_TO_AUTOEXPERIMENT_MCP_SERVER/server.py

法典 (--env 对于env变量）：

codex mcp add autoexperiment \
  --env AUTOEXPERIMENT_CONFIG=/path/to/my-experiment/autoexperiment.json \
  -- uv run \
  --project PATH_TO_AUTOEXPERIMENT_MCP_SERVER \
  python PATH_TO_AUTOEXPERIMENT_MCP_SERVER/server.py

替换 /path/to/my-experiment/autoexperiment.json 带有配置文件的绝对路径。

可选快捷方式：如果服务器进程是从您的实验文件夹启动的，并且配置文件名为 autoexperiment.json，可以省略环境变量。

您只需在每个MCP客户端配置文件中注册一次MCP服务器；之后，在新会话中正常重新连接。

注： 替换 PATH_TO_AUTOEXPERIMENT_MCP_SERVER 使用克隆存储库的实际路径。如果 uv 找不到命令，运行 which uv （Unix）或 Get-Command uv （PowerShell）并使用中的完整路径 "command" 现场。

6.开始实验

从您的实验文件夹中启动Claude Code、Codex或其他MCP客户端，并提示它：

读取实验状态，查看可编辑和只读文件， 首先运行基线，然后迭代，直到改进达到平稳状态 没有任何有意义的收获。

安全警告

setup_command 和 run_command 在主机上执行shell命令。默认情况下，此服务器不提供沙盒或容器隔离。

启动验证

服务器在启动时验证配置，并在以下情况下拒绝启动：

• workspace_dir 不存在或不是目录
• 中的任何文件 editable_files 或 read_only_files 缺失
• 文件同时出现在两个中 editable_files 和 read_only_files
• metric_regex 不是有效的正则表达式
• use_git 是 true 但工作区不是git存储库

错误消息是具体的，并确切地告诉您要修复什么。

配置

特定领域的一切都存在 autoexperiment.json:

保留政策

这 keep_policy 对象控制完成实验的时间 *保持* 对比 *丢弃*所有的门都必须通过才能保持运行。

代理人看到了全部 keep_policy 在 autoexp_get_status 并接收a required_metadata_keys 每一个提醒 autoexp_begin_experiment 响应——因此它总是确切地知道要包含什么 metadata 通话时发生争执 autoexp_complete_experiment.

工具参考

循环是如何工作的

外壳模式(execution_mode: "shell")

1. 客服电话 autoexp_get_status → 学习领域、度量和当前最佳值。
2. 客服电话 autoexp_read_file → 读取可编辑文件以理解代码。
3. 客服电话 autoexp_patch_file 或 autoexp_update_file → 做出改变。
4. 客服电话 autoexp_run_experiment 有一个假设→ 服务器运行它，提取指标。
5. 如果改进：服务器通过git自动提交并记录提交哈希。特工计划下一个实验。
6. 如果倒退或崩溃：代理调用 autoexp_rollback，然后尝试其他东西。
7. 客服电话 autoexp_get_history 定期审查趋势，避免重复。
8. 无限重复。

外部/混合模式(execution_mode: "external" 或 "hybrid")

当另一台MCP服务器（例如物理模拟、云评估器）运行实验时，请使用此选项。

1. 客服电话 autoexp_get_status → 注意 keep_policy 字段——它列出了策略将打开的每个元数据键。
2. 代理通过以下方式编辑可编辑文件 autoexp_update_file / autoexp_patch_file.
3. 客服电话 autoexp_begin_experiment → 接收 experiment_id 和一个 required_metadata_keys 提醒。
4. 代理触发外部系统并等待结果。
5. 代理组装 metadata dict包含 全部 钥匙来自 required_metadata_keys （均来自模拟输出 和 中定义的任何输入参数约束 numeric_min/numeric_max).
6. 客服电话 autoexp_complete_experiment 和 experiment_id, metric_value，和组装 metadata 字典
7. 服务器评估保留策略并响应 kept, keep_reason, is_best.
8. 如果没有保留：代理电话 autoexp_rollback 并调整其方法。

重要提示： numeric_min/numeric_max 盖茨经常引用 *输入* 参数（例如配置文件中的服务时间界限）而不是模拟输出。你必须自己阅读这些价值观，并将其纳入 metadata 以及模拟器的结果。

设计原则

• 领域无关。 服务器对ML、排序、提示或任何特定域一无所知。所有领域知识都存在于配置文件和代理的推理中。
• 单一度量。 一个数字决定成功。如果你的问题需要多个指标，你的run命令应该将它们组合成一个分数。
• 固定时间预算。 每个实验都有相同的挂钟超时，使结果具有可比性。
• Git作为内存。 每次改进都会记录其提交哈希值。每个回归都可以回滚到一个特定的实验。完整的历史总是可以恢复的。
• 代理人自主权。 服务器提供的是工具，而不是意见。代理决定尝试什么、何时回滚以及何时更改策略。

维护者

免责声明

• 正在进行的工作： 软件正在积极发展；特征可能会改变，某些功能可能不完整。
• LLM驱动的工作流程： 模型/代码质量取决于驱动循环的LLM的能力。
• 验证输出： 在依赖结果之前，始终严格审查和验证生成的模型、代码更改和指标。

引用

对于学术用途，请引用：

N.马尼亚特斯（2026）。 *CatoBot自动实验MCP服务器* （v1.0.0）。https://github.com/IamCatoBot/catobot-autoexperiment-mcp.版权所有卡托机器人有限公司。根据Apache 2.0许可。