Agent MCP

MCP 代理

使用 MCP（模型上下文协议）创建多智能体系统的框架，以实现协调、高效的 AI 协作。

快速入门指南

注意：我建议使用https://github.com/rinadelph/MultipleCursor以便在同一个代码库上启动不同的 Cursor 窗口，如上图所示。

1. 安装环境：
   • 克隆 repo 并将.env.example复制到.env
   • 将您的 OpenAI API 密钥添加到.env
   • 使用uv venv && uv pip install -e .
2. 启动 MCP 服务器：
   uv run -m mcp_template.main --port 8080 --project-dir /path/to/your/project
   重要提示：管理员令牌存储在项目上下文的.agent/mcp_state.db SQLite 数据库中。请安装 SQLite 查看器扩展程序来访问它。
3. 创建主上下文文档（MCD） ：
   • 创建包含系统架构、API 路由、数据模型等的详细MCD.md
4. 启动管理代理：
   • 在一个窗口/会话中启动
   • 给它管理员令牌
5. 初始化工作代理：
   • 为每个工作者打开新窗口/会话
   • 使用下面第 4 部分中的自动模式复制工人提示
   • 用正确的代理 ID 和管理员令牌替换

请按照以下详细说明获取更多信息。

特征

• 多代理协作框架
• 任务管理和协调
• 代理之间的上下文和知识共享
• 代理交互的图形可视化
• 支持嵌入和 RAG 功能
• 用于可视化任务、代理和上下文的交互式仪表板。

使用主上下文文档 (MCD) 进行项目规划

在开始开发之前，务必进行深入研究，创建一份主上下文文档 (MCD) ，这是应用程序的唯一可信来源。本文档提供了一个详细的计划，详细说明：

• 系统架构和组件关系
• 所有屏幕和组件的 UI/UX 设计
• API 路由和端点
• 数据结构和模型
• 实施单位及任务
• 依赖项和技术堆栈

MCD 至关重要，因为：

1. 它使代理能够在处理单个组件之前了解整个系统
2. 它允许线性、协调的建造（就像按照蓝图建造房屋一样）
3. 通过提供结构化、相关的上下文来减少令牌的使用
4. 它可以防止代理之间的冲突实现

**查看此存储库中的MCD.md文件，**了解所需的结构和详细程度。MCD 应包含：

• 概述和目标
• 上下文和架构图
• 功能要求
• 设计规范（UI/UX、API、数据模型）
• 实现细节
• 代理任务分解

通过全面的 MCD，代理可以逐步实施您的申请，并清楚地了解每个部分如何融入整体。

安装

先决条件

• Python 3.8+
• uv （建议使用，以便更快地安装包）

设置

1. 克隆存储库：
   git clone https://github.com/your-username/agent-mcp.git cd agent-mcp
2. 通过复制示例文件来设置环境变量：
   cp .env.example .env
3. 编辑.env文件并添加您的 OpenAI API 密钥：
   OPENAI_API_KEY=your_openai_api_key_here
4. 使用 uv 安装：
   uv venv uv pip install -e .
   或者使用 pip：
   pip install -e .

多代理工作流

工作流程概述

1. 从深度研究开始：在编码之前，使用AI帮助创建全面的主要上下文文档（MCD）
2. 启动基础设施：启动 MCP 服务器并在数据库中找到您的管理员令牌
3. 管理代理设置：使用令牌和 INSTRUCTIONS.md 初始化您的管理代理
4. 工人创建：管理员为项目的不同方面创建专门的工人
5. 任务分配：管理员将 MCD 分解为离散任务并分配给工人
6. 并行开发：Workers 通过 MCP 共享上下文并执行任务
7. 上下文保存：所有代理将其知识存储在中央数据库中

发展循环

架构概述

MCP 系统采用分层结构，其特点是：

• 管理代理：协调其他代理，分配任务，并维护整体项目方向
• 工作代理：执行特定任务（前端、后端、数据建模等）的专门代理

代理设置和操作

1. 启动 MCP 服务器

选项：

• --port ：运行服务器的端口（默认值：8080）
• --project-dir ：项目的基本目录

2. 访问管理员令牌

管理员令牌提供对 MCP 服务器的特权访问，并且是所有代理操作所必需的。

查找管理员令牌：

1. 启动服务器后，会自动生成token
2. 此令牌存储在.agent/mcp_state.db SQLite 数据库中
3. 为 VS Code 或其他 SQLite 工具安装 SQLite 查看器扩展
4. 打开数据库并检查project_context表
5. 查找管理员令牌条目

代理令牌：代理专用令牌也存储在.agent文件夹中。这些令牌赋予每个代理在 MCP 系统中的特定权限和身份。

3. 启动代理

1. 首先启动 MCP 服务器：
   uv run -m mcp_template.main --port 8080 --project-dir /path/to/your/project
   服务器将在启动时生成一个管理员令牌 - 保存此令牌，因为您需要它来进行代理身份验证。
2. 管理代理：使用以下命令启动单个管理代理：
   uv run -m mcp_template.mcp_client_runner --admin
   如果您遇到导入错误，例如ModuleNotFoundError: No module named 'mcp_client' ，请确保您从项目根目录运行并且您的 Python 包已正确安装。
3. 工作代理：无需直接启动工作代理，而是指示管理代理创建和管理它们。具体操作如下：
   "Create a new agent with ID 'frontend-worker' and assign it to implement the login page based on the MCD."
   管理代理将负责创建任务并将其分配给工作代理。

4. 使用 AUTO 模式与 Worker Agents

建议通过管理代理来初始化工作代理。创建代理后，请使用以下工作代理初始化提示（复制并粘贴到您的工作代理中）：

将[agent_id]替换为实际的 worker ID（例如“frontend-worker”），并将your_admin_token_here替换为启动 MCP 服务器时生成的 token。

这将命令代理：

• 自主操作，无需用户干预
• 遵循工人协议并跟踪任务状态
• 利用记忆在交互过程中保留上下文
• 主动查询 RAG 系统以了解任务上下文

为了获得最佳效果，请在初始化代理时将 INSTRUCTIONS.md 中的说明复制粘贴到 AUTO 命令之前进行附加。

仪表板

访问http://localhost:8080上的仪表板以：

• 实时监控代理活动
• 查看任务状态和依赖关系
• 观察代理关系和协调
• 跟踪文件操作和上下文共享

替代开发：多代理会话

对于复杂项目，建议采用以下方法：

1. 为您的管理代理使用一个对话
2. 为每个工作者代理启动单独的对话/会话
3. 与所有代理共享相同的管理令牌
4. 在多个窗口/会话中使用 Claude Code、RooCode 或 Cursor

这种方法为每个代理提供了自己的对话环境，同时它们通过共享 MCP 系统进行协作。

工作流程示例：

1. 启动 MCP 服务器并记下管理员令牌
2. 在一个窗口中创建管理代理
3. 对于每个工作者代理，打开一个新窗口并使用上面的工作者提示进行初始化
4. 为每个工作人员提供自己的代理 ID，但提供相同的管理令牌

代币系统和资源管理

理解代币

代币在 MCP 系统中有多种用途：

1. 身份验证令牌：用于代理识别和管理员访问
2. RAG 令牌：用于从知识库中嵌入和检索上下文
3. OpenAI 代币：在代理操作期间消耗（模型使用）

代币管理

监视和管理令牌使用情况：

1. 安装 SQLite Viewer 插件或使用命令行：
   sqlite3 /path/to/project/.agent/mcp_state.db
2. 查询令牌使用情况：
   SELECT * FROM token_usage;
3. 在仪表板的“资源”选项卡下进行监控

资源优化

对于大型项目：

1. 使用具有专注能力的专门代理来减少上下文大小
2. 将任务分解为具有明确依赖关系的较小单元
3. 利用 RAG 系统进行高效的上下文检索
4. 将共享信息存储在项目上下文中，而不是在消息中重复

RAG 项目和知识库

设置项目 RAG

检索增强生成 (RAG) 系统允许代理有效地访问相关项目知识：

1. 索引项目文件：
   python -m mcp_template.rag_indexer --project-dir /path/to/project
2. 将文档添加到知识库：
   python -m mcp_template.rag_indexer --add-doc /path/to/document.md

在代理工作流中使用 RAG

代理可以使用以下方式查询知识库：

这将返回相关上下文，而无需加载整个文件、保存令牌并提高响应质量。

Agent任务分配策略

为了获得最佳性能，请遵循以下准则：

1. 任务粒度：将大型任务分解为具有明确输入/输出的原子单元
2. 依赖关系跟踪：在任务分配中明确定义任务依赖关系
3. 能力匹配：将任务分配给具有相关能力的代理
4. 进度监控：使用明确的状态更新来跟踪任务进度
5. 上下文共享：在分配时提供必要的上下文，以减少以后的查找

管理员向工作人员分配任务的示例：

创建新的 Worker Agent 时：

1. 告诉您的管理代理：“创建一个 ID 为‘frontend-worker’的新代理，并指派它基于 MCD 实现登录页面。”
2. 打开一个新窗口/会话，并使用前面描述的 AUTO 提示初始化工作代理
3. 确保包含管理员令牌，以便工作人员可以访问其分配的任务

成分

• main.py ：MCP 服务器实现
• mcp_client.py ：用于将代理连接到 MCP 的客户端库
• dashboard_api.py ：可视化的 API 端点
• rag_agent_test.py ：支持 RAG 的代理示例
• INSTRUCTIONS.md ：代理操作指南

环境变量

• OPENAI_API_KEY ：您的 OpenAI API 密钥
• MCP_SERVER_URL ：MCP 服务器的 URL
• MCP_ADMIN_TOKEN ：（可选）用于直接访问的管理员令牌
• MCP_PROJECT_DIR ：项目目录的路径

执照

MIT 许可证

社区

加入我们的 Discord 社区，讨论 Agent MCP、分享你的项目、获取帮助，并与其他使用 AI 工具构建的开发者交流。我们是一个不断发展壮大的社区，致力于突破多智能体系统和 AI 协作的极限。