Agent-MCP：基于MCP协议的多智能体协作框架

Agent-MCP是一款基于Model Context Protocol（MCP）的多智能体系统开发框架，通过标准化协议实现智能体间的高效协同。

分层协作架构：包含管理智能体（Admin Agent）与工作智能体（Worker Agent）的双层结构，管理智能体负责全局任务调度与上下文维护，工作智能体专注于细分任务执行，如前端开发、后端接口实现等。

上下文共享机制：通过中央数据库存储项目上下文（如架构文档、任务细节），智能体可实时查询共享知识，避免重复信息传递，降低Token消耗。

可视化与管理工具：提供仪表盘（Dashboard）实时监控智能体交互与任务状态，搭配终端界面（TUI/CLI）实现令牌管理、任务追踪等操作。

快速入门流程

使用Agent-MCP的完整操作指南分为环境搭建、服务启动、智能体配置三个关键环节。

（一）环境准备

1、代码获取与配置

通过Git克隆仓库：

git clone https://github.com/rinadelph/Agent-MCP.git
cd Agent-MCP

复制环境变量示例文件并配置OpenAI密钥：

cp .env.example .env
# 编辑.env文件，填入你的OpenAI API密钥
OPENAI_API_KEY=your_api_key_here

2、依赖安装 推荐使用uv工具创建虚拟环境并安装项目：

uv venv
uv pip install -e .

若未安装uv，也可使用传统pip命令：

python -m venv venv
source venv/bin/activate  # Linux/macOS
venv\Scripts\activate     # Windows
pip install -e .

（二）启动MCP服务

执行以下命令启动服务，指定端口与项目目录：

uv run -m mcp_template.main --port 8080 --project-dir /path/to/your/project

关键操作提示：

服务启动后，会在项目目录下创建.agent文件夹，其中包含存储管理令牌的SQLite数据库mcp_state.db。

使用VS Code等编辑器的SQLite插件打开数据库，在project_context表中查找admin_token字段，获取管理令牌。

（三）智能体初始化与任务分配

1、管理智能体配置

打开AI代码助手（如Claude Code、Cursor），输入以下指令初始化管理智能体：

Initialize as an admin agent with this token: [粘贴获取的admin_token]
Please add the MCD.md file to the project context、Don't summarize it.

需提前在项目根目录创建主上下文文档（MCD.md），内容应包含系统架构、API设计、数据模型等详细规划（可参考仓库内MCD-EXAMPLE文件夹模板）。

2、工作智能体创建

向管理智能体发送任务创建指令，示例：

Create a worker agent with ID "backend-worker" to implement user authentication API.

管理智能体会返回专属工作令牌。打开新的AI助手窗口，使用以下格式初始化工作智能体：

You are backend-worker agent, your Worker Token: "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]与worker_token_here为实际值，工作智能体将自动从中央数据库获取任务上下文并启动执行。

核心组件和最佳实践

（一）主上下文文档（MCD）的关键作用

MCD是项目的唯一事实来源，其内容直接影响智能体协作效率，文档应包含：

系统架构图：展示组件间依赖关系（如前端、后端、数据库的交互流程）。

功能需求列表：按模块拆分需求，如用户模块包含注册、登录、权限管理等子功能。

任务拆解表：将需求细化为可执行任务，示例：

任务ID

描述

负责人

依赖项

task-front-01

实现登录页面UI组件

frontend

无

task-back-01

开发用户登录API接口

backend

task-front-01

（二）令牌系统与资源管理

管理令牌（Admin Token）：仅用于初始化管理智能体，具备创建工作智能体、更新项目上下文等高级权限。

工作令牌（Worker Token）：每个工作智能体独立生成，权限限于执行指定任务，需通过管理智能体分配获取。

Token使用监控：通过SQLite命令或仪表盘查看消耗情况：

sqlite3 .agent/mcp_state.db "SELECT * FROM token_usage;"

优化建议：将任务拆分为更小单元，利用RAG（检索增强生成）系统精准获取所需上下文，避免传递冗余信息。

（三）可视化与交互工具

仪表盘（Dashboard）：访问http://localhost:8080查看智能体网络拓扑、任务进度甘特图等实时数据，辅助理解协作流程。

终端界面（TUI/CLI）：通过命令行快速管理多项目实例，示例操作：

# 列出所有任务（CLI）
./scripts/mcp --token your_admin_token task list

# 启动交互式终端（TUI）
python -m mcp_template_terminal_ui.tui

工作流示例

以构建全栈应用为例，演示完整协作流程：

1、项目初始化：创建项目目录并初始化Git仓库，生成MCD文档定义整体架构。

2、服务启动与令牌获取：启动MCP服务后，从数据库提取管理令牌。

3、管理智能体部署：通过AI助手告知管理智能体加载MCD文档，建立项目上下文。

4、工作智能体分配：

指令管理智能体创建前端智能体，负责用户界面开发。

创建后端智能体，处理数据存储与API逻辑。

5、并行开发与上下文共享：各智能体通过中央数据库同步信息，如前端智能体完成UI组件后，后端智能体可直接查询组件接口定义进行对接。

进阶功能

（一）RAG系统集成

通过rag_indexer工具将项目文件（如API文档、设计稿）索引至中央知识库，智能体可通过自然语言查询获取相关内容：

# 索引项目文件
python -m mcp_template.rag_indexer --project-dir /path/to/project

# 查询知识库
response = await client.ask_project_rag("What's the structure of user table?")

（二）多智能体会话管理

推荐使用MultipleCursor等工具管理多个AI助手窗口，每个窗口对应一个智能体实例，实现真正的并行开发。

窗口编号

智能体类型

标识

令牌类型

1

管理智能体

admin

管理令牌

2

前端智能体

frontend

前端工作令牌

3

后端智能体

backend

后端工作令牌