MCP 代理
使用 MCP（模型上下文协议）创建多智能体系统的框架，以实现协调、高效的 AI 协作。
快速入门指南
注意：我建议使用MultipleCursor在同一个代码库上启动不同的聊天窗口，如上图所示。
1. 设置环境
- 克隆 repo 并将
.env.example复制到.env - 将您的 OpenAI API 密钥添加到
.env - 使用
uv venv && uv pip install -e .
2. 启动 MCP 服务器
uv run -m agent_mcp.cli --port 8080 --project-dir /path/to/your/project
# or if you have rye configured and are in the project root:
# rye run start --project-dir /path/to/your/project
重要提示：服务器启动时，会在项目的.agent文件夹中创建一个数据库。您的管理员令牌存储在此数据库中。要查找它，请执行以下操作：
- 在代码编辑器中安装 SQLite 查看器扩展
- 打开数据库
/path/to/your/project/.agent/mcp_state.db - 检查
project_context表中的管理员令牌
3. 创建主上下文文档（MCD）
- 在您的项目中创建一个详细的
MCD.md文件，其中包含架构、API 路由、数据模型等。 - 这可以是单个文件或多个文件（对于复杂项目）
- 请参阅MCD-EXAMPLE文件夹中的模板
4.启动管理代理
- 在项目文件夹中打开你的 AI 编码助手（Claude Code、Cursor 等）
- 复制您在步骤 2 中找到的管理员令牌
- 要求 AI“使用此令牌初始化为管理代理：[your-token]”
- 告诉管理代理将您的 MCD 添加到项目上下文中：
Please add the MCD.md file to the project context. Don't summarize it.
5. 通过管理员创建和管理工作代理
- 要求您的管理代理创建一个工作代理：
Create a worker agent with ID "frontend-worker" to implement the login page.
- 在你的 AI 助手中打开一个新窗口/会话（相同的代码库）
- 使用以下精确提示初始化工作者：
You are [worker-id] agent, your Admin Token: "[admin-token]"
Look at your tasks and ask the project RAG agent at least 5-7 questions to understand what you need to do. I want you to critically think when asking a question, then criticize yourself before asking that question. How you criticize yourself is by proposing an idea, criticizing it, and based on that criticism you pull through with that idea.
AUTO --worker --memory
- 工人将自动找到其分配的任务并开始工作
请按照以下详细说明获取更多信息。
特征
- 多代理协作框架
- 任务管理和协调
- 代理之间的上下文和知识共享
- 代理交互的图形可视化
- 支持嵌入和 RAG 功能
- 用于可视化任务、代理和上下文的交互式仪表板
使用主上下文文档 (MCD) 进行项目规划
观看视频教程：如何将 MCD 上下文添加到 Agent MCP
在开始开发之前，务必进行深入研究，创建一份主上下文文档 (MCD) ，这是应用程序的唯一可信来源。本文档提供了一个详细的计划，详细说明：
- 系统架构和组件关系
- 所有屏幕和组件的 UI/UX 设计
- API 路由和端点
- 数据结构和模型
- 实施单位及任务
- 依赖项和技术堆栈
MCD 至关重要，因为：
- 它使代理能够在处理单个组件之前了解整个系统
- 它允许线性、协调的建造（就像按照蓝图建造房屋）
- 通过提供结构化、相关的上下文来减少令牌的使用
- 它可以防止代理之间的冲突实现
**查看此存储库中的MCD.md文件，**了解所需的结构和详细程度。MCD 应包含：
- 概述和目标
- 上下文和架构图
- 功能要求
- 设计规范（UI/UX、API、数据模型）
- 实现细节
- 代理任务分解
通过全面的 MCD，代理可以逐步实施您的申请，并清楚地了解每个部分如何融入整体。
安装
先决条件
- Python 3.8+
- uv （建议使用，以便更快地安装包）
设置
- 克隆存储库：
git clone https://github.com/your-username/agent-mcp.git
cd agent-mcp
- 通过复制示例文件来设置环境变量：
- 编辑
.env文件并添加您的 OpenAI API 密钥：OPENAI_API_KEY=your_openai_api_key_here
- 使用 uv 安装：
uv venv
uv pip install -e .
多代理工作流
工作流程概述
- 从深度研究开始：在编码之前，使用AI帮助创建全面的主要上下文文档（MCD）
- 启动基础设施：启动 MCP 服务器并在数据库中找到您的管理员令牌
- 管理代理设置：使用令牌和docs/INSTRUCTIONS.md初始化您的管理代理
- 工人创建：管理员为项目的不同方面创建专门的工人
- 任务分配：管理员将 MCD 分解为离散任务并分配给工人
- 并行开发：Workers 通过 MCP 共享上下文并执行任务
- 上下文保存：所有代理将其知识存储在中央数据库中
发展循环
架构概述
MCP 系统采用分层结构，其特点是：
- 管理代理：协调其他代理，分配任务，并维护整体项目方向
- 工作代理：执行特定任务（前端、后端、数据建模等）的专门代理
代理设置和操作
1. 启动 MCP 服务器
uv run -m agent_mcp.cli -- server --port 8080 --project-dir /path/to/your/project
选项：
--port ：运行服务器的端口（默认值：8080）--project-dir ：项目的基本目录
2. 理解 MCP 代币
MCP 系统使用两种类型的令牌进行身份验证：
管理员令牌：
- 启动服务器后，会自动生成管理员令牌
- 此令牌存储在
.agent/mcp_state.db SQLite 数据库中 - 为 VS Code 或其他 SQLite 工具安装 SQLite 查看器扩展
- 打开数据库并检查
project_context表 - 查找管理员令牌条目
- 管理员令牌只能与管理员代理一起使用
工人代币：
- 当管理代理创建工作代理时，会生成一个特定的工作令牌
- 当被要求创建工作者时，管理代理将提供此工作者令牌
- 每个工人都有自己独特的令牌，并具有特定的权限
- 工作令牌也存储在
.agent/mcp_state.db数据库中
重要提示：请勿将管理员令牌用于工作代理。请务必使用管理代理在创建工作代理时提供的特定工作令牌。
3. 代理工作流程（重要）
注意：所有代理都是通过与您的 AI 助手聊天来创建和管理的 - 您不能使用命令行工具来创建代理。
MCP 服务器- 这是您使用命令启动的唯一组件：
uv run -m agent_mcp.cli -- server --port 8080 --project-dir /path/to/your/project
管理代理- 通过告诉您的 AI 助手来创建：
Initialize as an admin agent with this token: [paste-admin-token-here]
Please add the MCD.md file to the project context. Don't summarize it.
工作代理- 通过管理代理创建：
- 告诉管理代理：“创建一个 ID 为‘frontend-worker’的工作代理来实现登录页面”
- 管理员将为该代理提供特定的工作令牌
- 打开一个新的AI助手窗口/会话
- 使用下面第 4 部分中的工作人员令牌和工作人员提示进行初始化
仪表板（ http://localhost:8080 ）：
- 这只是为了可视化 - 您不能在这里创建代理
- 所有实际工作都通过您的 AI 助手聊天窗口进行
- 仪表板显示代理和任务之间的关系
4. 初始化工作代理（复制/粘贴此内容）
在您的管理代理创建工人后，打开一个新的 AI 助手窗口，并使用以下 EXACT 提示初始化工人：
You are [agent_id] agent, your Worker Token: "your_worker_token_here"
Look at your tasks and ask the project RAG agent at least 5-7 questions to understand what you need to do. I want you to critically think when asking a question, then criticize yourself before asking that question. How you criticize yourself is by proposing an idea, criticizing it, and based on that criticism you pull through with that idea.
AUTO --worker --memory
进行以下两个替换：
- 将
[agent_id]替换为您告诉管理员创建的工作者 ID（例如“frontend-worker”） - 将
your_worker_token_here替换为管理员代理在创建此工作者时提供的特定工作者令牌（不是管理员令牌）
初始化后，worker 将：
- 检查分配给其 ID 的任务
- 向 RAG 系统询问项目背景
- 开始自主执行任务
- 将实现细节存储在共享内存系统中
为了获得最佳效果，还请复制docs/INSTRUCTIONS.md的内容并将其粘贴到 AUTO 命令之前。
仪表板和终端 UI
仪表板（可视化）
访问http://localhost:8080上的仪表板来直观地查看多代理系统中发生的情况：
- 实时监控代理活动
- 查看任务状态和依赖关系
- 观察代理关系和协调
- 跟踪文件操作和上下文共享
**重要提示：**仪表板仅用于可视化 - 您无法在此创建或管理代理。所有代理的创建和任务分配均通过您的 AI 助手聊天进行。
多代理会话：视觉指南
对于复杂的项目，您可以同时打开多个聊天会话：
工作原理：
- 管理代理的一个窗口/会话
- 为每个工作代理提供单独的窗口/会话
- 管理员使用管理员令牌，工作人员使用其特定的工作人员令牌
- 每个工作人员都有一个唯一的代理 ID 和令牌
具有 3 个代理的示例设置：
| 窗户 | 代理类型 | 代理 ID | 代币类型 |
|---|
| 1 | 行政 | “行政” | 管理员令牌 |
| 2 | 工人 | “前端工作者” | 前端工作者令牌 |
| 3 | 工人 | “后端工作者” | 后端工作者令牌 |
您可以使用 Claude Code、RooCode 或MultipleCursor来管理在同一代码库上工作的多个窗口/会话。
完整的示例工作流程
以下是如何从头到尾使用 Agent MCP 的分步示例：
步骤 1：创建项目
mkdir -p my-project
cd my-project
git init
# Create initial project files
步骤 2：安装 Agent MCP
git clone https://github.com/rinadelph/Agent-MCP.git mcp
cd mcp
uv venv
uv pip install -e .
cd ..
步骤 3：创建您的 MCD
# Create your MCD file (with help from your AI assistant)
touch MCD.md
步骤 4：启动 MCP 服务器
uv run -m agent_mcp.cli -- server --port 8080 --project-dir $(pwd)
步骤 5：查找管理员令牌
- 在代码编辑器中安装 SQLite Viewer
- 打开
.agent/mcp_state.db - 在
project_context表中查找令牌
步骤 6：初始化管理代理
- 打开你的AI助手（Claude Code，Cursor等）
- 告诉它：
Initialize as an admin agent with this token: [paste-token-here]
Please add the MCD.md file to the project context. Don't summarize it.
步骤 7：创建工作代理
- 告诉管理代理：
Create a worker agent with ID "frontend-worker" to implement the login page component.
- 管理代理将为您提供此新代理的工作令牌
步骤 8：初始化 Worker Agent
- 打开新的AI助手窗口
- 告诉它：
You are frontend-worker agent, your Worker Token: "[paste-worker-token-here]"
Look at your tasks and ask the project RAG agent at least 5-7 questions to understand what you need to do. I want you to critically think when asking a question, then criticize yourself before asking that question. How you criticize yourself is by proposing an idea, criticizing it, and based on that criticism you pull through with that idea.
AUTO --worker --memory
工人现在将自动开始执行其分配的任务！
代币系统和资源管理
理解代币
代币在 MCP 系统中有多种用途：
- 身份验证令牌：用于代理识别和管理员访问
- RAG 令牌：用于从知识库中嵌入和检索上下文
- OpenAI 代币：在代理操作期间消耗（模型使用）
代币管理
监视和管理令牌使用情况：
- 安装 SQLite Viewer 插件或使用命令行：
sqlite3 /path/to/project/.agent/mcp_state.db
- 查询令牌使用情况：
SELECT * FROM token_usage;
- 在仪表板的“资源”选项卡下进行监控
资源优化
对于大型项目：
- 使用具有专注能力的专门代理来减少上下文大小
- 将任务分解为具有明确依赖关系的较小单元
- 利用 RAG 系统进行高效的上下文检索
- 将共享信息存储在项目上下文中，而不是在消息中重复
RAG 项目和知识库（中央记忆系统）
**观看上面的教程：**了解如何将 MCD 添加到中央存储系统
记忆系统如何运作
- MCP 服务器维护所有项目上下文的中央数据库
- 启动服务器时，它会在项目目录中创建一个
.agent文件夹 - 当您初始化 MCD 时，您的管理代理会将其添加到此数据库
- 工作代理会自动查询该数据库以了解其任务
- 所有实施细节都存储在该数据库中，以供其他代理访问
设置项目 RAG
检索增强生成 (RAG) 系统允许代理有效地访问相关项目知识：
- 索引项目文件：
python -m agent_mcp.features.rag.indexing -- --project-dir /path/to/project
- 将文档添加到知识库：
python -m agent_mcp.features.rag.indexing -- --add-doc /path/to/document.md
在代理工作流中使用 RAG
代理可以使用以下方式查询知识库：
response = await client.ask_project_rag("How does the authentication system work?")
社区
加入我们的 Discord 社区，讨论 Agent MCP、分享你的项目、获取帮助，并与其他使用 AI 工具构建的开发者交流。我们是一个不断发展壮大的社区，致力于突破多智能体系统和 AI 协作的极限。