内容
# AI 代理桥 MCP
用于 AI 代理的实时通信、任务委托和状态监控的桥梁，基于 MCP 协议。
## 快速开始
### 后端服务器
```bash
# 安装依赖
pip install -e .
# 启动服务器
python main.py
# 服务器运行在 http://localhost:8000
```
### 客户端（MCP 代理）
客户端组件连接 AI 代理（如 Claude Code）到桥梁服务器：
```bash
cd client
# 安装依赖
pip install -e .
# 创建 .env 文件（可选）
cat > .env << EOF
BRIDGE_URL=ws://localhost:8000/ws_proxy
LOG_LEVEL=INFO
EOF
# 启动 MCP 代理
python main.py
```
配置 Claude Code 使用代理：
```json
{
"mcpServers": {
"agent-bridge-proxy": {
"command": "python",
"args": ["F:/path/to/client/main.py"]
}
}
}
```
### 前端仪表盘
```bash
cd frontend
npm install
npm run dev
# 开发服务器在 http://localhost:3000（API 代理到 :8000）
```
### Docker
```bash
docker build -t ai-agent-bridge .
docker run -p 8000:8000 ai-agent-bridge
```
## 架构
> 📖 有关详细的技术架构文档，请参阅 [ARCHITECTURE.md](ARCHITECTURE.md)。
```
┌─────────────────────────────────────────────────────────────────┐
│ 前端仪表盘 │
│ （Vue 3 + WebSocket + Pinia） │
└─────────────────────────────────────────────────────────────────┘
│
│ WebSocket
▼
┌─────────────────────────────────────────────────────────────────┐
│ 桥梁服务器 │
│ （FastAPI + SSE + JSON-RPC） │
│ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────────────┐ │
│ │ 代理注册 │ │任务管理器 │ │ WebSocket 代理 API │ │
│ └──────────────┘ └──────────────┘ └──────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
│
┌───────────────┼───────────────┐
│ │ │
│ SSE │ WS 代理 │ SSE
▼ ▼ ▼
┌───────────────────┐ ┌───────────────────┐ ┌───────────────────┐
│ Claude Code A │ │ MCP 代理 │ │ Claude Code B │
│ （直接 SSE） │ │ （客户端代理） │ │ （直接 SSE） │
└───────────────────┘ └───────────────────┘ └───────────────────┘
```
## 客户端组件（MCP 代理）
客户端（`client/`）提供 MCP 代理，允许 Claude Code 实例：
- 向桥梁注册
- 列出不同机器上的远程代理
- 委托任务给其他代理
- 接收和处理分配的任务
- 更新任务状态和结果
### 客户端工具
| 工具 | 描述 |
|------|-------------|
| `agent_register` | 注册/更新代理信息（项目、技能、能力） |
| `get_pending_tasks` | 获取当前代理的待处理任务 |
| `list_remote_agents` | 列出其他机器上的代理 |
| `task_delegate` | 委托任务给另一个项目的代理 |
| `task_update` | 更新任务状态（IN_PROGRESS、DONE、FAILED） |
### 客户端配置
| 变量 | 默认值 | 描述 |
|----------|---------|-------------|
| `BRIDGE_URL` | `ws://localhost:8000/ws_proxy` | WebSocket 代理端点 |
| `LOG_LEVEL` | `INFO` | 日志级别 |
| `LLM_ENABLED` | `false` | 启用 LLM 路由 |
| `LLM_PROVIDER` | `qwen` | LLM 提供商（qwen、moonshot） |
| `DASHSCOPE_API_KEY` | — | DashScope API 密钥，用于 LLM |
## 用法
### 代理注册和连接
代理通过 **SSE + JSON-RPC 2.0** 协议连接：
**1. 连接到 SSE 获取会话 ID**
```bash
curl -N http://localhost:8000/sse
# → event: session
# → data: {"session_id": "abc123..."}
```
**2. 注册代理**
```bash
curl -X POST "http://localhost:8000/messages?session_id=abc123..." \
-H "Content-Type: application/json" \
-d '{
"jsonrpc": "2.0",
"id": "1",
"method": "agent.register",
"params": {
"name": "claude-code",
"project": "my-project",
"capabilities": {
"mcp_servers": ["gitnexus", "zread"],
"skills": ["pptx", "commit"],
"description": "代码生成和错误修复"
}
}
}'
```
一旦注册，仪表盘将实时显示该代理的状态、项目、IP 和能力徽章。
**3. 发送心跳保持在线**
```bash
curl -X POST "http://localhost:8000/messages?session_id=abc123..." \
-H "Content-Type: application/json" \
-d '{"jsonrpc": "2.0", "id": "2", "method": "agent.heartbeat"}'
```
代理在 60 秒内无心跳将被自动标记为离线。
### 任务委托
代理 A 可以委托任务给代理 B 并接收实时结果：
**1. 委托任务**
```bash
curl -X POST "http://localhost:8000/messages?session_id=<agent-a-session>" \
-H "Content-Type: application/json" \
-d '{
"jsonrpc": "2.0",
"id": "3",
"method": "task.delegate",
"params": {
"title": "修复登录错误",
"description": "登录端点在空输入时返回 500",
"to_agent": "<agent-b-id>"
}
}'
```
**2. 更新任务进度和结果**
代理 B 接收到 `task.assigned` 事件，通过 SSE 更新任务：
```bash
# 开始工作
curl -X POST "http://localhost:8000/messages?session_id=<agent-b-session>" \
-H "Content-Type: application/json" \
-d '{"jsonrpc": "2.0", "id": "4", "method": "task.update", "params": {"task_id": "<task-id>", "status": "IN_PROGRESS"}}'
# 完成并返回结果
curl -X POST "http://localhost:8000/messages?session_id=<agent-b-session>" \
-H "Content-Type: application/json" \
-d '{"jsonrpc": "2.0", "id": "5", "method": "task.update", "params": {"task_id": "<task-id>", "status": "DONE", "result": "Fixed: added null check"}}'
```
代理 A 通过 SSE 实时接收 `task.updated` 和 `task.result` 事件。
### Claude Code 集成
Claude Code 通过标准的 MCP SSE 协议连接到此桥梁。连接后，它出现在仪表盘上，可以与其他代理交换任务。
**1. 配置 Claude Code**
在项目根目录下创建 `.mcp.json`（或在 Claude Code 中使用 `/mcp` 命令）：
```json
{
"mcpServers": {
"agent-bridge": {
"type": "sse",
"url": "http://localhost:8000/sse"
}
}
}
```
**2. 连接后自动注册**
连接后，询问 Claude Code：
> 使用 agent_register 工具注册此代理。设置名称为 "claude-code-01"，项目为 "my-project"，并在功能中列出 MCP 服务器和技能。
Claude Code 调用 `agent_register` 进行注册。注册后：
- 此 Claude Code 实例出现在仪表盘上，显示状态、项目和能力徽章
- 使用 `agent_list` 查看所有在线代理
- 使用 `task_delegate` 向其他代理发送任务
- 通过 SSE 实时接收其他代理的任务更新
**3. 列出所有代理**
> 使用 agent_list 显示当前连接的所有代理
**4. 委托任务给其他代理**
> 使用 task_delegate 向代理 b（ID：xxx）发送 "Fix null pointer in login endpoint"。描述：登录端点在空输入时返回 500。
**5. 接收其他代理的结果**
当目标代理完成任务时，Claude Code 通过 SSE 接收 `task.result` 事件，并可以在对话中报告。
**6. 发送心跳**
> 使用 agent_heartbeat 发送心跳
考虑将心跳调用添加到 cron 钩子中，每 30 秒自动保持活动。
### Web 仪表盘
打开 `http://localhost:3000` 查看：
- **统计栏**：总代理数、在线/忙碌计数、任务统计
- **代理仪表盘**：代理卡片显示状态、项目、IP、当前任务和 MCP/技能标签
- **任务面板**：实时任务列表，带有委托流程和执行状态
## 功能
- **MCP JSON-RPC 2.0 over SSE** — 实时双向代理通信
- **任务委托和跟踪** — 跨代理任务调度、状态同步、结果传递
- **实时仪表盘** — Vue 3 实时显示代理状态、能力矩阵、任务流程
- **代理注册** — 心跳监测、自动离线检测、状态管理
- **REST API** — 查询代理、任务和统计数据
- **WebSocket 推送** — 实时前端更新
- **MCP 代理客户端** — 启用任何机器上的 Claude Code 加入桥梁
## 项目结构
```
ai-agent-bridge-mcp/
main.py # 入口点 — uvicorn 运行器
config.py # 日志和 LLM 配置
pyproject.toml # 项目元数据和依赖项
Dockerfile # Docker 构建
backend/
server.py # FastAPI 应用，SSE/WS 端点
mcp_handler.py # MCP JSON-RPC 2.0 over SSE
agent_registry.py # 代理 CRUD、心跳、状态
task_manager.py # 任务生命周期、委托
models.py # Pydantic 数据模型
routes.py # REST API 路由
client/
main.py # 客户端入口点
config.py # 客户端配置
bridge_client.py # WebSocket 客户端到桥梁
mcp_server.py # MCP 代理服务器
agent_manager.py # 本地代理管理
remote_agents_cache.py # 远程代理缓存
llm_router.py # LLM 路由（可选）
tools/
agent_tools.py # 代理注册工具
task_tools.py # 任务委托工具
remote_skill.py # 远程技能调用
utils/
logger.py # 日志实用程序
file_transfer.py # 文件传输实用程序
frontend/
src/
App.vue # 根布局
api/index.js # REST + WebSocket 客户端
components/
AgentDashboard.vue # 代理卡片网格
AgentCard.vue # 单个代理状态卡片
TaskPanel.vue # 任务列表面板
CapabilityBadge.vue # MCP/技能标签徽章
StatusIndicator.vue # 在线状态点
StatsBar.vue # 摘要统计栏
stores/ # Pinia 状态管理
```
## API 端点
| 方法 | 路径 | 描述 |
|--------|------|-------------|
| GET | `/health` | 健康检查 |
| GET | `/api/agents` | 列出所有代理 |
| GET | `/api/agents/{id}` | 获取代理详细信息 |
| GET | `/api/tasks` | 列出任务（可选 `?from_agent=` `?to_agent=`) |
| GET | `/api/tasks/{id}` | 获取任务详细信息 |
| GET | `/api/stats` | 仪表盘统计数据 |
| GET | `/sse` | SSE 端点（代理连接此处） |
| POST | `/messages?session_id=` | 来自代理的 JSON-RPC 消息 |
| WS | `/ws` | WebSocket 用于前端实时更新 |
| WS | `/ws_proxy` | WebSocket 代理用于客户端代理 |
## MCP 方法
### 代理方法
| 方法 | 描述 |
|--------|-------------|
| `agent.register` | 注册名称、项目、功能 |
| `agent.heartbeat` | 周期性保活 |
| `agent.update_status` | 更改状态（在线/忙碌/空闲） |
| `agent.list` | 列出所有注册代理 |
### 任务方法
| 方法 | 描述 |
|--------|-------------|
| `task.delegate` | 向另一个代理发送任务 |
| `task.update` | 更新任务状态和结果 |
| `task.list` | 列出此代理的任务 |
### 标准 MCP
| 方法 | 描述 |
|--------|-------------|
| `tools/list` | 列出可用的 MCP 工具 |
## 环境变量
| 变量 | 默认值 | 描述 |
|----------|---------|-------------|
| `SERVER_HOST` | `0.0.0.0` | 绑定地址 |
| `SERVER_PORT` | `8000` | 服务器端口 |
| `MOONSHOT_API_KEY` | — | Moonshot LLM API 密钥 |
| `DASHSCOPE_API_KEY` | — | DashScope (Qwen) API 密钥 |
| `DASHSCOPE_MODEL_NAME` | `qwen-max` | DashScope 模型名称 |
| `DEFAULT_OUTPUT_DIR` | `output` | 默认输出目录 |
## 双重远程推送
```bash
git push origin
git push github --all
```
## 许可证
MIT 许可证 - 请参阅 [LICENSE](LICENSE) 获取详细信息。
