金大哥 - systemprompt-code-orchestrator MCP 详情

article

README

🚀 SystemPrompt Coding Agent

SystemPrompt Coding Agent 是一个前沿项目，可将你的工作站转变为支持远程访问的 MCP（模型上下文协议）服务器，任何 MCP 客户端都能与之连接。它是 SystemPrompt.io 生态系统的一部分，该生态系统正为开发者开创原生移动语音控制的 AI 编排技术。

🚀 快速开始

前提条件

设置脚本会自动检查以下内容：

Node.js 18+（必需）
Docker 与 Docker Compose（必需）
Claude Code CLI（可选但推荐，设置脚本会提供指导）

克隆并设置

# Clone and setup
git clone https://github.com/systempromptio/systemprompt-code-orchestrator
cd systemprompt-code-orchestrator

# Install and run
npm i 
npm run setup
npm run start

# Test with the inspector
npm run inspector

创建的任务可以通过检查器执行，这些任务会连接到你的 Claude Code 安装，将结构化日志保存在 Docker 容器内（作为 MCP 资源公开），并支持通过检查器（以及任何 MCP 客户端）执行。

基本命令

npm run start    # 启动所有服务（守护进程 + Docker）
npm run stop     # 优雅地停止所有服务
npm run status   # 检查服务健康状况
npm run logs     # 查看实时日志
npm run tunnel   # 通过互联网隧道启动（需要 Cloudflare）

基本配置

# Required (setup will prompt for this)
PROJECT_ROOT=/path/to/your/code  # ⚠️ AI 代理对这里有完全访问权限

# Optional (with defaults)
PORT=3000
COMPOSE_PROJECT_NAME=systemprompt-coding-agent

# Optional (for additional features)
CLOUDFLARE_TOKEN=your_token  # 用于隧道访问
PUSH_TOKEN=your_token        # 用于移动通知

✨ 主要特性

🤖 AI 代理编排

多代理支持：开箱即用支持 Claude Code CLI，可扩展支持任何代理
任务管理：创建、跟踪和管理编码任务 - 任务管理 →
会话隔离：每个任务在其自己的上下文中运行 - Claude 集成 →
实时流：实时观看 AI 代理工作 - 事件系统 →

📱 移动优先设计

语音命令：例如“创建一个带验证的登录表单”
推送通知：任务完成时接收提醒 - 推送通知 →
快速操作：常见任务的预定义模板 - 提示模板 →
远程控制：随时随地管理你的开发环境

🔧 MCP 协议特性

持久状态：任务在服务器重启后仍可保留 - 状态持久化 →
资源管理：将任务数据作为 MCP 资源公开 - 工具与资源 →
交互式提示：AI 代理可以请求澄清
进度通知：实时状态更新
结构化数据：完整的模式验证 - MCP 服务器 →

📦 安装指南

克隆项目

git clone https://github.com/systempromptio/systemprompt-code-orchestrator
cd systemprompt-code-orchestrator

安装依赖并运行

npm i 
npm run setup
npm run start

测试

npm run inspector

💻 使用示例

基础用法

# 克隆并设置项目
git clone https://github.com/systempromptio/systemprompt-code-orchestrator
cd systemprompt-code-orchestrator

# 安装依赖并启动
npm i 
npm run setup
npm run start

高级用法

# 通过 Cloudflare 隧道实现远程访问
npm run tunnel

📚 详细文档

核心架构

守护进程 - 主机端桥梁，执行命令并管理 Claude 进程
Docker 架构 - Docker 容器与主机的交互方式
MCP 服务器 - 模型上下文协议服务器的实现

AI 代理系统

代理管理器 - 所有 AI 代理会话的中央编排器
Claude Code 集成 - Claude Code CLI 的集成与管理方式
任务管理 - 任务生命周期、持久化和状态管理

协议与 API

工具与资源 - MCP 工具和资源的实现
事件系统与日志 - 实时事件流和结构化日志

附加功能

测试框架 - 端到端测试设置和最佳实践
隧道与远程访问 - Cloudflare 隧道设置以实现互联网访问
状态持久化 - 任务和会话在重启后的持久化方式
推送通知 - 移动推送通知集成
提示模板 - 常见任务的预构建提示系统

🔧 技术细节

技术架构

MCP Client (Mobile/Desktop)
    |
    v
Docker Container (MCP Server)
    - Handles MCP protocol
    - Resource subscriptions
    - Event streaming
    |
    v
Host Bridge Daemon (TCP Socket)
    - Command routing
    |
    v
Host Machine
    - AI agent execution
    - File system access

关键技术创新

1. 实时资源订阅模型

服务器实现了 MCP SDK 的 listChanged 模式用于资源订阅。当任务状态改变时：

// Client subscribes to task resources, notified by listChanged notifications
client.listResources()
client.getResource({ uri: "task://abc-123" })

// When task updates, server automatically:
// 1. Saves task to disk (JSON persistence)
await this.persistence.saveTask(updatedTask);

// 2. Emits internal event
this.emit("task:updated", updatedTask);

// 3. Sends MCP notification to subscribed clients
await sendResourcesUpdatedNotification(`task://${taskId}`, sessionId);
// This triggers: { method: "notifications/resources/updated", params: { uri: "task://abc-123" } }

// Client receives notification and can re-fetch the updated resource

这使得无需轮询即可实现实时任务监控，客户端可随任务状态变化实时同步。

2. 任务完成推送通知

集成了 Firebase Cloud Messaging (FCM) 支持，任务完成时会向移动设备发送推送通知：

// Task completes → Push notification sent
{
  notification: {
    title: "Task Complete",
    body: "Your refactoring task finished successfully"
  },
  data: {
    taskId: "abc-123",
    status: "completed",
    duration: "45s"
  }
}

非常适合长时间运行的任务，启动任务后可在完成时收到通知。

3. 有状态进程管理

任务以 JSON 格式持久化到磁盘，采用原子写入
守护进程重启后仍可维护进程会话
任务生命周期的综合状态机：

pending → in_progress → waiting → completed
                    ↓
                  failed

事件驱动架构

所有操作都会发出事件，供多个子系统消费：

日志记录器：带有上下文的结构化 JSON 日志
状态管理器：任务状态更新
通知器：向移动客户端发送推送通知
指标：性能和使用情况分析

远程访问选项

🌐 通过 Cloudflare 隧道实现互联网访问

更复杂的选项（如打开 Cloudflare 隧道以将 HTTPS URL 暴露到本地机器）有文档说明，但默认不包含（操作需自行承担风险）。

npm run tunnel

这将：

创建到本地服务器的安全 HTTPS 隧道
显示公共 URL 和本地网络地址
支持从任何地方（包括移动设备）访问 → 完整隧道文档

🏠 本地网络访问

如果你希望将所有操作限制在本地网络内：

正常启动服务器：

npm start

从同一网络的设备访问：

找到你的机器的 IP 地址
使用 http://YOUR_IP:3000/mcp 进行连接

工具参考

→ 完整工具和资源文档

任务编排

| 属性 | 详情 | |------|------| | create_task | 启动新的 AI 编码会话 | {"title": "Add auth", "tool": "CLAUDECODE", "instructions": "..."} | | update_task | 发送额外的指令 | {"process": "session_123", "instructions": "..."} | | end_task | 完成并清理任务 | {"task_id": "task_123", "status": "completed"} | | report_task | 生成任务报告 | {"task_ids": ["task_123"], "format": "markdown"} |

系统管理

| 属性 | 详情 | |------|------| | check_status | 验证代理可用性 | {"test_sessions": true, "verbose": true} | | update_stats | 获取系统统计信息 | {"include_tasks": true} | | clean_state | 清理旧任务 | {"keep_recent": true, "dry_run": true} |

预构建提示

SystemPrompt 包含用于常见编码任务的强大提示模板。→ 完整提示模板文档

🐛 错误修复

{
  "prompt_template": "bug_fix",
  "variables": {
    "bug_description": "Login fails after password reset",
    "error_logs": "401 Unauthorized at auth.js:42"
  }
}

⚛️ React 组件

{
  "prompt_template": "react_component",
  "variables": {
    "component_name": "UserDashboard",
    "features": ["data visualization", "real-time updates", "export functionality"]
  }
}

🧪 单元测试

{
  "prompt_template": "unit_test",
  "variables": {
    "target_files": ["src/auth/*.js"],
    "framework": "jest",
    "coverage_target": 85
  }
}

性能优化

流式输出：代理输出以块形式流式传输，而非缓冲
懒加载资源：按需获取资源
连接池：复用与守护进程的 TCP 连接
高效状态持久化：仅将更改的字段写入磁盘

开发

项目结构

systemprompt-coding-agent/
├── src/
│   ├── server.ts           # MCP server setup
│   ├── handlers/           # Protocol handlers
│   ├── services/           # Agent services
│   ├── constants/          # Tool definitions
│   └── types/              # TypeScript types
├── docker-compose.yml
└── package.json

贡献

分叉仓库
创建功能分支
进行更改
提交拉取请求

如有安全问题，请发送邮件至 security@systemprompt.io

支持

文档：docs.systemprompt.io
GitHub 问题：报告错误
Discord：加入我们的社区
Twitter：@tyingshoelaces_

未来路线图

多代理编排：协调多个 AI 代理处理复杂任务
增量计算：缓存并重用 AI 输出
分布式执行：将任务分布到多台机器上
Web UI 仪表盘：基于浏览器的监控和控制

MCP 客户端选项

虽然此服务器可与任何 MCP 兼容客户端配合使用，但如果你希望获得移动语音控制体验，可查看 SystemPrompt.io - 该项目仍处于早期阶段，但它是专为语音驱动的 AI 编码工作流设计的原生 iOS/Android 应用。我们希望通过语音异步创建和交互这些任务！

📄 许可证

本项目采用 MIT 许可证，请参阅 LICENSE 了解详情。

由 SystemPrompt.io 用心打造
随时随地实现 AI 驱动的开发