使用说明
Claude多代理MCP系统
一种基于Kubernetes的解决方案，用于通过Minikube上的模型上下文协议（MCP）运行多个Claude代理。
建筑
Minikube Cluster
┌─────────────────────────────────────────────────────────────────┐
│ │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ Frontend Namespace │ │
│ │ ┌─────────────────────────────────────────────────┐ │ │
│ │ │ Frontend (Flask) │ │ │
│ │ │ - Web UI for prompt input │ │ │
│ │ │ - Agent count selector │ │ │
│ │ │ - Results display │ │ │
│ │ └─────────────────────────────────────────────────┘ │ │
│ └─────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ Backend Namespace │ │
│ │ ┌─────────────────────────────────────────────────┐ │ │
│ │ │ Orchestrator (2 replicas, load balanced) │ │ │
│ │ │ - Receives prompts from frontend │ │ │
│ │ │ - Spawns Claude agents via Agent SDK │ │ │
│ │ │ - Manages MCP server connections │ │ │
│ │ └─────────────────────────────────────────────────┘ │ │
│ │ │ │ │
│ │ ▼ │ │
│ │ ┌─────────────────────────────────────────────────┐ │ │
│ │ │ Claude MCP Server │ │ │
│ │ │ - Runs Claude Code CLI │ │ │
│ │ │ - Processes agent requests │ │ │
│ │ │ - Executes MCP commands │ │ │
│ │ └─────────────────────────────────────────────────┘ │ │
│ └─────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────┘
组件
前端（前端命名空间）
- 技术：Python Flask web应用程序
- 目的：为用户提供web界面，以便：
- 为Claude代理输入提示
- 选择代理数量（1-10）
- 查看代理执行的结果
- 端口：5000（内部），30080（节点端口）
后端（后端命名空间）
编排器
- 技术：带Claude Agent SDK的Python Flask
- 目的:
- 接收来自前端的请求
- 同时生成多个Claude代理
- 管理MCP服务器通信
- 复制品：2（负载平衡）
- 端口: 8080
Claude MCP服务器
- 技术：带Claude Code CLI的Alpine Linux
- 目的:
- 提供MCP服务器功能
- 以交互模式在后台运行
- 处理代理工具调用
先决条件
- 安装了Minikube的macOS
- Docker（可以使用Minikube的Docker守护进程）
- kubectl已配置
- 无烟煤API键
快速开始
1.启动Minikube
minikube start --driver=docker
2.设置环境变量
export ANTHROPIC_API_KEY='your-anthropic-api-key'
3.构建Docker镜像
./scripts/build-images.sh
4.部署到Minikube
./scripts/deploy.sh
5.访问应用程序
minikube service frontend-service -n frontend
或者获取URL：
minikube service frontend-service -n frontend --url
项目结构
.
├── README.md
├── frontend/
│ ├── Dockerfile
│ ├── app.py # Flask application
│ ├── requirements.txt
│ └── templates/
│ └── index.html # Web UI
├── backend/
│ └── orchestrator/
│ ├── Dockerfile
│ ├── app.py # Orchestrator application
│ ├── requirements.txt
│ └── mcp_settings.json
├── docker/
│ └── mcp/
│ └── Dockerfile # MCP server image
├── kubernetes/
│ ├── namespaces/
│ │ └── namespaces.yaml
│ ├── frontend/
│ │ ├── deployment.yaml
│ │ └── service.yaml
│ └── backend/
│ ├── orchestrator-deployment.yaml
│ ├── orchestrator-service.yaml
│ ├── mcp-server-deployment.yaml
│ ├── configmap.yaml
│ ├── secret.yaml
│ └── logs-pvc.yaml # Persistent volume for logs
└── scripts/
├── build-images.sh
├── deploy.sh
├── cleanup.sh
└── view-logs.sh # Log viewer utility
用法
- 在浏览器中打开前端
- 输入一个提示，描述您希望代理执行的操作
- 选择代理数量（1-10）
- 点击“GO-启动代理”
- 等待结果出现
配置
环境变量
| 变量 | 描述 | 默认值 |
|---|---|---|
ANTHROPIC_API_KEY |
您的Anthropic API密钥 | 必需 |
ORCHESTRATOR_URL |
后端编排器URL | http://orchestrator-service.backend.svc.cluster.local:8080 |
WORKSPACE_PATH |
MCP的工作区路径 | /workspace |
DOCKER_MCP_IMAGE |
MCP Docker镜像名称 | claude-mcp:latest |
扩展
要缩放编排器，请执行以下操作：
kubectl scale deployment orchestrator -n backend --replicas=4
持续日志记录
错误和异常被持久化在一个PersistentVolume中，因此即使在pod重启后，您也可以调查问题。
日志位置
| 组件 | 日志路径 | 描述 |
|---|---|---|
| 编排器 | /var/log/orchestrator/orchestrator.log |
所有日志（调试级别） |
| 编排器 | /var/log/orchestrator/orchestrator-errors.log |
仅错误 |
| MCP服务器 | /var/log/mcp-server/mcp-server.log |
服务器活动日志 |
使用助手脚本查看日志
# View all logs
./scripts/view-logs.sh
# View orchestrator logs only
./scripts/view-logs.sh --orchestrator
# View only error logs
./scripts/view-logs.sh --orchestrator-errors
# View MCP server logs
./scripts/view-logs.sh --mcp
# Follow logs in real-time
./scripts/view-logs.sh --tail --orchestrator
# List all log files
./scripts/view-logs.sh --list
手动日志访问
# List orchestrator log files
kubectl exec -n backend deploy/orchestrator -- ls -la /var/log/orchestrator/
# View orchestrator logs
kubectl exec -n backend deploy/orchestrator -- cat /var/log/orchestrator/orchestrator.log
# View orchestrator error logs
kubectl exec -n backend deploy/orchestrator -- cat /var/log/orchestrator/orchestrator-errors.log
# Follow orchestrator logs
kubectl exec -n backend deploy/orchestrator -- tail -f /var/log/orchestrator/orchestrator.log
# View MCP server logs
kubectl exec -n backend deploy/claude-mcp-server -- cat /var/log/mcp-server/mcp-server.log
日志保留
- 日志存储在1GB的持久卷索赔中
- 日志文件以10MB的速度轮换，保留5个备份
- 日志在pod重启和重新部署过程中持续存在
故障排除
检查Pod状态
kubectl get pods -n frontend
kubectl get pods -n backend
查看容器日志（stdout/stderr）
# Frontend logs
kubectl logs -n frontend -l app=frontend
# Orchestrator logs
kubectl logs -n backend -l app=orchestrator
# MCP server logs
kubectl logs -n backend -l app=claude-mcp-server
查看持久错误日志
# Quick error investigation
./scripts/view-logs.sh --orchestrator-errors
重新启动部署
kubectl rollout restart deployment frontend -n frontend
kubectl rollout restart deployment orchestrator -n backend
kubectl rollout restart deployment claude-mcp-server -n backend
清理
./scripts/cleanup.sh
安全说明
- API密钥存储为Kubernetes机密
- MCP服务器在沙盒环境中运行(
IS_SANDBOX=1) - 编排器挂载Docker套接字-确保适当的安全策略
许可证
麻省理工学院
