使用说明

Autobox MCP 服务器

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

特性/功能

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

先决条件

Node.js 18及以上版本运行服务器所需的（条件/软件/配置等）
Docker必须已安装并正在运行
OpenAI API密钥用于AI智能体模拟
```
export OPENAI_API_KEY=sk-your-key-here
```
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桌面应用程序

构建Docker镜像：
```
./bin/docker-build
```

编辑Claude桌面配置：

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

在配置中添加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"
      ]
    }
  }
}

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

对于 Claude CLI

构建Docker镜像：
```
./bin/docker-build
```

添加到 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

验证连接：

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版本的不同之处

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

故障排除

MCP服务器无法连接

检查 Docker：

docker ps
docker images | grep autobox-mcp-ts

检查环境变量：
```
echo $OPENAI_API_KEY
```
手动测试：
```
./bin/docker-run
```

Docker 问题

未找到图像：

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

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

开发技巧

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

做出贡献

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

许可证

Apache许可证2.0

支持

问题: GitHub Issues（GitHub问题）
讨论： GitHub 讨论区

用 TypeScript 带着爱意构建而成

使用说明

Autobox MCP 服务器

特性/功能

先决条件

安装

发展

生产设置

对于Claude桌面应用程序

对于 Claude CLI

重要注意事项

故障排除

使用JSON-RPC进行本地测试

1. 在本地运行服务器

2. 发送JSON-RPC消息

初始化连接

列出可用工具

列出正在运行的模拟

列出可用配置

开始模拟

获取模拟状态

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

获取模拟指标

Ping 模拟 API

获取模拟健康状态

指令代理

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

停止模拟

获取模拟日志

3. 交互式测试脚本

4. 使用MCP检查器

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

注释

可用工具

模拟管理

配置

高级的

在Claude中的示例用法

建筑

类型安全

与Python版本的不同之处

故障排除

MCP服务器无法连接

Docker 问题

开发技巧

做出贡献

许可证

支持

相关 MCP

Unity编辑器AI集成插件

英雄联盟模拟比赛预测器

日志管理服务

开发容器协议服务器

ROS MCP服务器

交换机CLI协议服务器