内容
# infra-lens-mcp
<p align="center">
<a href="https://www.buymeacoffee.com/oaslananka">
<img src="https://img.buymeacoffee.com/button-api/?text=给我买杯咖啡&emoji=%E2%98%95&slug=oaslananka&button_colour=FFDD00&font_colour=000000&font_family=Arial&outline_colour=000000&coffee_colour=ffffff" alt="给我买杯咖啡" />
</a>
</p>
通过 SSH 解释 Linux 事件，具备基线感知 MCP 工具。
[](https://www.npmjs.com/package/infra-lens-mcp)
[](https://www.npmjs.com/package/infra-lens-mcp)
[](./LICENSE)
[](https://nodejs.org/)
[](https://www.npmjs.com/package/@modelcontextprotocol/sdk)
`infra-lens-mcp` 是一个 TypeScript MCP 服务器，通过 SSH 连接到 Linux 主机，捕获实时指标，存储本地 SQLite 历史记录，将快照与基线进行比较，并返回基础设施的纯英文解释。
## 演示
参见 [MCP 2025-11-25 合规性矩阵](./docs/compliance/mcp-2025-11-25.md)，了解当前协议支持、委托行为和开放的后续问题。
## 工具
| 工具 | 目的 |
| --- | --- |
| `analyze_server` | 收集采样快照，存储并解释异常 |
| `snapshot` | 存储一个时间点的快照，无异常分析 |
| `record_baseline` | 保存一个标记为健康的样本 |
| `compare_to_baseline` | 将当前状态与命名基线进行比较 |
| `get_history` | 从 SQLite 返回 CPU、内存或负载历史记录 |
| `inspect_host_capabilities` | 在收集前检查所需的 Linux 命令和 proc 文件 |
所有工具都返回可读的 JSON 文本和 MCP `structuredContent`，通过声明的 `outputSchema` 定义进行验证，以便客户端和代理可以无需解析文本块即可使用响应。收集工具在可选部分无法收集但仍有用的部分快照时包含一个 `warnings` 数组。
## 要求
- 用于 CI、Docker 和发布工作流的 Node.js 24 LTS
- 用于包运行时兼容性的 Node.js 22 或更高版本
- 通过 Corepack 进行开发安装的 pnpm 11.3.0
- 具有 `/proc`、`free`、`df`、`ps` 和 `uname` 的 Linux SSH 目标
- 通过 `known_hosts` 或固定的 SHA256 主机密钥进行严格的 SSH 主机验证
## 快速开始
从 npm 运行 stdio MCP 服务器：
```bash
npx -y infra-lens-mcp
```
桌面 MCP 客户端样式配置：
```json
{
"mcpServers": {
"infra-lens": {
"command": "npx",
"args": ["-y", "infra-lens-mcp"],
"env": {
"INFRA_LENS_DB": "/Users/you/.infra-lens-mcp/metrics.db"
}
}
}
}
```
本地开发：
```bash
corepack enable
corepack prepare pnpm@11.3.0 --activate
pnpm install --frozen-lockfile
pnpm run build
node dist/mcp.js
```
## 配置
| 变量 | 默认值 | 描述 |
| --- | --- | --- |
| `MCP_TRANSPORT` | `stdio` | 预期的传输模式：`stdio` 或 `http` |
| `INFRA_LENS_DB` | `~/.infra-lens-mcp/metrics.db` | SQLite 数据库路径 |
| `MCP_HTTP_HOST` | `127.0.0.1` | HTTP 绑定主机。`HOST` 仍然是一个废弃的别名 |
| `MCP_HTTP_PORT` | `3000` | HTTP 绑定端口。`PORT` 仍然是一个废弃的别名 |
| `MCP_HTTP_ENDPOINT_PATH` | `/mcp` | 规范的 Streamable HTTP MCP 端点路径 |
| `MCP_HTTP_ALLOWED_ORIGINS` | 未设置 | 以逗号分隔的允许 Origin 值 |
| `MCP_HTTP_ALLOWED_HOSTS` | 未设置 | 以逗号分隔的允许 Host 值 |
| `MCP_HTTP_AUTH_MODE` | `none` | `none`、`bearer` 或 `oauth-gateway`；`oauth` 被接受为兼容性别名 |
| `MCP_HTTP_BEARER_TOKEN` | 未设置 | 本地/开发的 bearer 后备令牌 |
| `MCP_HTTP_OAUTH_GATEWAY_HEADER` | `x-infra-lens-gateway-auth` | 由受信任的 OAuth 网关注入的标头 |
| `MCP_HTTP_OAUTH_GATEWAY_SECRET` | 未设置 | `oauth-gateway` 模式所需的共享后端密钥 |
| `MCP_HTTP_BODY_LIMIT_BYTES` | `1048576` | 最大 JSON 请求正文大小 |
| `MCP_HTTP_REQUEST_TIMEOUT_MS` | `30000` | 在关闭套接字之前接收和处理 HTTP 请求的最大时间 |
| `MCP_HTTP_MAX_CONCURRENT_REQUESTS` | `100` | Node 进程接受的最大并发 HTTP 请求数 |
| `MCP_HTTP_RATE_LIMIT_PER_MINUTE` | `0` | 可选的每客户端内存速率限制；`0` 禁用它 |
| `MCP_HTTP_AUTHORIZATION_SERVERS` | 未设置 | OAuth 授权服务器元数据 URL |
| `MCP_PROFILE` | `full` | `full`、`remote-safe`、`chatgpt` 或 `claude` |
| `MCP_SSH_STRICT_HOST_CHECKING` | `true` | 严格的主机密钥验证开关 |
| `MCP_SSH_KNOWN_HOSTS` | `~/.ssh/known_hosts` | 已知主机文件 |
| `MCP_SSH_ALLOWED_HOSTS` | 未设置 | 精确主机/IP 或 IPv4 CIDR 允许列表；`full` 配置文件中设置时强制执行 |
| `MCP_SSH_ALLOWED_USERS` | 未设置 | 可选的以逗号分隔的 SSH 用户名允许列表 |
| `MCP_SSH_ALLOWED_PORTS` | 未设置 | 可选的以逗号分隔的 SSH 端口允许列表 |
| `MCP_SSH_MAX_SESSIONS_PER_HOST` | `0` | 可选的主机:端口活动 SSH 会话上限；`0` 禁用它 |
| `MCP_SSH_MAX_CONNECTION_ATTEMPTS_PER_MINUTE` | `0` | 可选的主机:端口每分钟 SSH 连接尝试上限；`0` 禁用它 |
旧版示例中不再使用 `MCP_DB_PATH`；请使用 `INFRA_LENS_DB`。
## SSH 安全
默认启用严格的主机密钥检查。提供：
- 连接输入中的 `hostKeySha256` 值，例如 `SHA256:...`
- 连接输入中的 `knownHostsPath`
- 指向 OpenSSH `known_hosts` 文件的 `MCP_SSH_KNOWN_HOSTS`
仅在 `full` 配置文件中为受信任的本地 MCP 上下文接受原始密码、私钥和通行短语。`remote-safe`、`chatgpt` 和 `claude` 配置文件拒绝工具输入中的原始 SSH 凭据，并要求 `MCP_SSH_ALLOWED_HOSTS`。生产 SSH 策略还可以限制精确主机或 IPv4 CIDR 范围、用户、端口、每个主机的活动会话和每个主机的连接尝试。
默认进程命令不收集进程命令参数。进程数据、SSH 错误和日志中的类似机密的值在存储或输出之前会进行编辑。
## HTTP 传输
在本地运行 Streamable HTTP 传输。规范的 MCP 端点是 `http://127.0.0.1:3000/mcp`，除非更改了 `MCP_HTTP_ENDPOINT_PATH`。HTTP 模式目前是无状态的：服务器不发出或接受 `MCP-Session-Id`，并且仅在 MCP 端点上支持 POST JSON-RPC 调用。
```bash
MCP_TRANSPORT=http MCP_HTTP_HOST=127.0.0.1 MCP_HTTP_PORT=3000 node dist/server-http.js
```
环回 HTTP 可以在本地开发中无需身份验证运行。任何非环回绑定（例如 `0.0.0.0`）都会快速失败，除非配置了以下所有内容：
- `MCP_PROFILE=remote-safe`、`chatgpt` 或 `claude`
- `MCP_HTTP_AUTH_MODE=bearer` 或 `oauth-gateway`
- `MCP_HTTP_ALLOWED_ORIGINS`
- `MCP_HTTP_ALLOWED_HOSTS`
此软件包内未实现本机 OAuth/JWT 验证。公共部署应使用 `MCP_HTTP_AUTH_MODE=oauth-gateway`，位于生产 OAuth 感知网关或反向代理后面，配置 HTTPS `MCP_HTTP_RESOURCE_URL`，并阻止直接访问 Node 进程。即使上游代理也强制执行源/主机允许列表、正文限制、请求超时、并发限制和可选的速率限制，请在 Node 进程上保持启用状态。参见 [ADR 0006](./docs/adr/0006-oauth-gateway-strategy.md)。在验证完整的连接器部署之前，连接器发布准备状态为假。
## Docker
Docker 镜像默认为 stdio 模式：
```bash
docker build -t infra-lens-mcp .
docker run --rm -it \
-v "$HOME/.infra-lens-mcp:/home/appuser/.infra-lens-mcp" \
infra-lens-mcp
```
对于本地 HTTP 测试，覆盖命令并将绑定主机保留在环回地址上，除非配置了远程安全配置文件和身份验证控制：
```bash
docker run --rm -p 127.0.0.1:3000:3000 \
-e MCP_TRANSPORT=http \
-e MCP_HTTP_HOST=0.0.0.0 \
-e MCP_HTTP_ALLOWED_ORIGINS=http://localhost:3000 \
-e MCP_HTTP_ALLOWED_HOSTS=localhost:3000 \
-e MCP_HTTP_AUTH_MODE=bearer \
-e MCP_HTTP_BEARER_TOKEN=local-dev-token \
infra-lens-mcp node dist/server-http.js
```
## 开发
```bash
pnpm run format:check
pnpm run lint
pnpm test
pnpm run test:coverage
pnpm run build
pnpm run check:metadata
pnpm run package:dry-run
```
基于 Docker 的 SSH 端到端验证使用自包含的夹具生命周期：
```bash
pnpm run test:e2e
```
如果一个夹具已经运行，并且您故意想要跳过生命周期管理，请使用：
```bash
INFRA_LENS_E2E_SKIP_FIXTURE=1 pnpm run test:e2e:raw
```
生成的 API 文档位于 [docs/api](./docs/api/README.md)。客户端设置配方位于 [docs/integrations/client-setup.md](./docs/integrations/client-setup.md)。
参见 [docs/testing.md](./docs/testing.md)、[docs/security.md](./docs/security.md)、[docs/operations.md](./docs/operations.md) 和 [docs/release.md](./docs/release.md)，了解完整的操作工作流程。
## 社区
使用 [SUPPORT.md](./SUPPORT.md) 获取支持渠道和响应预期。项目行为准则定义在 [CODE_OF_CONDUCT.md](./CODE_OF_CONDUCT.md) 中，维护者三级评审政策位于 [docs/governance.md](./docs/governance.md)。
## 发布
发布通过 release-please 声明模式和受保护的 GitHub Actions 发布工作流进行管理。实施 PR 不得发布软件包、容器、MCP 注册表条目、市场工件或生产 GitHub Releases。
参见 [docs/release.md](./docs/release.md) 和 [docs/release-state-machine.md](./docs/release-state-machine.md)。
## 许可证
[MIT](./LICENSE)
