集群执行MCP服务器
集群感知命令执行,用于跨AGI代理集群的分布式任务路由。
版本: 0.2.0
特性
- 自动任务路由:根据负载、能力和要求将命令路由到最佳节点
- 多节点支持:macpro51(Linux x86_64)、mac studio(macOS ARM64)、macbook air(macOS ARM六十四)、推理节点
- 动态IP解析:mDNS、DNS和带缓存的回退方法
- 加强安保:无shell注入、基于环境的配置、命令验证
- SSH连接验证:具有可配置超时的重试逻辑
- 并行执行:跨集群分发命令以实现最大吞吐量
安装```bash
cd /mnt/agentic-system/mcp-servers/cluster-execution-mcp
pip install -e .
For development:
pip install -e ".[dev]"
## 配置
### Claude代码配置
添加到 `~/.claude.json`:```json
{
"mcpServers": {
"cluster-execution": {
"command": "/mnt/agentic-system/.venv/bin/python3",
"args": ["-m", "cluster_execution_mcp.server"]
}
}
}
环境变量
所有配置都通过环境变量外部化:
| 变量 | 默认值 | 描述 |
|---|---|---|
CLUSTER_SSH_USER |
marcssh |
远程执行的SSH用户名 |
CLUSTER_SSH_TIMEOUT |
5 |
SSH连接超时(秒) |
CLUSTER_SSH_CONNECT_TIMEOUT |
2 |
初始SSH连接超时(秒) |
CLUSTER_SSH_RETRIES |
2 |
SSH重试次数 |
CLUSTER_CPU_THRESHOLD |
40 |
卸载的CPU使用率百分比阈值 |
CLUSTER_LOAD_THRESHOLD |
4 |
卸载的平均负载阈值 |
CLUSTER_MEMORY_THRESHOLD |
80 |
卸载的内存使用百分比阈值 |
CLUSTER_CMD_TIMEOUT |
300 |
命令执行超时(秒) |
CLUSTER_STATUS_TIMEOUT |
5 |
状态检查超时(秒) |
CLUSTER_IP_CACHE_TTL |
300 |
IP分辨率缓存TTL(秒) |
CLUSTER_GATEWAY |
192.168.1.1 |
用于路由检测的网关IP |
CLUSTER_DNS |
8.8.8.8 |
用于IP检测的DNS服务器 |
AGENTIC_SYSTEM_PATH |
/mnt/agentic-system |
数据库的基本路径 |
节点配置
节点主机名和IP可以自定义:
| 变量 | 默认值 | 描述 |
|---|---|---|
CLUSTER_MACPRO51_HOST |
macpro51.local |
Mac Pro主机名 |
CLUSTER_MACPRO51_IP |
192.168.1.2 |
Mac Pro回退IP |
CLUSTER_MACSTUDIO_HOST |
Marcs-Mac-Studio.local |
Mac Studio主机名 |
CLUSTER_MACSTUDIO_IP |
192.168.1.6 |
Mac Studio回退IP |
CLUSTER_MACBOOKAIR_HOST |
Marcs-MacBook-Air.local |
MacBook Air主机名 |
CLUSTER_MACBOOKAIR_IP |
192.168.1.7 |
MacBook Air后备IP |
CLUSTER_INFERENCE_HOST |
server.local |
推理节点主机名 |
CLUSTER_INFERENCE_IP |
192.168.1.8 |
推理节点回退IP |
MCP工具
| 工具 | 说明 |
|---|---|
cluster_bash |
使用自动集群路由执行bash命令 |
cluster_status |
获取当前集群状态和负载分布 |
offload_to |
明确地将命令路由到特定节点 |
parallel_execute |
跨节点并行运行多个命令 |
用法示例
自动路由```python
Heavy commands auto-route to least loaded node
result = await cluster_bash("make -j8 all")
Simple commands run locally
result = await cluster_bash("ls -la")
### 部队特定要求```python
# Force Linux execution
result = await cluster_bash("docker build .", requires_os="linux")
# Force x86_64 architecture
result = await cluster_bash("cargo build", requires_arch="x86_64")
显式节点路由```python
Run on Linux builder
result = await offload_to("podman run -it ubuntu:22.04", node_id="macpro51")
Run on Mac Studio
result = await offload_to("swift build", node_id="mac-studio")
### 并行执行```python
# Run tests across cluster
results = await parallel_execute([
"pytest tests/unit/",
"pytest tests/integration/",
"pytest tests/e2e/"
])
群集状态```python
Get cluster health before heavy operations
status = await cluster_status()
Returns:
{
"local_node": "macpro51",
"nodes": {
"macpro51": {"cpu_percent": 15.2, "memory_percent": 45.3, ...},
"mac-studio": {"cpu_percent": 8.1, "memory_percent": 32.1, ...},
...
}
}
## 集群节点
|节点|操作系统|架构|功能|特性|
|------|-----|------|--------------|-------------|
| `macpro51` |Linux|x86_64|docker、podman、raid、nvme、编译、测试、tpu|编译、测试,容器化,基准测试|
| `mac-studio` |macOS | ARM64 |编排、协调、时态、mlx gpu、arduino |编排、协作、监控|
| `macbook-air` |macOS | ARM64 |研究、文档、分析|研究、文件、移动|
| `inference` |macOS | ARM64 | ollama,推理,模型服务,llm-api | ollama推理,模型服务器|
## 卸载模式
与这些模式匹配的命令会自动卸载:
- 构建: `make`, `cargo`, `npm`, `yarn`, `pnpm`
- 测试: `pytest`, `jest`, `mocha`, `test`
- 编译: `gcc`, `g++`, `clang`
- 集装箱: `docker`, `podman`, `kubectl`
- 文件操作: `rsync`, `scp`, `tar`, `zip`, `find`, `grep -r`
本地命令:
- 简单: `ls`, `pwd`, `cd`, `echo`, `cat`, `head`, `tail`, `which`, `type`
## 安全
### 壳体防喷
所有命令都使用 `subprocess.run()` 在可能的情况下使用列表参数:```python
# SAFE: List arguments
subprocess.run(["ssh", "-o", "ConnectTimeout=5", f"{user}@{ip}", command])
# Complex shell commands are validated before execution
命令验证
针对危险模式验证命令:
rm -rf /rm -rf /*> /dev/sda- 叉式炸弹
- 还有更多。..
SSH配置
StrictHostKeyChecking=accept-new-接受新主机,但验证返回的主机BatchMode=yes-脚本编写的非交互模式- 可配置的超时和重试
发展
运行测试```bash
Install dev dependencies
pip install -e ".[dev]"
Run tests
pytest tests/ -v
With coverage
pytest tests/ --cov=cluster_execution_mcp --cov-report=html
### 项目结构```
cluster-execution-mcp/
├── src/cluster_execution_mcp/
│ ├── __init__.py # Package exports
│ ├── config.py # Configuration, validation, node definitions
│ ├── router.py # Task routing and IP resolution
│ └── server.py # FastMCP server and tools
├── tests/
│ ├── conftest.py # Pytest fixtures
│ ├── test_config.py # Config module tests (29 tests)
│ ├── test_router.py # Router module tests (21 tests)
│ └── test_server.py # Server and tool tests (21 tests)
└── pyproject.toml # Package configuration
CLI接口```bash
Submit a command
cluster-router submit "make -j8 all"
Check task status
cluster-router status
Show cluster status
cluster-router cluster-status
## 监控
操作前检查群集运行状况:```
User: "Show me cluster status"
Claude Code: cluster_status tool
Output:
macpro51:
CPU: 45.2%
Memory: 18.3%
Load: 3.21
Status: healthy
mac-studio:
CPU: 22.1%
Memory: 54.7%
Load: 2.15
Status: healthy
macbook-air:
CPU: 12.8%
Memory: 38.2%
Load: 1.03
Status: healthy
故障排除
MCP服务器未加载:```bash
Check config
cat ~/.claude.json | jq '.mcpServers["cluster-execution"]'
Test server import
python3 -c "from cluster_execution_mcp.server import main; print('OK')"
**节点不可达**:```bash
# Test SSH connectivity
ssh marc@macpro51.local hostname
ssh marc@Marcs-Mac-Studio.local hostname
# Check with fallback IP
ssh marc@192.168.1.183 hostname
命令超时:```bash
Increase timeout via environment
export CLUSTER_CMD_TIMEOUT=600 # 10 minutes
export CLUSTER_SSH_TIMEOUT=10 # 10 seconds
```
更新日志
v0.2.0版本
-
新功能:
-
使用pyproject.toml进行适当的包结构
- 基于环境的配置(无硬编码凭据)
- 具有验证功能的共享配置模块
- SSH连接的重试逻辑
- 带TTL的IP解析缓存
-
推理节点支持
-
安全改进:
-
消除了shell注入漏洞
- 危险模式的命令验证
- IP验证拒绝环回/Docker/本地链接
-
SSH主机密钥处理(接受新密钥)
-
代码质量:
-
整个代码库中的完整类型提示
- 除特定例外条款外,其余条款均已替换
- 添加了全面的日志记录
-
71个模拟单元测试
-
错误修复:
-
修复了darwin/macos操作系统别名处理问题
- SSH操作中的正确超时处理
- 针对失败操作的更好错误消息
v0.1.0
- 具有基本集群执行的初始版本
许可证
麻省理工学院
AGI代理系统的一部分
另请参见:
- 节点聊天MCP-节点间通信
- 增强内存MCP-带RAG的持久内存
- 代理运行时MCP-目标和任务队列
