Autobox MCP

Autobox MCP 服务器

这是一个用于管理Autobox AI模拟的MCP（模型上下文协议）服务器的TypeScript实现。这是Python版本的完整重写，具有增强的类型安全性、更好的性能以及统一的堆栈一致性。

特性/功能

• 🚀 表情符号“🚀”在中文中通常被翻译为“火箭”或“飞速前进”，用以表达快速、迅速或充满动力和活力的含义。因此，这个表情符号可以翻译为“🚀 火箭”或“🚀 飞速前进”，具体翻译取决于上下文和语境。 模拟管理启动、停止和监控人工智能模拟
• 🐳（海豚） Docker 集成每个模拟都在一个独立的容器中运行
• 📊（表格/数据图表） 实时监控获取正在运行的模拟的状态和日志
• 🎯（瞄准靶心） 配置管理创建并验证仿真配置
• 🤖（机器人） AI辅助设置借助人工智能生成模拟配置
• 📝 便签/记事本 类型安全使用Zod模式的完整TypeScript实现
• ⚡（闪电符号，常用于表示速度、活力或电） 现代堆栈使用ES模块和最新Node.js特性构建

先决条件

1. Node.js 18及以上版本运行服务器所需的（条件/软件/配置等）

1. Docker必须已安装并正在运行

1. OpenAI API密钥用于AI智能体模拟

   export OPENAI_API_KEY=sk-your-key-here

1. Autobox 引擎 TypeScript必须构建引擎的Docker镜像：

   cd ../autobox-engine-ts
   ./bin/docker-build

安装

# Clone and install dependencies
git clone https://github.com/margostino/autobox.git
cd autobox/autobox-mcp-ts
yarn install

发展

# Run in development mode with auto-reload
yarn dev

# Build TypeScript
yarn build

# Run tests
yarn test

# Run tests with coverage
yarn test:coverage

# Lint code
yarn lint

# Format code
yarn format

生产设置

对于Claude桌面应用程序

1. 构建Docker镜像：

   ./bin/docker-build

1. 编辑Claude桌面配置：

   open ~/Library/Application\ Support/Claude/claude_desktop_config.json

1. 在配置中添加Autobox MCP服务器：

   {
     "mcpServers": {
       "autobox": {
         "command": "docker",
         "args": [
           "run", "-i", "--rm",
           "-e", "HOST_HOME=${HOME}",
           "-e", "HOST_USER=${USER}",
           "-e", "OPENAI_API_KEY=${OPENAI_API_KEY}",
           "-v", "/var/run/docker.sock:/var/run/docker.sock",
           "-v", "${HOME}/.autobox:/root/.autobox",
           "autobox-mcp:latest"
         ]
       }
     }
   }

1. 重启Claude桌面版 （Cmd+Q 然后重新打开）

对于 Claude CLI

1. 构建Docker镜像：

   ./bin/docker-build

1. 添加到 Claude CLI：

   claude mcp add autobox -s user docker -- run -i --rm \
     -e HOST_HOME=$HOME \
     -e HOST_USER=$USER \
     -e OPENAI_API_KEY=$OPENAI_API_KEY \
     -v /var/run/docker.sock:/var/run/docker.sock \
     -v ${HOME}/.autobox:/root/.autobox \
     autobox-mcp:latest

1. 验证连接：

   claude mcp list
   # Should show: autobox ... ✓ Connected

重要注意事项

• OPENAI_API_KEY这个环境变量是 所需的；要求的 并且必须传递给MCP容器。MCP将其转发给模拟容器，以便智能体能够与OpenAI进行通信。
• HOST_HOME 翻译为中文是“主机主目录”当MCP在Docker中运行时，需要此设置以正确挂载卷。否则，模拟容器将无法访问配置文件。
• HOST_USER（主机用户）可选，但建议设置以确保适当的文件权限。

故障排除

加载配置时，模拟失败，出现错误“ENOENT: 没有此文件或目录”

• 确保 HOST_HOME 在Docker命令中设置
• 验证 ${HOME}/.autobox/config/simulations/ 包含您的模拟配置
• 检查MCP容器是否具有访问权限 /var/run/docker.sock

模拟失败，提示“401 未提供API密钥”：

• 确保 OPENAI_API_KEY 在启动MCP之前，请在您的环境中进行设置
• 验证环境变量是否已传递给MCP容器，使用 -e OPENAI_API_KEY
• 请检查您的OpenAI API密钥是否有效且拥有信用额度

无法连接到 Docker：

• 确保Docker正在运行
• 验证 /var/run/docker.sock 安装在MCP容器中
• 检查Docker权限（用户必须属于 docker （在Linux上的）组

使用JSON-RPC进行本地测试

您可以通过直接运行MCP服务器并在标准输入/输出中发送JSON-RPC消息来在本地测试它。

1. 在本地运行服务器

开发模式（带自动重载）：

yarn dev

构建版本：

yarn build
node dist/index.js

使用 Docker：

./bin/docker-run

2. 发送JSON-RPC消息

MCP服务器通过标准输入输出（stdio）使用JSON-RPC 2.0协议。每条消息必须位于单独的一行。

初始化连接

echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test-client","version":"1.0.0"}}}' | yarn dev

列出可用工具

{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}

列出正在运行的模拟

{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"list_simulations","arguments":{}}}

列出可用配置

{"jsonrpc":"2.0","id":4,"method":"tools/call","params":{"name":"list_available_configs","arguments":{}}}

开始模拟

{"jsonrpc":"2.0","id":5,"method":"tools/call","params":{"name":"start_simulation","arguments":{"config_name":"gift_choice","daemon":false}}}

获取模拟状态

{"jsonrpc":"2.0","id":6,"method":"tools/call","params":{"name":"get_simulation_status","arguments":{"simulation_id":"03a961047a33"}}}

获取模拟执行状态（来自API）

{"jsonrpc":"2.0","id":7,"method":"tools/call","params":{"name":"get_simulation_execution_status","arguments":{"simulation_id":"03a961047a33"}}}

获取模拟指标

{"jsonrpc":"2.0","id":8,"method":"tools/call","params":{"name":"get_simulation_metrics","arguments":{"simulation_id":"03a961047a33","include_docker_stats":true}}}

Ping 模拟 API

{"jsonrpc":"2.0","id":9,"method":"tools/call","params":{"name":"ping_simulation","arguments":{"simulation_id":"abc123def456"}}}

获取模拟健康状态

{"jsonrpc":"2.0","id":10,"method":"tools/call","params":{"name":"get_simulation_health","arguments":{"simulation_id":"03a961047a33"}}}

指令代理

{"jsonrpc":"2.0","id":11,"method":"tools/call","params":{"name":"instruct_agent","arguments":{"simulation_id":"abc123def456","agent_name":"Alice","instruction":"Focus on being more creative"}}}

模拟中止（或：模拟流产）

{"jsonrpc":"2.0","id":12,"method":"tools/call","params":{"name":"abort_simulation","arguments":{"simulation_id":"abc123def456"}}}

停止模拟

{"jsonrpc":"2.0","id":13,"method":"tools/call","params":{"name":"stop_simulation","arguments":{"simulation_id":"abc123def456"}}}

获取模拟日志

{"jsonrpc":"2.0","id":14,"method":"tools/call","params":{"name":"get_simulation_logs","arguments":{"simulation_id":"abc123def456","tail":50}}}

3. 交互式测试脚本

创建一个用于交互式测试的测试脚本：

#!/bin/bash
# test-mcp.sh

# Build and run the server in the background
yarn build
node dist/index.js &
SERVER_PID=$!

# Wait for server to start
sleep 2

# Send test messages
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test-client","version":"1.0.0"}}}' | nc localhost 3000
echo '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}' | nc localhost 3000
echo '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"list_simulations","arguments":{}}}' | nc localhost 3000

# Cleanup
kill $SERVER_PID

4. 使用MCP检查器

这个（或：该） MCP 检查员 为测试MCP服务器提供了一个可视化界面：

# Install MCP Inspector globally
npm install -g @modelcontextprotocol/inspector

# Run the inspector with your MCP server
mcp-inspector node dist/index.js

然后打开浏览器，以交互方式测试服务器。

5. 使用MCP Inspector进行测试（推荐）

MCP Inspector 提供了在开发过程中测试您的 MCP 服务器的最简便方法。

直接使用TypeScript（无需构建）：

npx @modelcontextprotocol/inspector tsx src/index.ts

这将会：

• 启动MCP Inspector网页界面
• 直接通过（某种方式）运行你的TypeScript源代码 tsx
• 在浏览器中打开 http://localhost:5173
• 提供一个可视化界面，用于交互式测试所有工具

使用构建的JavaScript：

npx @modelcontextprotocol/inspector node dist/index.js

优点：

• ✅ 无需建造（tsx 直接运行 TypeScript
• ✅ 测试工具的可视化界面
• ✅ 实时查看请求/响应
• ✅ 使用表单验证测试工具参数
• ✅ 查看完整的JSON-RPC消息
• ✅ 无需手动格式化JSON-RPC

无需提示的快速测试：

npx -y @modelcontextprotocol/inspector tsx src/index.ts

注释

• 服务器通过……进行通信 stdio（在中文语境中，通常直接使用原英文缩写，不特别翻译，若需解释，可译为“标准输入输出库”或“标准输入输出文件”） (stdin/stdout)，非HTTP
• 每个JSON-RPC消息必须位于一行上 单行
• 该 id 字段用于将请求与响应相匹配
• 为了使与模拟相关的工具能够运行，必须启动Docker
• 设定 OPENAI_API_KEY 在开始之前设置环境变量
• 设定 LOG_LEVEL=debug 在测试期间启用详细日志记录

可用工具

模拟管理

• list_simulations - 列出所有模拟（运行中和已完成的）
• start_simulation - 从配置开始新的模拟
• stop_simulation - 停止正在运行的模拟
• get_simulation_status - 获取模拟的详细状态
• get_simulation_logs - 从模拟中检索日志
• get_simulation_metrics - 获取实时指标（进度、代理状态、Docker状态）

配置

• list_available_configs - 列出可用的模拟模板
• create_simulation_config - 创建新的模拟配置，借助AI辅助
• create_simulation_metrics - 利用AI辅助创建指标配置
• delete_simulation - 删除一个仿真配置及其度量文件

高级的

• instruct_agent - 向代理发送运行模拟的指令
• stop_all_simulations - 立即停止所有正在运行的模拟

在Claude中的示例用法

"List all available simulation configs"
"Start the summer_vacation simulation"
"Show me the status of running simulations"
"Create a new simulation about negotiating a business deal"
"Get the logs from simulation abc123"
"Delete the test_simulation config and its metrics"
"Send an instruction to Alice in the running simulation"

建筑

autobox-mcp-ts/
├── src/
│   ├── config/         # Configuration management
│   ├── docker/         # Docker container management
│   ├── mcp/            # MCP server implementation
│   ├── types/          # TypeScript types and schemas
│   ├── utils/          # Utilities (logger, etc.)
│   └── index.ts        # Entry point
├── tests/
│   ├── unit/           # Unit tests
│   └── integration/    # Integration tests
└── bin/                # Build and run scripts

类型安全

所有配置均使用与autobox-engine-ts类型相匹配的Zod模式进行验证：

import { SimulationConfigSchema, type SimulationConfig } from './types';

// Validated at runtime
const config = SimulationConfigSchema.parse(jsonData);

与Python版本的不同之处

1. 类型安全使用Zod进行完整验证的TypeScript
2. 现代异步使用原生的 Promises 和 async/await
3. ES 模块（或称为 ECMAScript 模块）现代模块系统
4. 共享类型可以与autobox-engine-ts共享类型
5. 更好的错误处理强类型错误响应
6. 改进的日志记录带日志级别的结构化日志记录
7. 测试基于Jest的综合测试套件

故障排除

MCP服务器无法连接

1. 检查 Docker：

   docker ps
   docker images | grep autobox-mcp-ts

1. 检查环境变量：

   echo $OPENAI_API_KEY

1. 手动测试：

   ./bin/docker-run

Docker 问题

1. 未找到图像：

   cd ../autobox-engine-ts
   ./bin/docker-build

1. 权限错误：

- 确保 Docker Desktop 正在运行 - 在Linux上： sudo usermod -aG docker $USER

开发技巧

1. 手表模式使用 yarn dev 在开发期间用于自动重新加载
2. 类型检查跑 tsc --noEmit 在不构建的情况下检查类型
3. 调试设定 LOG_LEVEL=debug 用于详细日志记录
4. 测试使用 yarn test:watch 用于持续测试

做出贡献

1. 为仓库创建分支（或：克隆仓库）
2. 创建一个特性分支
3. 在测试中进行更改
4. 跑 yarn lint && yarn test
5. 提交拉取请求

许可证

Apache许可证2.0

支持

• 问题:
• 讨论：

______________________________________________________________________

用 TypeScript 带着爱意构建而成