AI导哈

远程子代理服务器

一个MCP（模型上下文协议）服务器，允许本地AI代理使用E2B沙箱生成临时的远程子代理。

  • by GeorgePearse
  • TypeScript
  • 本地部署
  • 更新于
在 GitHub 查看 GeorgePearse/remote-subagents

使用说明

远程子代理MCP服务器

MCP（模型上下文协议）服务器，使您的本地AI代理能够使用E2B沙箱生成短暂的远程子代理。

特性

  • 短暂的沙盒：每个任务都在隔离的E2B云环境中运行
  • 安全执行：风险操作发生在远程，而不是在您的机器上
  • Claude代码集成：子代理使用Claude代码执行复杂任务
  • 可配置超时：沙盒、安装和执行阶段的可定制超时
  • 结构化日志记录：JSON格式的日志，便于解析和监控
  • 优雅关闭：终止时正确清理沙盒

目录

建筑

┌─────────────────────────────────────────────────────────────────┐
│                        MCP Client                                │
│                  (Claude Desktop / claude-code)                  │
└─────────────────────────────┬───────────────────────────────────┘
                              │ MCP Protocol (stdio)
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                   Remote Sub-agents Server                       │
│  ┌─────────────┐  ┌──────────────┐  ┌────────────────────────┐  │
│  │   Metrics   │  │   Logging    │  │   Shutdown Handler     │  │
│  └─────────────┘  └──────────────┘  └────────────────────────┘  │
│  ┌─────────────────────────────────────────────────────────────┐│
│  │              spawn_remote_agent Tool                        ││
│  │  • Input validation (Zod)                                   ││
│  │  • Shell argument escaping                                  ││
│  │  • Sandbox lifecycle management                             ││
│  └─────────────────────────────────────────────────────────────┘│
└─────────────────────────────┬───────────────────────────────────┘
                              │ E2B API
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                      E2B Cloud Sandbox                           │
│  ┌─────────────────────────────────────────────────────────────┐│
│  │  1. npm install @anthropic-ai/claude-code                   ││
│  │  2. claude --dangerously-skip-permissions -p "<task>"       ││
│  │  3. Return stdout/stderr                                    ││
│  └─────────────────────────────────────────────────────────────┘│
│                        (Auto-terminated)                         │
└─────────────────────────────────────────────────────────────────┘

请求流

  1. MCP客户端发送 spawn_remote_agent 工具调用
  2. 服务器使用Zod模式验证输入
  3. E2B沙盒已创建，并配置了超时
  4. Claude Code已安装在沙盒中
  5. 使用正确转义的参数执行任务
  6. 结果（stdout/stderr）返回给客户端
  7. 沙盒已终止并清理干净

快速开始

# Clone the repository
git clone https://github.com/GeorgePearse/remote-subagents.git
cd remote-subagents

# Install dependencies
npm install

# Create .env file
cat > .env << EOF
E2B_API_KEY=your_e2b_api_key
ANTHROPIC_API_KEY=your_anthropic_api_key
EOF

# Build and start
npm run build
npm start

配置

环境变量

变量 必填 默认 描述
E2B_API_KEY 是 - 用于沙箱访问的E2B API密钥
ANTHROPIC_API_KEY 是 - Claude的Anthropic API密钥
SANDBOX_TIMEOUT_MS 没有 600000 沙盒寿命（10分钟）
INSTALL_TIMEOUT_MS 没有 120000 npm安装超时（2分钟）
EXECUTE_TIMEOUT_MS 没有 300000 Claude执行超时（5分钟）
CLAUDE_PACKAGE 没有 @anthropic-ai/claude-code 要安装的Claude软件包
MAX_TASK_LENGTH 没有 51200 最大任务描述长度（50KB）

示例 .env 文件

# Required
E2B_API_KEY=e2b_xxxxxxxxxxxxxxxxxxxxxxxx
ANTHROPIC_API_KEY=sk-ant-xxxxxxxxxxxxxxxxxxxxxxxx

# Optional - Custom timeouts
SANDBOX_TIMEOUT_MS=900000      # 15 minutes
INSTALL_TIMEOUT_MS=180000      # 3 minutes
EXECUTE_TIMEOUT_MS=600000      # 10 minutes
MAX_TASK_LENGTH=102400         # 100KB

MCP客户端配置

添加到您的Claude Desktop或Claude代码配置中：

{
  "mcpServers": {
    "remote-subagents": {
      "command": "node",
      "args": ["/path/to/remote-subagents/dist/index.js"],
      "env": {
        "E2B_API_KEY": "your_e2b_api_key",
        "ANTHROPIC_API_KEY": "your_anthropic_api_key"
      }
    }
  }
}

用法

工具： spawn_remote_agent

生成一个临时远程子代理来执行复杂的任务。

论据：

参数 类型 必填 描述
task_description string 是 远程代理的目标或任务
requirements string 否 其他要求或上下文

例子：

// From your MCP client
const result = await client.callTool("spawn_remote_agent", {
  task_description: "Create a Python script that fetches weather data from OpenWeatherMap API",
  requirements: "Use requests library, handle errors gracefully, output as JSON"
});

发展

先决条件

  • Node.js 18+
  • npm 9+
  • E2B账户和API密钥
  • 无烟煤API键

设置

# Install dependencies
npm install

# Run tests
npm test

# Run tests in watch mode
npm run test:watch

# Build TypeScript
npm run build

# Run locally
npm start

项目结构

remote-subagents/
├── src/
│   ├── index.ts        # Main MCP server entry point
│   ├── utils.ts        # Utility functions (escaping, logging, validation)
│   ├── utils.test.ts   # Unit tests
│   ├── types.ts        # TypeScript interfaces
│   ├── errors.ts       # Custom error classes
│   ├── constants.ts    # Configuration constants
│   ├── metrics.ts      # Metrics collection
│   ├── retry.ts        # Retry utility with backoff
│   └── shutdown.ts     # Graceful shutdown handling
├── dist/               # Compiled JavaScript
├── package.json
├── tsconfig.json
└── vitest.config.ts

运行测试

# Run all tests
npm test

# Run with coverage
npm test -- --coverage

# Run specific test file
npm test -- src/utils.test.ts

# Watch mode
npm run test:watch

故障排除

常见问题

沙盒创建失败

症状： Failed to create sandbox 错误

解决：

  • 验证您的 E2B_API_KEY 有效
  • 检查E2B服务状态 status.e2b.dev
  • 确保您有可用的沙盒配额

Claude安装超时

症状： Package installation timed out 错误

解决：

  • 增加 INSTALL_TIMEOUT_MS （默认值为2分钟）
  • 检查沙盒区域中的网络连接

任务执行超时

症状： Claude execution timed out 错误

解决：

  • 增加 EXECUTE_TIMEOUT_MS 用于复杂任务
  • 将大型任务分解为较小的子任务
  • 检查任务是否卡住（无限循环，等待输入）

API密钥无效

症状： ANTHROPIC_API_KEY is required 或身份验证错误

解决：

  • 验证API密钥是否正确且处于活动状态
  • 确保密钥具有适当的权限
  • 检查中是否有多余的空格 .env 文件

调试模式

通过检查stderr输出启用详细日志记录：

npm start 2>debug.log

获取帮助

贡献

我们欢迎捐款！请遵循以下指南：

入门指南

  1. 复刻仓库
  2. 创建要素分支： git checkout -b feature/my-feature
  3. 进行更改
  4. 运行测试： npm test
  5. 用描述性消息提交
  6. 推送并创建拉取请求

代码风格

  • 对所有新代码使用TypeScript
  • 遵循现有代码格式（Prettier）
  • 为公共功能添加JSDoc注释
  • 编写新功能的单元测试

提交消息

使用常规提交格式：

feat: add retry logic for sandbox creation
fix: handle unicode characters in task description
docs: update configuration section
test: add edge cases for shell escaping

拉取请求流程

  1. 必要时更新文档
  2. 为新功能添加测试
  3. 确保所有测试通过
  4. 请求维护人员审查

许可证

MIT许可证-请参阅 许可证 了解详情。

链接

相关 MCP