内容
# 网格状态 MCP 服务器
通过 MCP 工具或命令行界面监控您的家庭实验室代理网格。
## 功能概述
提供 6 种工具来监控多代理家庭实验室：
- **代理健康状态** — 角色、工作区、Docker 容器
- **Docker 服务** — 列表、状态、健康检查、日志
- **路由器 V3** — 路由统计、消息路由、查询分发
- **网格概览** — 一目了然
既可作为 **MCP 服务器** （用于 AI 代理），也可作为 **命令行界面** （用于人类）。
## 安装
```bash
pip install mesh-status-mcp
```
或从源代码安装：
```bash
git clone https://github.com/Proto-labs-rnd/mesh-status-mcp.git
cd mesh-status-mcp
pip install -e ".[dev]"
```
## 快速入门
### 命令行界面
```bash
# 完整概览
mesh-status overview
# 代理详情
mesh-status agents proto
# 容器健康状态
mesh-status health router-v3
# 路由查询
mesh-status route "重启数据库"
# 路由器统计
mesh-status stats
# Docker 服务
mesh-status services
# JSON 输出（适用于所有命令）
mesh-status --json overview
mesh-status --json agents
mesh-status --json services
mesh-status --json health router-v3
mesh-status --json route "重启数据库"
mesh-status --json stats
```
### MCP 服务器（OpenClaw / Claude / 等）
将以下内容添加到您的 MCP 配置中：
```json
{
"mcpServers": {
"mesh-status": {
"command": "python3",
"args": ["-m", "mesh_status.mcp_server"]
}
}
}
```
或如果通过 pip 安装：
```json
{
"mcpServers": {
"mesh-status": {
"command": "mesh-status-mcp"
}
}
}
```
## 配置
创建 `mesh_status_config.yaml` 或设置环境变量：
```yaml
router:
url: "http://127.0.0.1:8905"
timeout: 5.0
retries: 2
retry_delay: 0.5
docker:
timeout: 10.0
max_containers_display: 20
log_tail_lines: 10
agents:
tachikoma:
role: "Orchestrator"
emoji: "🤖"
workspace: "workspace"
proto:
role: "R&D"
emoji: "🧪"
workspace: "workspace-labs"
log_level: "WARNING"
```
### 环境变量
| 变量 | 默认值 | 描述 |
|----------|---------|-------------|
| `MESH_ROUTER_URL` | `http://127.0.0.1:8905` | 路由器 V3 URL |
| `MESH_ROUTER_TIMEOUT` | `5.0` | 路由器超时（秒） |
| `MESH_LOG_LEVEL` | `WARNING` | 日志级别（DEBUG, INFO, WARNING） |
| `MESH_STATUS_CONFIG` | — | 配置文件路径 |
### 配置搜索顺序
1. `--config` 命令行标志
2. `MESH_STATUS_CONFIG` 环境变量
3. `./mesh_status_config.yaml`
4. `~/.config/mesh-status/config.yaml`
5. `/etc/mesh-status/config.yaml`
6. 内置默认值
## 架构
```
mesh_status/
├── __init__.py # 版本
├── config.py # 配置（YAML + 环境变量 + 默认值）
├── core.py # MeshStatus — 共享业务逻辑
├── docker_client.py # Docker CLI 包装器（超时、重试、错误类型）
├── router_client.py # 路由器 V3 HTTP 客户端（重试、类型化结果）
├── mcp_server.py # MCP 服务器入口点（6 种工具通过 FastMCP）
└── cli.py # 命令行界面入口点（argparse 子命令）
```
**关键设计决策：**
- `core.MeshStatus` 是单一事实来源 — MCP 和命令行界面都使用它
- Docker 和路由器客户端具有类型化的错误层次结构（`DockerError`, `RouterUnavailableError`）
- 每个外部调用都有超时 + 重试，带有可配置的尝试次数
- 优雅降级：工具返回信息性消息而不是崩溃
## 工具参考
| 工具 | 描述 | 参数 |
|------|-------------|------|
| `get_mesh_overview` | 完整的网格概览 | — |
| `get_agent_info` | 代理详情 | `agent_name` |
| `list_services` | 运行中的 Docker 容器 | — |
| `route_message` | 通过路由器 V3 路由 | `query` |
| `get_router_stats` | 路由器统计 | — |
| `check_container_health` | 容器健康状态 + 日志 | `container_name` |
## 开发
```bash
pip install -e ".[dev]"
pytest
pytest --cov=mesh_status
```
## 许可证
MIT
