内容
# homelab-evidence-mcp
[](https://github.com/ThomasCrouzet/homelab-evidence-mcp/actions/workflows/ci.yml)
[](LICENSE)
本地MCP服务器，通过**标准输入输出**传输，收集家庭实验室的事件证据。它以静态Go二进制文件形式提供，不提供任何修改操作。
## 为什么
当服务失败时，信号是分散的：
- Gatus报告错误；
- Docker显示容器正在重启；
- Loki包含几 moments 前的超时；
- Healthchecks显示计划任务失败。
专用工具正确地暴露了它们自己的源，但它们既没有共享服务标识，也没有共享证据格式，更没有共享时间线。这个项目提供了这种相关性层，而没有发明因果关系。
## 原则
1. **规范注册表**：明确的`service_id`链接Gatus、Docker、Loki、Healthchecks、Beszel和ntfy标识。
2. **通用证据模型**：每个项目都有边界、时间戳、属性、编辑和截断标记。
3. **确定性关联**：时间线呈现事实；它不声称建立根本原因。
4. **结构只读**：仅允许启动时锁定的目标的HTTP `GET`请求。
简短示例：
```text
02:12 Loki 上游超时 [已编辑]
02:13 Docker 容器媒体正在重启
02:14 Gatus 媒体/应用程序失败 状态=503
02:15 Healthchecks "media-cron" 已关闭
时间线按observed_at排序；关联不确定根本原因。
```
该服务器既不是仪表盘，也不是通用HTTP代理，也不是控制平面。它不会重启容器，也不会产生根本原因分析。
## 安装
先决条件：Go 1.25或更高版本。
```bash
go install github.com/ThomasCrouzet/homelab-evidence-mcp/cmd/homelab-evidence-mcp@latest
```
从存储库构建：
```bash
make build
./bin/homelab-evidence-mcp --version
```
## 快速开始
1. 将`config.example.yaml`复制到私有位置。
2. 将文件限制为所有者：`chmod 600 /path/config.yaml`在Unix上，或在Windows上使用仅限用户ACL。
3. 填写内部URL和一些试点服务。
4. 导出所需的令牌，例如`HEALTHCHECKS_API_TOKEN`。
5. 在将其连接到MCP客户端之前，验证配置。
```bash
homelab-evidence-mcp --config /path/config.yaml --validate
```
验证加载令牌，检查目标，并在任何未知YAML键上失败。查询字符串和片段在`base_url`中被禁止；身份验证使用`token_env`或`token_file`。
与MCP客户端注册：
```json
{
"mcpServers": {
"homelab-evidence": {
"command": "/path/homelab-evidence-mcp",
"args": ["--config", "/path/config.yaml"],
"env": {
"HEALTHCHECKS_API_TOKEN": "readonly-key"
}
}
}
}
```
标准输出保留给JSON-RPC协议。日志和审计事件写入标准错误。参见
[MCP客户端配置](docs/mcp-hosts.md)和
[集成示例](docs/configuration-example.md)。
## 支持的源
| 源 | 使用的表面 | 主要保证 |
|---|---|---|
| Gatus | `GET /api/v1/endpoints/statuses` | 最新结果按时间戳选择 |
| Docker Engine | `GET /containers/json?all=true` | 过滤字段，永不`Config.Env` |
| Loki | `GET /loki/api/v1/query_range` | 选择器固定在配置中 |
| Healthchecks | `GET /api/v3/checks/` | 只读密钥，无ping URL |
| Beszel | `GET /api/systems` 和兼容变体 | 可选主机快照 |
| ntfy | `GET /{topic}/json?poll=1` | 主题固定在配置中 |
目标只接受`http`和`https`。对于Docker，请使用有限读取的套接字代理；不支持直接Unix套接字。`HTTP_PROXY`和`HTTPS_PROXY`被忽略。
`base_url`中允许路径前缀：`https://proxy.example/gatus`与Gatus路由正确组合。
源响应缓存（`limits.source_cache_ttl`，默认为`15s`，`0`禁用）会短暂记住相同的请求。身份验证值永远不会以明文存储在其中的键中；进程本地HMAC指纹区分访问秘密。命中时，`observed_at`保留原始收集时间，`retrieved_at`标记当前读取；因此， freshness 反映快照的真实年龄。
## MCP工具
| 工具 | 用途 |
|---|---|
| `evidence_capabilities` | 版本、活动源、限制和统计信息 |
| `list_services` | 规范服务和覆盖范围 |
| `service_status` | Gatus、Docker、Healthchecks和Beszel快照 |
| `incident_context` | 有界多源时间线 |
| `search_logs` | 配置的筛选器上的Loki搜索 |
| `failed_crons` | 当前处于`down`、`grace`或`paused`状态的检查 |
| `get_evidence` | 通过不透明标识暂时重新读取证据 |
所有工具都注释为只读。全局限制绑定窗口、HTTP正文、证据计数和并发性。
## 证据模型
每个证据项都包含其源、观察时间戳、收集时间戳、严重性、freshness状态、任何截断和应用的编辑次数。响应还报告源成功、不存在、跳过、错误或超时。
参见 [证据模型](docs/evidence-model.md)和
[测试的API合约](docs/api-compatibility.md)。
## 安全
保证和剩余风险在[SECURITY.md](SECURITY.md)中有详细说明。关键点：
- 启动时锁定目标；
- 拒绝HTTP重定向；
- MCP调用不提供URL或流选择器；
- 日志内容被视为敌对数据；
- 内置编辑和可选的本地规则；
- 配置和令牌文件仅限于Unix上的`0600`模式或Windows上的用户ACL。
## 本地演示
```bash
go run ./demo
```
演示启动测试HTTP服务器，打开内存MCP会话，验证部分结果、编辑和完全没有非`GET`请求。不需要真正的家庭实验室。
## 开发
```bash
make test # 测试带有竞争检测
make test-quick # 快速测试
make lint # 格式化，go vet和golangci-lint（如果可用）
make coverage
make build
```
该项目在CI中为Linux、macOS和Windows构建二进制文件。主要目标仍然是无头Linux和macOS系统。
## 许可证
MIT。参见[LICENSE](LICENSE)。
