oaslananka/mcp-infra-lens

# mcp-infra-lens 通过支持基线感知的 MCP 工具，经由 SSH 解释 Linux 事件。 [](https://www.npmjs.com/package/mcp-infra-lens) [](https://github.com/oaslananka-lab/mcp-infra-lens/actions/workflows/ci.yml) [](https://github.com/oaslananka-lab/mcp-infra-lens/actions/workflows/security.yml) [](https://github.com/oaslananka-lab/mcp-infra-lens/actions/workflows/codeql.yml) [](https://scorecard.dev/viewer/?uri=github.com/oaslananka-lab/mcp-infra-lens) [](https://github.com/oaslananka-lab/mcp-infra-lens/actions/workflows/release.yml) [](https://www.npmjs.com/package/mcp-infra-lens) [](./LICENSE) [](https://nodejs.org/) [](https://www.npmjs.com/package/@modelcontextprotocol/sdk) [](https://dev.azure.com/oaslananka/open-source/_build?definitionId=61) ## 演示  Claude 提问“prod-01 怎么了？”时，`analyze_server` 响应的示例： ``` { "host": "prod-01.internal", "health_score": 42, "summary": "Found 2 anomalies on prod-01.internal. Most urgent signal: CPU is at 91% (3.4σ above baseline 28.2%). Load is 7.2/6.8/5.1. Top CPU consumer: java (87%).", "anomalies": [ { "metric": "cpu", "severity": "high", "value": 91, "z_score": 3.4, "explanation": "CPU is at 91% (3.4σ above baseline 28.2%). Load is 7.2/6.8/5.1. Top CPU consumer: java (87%).", "recommendation": "Investigate java (PID 18432) and review application logs or scale-out options." }, { "metric": "disk:/", "severity": "high", "value": 91, "explanation": "Disk / is 91% full (182GB/200GB).", "recommendation": "Run du -sh //* | sort -rh | head -20 and clean logs or temporary files." } ] } ``` ## 功能介绍 `mcp-infra-lens` 通过 SSH 连接到 Linux 主机，捕获实时基础设施快照，将其与最近记录的基线进行比较，并用通俗易懂的英语解释异常情况。 - 收集 CPU、内存、磁盘、网络、进程和 OS 数据，不改变目标主机状态 - 在 SQLite 中记录本地指标历史，用于基线比较和趋势查询 - 当存在足够基线样本时，使用 z-score 分析进行 CPU 异常检测 - 解释造成压力的可能原因，而不仅仅是原始指标值 - 支持基于 `stdio` 和 Streamable HTTP 的 MCP ## 工作原理 ``` flowchart TD A["Claude / Cursor / VS Code / Windsurf"] --> B["mcp-infra-lens"] B --> C["server-core.ts"] C --> D["collector.ts"] C --> E["analyzer.ts"] C --> F["baseline.ts + db.ts"] D --> G["ssh.ts"] G --> H["Linux host over SSH"] F --> I["SQLite history + baselines"] ``` `analyze_server` 现在会在请求的 `duration_minutes` 内执行真实的采样收集，计算采集窗口内的平均 CPU 和内存压力，持久化生成的快照，然后针对选定的基线运行异常检测。 ## 工具列表 | 工具 | 功能 | 关键参数 | | --- | --- | --- | | `analyze_server` | 收集采样快照，存储并解释异常情况 | `connection`、`duration_minutes`、`include_processes`、`include_network` | | `snapshot` | 捕获并存储当前时间点的指标，不进行分析 | `connection` | | `record_baseline` | 保存标记为健康状态的样本，以供将来比较 | `connection`、`label` | | `compare_to_baseline` | 将当前状态与指定基线进行比较并解释差异 | `connection`、`baseline_label` | | `get_history` | 从 SQLite 返回历史 CPU、内存或负载数据点 | `host`、`metric`、`hours`、`label?` | ## 快速开始 ### 1. 通过 `npx` 运行 ``` npx -y mcp-infra-lens ``` 如果您固定使用 `1.0.1` 版本，请升级到 `1.0.2` 或更新版本，以避免 Node 24 原生安装失败： ``` npx -y mcp-infra-lens@latest ``` ### 2. Claude Desktop 已发布包： ``` { "mcpServers": { "infra-lens": { "command": "npx", "args": ["-y", "mcp-infra-lens"], "env": { "INFRA_LENS_DB": "/Users/you/.mcp-infra-lens/metrics.db" } } } } ``` 本地开发： ``` { "mcpServers": { "infra-lens": { "command": "node", "args": ["/absolute/path/to/mcp-infra-lens/dist/mcp.js"], "env": { "INFRA_LENS_DB": "/Users/you/.mcp-infra-lens/metrics.db" } } } } ``` ### 3. Docker ``` docker build -t mcp-infra-lens . docker run --rm -it \ -v "$HOME/.mcp-infra-lens:/home/appuser/.mcp-infra-lens" \ mcp-infra-lens ``` ## 配置 | 环境变量 | 默认值 | 描述 | | --- | --- | --- | | `INFRA_LENS_DB` | `~/.mcp-infra-lens/metrics.db` | SQLite 数据库路径。在测试时使用 `:memory:` | | `HOST` | `127.0.0.1` | HTTP 传输的绑定地址 | | `PORT` | `3000` | HTTP 传输的端口 | ## 健康评分 - `90-100`：健康，未检测到明显异常 - `70-89`：轻微或局部压力 - `40-69`：多个警告或正在发生重大问题 - `0-39`：危急状态，需要紧急修复 ## 推荐工作流 1. 在健康运行时段记录 `record_baseline` 样本。 2. 在发生事件或负载高峰期间使用 `analyze_server`。 3. 使用 `compare_to_baseline` 针对指定的基线进行更严格的差异对比。 4. 使用 `get_history` 检查趋势，并将默认快照与标记的基线会话区分开。 ## 身份验证 SSH 输入 schema 支持： - 密码身份验证 - 内联私钥身份验证 - 对加密密钥的可选密码短语支持 凭据字段在写入 `stderr` 之前会从结构化日志中隐去。 ## 安全说明 - 目标主机上的 SSH 收集操作是只读的 - SSH 凭据绝不存储在 SQLite 中 - v1 版本中的主机密钥验证较为宽松以保证兼容性；生产环境部署应限制出站网络访问，并计划在后续版本中强制执行严格的主机验证 - HTTP 传输没有内置身份验证；在任何非本地部署中，请绑定到环回接口，并将其置于经过身份验证的反向代理之后 有关报告策略和存储数据范围，请参阅 [SECURITY.md](./SECURITY.md)。 ## 集成 ### Claude Desktop ``` { "mcpServers": { "infra-lens": { "command": "npx", "args": ["-y", "mcp-infra-lens"], "env": { "INFRA_LENS_DB": "/Users/you/.mcp-infra-lens/metrics.db" } } } } ``` ### Cursor IDE ``` { "mcpServers": { "infra-lens": { "command": "npx", "args": ["-y", "mcp-infra-lens"] } } } ``` ### VS Code (MCP 扩展) ``` { "inputs": [], "servers": { "infra-lens": { "type": "stdio", "command": "npx", "args": ["-y", "mcp-infra-lens"] } } } ``` ### Windsurf ``` { "mcpServers": { "infra-lens": { "command": "npx", "args": ["-y", "mcp-infra-lens"] } } } ``` ### Docker (HTTP 传输) ``` docker run -d \ -p 3000:3000 \ -v $HOME/.mcp-infra-lens:/home/appuser/.mcp-infra-lens \ ghcr.io/oaslananka/mcp-infra-lens:latest ``` 然后将您的 MCP 客户端配置为使用 `http://localhost:3000`。 ## Docker 内置的 Docker 镜像： - 在独立的阶段中构建 TypeScript 项目 - 在两个阶段中针对容器架构重新构建 `better-sqlite3` - 以非 root 用户 `appuser` 运行 - 将 SQLite 数据存储在 `/home/appuser/.mcp-infra-lens/metrics.db` ## 运维 / CI 说明 - `azure-pipelines.yml` 是规范的 CI 流水线，目前在 Node 20 和 Node 22 上运行 `Quality` 阶段，发布 JUnit 和 Cobertura 工件，并在 Node 20 上执行基于 Docker 的 SSH 端到端覆盖率测试 - `.azure/pipelines/publish.yml` 仍然是手动的 npm 发布流水线 - `.azure/pipelines/mirror.yml` 仍可用于仓库镜像工作流 - 只有在本地预发布检查清单和 CI 都在 Node 20 上完全通过后才进行发布 - 在决定某项更改需要通过 npm、MCP Registry 还是仅限 Registry 的预发布时，请遵循 [RELEASE_POLICY.md](./RELEASE_POLICY.md) ## 许可证 [MIT](./LICENSE)

标签：Claude集成, CPU监控, DNS解析, GNU通用公共许可证, IT运维, Linux运维, MCP SDK, MCP工具, MITM代理, Node.js, Socks5代理, SQLite, SRE, SSH远程连接, 事故响应, 偏差过滤, 内存监控, 基础设施监控, 基线分析, 开源项目, 异常报告, 异常检测, 无线安全, 本地存储, 磁盘监控, 系统性能监控, 网络信号, 自动化攻击, 请求拦截