AI Ops MCP

English | 简体中文

AI Ops MCP 是一个本地 SSH 凭据代理和 stdio MCP 服务器。它允许 AI 客户端通过稳定的 server_id 别名执行 SSH 和 SFTP 操作，而无需接收密码、私钥内容或私钥口令。

[!WARNING] AI Ops MCP 保护的是身份验证边界；它不会对远程命令进行分类、批准或阻止。每条命令都以所配置 SSH 账户的权限运行。请使用专用的最低权限账户和服务端控制措施。

版本 0.1.0 仅以源码形式分发。本项目未发布到 npm。

功能特性

• 交互式服务器注册与可信主机密钥固定

• SSH Agent、系统凭据存储密码和私钥身份验证

• 集成 Windows 凭据管理器、macOS 钥匙串和 Linux Secret Service

• 连接池，支持每服务器和全局并发限制

• 远程命令、上传、下载和目录列表

• 本地和远程文件路径边界、超时、输出限制和文件大小限制

• 结构化审计日志，包含稳定的公共错误码

安全模型

密码和私钥口令通过隐藏提示请求，并存储在操作系统凭据存储中。非机密连接元数据存储在本地私有配置文件中。私钥始终是本地机器上的文件，仅在连接时读取。主机密钥指纹在注册时确认，之后的变更将被拒绝。

MCP 接口无法枚举或导出凭据。默认情况下，本地文件操作仅限于 MCP 进程的工作目录；可以为每个服务器配置额外的本地和远程根目录。审计日志可能包含命令和路径，请将其作为运营数据加以保护。漏洞报告请参阅 SECURITY.md。

该模型无法防范本地用户账户被入侵、恶意远程输出、远程主机被入侵，或使用有效 SSH 权限发出的破坏性命令。

环境要求

• Node.js 22 或 24

• Git 和可访问的 SSH 服务器

• 已验证的 SSH 主机密钥指纹

• 一种受支持的身份验证方法

• Linux 密码/口令用户：需要正在运行的 Secret Service 提供程序

Windows 凭据管理器已在 Windows 10 上使用 Node.js 24 验证。macOS 钥匙串和 Linux Secret Service 需要更广泛的真机反馈。

安装与构建

git clone https://github.com/Finn-Aigc/ai-ops-mcp.git
cd ai-ops-mcp
npm ci
npm run typecheck
npm test
npm run build
npm link
ai-ops doctor

npm link 会在本地暴露 ai-ops 和 ai-ops-mcp。CLI 开发期间运行 npm run dev -- --help，构建后运行 npm start -- --help。

身份验证

SSH Agent

将密钥加载到系统 Agent 中，然后运行 ai-ops add --auth agent 或导入有效的 OpenSSH 元数据：

ai-ops import-ssh my-host-alias

系统凭据存储密码

ai-ops add --id dev-box --host ssh.example.com --user deploy --auth password

密码以交互方式请求，不能通过命令行参数传入。

私钥文件

ai-ops add --id dev-key --host ssh.example.com --user deploy \
  --auth private-key --key <path-to-private-key>

密钥保留在指定路径。如果密钥已加密，其口令将以交互方式请求并存储在系统凭据存储中。

CLI 参考

所有选项请使用 ai-ops <command> --help 查看。切勿通过命令行参数自动输入密码或口令。

MCP 客户端配置

执行 npm link 后，可按如下方式配置任何 stdio MCP 客户端：

{
  "mcpServers": {
    "ai-ops": {
      "command": "ai-ops-mcp"
    }
  }
}

如需在不链接的情况下进行开发，请先构建，然后使用 node，并将 "<absolute-path-to-repository>/dist/mcp-entry.js" 作为唯一参数。

MCP 工具

默认限制为：每条命令 30 秒、命令输出合计 10 MiB、每个文件 100 MiB、每台服务器 4 个并发操作、全局 16 个并发操作。服务器设置可以降低或调整这些限制。

故障排除

• 首先运行 ai-ops doctor 进行密钥环、Agent、配置和服务器诊断。

• HOST_KEY_MISMATCH：通过带外方式验证新指纹，然后运行 ai-ops trust-host <id>。

• AGENT_UNAVAILABLE：启动 SSH Agent 并使用 ssh-add 加载密钥。

• CREDENTIAL_STORE_UNAVAILABLE：解锁或启动平台凭据服务。

• LOCAL_PATH_NOT_ALLOWED 或 REMOTE_PATH_NOT_ALLOWED：使用 ai-ops edit <id> --allowed-local ... --allowed-remote ... 更新根目录。

• MCP 进程立即退出：运行 npm run build 并确认配置的可执行文件或绝对入口路径。

本地实时 E2E 测试

实时测试有意不纳入 GitHub Actions。请使用隔离的主目录和一个专用的低权限服务器账户，该账户可以在 /tmp 下创建临时文件并更新自己的 ~/.ssh/authorized_keys：

$env:AI_OPS_HOME = "<isolated-ai-ops-home>"
$env:AI_OPS_E2E_SERVER_ID = "test-server"
npm run build
npm run test:e2e:core
npm run test:e2e:mcp
npm run test:e2e:auth
npm run test:e2e:agent
npm run test:e2e:cleanup

每个测试都使用独立资源，并在 finally 块中清理。切勿使用生产凭据或配置。请参阅 CONTRIBUTING.md、docs/PRD.md 和 docs/IMPLEMENTATION_PLAN.md。

许可证

MIT © 2026 AI Ops MCP 贡献者。