MCP 代理

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

快速入门指南

注意：我建议使用MultipleCursor在同一个代码库上启动不同的聊天窗口，如上图所示。

1. 设置环境

• 克隆 repo 并将.env.example复制到.env

• 将您的 OpenAI API 密钥添加到.env

• 使用uv venv && uv pip install -e .

2. 启动 MCP 服务器

重要提示：服务器启动时，会在项目的.agent文件夹中创建一个数据库。您的管理员令牌存储在此数据库中。要查找它，请执行以下操作：

1. 在代码编辑器中安装 SQLite 查看器扩展

2. 打开数据库/path/to/your/project/.agent/mcp_state.db

3. 检查project_context表中的管理员令牌

3. 创建主上下文文档（MCD）

• 在您的项目中创建一个详细的MCD.md文件，其中包含架构、API 路由、数据模型等。

• 这可以是单个文件或多个文件（对于复杂项目）

• 请参阅MCD-EXAMPLE文件夹中的模板

4.启动管理代理

1. 在项目文件夹中打开你的 AI 编码助手（Claude Code、Cursor 等）

2. 复制您在步骤 2 中找到的管理员令牌

3. 要求 AI“使用此令牌初始化为管理代理：[your-token]”

4. 告诉管理代理将您的 MCD 添加到项目上下文中：

   Please add the MCD.md file to the project context. Don't summarize it.

5. 通过管理员创建和管理工作代理

1. 要求您的管理代理创建一个工作代理：

   Create a worker agent with ID "frontend-worker" to implement the login page.

2. 在你的 AI 助手中打开一个新窗口/会话（相同的代码库）

3. 使用以下精确提示初始化工作者：

   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

4. 工人将自动找到其分配的任务并开始工作

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

Related MCP server: MCP Server for n8n Integration

特征

• 多代理协作框架

• 任务管理和协调

• 代理之间的上下文和知识共享

• 代理交互的图形可视化

• 支持嵌入和 RAG 功能

• 用于可视化任务、代理和上下文的交互式仪表板

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

观看视频教程：如何将 MCD 上下文添加到 Agent MCP

在开始开发之前，务必进行深入研究，创建一份主上下文文档 (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. 管理代理设置：使用令牌和docs/INSTRUCTIONS.md初始化您的管理代理

4. 工人创建：管理员为项目的不同方面创建专门的工人

5. 任务分配：管理员将 MCD 分解为离散任务并分配给工人

6. 并行开发：Workers 通过 MCP 共享上下文并执行任务

7. 上下文保存：所有代理将其知识存储在中央数据库中

发展循环

架构概述

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

• 管理代理：协调其他代理，分配任务，并维护整体项目方向

• 工作代理：执行特定任务（前端、后端、数据建模等）的专门代理

代理设置和操作

1. 启动 MCP 服务器

选项：

• --port ：运行服务器的端口（默认值：8080）

• --project-dir ：项目的基本目录

2. 理解 MCP 代币

MCP 系统使用两种类型的令牌进行身份验证：

管理员令牌：

1. 启动服务器后，会自动生成管理员令牌

2. 此令牌存储在.agent/mcp_state.db SQLite 数据库中

3. 为 VS Code 或其他 SQLite 工具安装 SQLite 查看器扩展

4. 打开数据库并检查project_context表

5. 查找管理员令牌条目

6. 管理员令牌只能与管理员代理一起使用

工人代币：

1. 当管理代理创建工作代理时，会生成一个特定的工作令牌

2. 当被要求创建工作者时，管理代理将提供此工作者令牌

3. 每个工人都有自己独特的令牌，并具有特定的权限

4. 工作令牌也存储在.agent/mcp_state.db数据库中

重要提示：请勿将管理员令牌用于工作代理。请务必使用管理代理在创建工作代理时提供的特定工作令牌。

3. 代理工作流程（重要）

注意：所有代理都是通过与您的 AI 助手聊天来创建和管理的 - 您不能使用命令行工具来创建代理。

MCP 服务器- 这是您使用命令启动的唯一组件：

管理代理- 通过告诉您的 AI 助手来创建：

工作代理- 通过管理代理创建：

1. 告诉管理代理：“创建一个 ID 为‘frontend-worker’的工作代理来实现登录页面”

2. 管理员将为该代理提供特定的工作令牌

3. 打开一个新的AI助手窗口/会话

4. 使用下面第 4 部分中的工作人员令牌和工作人员提示进行初始化

仪表板（ http://localhost:8080 ）：

• 这只是为了可视化 - 您不能在这里创建代理

• 所有实际工作都通过您的 AI 助手聊天窗口进行

• 仪表板显示代理和任务之间的关系

4. 初始化工作代理（复制/粘贴此内容）

在您的管理代理创建工人后，打开一个新的 AI 助手窗口，并使用以下 EXACT 提示初始化工人：

进行以下两个替换：

1. 将[agent_id]替换为您告诉管理员创建的工作者 ID（例如“frontend-worker”）

2. 将your_worker_token_here替换为管理员代理在创建此工作者时提供的特定工作者令牌（不是管理员令牌）

初始化后，worker 将：

1. 检查分配给其 ID 的任务

2. 向 RAG 系统询问项目背景

3. 开始自主执行任务

4. 将实现细节存储在共享内存系统中

为了获得最佳效果，还请复制docs/INSTRUCTIONS.md的内容并将其粘贴到 AUTO 命令之前。

仪表板和终端 UI

仪表板（可视化）

访问http://localhost:8080上的仪表板来直观地查看多代理系统中发生的情况：

• 实时监控代理活动

• 查看任务状态和依赖关系

• 观察代理关系和协调

• 跟踪文件操作和上下文共享

**重要提示：**仪表板仅用于可视化 - 您无法在此创建或管理代理。所有代理的创建和任务分配均通过您的 AI 助手聊天进行。

多代理会话：视觉指南

对于复杂的项目，您可以同时打开多个聊天会话：

工作原理：

1. 管理代理的一个窗口/会话

2. 为每个工作代理提供单独的窗口/会话

3. 管理员使用管理员令牌，工作人员使用其特定的工作人员令牌

4. 每个工作人员都有一个唯一的代理 ID 和令牌

具有 3 个代理的示例设置：

您可以使用 Claude Code、RooCode 或MultipleCursor来管理在同一代码库上工作的多个窗口/会话。

完整的示例工作流程

以下是如何从头到尾使用 Agent MCP 的分步示例：

步骤 1：创建项目

步骤 2：安装 Agent MCP

步骤 3：创建您的 MCD

步骤 4：启动 MCP 服务器

步骤 5：查找管理员令牌

1. 在代码编辑器中安装 SQLite Viewer

2. 打开.agent/mcp_state.db

3. 在project_context表中查找令牌

步骤 6：初始化管理代理

1. 打开你的AI助手（Claude Code，Cursor等）

2. 告诉它：

步骤 7：创建工作代理

1. 告诉管理代理：

2. 管理代理将为您提供此新代理的工作令牌

步骤 8：初始化 Worker Agent

1. 打开新的AI助手窗口

2. 告诉它：

工人现在将自动开始执行其分配的任务！

代币系统和资源管理

理解代币

代币在 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 项目和知识库（中央记忆系统）

**观看上面的教程：**了解如何将 MCD 添加到中央存储系统

记忆系统如何运作

1. MCP 服务器维护所有项目上下文的中央数据库

2. 启动服务器时，它会在项目目录中创建一个.agent文件夹

3. 当您初始化 MCD 时，您的管理代理会将其添加到此数据库

4. 工作代理会自动查询该数据库以了解其任务

5. 所有实施细节都存储在该数据库中，以供其他代理访问

设置项目 RAG

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

1. 索引项目文件：

   python -m agent_mcp.features.rag.indexing -- --project-dir /path/to/project

2. 将文档添加到知识库：

   python -m agent_mcp.features.rag.indexing -- --add-doc /path/to/document.md

在代理工作流中使用 RAG

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

社区

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