Agent-MCP

背景：为什么需要多 Agent 协作？

当你用 AI 编程工具处理一个中小型项目时，单 Agent 模式通常足够。但面对一个拥有数十个模块、数万行代码的大型代码库时，单 Agent 的局限性立刻显现：上下文窗口溢出、对话间知识丢失、单线程执行瓶颈、无法专业化分工。每一个问题都足以拖慢开发节奏。

Agent-MCP 的作者 Luis Alejandro Rincon（GitHub @rinadelph）正是带着这个问题出发，设计了一套多 Agent 协作框架。它的核心哲学是：把一个大型代码库交给多个专业化 Agent 并行处理，每个 Agent 专注自己的领域（后端、前端、测试、文档），通过共享知识图谱保持上下文连贯，就像一个真实的软件开发团队。## 核心技术架构

双运行时设计

Agent-MCP 提供了两套实现，推荐使用 Python 版本（基于 Starlette/Uvicorn），同时也保留了 Node.js/TypeScript 版本作为备选。这种双运行时策略让框架的适用范围更广：Python 生态中偏工程化的项目可直接使用 Python 版本，而更习惯 JS/TS 全栈的团队可以用 Node.js 版本。

Python 版本的核心依赖：

• Starlette + Uvicorn：异步 Web 服务框架，提供 HTTP 和 SSE（Server-Sent Events）传输层
• MCP SDK（mcp>=1.8.1）：核心协议层，通过 mcp.server.lowlevel.Server 实现 MCP 协议端点，将框架自身暴露为一个 MCP Server，供 Claude Desktop、Cline 等 MCP 兼容客户端连接
• OpenAI API：唯一支持的 LLM 后端，通过 openai Python 包调用 GPT 系列模型
• sqlite-vec：SQLite 的向量搜索扩展，用于 RAG 系统的语义检索（chunk 级别的向量存储与相似度查询）

模块化目录结构

agent_mcp/
├── core/          # 配置、全局状态（globals.py）、认证
├── app/           # Starlette 应用：路由、静态文件、SSE 传输
├── db/            # SQLite 连接层、vec 扩展加载、写队列
├── external/      # OpenAI 客户端初始化封装
├── features/
│   ├── rag/       # RAG 系统核心（indexing.py + query.py + chunking.py）
│   └── dashboard/ # Dashboard API（图形数据、任务树）
├── tools/         # MCP 工具注册与分发（create_agent, assign_task 等）
└── dashboard/     # Next.js 前端（React + TypeScript）

值得注意的是，Dashboard 是一个独立的 Next.js 应用，通过 npm run dev 单独启动，与 Python 后端通过 HTTP API 交互。这使得前后端可以独立部署和迭代。## RAG 知识图谱系统

Agent-MCP 的记忆层是其最有技术深度的部分。代码库被索引后，以向量形式存入 SQLite-vec，向量维度与 OpenAI text-embedding-3-small 模型对齐。

三层检索策略

当 Agent 发起查询时，query_rag_system 执行一个精心设计的三层检索：

1. 活跃上下文（Live Context）：查询最近更新的上下文条目（基于 last_indexed_context 元数据），保证 Agent 拿到的是最新状态
2. 任务相关上下文：从任务数据库中检索相关任务记录，确保任务上下文的连贯性
3. 向量语义搜索：使用 OpenAI embedding 将查询文本向量化，在 sqlite-vec 中做 Top-K 相似度匹配，取最相关的知识片段

三层结果合并后，由 GPT 模型综合生成回答。这种设计兼顾了时效性和语义相关性，比纯向量检索更稳定。

智能分块策略

chunking.py 提供了多种分块策略：

• simple_chunker：按固定字符数和重叠量切分（chunk_size=500, overlap=50）
• markdown_aware_chunker：识别 Markdown 标题结构，按语义段落切分
• chunk_code_aware：针对代码文件，识别语言家族（Python/JS/Go/Rust 等）、提取函数/类级别的代码实体，生成文件摘要

分块策略的选择直接影响 RAG 效果。对于代码项目，chunk_code_aware 能保留函数级别的上下文完整性，避免跨函数截断导致的语义破坏。## 实时可视化 Dashboard

Dashboard 是 Agent-MCP 的用户交互层，基于 Next.js + React 构建，提供六个主要视图：

图1：Dashboard 总览界面

• Overview：全局概览，展示 Agent 网络拓扑、任务完成进度
• Agents：所有 Agent 的实时状态、分配的 Token（认证标识）、当前工作目录
• Tasks：任务树视图，支持父子任务依赖关系可视化
• Memories：持久化知识图谱的内容查询界面
• Prompt Book：复用性高的 Prompt 模板库
• System：系统健康度监控（DB 连接状态、API Key 配置等）

图2：Memory Bank 界面 — 持久化知识图谱查询## MCP 协议集成

这是 Agent-MCP 区别于其他 AI 编程 Agent 工具的关键。它不仅仅是一个 CLI 工具，而是一个标准的 MCP Server。

MCP 工具清单

框架注册了以下 MCP 工具，供 MCP 兼容客户端调用：

工具名	功能
create_agent	创建一个新的专业化 Agent（如 backend-dev、frontend-dev）
list_agents	查看所有活跃 Agent 及其状态
terminate_agent	安全关闭指定 Agent
assign_task	向指定 Agent 分配任务
view_tasks	查看任务进度和依赖关系
update_task_status	更新任务状态（pending/completed/blocked）
ask_project_rag	查询持久化知识图谱
update_project_context	向知识图谱写入架构决策和上下文
send_agent_message	Agent 间直接通信
broadcast_message	向所有 Agent 广播消息
request_assistance	请求其他 Agent 协助

与 Claude Desktop 的集成

Claude Desktop 用户只需在 claude_desktop_config.json 中添加 Agent-MCP 的配置（指向本地运行的 uv run -m agent_mcp.cli 进程），即可在对话中直接调用上述工具。这意味着可以在 Claude 的自然语言界面中驱动整个多 Agent 团队工作。## 部署体验

优点

• 零容器依赖：纯 Python + Node.js 环境，可直接通过 uv 和 npm 管理依赖
• MCP 生态兼容：接入 Claude Desktop 等主流 AI 工具的生态链路短
• Dashboard 可视化好：任务状态、Agent 拓扑、Memory 内容均有图形界面

局限

• 不支持一键部署：缺少 Dockerfile 和 docker-compose，跨机器迁移需要手动重装环境
• 仅支持 OpenAI：不支持 Anthropic、Google、Azure 等其他 LLM 提供商，对于希望使用 Claude 的团队是硬性限制
• 文档不够友好：README 开篇明确说"本框架面向有经验的 AI 开发者"，对新手不友好，文档中大量实现细节缺失## 行业意义与发展趋势

Agent-MCP 代表了 AI 编程工具从"单 Agent 对话"向"多 Agent 协作"的演进方向。类似的项目还包括 AutoGPT、BabyAGI、CrewAI 等，但 Agent-MCP 的差异化在于：

1. MCP 协议优先：不是自建 Agent 通信协议，而是拥抱 MCP 生态，降低与其他工具的集成成本
2. 代码库级持久化：通过 sqlite-vec 将索引持久化在本地，不依赖外部向量数据库
3. tmux 深度集成：Agent 工作在真实的 tmux session 中，可以手动接管调试

随着 Claude Desktop、Cursor 等工具对 MCP 支持的成熟，Agent-MCP 这类框架的价值会进一步凸显——它为 AI 编码工具提供了可编排的多 Agent 基础设施。

图3：Agent 网络拓扑可视化 — 紫色节点为上下文条目，蓝色节点为 Agent，边表示活跃协作关系

图4：Agent Fleet 视图 — 实时监控多个专业化 Agent 的工作状态