项目介绍
Agent-MCP
🚀 高级工具通知：此框架专为需要复杂多代理编排能力的有经验的人工智能开发者设计。Agent-MCP 需要熟悉人工智能编码工作流程、MCP 协议以及分布式系统概念。我们正在积极改进文档和易用性。如果您是新接触人工智能辅助开发，请考虑从更简单的工具开始，并在需要高级多代理功能时再返回。
💬 加入社区：通过 Discord 与我们联系，获取帮助、分享经验并与构建多代理系统的其他开发者合作。
用于协调人工智能软件开发的多代理协作协议。
<div align="center"> <img src="assets/images/agent-network-viz.png" alt="代理网络可视化" width="600"> </div>想象一下AI代理的 Obsidian——一个活生生的知识图谱，多个AI代理通过共享上下文、智能任务管理和实时可视化进行协作。观察您的代码库随着专门的代理并行工作而演变，永远不会丢失上下文或相互干扰。
为什么使用多个代理？
除了哲学问题外，传统的AI编码助手在实际应用中存在局限性：
- 上下文窗口溢出在大型代码库上
- 知识在对话之间丢失
- 单线程执行造成瓶颈
- 没有专业化——一个代理试图做一切
- 由于丢失上下文和混淆导致的重复工作
多代理解决方案
Agent-MCP 将AI开发从单一助手转变为协调团队：
<div align="center"> <img src="assets/images/dashboard-overview.png" alt="多代理协作网络" width="800"> </div>实时可视化显示您的AI团队的工作状态——紫色节点代表上下文条目，蓝色节点是代理，连接显示活跃的合作。就像拥有一个开发团队的任务控制中心一样。
核心功能
并行执行
多个专门的代理同时在代码库的不同部分工作。后端代理处理API，前端代理构建UI组件，所有这些都通过共享内存进行协调。
持久知识图谱
<div align="center"> <img src="assets/images/memory-bank.png" alt="记忆银行界面" width="800"> </div>您项目的整个上下文存在于一个可搜索的持久记忆库中。代理查询这个共享知识以理解需求、架构决策和实现细节。会话之间不会丢失任何内容。
智能任务管理
<div align="center"> <img src="assets/images/agent-fleet.png" alt="代理舰队管理" width="800"> </div>监控每个代理的状态、分配的任务和最近活动。系统自动管理任务依赖关系，防止冲突，并确保工作从规划到实施顺利进行。
快速入门
Python 实现（推荐）
# 克隆并设置
git clone https://github.com/rinadelph/Agent-MCP.git
cd Agent-MCP
# 检查版本要求
python --version # 应该 >=3.10
node --version # 应该 >=18.0.0
npm --version # 应该 >=9.0.0
# 如果使用 nvm 管理 Node.js 版本
nvm use # 使用 .nvmrc 中指定的版本
# 配置环境
cp .env.example .env # 添加您的 OpenAI API 密钥
uv venv
uv install
# 启动服务器
uv run -m agent_mcp.cli --port 8080 --project-dir 路径到目录
# 启动仪表板（推荐以获得完整体验）
cd agent_mcp/dashboard && npm install && npm run dev
Node.js/TypeScript 实现（替代方案）
# 克隆并设置
git clone https://github.com/rinadelph/Agent-MCP.git
cd Agent-MCP/agent-mcp-node
# 安装依赖
npm install
# 配置环境
cp .env.example .env # 添加您的 OpenAI API 密钥
# 启动服务器
npm run server
# 或使用构建版本
npm run build
npm start
# 或全局安装
npm install -g agent-mcp-node
agent-mcp --port 8080 --project-dir 路径到目录
MCP 集成指南
什么是 MCP？
模型上下文协议 (MCP) 是一个开放标准，使AI助手能够安全地连接到外部数据源和工具。Agent-MCP 利用 MCP 提供与各种开发工具和服务的无缝集成。
运行 Agent-MCP 作为 MCP 服务器
Agent-MCP 可以作为 MCP 服务器运行，向兼容 MCP 的客户端（如 Claude Desktop、Cline 和其他AI编码助手）暴露其多代理功能。
快速 MCP 设置
# 1. 安装 Agent-MCP
uv venv
uv install
# 2. 启动 MCP 服务器
uv run -m agent_mcp.cli --port 8080
# 3. 配置您的 MCP 客户端连接到：
# HTTP: http://localhost:8000/mcp
# WebSocket: ws://localhost:8000/mcp/ws
MCP 服务器配置
创建一个 MCP 配置文件（mcp_config.json）：
{
"server": {
"name": "agent-mcp",
"version": "1.0.0"
},
"tools": [
{
"name": "create_agent",
"description": "创建一个新的专门的AI代理"
},
{
"name": "assign_task",
"description": "将任务分配给特定的代理"
},
{
"name": "query_project_context",
"description": "查询共享知识图谱"
},
{
"name": "manage_agent_communication",
"description": "处理代理间的消息传递"
}
],
"resources": [
{
"name": "agent_status",
"description": "实时代理状态和活动"
},
{
"name": "project_memory",
"description": "持久项目知识图谱"
}
]
}
使用 Agent-MCP 与 Claude Desktop
-
添加到 Claude Desktop 配置：
打开
~/Library/Application Support/Claude/claude_desktop_config.json（macOS）或等效文件：{ "mcpServers": { "agent-mcp": { "command": "uv", "args": ["run", "-m", "agent_mcp.cli", "--port", "8080"], "env": { "OPENAI_API_KEY": "您的-openai-api-key" } } } } -
重启 Claude Desktop 以加载 MCP 服务器
-
验证连接：Claude 应该显示“🔌 agent-mcp”在对话中
MCP 工具可用
一旦连接，您可以在 Claude 中直接使用这些 MCP 工具：
代理管理
create_agent- 创建专门的代理（后端、前端、测试等）list_agents- 查看所有活跃代理及其状态terminate_agent- 安全关闭代理
任务编排
assign_task- 将工作委托给特定代理view_tasks- 监控任务进度和依赖关系update_task_status- 跟踪完成情况和阻碍因素
知识管理
ask_project_rag- 查询持久知识图谱update_project_context- 添加架构决策和模式view_project_context- 访问存储的项目信息
通信
send_agent_message- 代理之间的直接消息传递broadcast_message- 向所有代理发送更新request_assistance- 升级复杂问题
高级 MCP 配置
自定义传输选项：
# HTTP 使用自定义端口
uv run -m agent_mcp.cli --port 8080
# WebSocket 带认证
uv run -m agent_mcp.cli --port 8080 --auth-token 您的秘密令牌
# Unix 套接字（Linux/macOS）
uv run -m agent_mcp.cli --port 8080
环境变量：
export AGENT_MCP_HOST=0.0.0.0 # 服务器主机
export AGENT_MCP_PORT=8000 # 服务器端口
export AGENT_MCP_LOG_LEVEL=INFO # 日志级别
export AGENT_MCP_PROJECT_DIR=/您的项目 # 默认项目目录
export AGENT_MCP_MAX_AGENTS=10 # 最大并发代理数
MCP 客户端示例
Python 客户端
import asyncio
from mcp import Client
async def main():
async with Client("http://localhost:8000/mcp") as client:
# 创建后端代理
result = await client.call_tool("create_agent", {
"role": "backend",
"specialization": "API 开发"
})
# 分配任务
await client.call_tool("assign_task", {
"agent_id": result["agent_id"],
"task": "实现用户身份验证端点"
})
# 查询项目上下文
context = await client.call_tool("ask_project_rag", {
"query": "我们的当前数据库模式是什么？"
})
print(context)
asyncio.run(main())
JavaScript 客户端
import { MCPClient } from '@modelcontextprotocol/client';
const client = new MCPClient('http://localhost:8000/mcp');
async function createAgent() {
await client.connect();
const agent = await client.callTool('create_agent', {
role: 'frontend',
specialization: 'React 组件'
});
console.log('创建代理：', agent.agent_id);
await client.disconnect();
}
createAgent().catch(console.error);
解决 MCP 连接问题
连接问题：
# 检查 MCP 服务器是否运行
curl http://localhost:8000/mcp/health
# 验证 WebSocket 连接
wscat -c ws://localhost:8000/mcp/ws
# 检查服务器日志
uv run -m agent_mcp.cli --port 8080 --log-level DEBUG
常见问题：
- 端口冲突：使用
--port标志更改端口 - 权限错误：确保设置了 OpenAI API 密钥
- 客户端超时：在客户端配置中增加超时时间
- 达到代理限制：使用
list_agents检查活跃代理数量
集成示例
VS Code 与 MCP： 使用 MCP 扩展将 Agent-MCP 直接集成到您的编辑器工作流中。
终端使用：
# 通过 curl 快速分配任务
curl -X POST http://localhost:8000/mcp/tools/assign_task \
-H "Content-Type: application/json" \
-d '{"task": "为 API 端点添加错误处理", "agent_role": "backend"}'
CI/CD 集成：
# GitHub Actions 示例
- name: 运行 Agent-MCP 代码审查
run: |
uv run -m agent_mcp.cli --port 8080 --daemon
curl -X POST localhost:8000/mcp/tools/assign_task \
-d '{"task": "审查 PR 中的安全问题", "agent_role": "security"}'
如何运作：将复杂性分解为简单步骤
graph LR
A[步骤 1] --> B[步骤 2] --> C[步骤 3] --> D[步骤 4] --> E[完成！]
style A fill:#4ecdc4,color:#fff
style E fill:#ff6b6b,color:#fff
每个任务都可以分解为线性步骤。这是 Agent-MCP 强大的核心见解。
复杂任务的问题
graph TD
A["构建用户身份验证"] -->|单个代理尝试一切| B{???}
B --> C[数据库？]
B --> D[API？]
B --> E[前端？]
B --> F[安全性？]
B --> G[测试？]
C -.->|困惑| H[不完整的实现]
D -.->|不知所措| H
E -.->|丢失上下文| H
F -.->|假设| H
G -.->|忘记| H
style A fill:#ff6b6b,color:#fff
style H fill:#666,color:#fff
Agent-MCP 解决方案
graph TD
A["构建用户身份验证"] -->|分解| B[线性任务]
B --> C["代理 1：数据库"]
B --> D["代理 2：API"]
B --> E["代理 3：前端"]
C --> C1[创建用户表]
C1 --> C2[添加索引]
C2 --> C3[创建会话表]
D --> D1[POST /register]
D1 --> D2[POST /login]
D2 --> D3[POST /logout]
E --> E1[登录表单]
E1 --> E2[注册表单]
E2 --> E3[身份验证上下文]
C3 --> F[工作系统]
D3 --> F
E3 --> F
style A fill:#4ecdc4,color:#fff
style F fill:#4ecdc4,color:#fff
每个代理专注于他们的线性链。没有困惑。没有上下文污染。只有清晰、确定的进步。
五步工作流程
1. 初始化管理员代理
您是管理员代理。
管理员令牌："来自服务器的您的管理员令牌"
您的角色是：
- 协调所有开发工作
- 创建和管理工人代理
- 维护项目上下文
- 根据代理专业领域分配任务
2. 加载您的项目蓝图（MCD）
将此 MCD（主要上下文文档）添加到项目上下文中：
[在此处粘贴您的 MCD —— 请参阅 docs/mcd-guide.md 结构]
将每个细节存储在知识图谱中。这成为所有代理的唯一事实来源。
MCD（主要上下文文档）是您项目的综合蓝图——可以将其视为在构建应用程序之前编写应用程序的书籍。它包括：
- 技术架构和设计决策
- 数据库模式和API规范
- UI组件层次结构和工作流
- 清晰依赖关系的任务分解
请参阅我们的 MCD 指南以获取详细示例和模板。
3. 部署您的代理团队
创建专门的代理进行并行开发：
- backend-worker：API 端点、数据库操作、业务逻辑
- frontend-worker：UI 组件、状态管理、用户交互
- integration-worker：API 连接、数据流、系统集成
- test-worker：单元测试、集成测试、验证
- devops-worker：部署、CI/CD、基础设施
每个代理在其领域内专业化，从而实现更高质量的实现和更快的开发速度。
4. 初始化并部署工人
# 对于每个工人，在新窗口中：
您是 [工人名称] 代理。
您的管理员令牌："来自管理员的工人令牌"
查询项目知识图谱以了解：
1. 整体系统架构
2. 您的具体职责
3. 与其他组件的集成点
4. 遵循的编码标准和模式
5. 当前实现状态
按照既定模式开始实现。
AUTO --worker --memory
重要：设置代理模式
代理模式（如 --worker、--memory、--playwright）不仅仅是标志——它们激活特定的行为模式。在 Claude Code 中，您可以通过以下方式使其持久化：
- 将模式指令复制到剪贴板
- 输入
#打开 Claude 的记忆功能 - 粘贴指令以实现持久行为
Claude Code 记忆示例：
# 当我使用 "AUTO --worker --memory" 时，遵循这些模式：
- 在编辑文件之前始终检查文件状态
- 在实现之前查询项目 RAG 获取上下文
- 在任务笔记中记录所有更改
- 一次只处理一个文件，在继续之前完成它
- 每次完成后更新任务状态
这确保在整个会话期间行为一致，无需重复指令。
5. 监控和协调
仪表板提供了对您的AI开发团队的实时可见性：
网络可视化 - 观察代理如何协作和共享信息
任务进度 - 跨所有并行工作流跟踪完成情况
记忆健康 - 确保上下文保持新鲜和可访问
活动时间线 - 精确查看每个代理正在做什么
在启动仪表板后，访问 http://localhost:3847。
高级功能
专门的代理模式
代理模式从根本上改变了代理的行为方式。它们不仅仅是配置——它们是行为契约，确保代理遵循优化其角色的特定模式。
标准工人模式
AUTO --worker --memory
针对实现任务进行了优化：
- 在任何编辑之前进行细粒度的文件状态检查
- 顺序任务完成（一次一个）
- 自动记录更改
- 与项目 RAG 集成以获取上下文
- 每次完成后更新任务状态
前端专家模式
AUTO --worker --playwright
增强了视觉验证能力：
- 所有标准工人功能
- 测试组件的浏览器自动化
- 视觉回归的截图能力
- 端到端测试的DOM交互
- 组件级别的实现和视觉验证
研究模式
AUTO --