内容
# Claude Code MCP - 代理编排平台
## 概述
一个复杂的 **FastMCP Python 服务器**，能够在 iTerm2 会话中编排多个 Claude Code 代理，通过基于任务的工作流提供集中管理和代理间通信。
## 架构
**代理编排平台**具有：
- **iTerm2 标签式会话**：无窗口复杂性，纯粹的标签管理
- **持久代理状态**：在 iTerm 重启后仍能恢复状态
- **与代码库关联的会话**：会话与特定根文件路径绑定
- **最大安全隔离**：代理之间的进程级分离
- **基于任务的代理间通信**：通过 ADDER+ 工作流协调
- **系统提示注入**：自动命名 Agent_# 和提示前缀
## 核心 MCP 工具
| 工具 | 目的 | 安全级别 |
|------|---------|----------------|
| `create_agent` | 创建新的 Claude Code 代理实例 | 高 |
| `delete_agent` | 从系统中移除代理 | 高 |
| `create_session` | 创建与根文件路径绑定的会话 | 中 |
| `get_session_status` | 返回会话中所有代理的状态 | 低 |
| `delete_session` | 移除整个会话及所有代理 | 高 |
| `send_message_to_agent` | 发送带有 ADDER+ 前缀的消息 | 中 |
| `clear_agent_conversation` | 关闭当前 iTerm 标签的代理 | 中 |
| `start_new_agent_conversation` | 为代理打开新的 iTerm 标签 | 中 |
## ADDER+ 工作流集成
每个代理都使用全面的 **ADDER+ (Advanced Development, Documentation & Error Resolution)** 协议，支持：
- **自主任务管理**：基于 TODO.md 的执行，实时进度跟踪
- **高级编程综合**：契约设计 + 防御性编程 + 类型驱动开发 + 基于属性的测试 + 函数式编程模式
- **系统化错误解决**：根本原因分析与自动任务生成
- **代理间协调**：通过文档文件进行基于任务的通信
## 安全模型
- **进程隔离**：每个 Claude Code 代理在单独的进程中运行
- **会话边界**：代理无法访问其他会话的代码库
- **状态加密**：持久代理状态在静止时加密
- **审计日志**：所有代理交互记录用于安全分析
- **权限模型**：基于角色的访问控制用于代理操作
## 快速开始
```bash
# 安装依赖
uv sync
# 启动 MCP 服务器
python src/main.py
```
## Claude Desktop 配置
要将此代理编排平台与 Claude Desktop 一起使用，您需要在 Claude 的配置文件中将其配置为 MCP 服务器。
### 配置文件位置
**macOS:**
```
~/Library/Application Support/Claude/claude_desktop_config.json
```
**Windows:**
```
%APPDATA%/Claude/claude_desktop_config.json
```
### 配置步骤
1. **打开配置文件**：导航到上述配置文件位置。如果文件不存在，请创建它。
2. **添加服务器配置**：将以下配置添加到您的 `claude_desktop_config.json` 中：
#### 选项 1：使用 UV（推荐）
```json
{
"mcpServers": {
"claude-code-mcp": {
"command": "uv",
"args": [
"--directory",
"/ABSOLUTE/PATH/TO/Claude_Code_MCP",
"run",
"python",
"src/main.py"
],
"env": {
"PYTHONPATH": "/ABSOLUTE/PATH/TO/Claude_Code_MCP/src"
}
}
}
}
```
#### 选项 2：直接使用 Python
```json
{
"mcpServers": {
"claude-code-mcp": {
"command": "python",
"args": [
"/ABSOLUTE/PATH/TO/Claude_Code_MCP/src/main.py"
],
"env": {
"PYTHONPATH": "/ABSOLUTE/PATH/TO/Claude_Code_MCP/src"
}
}
}
}
```
#### 选项 3：使用虚拟环境
```json
{
"mcpServers": {
"claude-code-mcp": {
"command": "/ABSOLUTE/PATH/TO/Claude_Code_MCP/.venv/bin/python",
"args": [
"/ABSOLUTE/PATH/TO/Claude_Code_MCP/src/main.py"
],
"env": {
"PYTHONPATH": "/ABSOLUTE/PATH/TO/Claude_Code_MCP/src"
}
}
}
}
```
### 配置注意事项
- **将 `/ABSOLUTE/PATH/TO/Claude_Code_MCP`** 替换为您项目目录的实际绝对路径
- **在 Windows 上**，路径中使用反斜杠：`C:\\path\\to\\Claude_Code_MCP`
- **服务器名称**：您可以将 `"claude-code-mcp"` 更改为您喜欢的任何名称
- **虚拟环境**：如果使用虚拟环境，请相应调整 Python 路径
### 高级配置选项
#### 自定义安全级别
```json
{
"mcpServers": {
"claude-code-mcp": {
"command": "uv",
"args": [
"--directory",
"/ABSOLUTE/PATH/TO/Claude_Code_MCP",
"run",
"python",
"src/main.py",
"--security-level",
"HIGH",
"--max-agents",
"16",
"--max-sessions",
"8"
],
"env": {
"PYTHONPATH": "/ABSOLUTE/PATH/TO/Claude_Code_MCP/src"
}
}
}
}
```
#### 自定义日志目录
```json
{
"mcpServers": {
"claude-code-mcp": {
"command": "uv",
"args": [
"--directory",
"/ABSOLUTE/PATH/TO/Claude_Code_MCP",
"run",
"python",
"src/main.py",
"--log-dir",
"/ABSOLUTE/PATH/TO/Claude_Code_MCP/logs"
],
"env": {
"PYTHONPATH": "/ABSOLUTE/PATH/TO/Claude_Code_MCP/src"
}
}
}
}
```
### 验证步骤
1. **保存配置**：保存 `claude_desktop_config.json` 文件
2. **重启 Claude Desktop**：完全退出并重启 Claude Desktop
3. **检查 MCP 状态**：在 Claude Desktop 界面中查找 MCP 服务器指示器：
- 锤子图标 (🔨) 表示可用工具
- 连接器图标表示 MCP 服务器连接
4. **测试功能**：尝试使用其中一个代理编排工具
### 故障排除
#### 服务器未加载
- 验证所有路径是否为绝对路径（而非相对路径）
- 检查 `uv` 或 `python` 是否在您的系统 PATH 中
- 确保项目目录存在并具有正确的权限
- 查看 Claude Desktop 日志：
- **macOS**: `~/Library/Logs/Claude/mcp*.log`
- **Windows**: `%APPDATA%\Claude\logs\mcp*.log`
#### 手动测试
在配置 Claude Desktop 之前手动测试服务器：
```bash
# 导航到项目目录
cd /path/to/Claude_Code_MCP
# 使用 UV 测试
uv run python src/main.py --help
# 直接使用 Python 测试
python src/main.py --help
```
#### 常见问题
- **权限错误**：确保 Claude Desktop 有权限执行 Python 解释器
- **导入错误**：验证配置中的 `PYTHONPATH` 是否正确设置
- **端口冲突**：如果使用 HTTP 传输，确保端口（默认 8000）可用
### 可用的 MCP 工具
配置完成后，Claude Desktop 将可以访问这些代理编排工具：
- `create_agent` - 创建新的 Claude Code 代理实例
- `delete_agent` - 从系统中移除代理
- `create_session` - 创建与特定代码库绑定的会话
- `get_session_status` - 获取会话中所有代理的状态
- `delete_session` - 移除整个会话及所有代理
- `send_message_to_agent` - 发送带有 ADDER+ 协议集成的消息
- `clear_agent_conversation` - 关闭当前 iTerm 标签的代理
- `start_new_agent_conversation` - 为代理打开新的 iTerm 标签
## 开发工作流
1. **会话创建**：将会话链接到特定代码库
2. **代理生成**：创建具有自定义系统提示的专用代理
3. **任务协调**：代理通过 TODO.md 和任务文件进行通信
4. **状态监控**：实时查看代理的进度和健康状况
5. **会话管理**：持久状态与恢复能力
## 集成点
- **FastMCP 框架**：高性能 MCP 服务器实现
- **iTerm2 Python API**：高级终端会话管理
- **Claude Code**：AI 代理过程编排
- **Asyncio 架构**：事件驱动的并发代理管理
该平台使得复杂的 AI 开发工作流得以实现，多个专用代理协同工作于复杂的代码库，同时保持严格的安全隔离和全面的审计跟踪。
MCP 市场