人群mcp
> 通过MCP生成和编排自主AI代理
MCP(模型上下文协议)服务器,使AI编码助手能够生成、管理和协调在隔离的Docker容器中运行的多个自主AI代理。代理可以在复杂的任务上进行协作,相互通信,并在需要时进行手动监督。
特性
- 🚀 特工产卵 -通过MCP工具生成自主代理
- 🎭 代理模板 -具有专门行为的预配置代理类型
- 每种代理类型的自定义系统提示
- 模型首选项和LLM设置
- MCP服务器配置(stdio+HTTP/SSE)
- 示例代理:架构师、程序员、审阅者
- 💬 代理消息传递 -具有持久性的完整消息传递系统(基于JSONL)
- 直接代理到代理消息传递
- 向所有代理广播消息
- 消息历史和检索
- 基于优先级的消息队列
- 🎨 实时Web仪表板 -使用实时更新监控代理(无轮询!)
- 🤝 代理协作 -代理发现并相互沟通
- 📂 共享工作区 -所有代理都在相同的代码库上工作
- 🔒 独立执行 -每个代理都在自己的Docker容器中运行
- 🎯 零安装 -运行通过
npx,无需全局安装 - 🔌 双MCP接口 -管理(stdio)+代理(SSE)接口
用例
使您的AI助手能够将复杂的软件任务委托给专业代理:```
AI Assistant: "Build a full-stack user authentication system"
↓
Spawns 3 specialized agents:
- Architect Agent: Design the authentication architecture
- Coder Agent (Frontend): Build React login/signup UI
- Coder Agent (Backend): Implement JWT auth API
Agents collaborate:
- Architect defines: "Use JWT with refresh tokens, httpOnly cookies"
- Frontend Coder asks Backend: "What's the login endpoint?"
- Backend Coder responds: "POST /api/auth/login"
- Architect reviews: "Add rate limiting to prevent brute force"
Operator can attach to any agent for debugging
## 先决条件
- **码头工人** -代理容器在Docker中运行
- **Node.js 20+** -用于开发(如果使用npx,则不需要)
- **MCP兼容客户端** -例如Claude Desktop、GitHub Copilot、Amazon Q或OpenCode
## 文档
- 📋 产品要求(PRD) -功能需求和用户角色
- 🏗️ 建筑 -技术无关的系统设计
- 🔧 设计 -Types/Docker实现细节
## 状态
✅ **核心功能已完成** -代理生命周期、消息传递和web仪表板完全可操作
**已实施:**
- ✅ **代理生命周期** (FR1)
- 生成代理、列表代理、停止代理MCP工具
- 专用代理的可选agentType参数
- ✅ **Agent通信** (FR2)
- 代理间消息传递
- 广播消息
- 消息发现和检索
- 基于JSONL的持久消息存储
- 代理MCP服务器(端口3100上的SSE)
- ✅ **代理配置** (第7页)
- 基于YAML的代理模板(.cowd/agents/)
- 每种代理类型的自定义系统提示
- 模型首选项和LLM设置
- MCP服务器配置(stdio+HTTP/SSE)
- 环境变量模板
- 自动消息服务器注入
- 示例代理:架构师、程序员、审阅者
- ✅ **实时Web仪表板** (FR6)
- 带有SSE更新的实时代理列表
- 从UI停止代理
- 从UI查看代理日志
- ✅ **Docker集成**
- 集装箱管理
- 共享工作区安装
- 代理环境配置
- 通过AGENT_config环境变量生成运行时配置
**文档:**
- 📋 产品需求文档 -要求和实施情况
- 🏗️ 建筑 -系统概述
- 💬 消息传递体系结构 -详细的消息系统设计
**进行中/计划中:**
- ⏳ CLI连接功能(FR3.2)
- ⏳ 资源限制(FR5.x)
- ⏳ 加密代理身份验证
- ⏳ 消息TTL和自动清理
- ⏳ 自动清理已完成的代理(FR1.4)
**测试覆盖范围:** 158个测试通过(包括MessageRouter、MessagingTools、AgentConfig、ContainerManager、McpServer+集成测试)
## 快速开始
### 0.配置OpenCode(必需)
在使用crowd-mcp之前,你 **必须至少配置一个LLM提供程序** 对于OpenCode:
1. **创建配置目录:**```bash
mkdir -p .crowd/opencode
- 复制示例配置:```bash
cp .crowd/opencode/opencode.json.example .crowd/opencode/opencode.json
cp .crowd/opencode/.env.example .crowd/opencode/.env.local
1. **编辑 `.crowd/opencode/opencode.json`** -配置LLM提供程序
1. **编辑 `.crowd/opencode/.env.local`** -添加API密钥
**最低配置:**```json
{
"$schema": "https://opencode.ai/config.json",
"provider": {
"anthropic": {
"npm": "@anthropic-ai/sdk",
"options": { "apiKey": "{env:ANTHROPIC_API_KEY}" },
"models": {
"claude-3-5-sonnet-20241022": { "name": "Claude 3.5 Sonnet" }
}
}
}
}
看 OpenCode配置指南 以获取完整的文档。
> 没有LLM提供者的测试? 集 CROWD_DEMO_MODE=true 绕过验证。看 示范模式 了解详情。
代理模板(可选)
crowd-mcp包括三个示例代理模板:
- 建筑师 -软件架构和系统设计
- 程序员 -实施和编码任务
- 审稿人 -代码审查和质量保证
这些位于 .crowd/agents/*.yaml 并且可以定制或扩展。在生成代理时,您可以指定 agentType 使用这些模板,或省略它以使用默认的OpenCode配置。
1.设置您的MCP客户端
示例:克劳德桌面
添加到您的Claude Desktop配置文件中:
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
视窗: %APPDATA%/Claude/claude_desktop_config.json
Linux: `~/.config/Claude/claude_desktop_config.json````json
{
"mcpServers": {
"crowd-mcp": {
"command": "npx",
"args": ["-y", "crowd-mcp@latest"],
"env": {
"HTTP_PORT": "3000",
"AGENT_MCP_PORT": "3100"
}
}
}
}
**环境变量:**
- `HTTP_PORT` -Web仪表板端口(默认值:3000)
- `AGENT_MCP_PORT` -代理通信端口(默认值:3100)
- `MESSAGE_BASE_DIR` -消息存储目录(默认:./.cowd/sessions)
- `SESSION_ID` -自定义会话ID(默认:自动生成时间戳)
- `CROWD_LOG_LEVEL` -日志级别:调试、信息、警告、错误(默认值:警告)
- `OPERATOR_NAME` -消息传递中人工操作员的显示名称(默认:“人工操作员”)
看 日志记录配置 查看详细的日志设置。
重新启动MCP客户端。当您的客户端启动时,服务器将自动启动。
> **注:** 配置步骤因客户而异。有关具体的设置说明,请参阅MCP客户端的文档。上面的配置格式适用于Claude Desktop,但相同 `npx crowd-mcp@latest` 该命令适用于任何兼容MCP的客户端。
### 2.打开Web仪表板
引导到http://localhost:3000查看实时代理仪表板。当创建、更新或删除代理时,UI会通过服务器发送事件自动更新。
**仪表板功能:**
- 📊 实时代理列表,实时更新
- 🔍 代理详细信息(ID、任务、容器ID、状态)
- 🛑 通过确认对话框停止代理
- 📜 在模态查看器中查看代理日志
- 🟢 连接状态指示器
- 🎨 深色主题UI
**配置端口:**
web服务器正在监听 **端口3000** 默认情况下。如果此端口已在使用中,您可以通过设置 `HTTP_PORT` MCP客户端配置中的环境变量:```json
{
"mcpServers": {
"crowd-mcp": {
"command": "npx",
"args": ["-y", "crowd-mcp@latest"],
"env": {
"HTTP_PORT": "3001"
}
}
}
}
如果端口不可用,服务器将显示明确的错误消息,并指导您进行更改。
3.使用MCP工具
可用工具:
代理生命周期:
- spawn_agent -创建新的自主代理
-task(必填):任务描述
-agentType(可选):要使用的代理模板(架构师、程序员、审阅者或自定义) - 列表_代理 -查看所有正在运行的代理
- 停止代理 -终止特定代理
消息和通信:
- send_message -向代理发送消息或向所有人广播
- 获取消息 -为操作员检索消息
- mark_messages_read -将邮件标记为已读
- 发现_代理商 -使用筛选器列出活动代理
注: 代理商使用 send_message_to_operator 与您沟通的工具。向代理显示的操作员名称可通过以下方式配置 OPERATOR_NAME 环境变量。
示例用法:
基本代理生成:```
You: "Spawn an agent to refactor the authentication module"
AI Assistant: [Uses spawn_agent tool with task only]
Agent spawned successfully!
ID: agent-1730000000000
Task: Refactor the authentication module
Container: abc123def456
View and control agents at:
http://localhost:3000
**Spawn专业代理:**```
You: "Spawn an architect agent to design the API structure"
AI Assistant: [Uses spawn_agent tool with task and agentType="architect"]
Agent spawned successfully!
ID: agent-1730000000001
Task: Design the API structure
Type: architect
Container: def456ghi789
View and control agents at:
http://localhost:3000
``````
You: "List all running agents"
AI Assistant: [Uses list_agents tool]
Active Agents (2):
1. agent-1730000000000
Task: Refactor the authentication module
Container: abc123def456
2. agent-1730000000123
Task: Fix bug in payment processing
Container: def789ghi012
``````
You: "Stop agent agent-1730000000000"
AI Assistant: [Uses stop_agent tool]
Agent agent-1730000000000 stopped successfully.
AI助手现在可以通过编程完全管理代理生命周期!您还可以在以下网址使用网络仪表板http://localhost:3000用于视觉监控和控制。
4.发展模式
对于本地开发和测试:```bash
Clone and install
git clone https://github.com/mrsimpson/crowd-mcp
cd crowd-mcp
pnpm install
Build
pnpm build
Run server
pnpm --filter crowd-mcp start
## 运作原理```
┌─────────────────────────────────────────────────────┐
│ MCP Client (Claude, Copilot, etc.) │
└────────────────────┬────────────────────────────────┘
│ stdio (MCP Protocol)
│
┌────────────────────▼────────────────────────────────┐
│ crowd-mcp MCP Server │
│ ┌────────────────────────────────────────────────┐ │
│ │ MCP Tools │ │
│ │ - spawn_agent │ │
│ └────────────────────────────────────────────────┘ │
│ ┌────────────────────────────────────────────────┐ │
│ │ HTTP/SSE Server (Web Dashboard) │ │
│ │ - GET /api/agents - List agents │ │
│ │ - GET /api/agents/:id - Get agent details │ │
│ │ - GET /api/events - Real-time SSE stream │ │
│ │ - GET / - Web UI │ │
│ └────────────────────────────────────────────────┘ │
│ ┌────────────────────────────────────────────────┐ │
│ │ AgentRegistry (Event-Driven) │ │
│ │ - Syncs from Docker on startup │ │
│ │ - Emits events: agent:created/updated/removed │ │
│ └────────────────────────────────────────────────┘ │
└────────────────────┬────────────────────────────────┘
│ Docker API
┌───────────┼───────────┐
│ │ │
┌────▼────┐ ┌────▼────┐ ┌───▼─────┐
│ Agent-1 │ │ Agent-2 │ │ Agent-3 │
│(OpenCode│ │(OpenCode│ │(OpenCode│
│ in │ │ in │ │ in │
│ Docker) │ │ Docker) │ │ Docker) │
└────┬────┘ └────┬────┘ └────┬────┘
│ │ │
└───────────┴───────────┘
│
┌──────▼──────┐
│ Workspace │
│ (Shared) │
└─────────────┘
▲
│
┌───────────┴───────────┐
│ │
┌────┴──────┐ ┌──────┴─────┐
│ Browser │ │ CLI Attach │
│ Dashboard │ │ (Future) │
└───────────┘ └────────────┘
(SSE) (TTY)
关键部件:
- MCP服务器 -作为MCP客户端的子进程运行,提供MCP工具
- HTTP/SSE服务器 -提供web仪表板和实时事件流(端口3000)
- 代理商注册 -从Docker同步的事件驱动内存注册表
- 代理容器 -运行OpenCode(AI编码代理)的隔离Docker容器
- Web仪表板 -使用服务器发送事件的实时监控UI
- 共享工作区 -所有代理都可以访问已安装的卷
发展
本地设置```bash
Clone repository
git clone https://github.com/mrsimpson/crowd-mcp
cd crowd-mcp
Install dependencies
npm install
Build TypeScript
npm run build
Run MCP server directly (for testing)
node packages/server/dist/index.js
### 运行测试```bash
# Unit tests
npm test
# Integration tests (requires Docker)
npm run test:integration
项目结构```
crowd-mcp/
├── packages/
│ ├── server/ # MCP server implementation
│ ├── web-server/ # HTTP API + real-time web dashboard
│ └── shared/ # Shared types (Agent interface)
├── docker/
│ └── agent/ # Agent container Dockerfile
└── docs/ # Documentation (PRD, Architecture, Design)
```
贡献
欢迎投稿!请先阅读文档:
- 检查 未解决问题
- 查看 建筑 和 设计 文档
- 提交带有测试的PR
相关项目
- 模型上下文协议 -协议规范
- OpenCode -集装箱中使用的AI编码代理
MCP客户端:
- 克劳德桌面 -支持MCP的桌面应用程序
- GitHub Copilot -AI配对程序员
- 亚马逊Q -AWS人工智能助手
- OpenCode -自主编码代理
路线图
v0.1 (当前-进行中)
- ✅ 代理生命周期管理(spawn_Agent、list_agents、stop_Agent)
- ✅ 带有模板的代理配置系统
- ✅ 代理间消息传递
- ✅ 带有交互式控件的实时web仪表板
- ✅ 事件驱动架构
- ⏳ CLI连接功能
- ⏳ 自动清理已完成的代理
v0.2 (计划中)
- 持久消息队列
- 代理状态恢复
- 资源使用跟踪和限制
v0.3 (计划中)
- 独立二进制分布
- 高级代理调度
- web连接的WebSocket支持
许可证
麻省理工学院
作者
由...创建 奥利弗·辛普森
