hueilau/mcp-risk

# MCP 风险 为 MCP 服务器和 agent 工具提供安装前和配置风险检查。 [](https://github.com/hueilau/mcp-risk/actions/workflows/ci.yml) [](LICENSE) [](package.json) [](https://modelcontextprotocol.io/) `mcp-risk` 为开发者提供了两个快速审查循环： - `mcp-risk check ` 在你安装 MCP 服务器之前，对 npm 包或 GitHub 仓库进行评分。 - `mcp-risk scan [config files...]` 扫描 MCP 配置文件，检查是否存在有风险的服务器设置。 其目标并不是证明某个服务器是安全的。其目标是让首次审查变得显而易见：近期的维护情况、采用信号、包规范、固定版本安装、可见的授权、字面量密钥、文件系统范围以及特权容器访问权限。 目前支持从 GitHub 运行。npm 发布可能会在稍后进行。 ## 功能 - 为 MCP 服务器和 agent 工具提供安装前的包和仓库评分。 - 静态 MCP 配置扫描，检测常见的本地和远程服务器风险。 - 支持人类可读格式、JSON 和 Markdown 输出，适用于本地使用或 CI 评论。 - 对 CI 友好的阈值设置及稳定的退出代码。 - 小型 TypeScript CLI，包含确定性测试和基于 fixture 的 provider 测试。 ## 为什么会有这个项目 MCP 非常实用，因为它允许 agent 使用真实工具。这也意味着，在 MCP 服务器配置于开发者机器或 CI 环境中运行之前，对其进行快速审查是很有必要的。 MCP 规范指出，当本地服务器以客户端用户的权限运行时，可能会带来安全风险；并且 HTTP 传输应使用授权或其他强大的访问控制机制。`mcp-risk` 将这些实际关注点转化为了简单的检查项。 ## 快速开始 直接从公开的 GitHub 仓库运行： ``` npm exec --yes --package github:hueilau/mcp-risk -- mcp-risk check chrome-devtools-mcp npm exec --yes --package github:hueilau/mcp-risk -- mcp-risk scan .cursor/mcp.json ``` 预期的 `check` 输出结构： ``` 97 A Low visible metadata risk. ``` 或者克隆并在本地运行： ``` git clone https://github.com/hueilau/mcp-risk.git cd mcp-risk npm ci npm run build node dist/cli.js check chrome-devtools-mcp --quiet node dist/cli.js scan examples/risky.mcp.json ``` 当该包发布到 npm 之后，就可以使用以下更简短的命令： ``` npx mcp-risk check chrome-devtools-mcp npx mcp-risk scan .cursor/mcp.json ``` 发布后，你也可以通过 npm 全局安装： ``` npm install -g mcp-risk mcp-risk check @playwright/mcp mcp-risk scan ``` ## 检查包或仓库 当 README、市场或 agent 建议安装新的 MCP 包时，请使用 `check`： ``` mcp-risk check chrome-devtools-mcp mcp-risk check @playwright/mcp --quiet mcp-risk check ChromeDevTools/chrome-devtools-mcp --json mcp-risk check fake-package --fail-under 80 ``` `check` 会查看来自 npm 和 GitHub 的可见公开元数据： - 维护的新近程度 - 下载量、星标数、分支数和依赖项 - 许可证、仓库链接、issue 链接、关键词和维护者 - 明显的风险标志，例如被归档的仓库或缺失的许可证元数据 `check` 仅针对元数据。它不会安装或执行目标包。 ## 扫描 MCP 配置 当你已经拥有一个 MCP 配置并想审查它将运行的内容时，请使用 `scan`： ``` mcp-risk scan examples/risky.mcp.json mcp-risk scan --format json examples/risky.mcp.json mcp-risk scan --format markdown examples/risky.mcp.json > mcp-risk-report.md mcp-risk scan --fail-on high examples/risky.mcp.json ``` 如果未提供配置路径，`mcp-risk scan` 会寻找常见的项目本地文件： - `.mcp.json` - `mcp.json` - `.cursor/mcp.json` - `.vscode/mcp.json` - `package.json` 在 macOS 上扫描 Claude Desktop 配置： ``` mcp-risk scan ~/Library/Application\ Support/Claude/claude_desktop_config.json ``` 预期的 `scan` 输出结构： ``` MCP Risk scan Servers: 2 Findings: 5 Max severity: critical ``` ## 扫描检查项 | 代码 | 严重性 | 捕获内容 | |---|---:|---| | `MCP010` | 中/高 | Shell 或解释器包装器，例如 `bash`、`sh`、`python` 或 `node` | | `MCP011` | 高 | 内联命令执行，例如 `bash -c` | | `MCP012` | 严重 | 远程下载通过管道传递给 shell | | `MCP021` | 高 | 包运行器直接从 URL 或 git 安装 | | `MCP022` | 高 | 浮动的 `@latest` 包安装 | | `MCP023` | 中 | 没有固定确切版本的包运行器 | | `MCP031` | 严重 | 使用纯 HTTP 的远程 MCP URL | | `MCP032` | 高 | 没有可见授权的远程 MCP URL | | `MCP040` | 严重 | 配置环境变量中的字面量密钥 | | `MCP050` | 高 | 广泛的文件系统访问权限，例如 `/`、`~` 或 `$HOME` | | `MCP060` | 严重 | Docker socket 访问权限 | | `MCP061` | 高 | 提升的容器权限标志 | ## CI 在 npm 发布之前，请使用 GitHub 包： ``` - name: Scan MCP config run: npm exec --yes --package github:hueilau/mcp-risk -- mcp-risk scan --fail-on high ``` npm 发布后，该命令可以缩短为 `npx mcp-risk scan --fail-on high`。 退出代码： - `0`：命令已完成，且未触发配置的阈值失败。 - `1`：命令无法运行、无法解析输入或无法获取所需的元数据。 - `2`：`check --fail-under` 或 `scan --fail-on` 未通过。 这意味着，对于故意设置了风险的 fixture，此命令预计会以 `2` 退出： ``` node dist/cli.js scan examples/risky.mcp.json --fail-on high ``` ## 开发 ``` npm ci npm run check npm run build node dist/cli.js check chrome-devtools-mcp --quiet node dist/cli.js scan examples/risky.mcp.json npm pack --dry-run ``` 该包的压缩包仅包含编译好的 CLI、示例、README、许可证和包元数据。 ## 局限性 - 评分仅作为审查辅助，并非安全保证。 - `check` 依赖于公开的 npm 和 GitHub 元数据，这些数据可能不完整。 - `scan` 是保守的且基于规则的；如果某个规则产生了太多噪音，请提一个误报 issue。 ## 项目状态 这是一个早期的 OSS（开源软件）切入点：目前非常实用，设计精简，并且欢迎专注于规则的代码贡献。 近期路线图： - 提供更多真实的 MCP 客户端配置 fixture。 - 为流行的 MCP 服务器提供更安全的配置示例。 - 输出 SARIF 或 GitHub annotation 以适配安全工作流。 - 一旦 CLI 表面稳定，将提供可选的 npm 发布。 ## 贡献 绝佳的首次贡献： - 为来自流行客户端的 MCP 配置添加 fixture。 - 在不增加嘈杂误报的情况下，改进对某一种风险模式的检测。 - 为包或仓库元数据添加评分信号。 - 为安全工具添加输出适配器。 请参阅 [CONTRIBUTING.md](CONTRIBUTING.md)。请保持规则的可解释性：检查结果应明确告知用户需要审查或更改什么。

标签：AI智能体, MCP, MITM代理, 暗色界面, 自动化攻击, 错误基检测, 静态代码分析