Infra Lens

infra-lens-mcp 通过 SSH 连接 Linux 主机，采集有界的实时指标，将观测数据和经批准的基线存储在本地 SQLite 中，解释异常，并生成以审核为先的事件材料。npm 包和已签名容器已准备好发布；在验证外部 OAuth/HTTPS 部署之前，我们仍有意暂缓公开发布连接器。

演示

有关当前的协议支持、委托行为和连接器发布限制，请参阅 MCP 2025-11-25 合规性矩阵。

工具

工具	用途
analyze_server	分析一个有界采样时间窗口，并支持进度报告和取消，随后仅存储已完成的观测结果
analyze_server_snapshot	立即分析并存储一个快照，无需采样延迟
snapshot	存储某个时间点的观测结果，不进行异常分析
record_baseline	保存带标签的健康状态样本
compare_to_baseline	将当前状态与指定基线进行比较
get_history	从 SQLite 返回 CPU、内存或负载历史记录
inspect_host_capabilities	在采集前检查所需的 Linux 命令和 proc 文件
plan_remediation	提出有证据支持且需要审批的修复方案，不执行任何更改
draft_incident_report	根据已持久化的观测结果起草事件报告和事后复盘
compare_incident_windows	比较单个主机相邻时间窗口的数据，或比较两台主机的同一时间窗口数据

所有工具都会返回易读的 JSON 文本和经过声明的 outputSchema 定义验证的 MCP structuredContent，因此客户端和 Agent 无需解析文本块即可使用响应。如果无法采集可选部分，但部分快照仍可用，采集工具会在 warnings 数组中提供相关信息。交互式检查请使用 analyze_server_snapshot；只有在需要采样时间窗口时才使用 analyze_server。如果客户端提供了进度令牌，采样分析会发送 MCP 进度通知，且绝不会持久化已取消的部分运行结果。

要求

• CI、Docker 和发布工作流需要 Node.js 24 LTS
• 软件包运行时兼容性需要 Node.js 22 或更高版本
• 开发安装需要通过 Corepack 使用 pnpm 11.15.1
• Linux SSH 目标需具备 /proc、free、df、ps 和 uname
• 通过 known_hosts 或固定的 SHA256 主机密钥严格验证 SSH 主机

快速开始

从 npm 运行 stdio MCP 服务：

npx -y infra-lens-mcp

桌面 MCP 客户端样式配置：

{
  "mcpServers": {
    "infra-lens": {
      "command": "npx",
      "args": ["-y", "infra-lens-mcp"],
      "env": {
        "INFRA_LENS_DB": "/Users/you/.infra-lens-mcp/metrics.db"
      }
    }
  }
}

本地开发：

corepack enable
corepack prepare [email protected] --activate
pnpm install --frozen-lockfile
pnpm run build
node dist/mcp.js

配置

传输方式由可执行入口点选择，而非由环境变量选择：npx -y infra-lens-mcp 或 node dist/mcp.js 会启动 stdio，而 node dist/server-http.js 会启动 Streamable HTTP。

变量	默认值	说明
INFRA_LENS_DB	~/.infra-lens-mcp/metrics.db	SQLite 数据库路径
INFRA_LENS_RETENTION_DAYS	30	快照保留天数；0 表示禁用自动清理
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 调用。MCP_HTTP_REQUEST_TIMEOUT_MS 和任何代理超时时间都必须大于请求的采样时长；否则请使用 analyze_server_snapshot。stdio 没有由服务控制的墙钟请求超时，因此超时和 MCP 取消由客户端控制。

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 验证。公共部署应在支持 OAuth 的生产级网关或反向代理后使用 MCP_HTTP_AUTH_MODE=oauth-gateway，配置 HTTPS MCP_HTTP_RESOURCE_URL，并阻止对 Node 进程的直接访问。即使上游代理也执行这些限制，仍应在 Node 进程上启用来源/主机允许列表、请求正文大小限制、请求超时、并发限制和可选的速率限制。请参阅 ADR 0006。在验证完整的连接器部署之前，连接器发布就绪状态仍为 false。

Docker

Docker 镜像默认使用 stdio 模式：

docker build -t infra-lens-mcp .
docker volume create infra-lens-data
docker run --rm -i \
  --read-only \
  --cap-drop=ALL \
  --security-opt=no-new-privileges:true \
  --tmpfs /tmp:rw,noexec,nosuid,nodev,size=64m \
  --mount type=volume,src=infra-lens-data,dst=/home/appuser/.infra-lens-mcp \
  infra-lens-mcp

如需进行本地 HTTP 测试，请覆盖命令，并将绑定主机保持为回环地址，除非已配置远程安全配置文件和身份验证控制：

docker run --rm -p 127.0.0.1:3000:3000 \
  --read-only \
  --cap-drop=ALL \
  --security-opt=no-new-privileges:true \
  --tmpfs /tmp:rw,noexec,nosuid,nodev,size=64m \
  --mount type=volume,src=infra-lens-data,dst=/home/appuser/.infra-lens-mcp \
  -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

可观测性导出

可观测性导出是一个独立且默认禁用的进程，它会读取最新的持久化观测数据，不会发起 SSH 收集：

INFRA_LENS_OBSERVABILITY_ENABLED=true infra-lens-observe

默认的 OpenMetrics 端点为 http://127.0.0.1:9464/metrics。可选的 OTLP/HTTP JSON 导出使用标准的 OTEL_EXPORTER_OTLP_* 变量。有关 Prometheus、OpenTelemetry、隐私和远程访问的指南，请参阅可观测性导出。

开发

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 端到端验证使用独立的测试夹具生命周期：

pnpm run test:e2e

如果测试夹具已在运行，且你有意跳过生命周期管理，请使用：

INFRA_LENS_E2E_SKIP_FIXTURE=1 pnpm run test:e2e:raw

请从文档索引开始，了解用法、客户端设置、运维、事件工作流、可观测性、存储、安全、治理、测试和发布指南。生成的 API 文档位于 docs/api，经过审核的事件示例位于 examples/incidents。

社区

请通过 SUPPORT.md 了解支持渠道和响应预期。当前工作在 infra-lens-mcp Governance 项目中跟踪。项目行为规范见 CODE_OF_CONDUCT.md，维护者的分类处理政策见 docs/governance.md。

发布

发布通过 release-please manifest 模式和受保护的 GitHub Actions 发布工作流进行管理。实现类 PR 不得发布软件包、容器、MCP Registry 条目、市场工件或生产环境中的 GitHub Releases。

请参阅 docs/release.md 和 docs/release-state-machine.md。

许可证

MIT

Agent 插件和运行时配置

此代码仓库维护 infra-lens-mcp 的产品级 Agent 插件、MCP 运行时配置和产品专属技能。中央 agent-tools 代码仓库应收录此插件，但清单和工作流说明保存在这里，以便与实际 MCP 服务包保持同步。

文件	用途
.claude-plugin/plugin.json	符合 Claude Code 规范的产品插件清单。
.mcp.json	Claude Code 项目本地 MCP 服务配置。
.codex/config.example.toml	Codex CLI MCP 配置示例。
.vscode/mcp.example.json	VS Code / GitHub Copilot 工作区 MCP 配置示例。
opencode.example.jsonc	OpenCode 项目 MCP 配置示例。
.opencode/skills/	OpenCode 原生镜像技能定义。
docs/agent-runtime-config.md	Agent 运行时设置和验证说明。

在本地验证插件打包：

claude plugin validate .

如需优先审核的修复计划、事件草稿以及主机/时间窗口比较，请参阅事件工作流。