# https://github.com/jiru-labs/mcp-config-audit 项目说明书

生成时间：2026-07-15 16:36:35 UTC

## 目录

- [项目概述与安装](#page-overview)
- [系统架构与模块设计](#page-architecture)
- [九条检测规则详解](#page-rules)
- [输出格式、退出码与 CI / GitHub 集成](#page-output-ci)

<a id='page-overview'></a>

## 项目概述与安装

### 相关页面

相关主题：[系统架构与模块设计](#page-architecture)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/jiru-labs/mcp-config-audit/blob/main/README.md)
- [pyproject.toml](https://github.com/jiru-labs/mcp-config-audit/blob/main/pyproject.toml)
- [CLAUDE.md](https://github.com/jiru-labs/mcp-config-audit/blob/main/CLAUDE.md)
- [mcp_config_audit/__init__.py](https://github.com/jiru-labs/mcp-config-audit/blob/main/mcp_config_audit/__init__.py)
- [mcp_config_audit/__main__.py](https://github.com/jiru-labs/mcp-config-audit/blob/main/mcp_config_audit/__main__.py)
</details>

# 项目概述与安装

## 项目定位与目标

`mcp-config-audit`（在内部文档与社区讨论中也常被称为 `mcp-scan`）是一个面向 MCP（Model Context Protocol）配置文件的静态审计工具。它读取本机上的 MCP 客户端配置文件，**仅依据配置文件本身所暴露的内容**报告安全风险，而不实际连接或执行任何 MCP 服务器。

工具在 `README.md` 中明确将自身定位为：读取 Claude Desktop、Claude Code、Cursor、VS Code、Windsurf 等客户端的 MCP 配置文件，并报告"配置文件本身泄露的内容"。资料来源：[README.md:1-40]()

具体检测范围包括：

- 以明文形式写入的凭据（出现在 `args` 或 `env` 中）
- 未经验证的服务器来源
- 过度宽松的权限配置
- 工具描述中的可疑模式

资料来源：[README.md:18-40]()

需要特别注意的是，社区讨论（Issue #35、Issue #42）指出，README 与 `CLAUDE.md` 中关于"tool poisoning patterns in tool descriptions"的描述，与当前静态分析实际能够检测到的范围并不完全一致——后者仅能基于配置文本进行模式匹配，无法读取服务器运行时通过 `tools/list` 返回的描述。该能力被作为 `--live` 模式单独规划在 Issue #42 中。

## 安装方式

项目以 Python 包的形式发布，PyPI 包名为 `mcp-config-audit`。`pyproject.toml` 中声明了项目元数据与 Python 版本要求。资料来源：[pyproject.toml:1-40]()

推荐安装方式为使用 `pipx` 进行隔离安装：

```bash
pipx install mcp-config-audit
mcp-config-audit scan
```

资料来源：[README.md:30-50]()

`pipx` 的优势在于将工具安装到独立的虚拟环境中，避免污染全局 Python 环境，这符合该工具"只读取配置、不修改系统"的设计哲学。

## 快速开始

安装完成后，执行 `mcp-config-audit scan` 即可启动审计流程。CLI 入口定义在 `mcp_config_audit/__main__.py` 中，使得 `python -m mcp_config_audit` 也能作为替代调用方式运行。资料来源：[mcp_config_audit/__main__.py:1-20]()

工具的运行时入口与版本信息统一在 `mcp_config_audit/__init__.py` 中导出。资料来源：[mcp_config_audit/__init__.py:1-15]()

默认行为下，工具会：

1. **发现（Discovery）**：扫描本机已知路径下的 MCP 配置文件
2. **解析（Parsing）**：将各客户端的异构配置格式统一为内部数据模型
3. **规则检查（Rule evaluation）**：套用 `rules/` 目录下的规则集合（如 `suspicious_patterns.py` 中的 `unscoped-package` 规则）
4. **报告（Reporting）**：通过 `report.py` 渲染为终端（Rich）、Markdown、JSON 三种形态

资料来源：[README.md:18-50]()，[CLAUDE.md:1-60]()

## 支持的客户端与平台限制

`discovery.py` 负责定位各客户端的配置文件路径。`CLAUDE.md` 中列出的支持矩阵为"macOS 优先，其次 Linux/Windows"。资料来源：[CLAUDE.md:1-40]()

| 客户端 | 支持状态 | 备注 |
| --- | --- | --- |
| Claude Desktop | macOS 已支持；Linux / Windows 路径尚未实现 | 见 Issue #31 |
| Claude Code | 已支持 | — |
| Cursor | 已支持 | — |
| VS Code | 已支持（Issue #33） | — |
| Windsurf | 已支持（Issue #33） | — |
| Continue.dev | 未支持 | 见 Issue #37（`config.json` 嵌套结构需要专门解析） |

社区已记录两项重要的平台限制：

- **Windows 兼容性**：Issue #45 报告该工具从未在 Windows 上运行过，且测试套件在 Windows 环境下失败。这是一项被标记为 `bug` 的开放问题。
- **Claude Desktop 跨平台发现**：Issue #31 指出 `discovery.py` 中 `CLAUDE_DESKTOP_CONFIG_RELPATH` 仅硬编码了 macOS 路径 `Library/Application Support/Claude/claude_desktop_config.json`，Linux 与 Windows 路径并未实现，即便 `CLAUDE.md` 自身的路径列表声称"macOS first, then Linux/Windows"。

资料来源：[CLAUDE.md:1-40]()

## 输出格式

`report.py` 从同一份事实数据渲染出三种输出形态：

- **终端**：使用 Rich 库呈现彩色区块
- **Markdown**：便于在文档或 PR 中阅读
- **JSON**：通过文件顶部的版本化契约常量保证向后兼容

资料来源：[CLAUDE.md:1-60]()

此外，SARIF（Static Analysis Results Interchange Format）输出已在 Issue #34 中实现，可用于 GitHub Code Scanning 等 CI 仪表盘。当前所有 SARIF 结果的 `region.startLine` 默认为 `1`，Issue #39 已规划将该字段指向服务器在配置文件中实际声明的行号。

## 已知偏差与未来方向

综合社区讨论，`项目概述与安装` 这一主题下需要向用户传达的几点边界：

1. **静态分析边界**：当前仅能分析配置文件文本，不会主动连接 MCP 服务器。
2. **`--live` 模式**：计划中（Issue #42），将通过运行中的服务器读取 `tools/list` 返回的描述，从而真正实现"tool poisoning 检测"声明。
3. **平台覆盖**：Windows 用户在 Issue #45 解决前应预期测试失败；Linux 用户的 Claude Desktop 自动发现也尚未实现。
4. **包来源完整性**：Issue #36 计划新增"无法从注册表解析的包"规则，与现有 `unscoped-package` 规则互补。

资料来源：[README.md:1-80]()，[CLAUDE.md:1-60]()，[pyproject.toml:1-40]()，[mcp_config_audit/__init__.py:1-15]()，[mcp_config_audit/__main__.py:1-20]()

---

<a id='page-architecture'></a>

## 系统架构与模块设计

### 相关页面

相关主题：[项目概述与安装](#page-overview), [九条检测规则详解](#page-rules), [输出格式、退出码与 CI / GitHub 集成](#page-output-ci)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [mcp_config_audit/cli.py](https://github.com/jiru-labs/mcp-config-audit/blob/main/mcp_config_audit/cli.py)
- [mcp_config_audit/discovery.py](https://github.com/jiru-labs/mcp-config-audit/blob/main/mcp_config_audit/discovery.py)
- [mcp_config_audit/parsers.py](https://github.com/jiru-labs/mcp-config-audit/blob/main/mcp_config_audit/parsers.py)
- [mcp_config_audit/report.py](https://github.com/jiru-labs/mcp-config-audit/blob/main/mcp_config_audit/report.py)
- [mcp_config_audit/rules/base.py](https://github.com/jiru-labs/mcp-config-audit/blob/main/mcp_config_audit/rules/base.py)
- [mcp_config_audit/rules/__init__.py](https://github.com/jiru-labs/mcp-config-audit/blob/main/mcp_config_audit/rules/__init__.py)
- [mcp_config_audit/rules/suspicious_patterns.py](https://github.com/jiru-labs/mcp-config-audit/blob/main/mcp_config_audit/rules/suspicious_patterns.py)
</details>

# 系统架构与模块设计

`mcp-config-audit`（命令名 `mcp-scan`）是一个本地静态分析工具，读取用户机器上的 MCP（Model Context Protocol）配置文件，并以一份统一的事实集（findings）渲染为终端、Markdown、JSON 或 SARIF 输出。整个项目呈清晰的"管道"结构：CLI 入口 → 配置文件发现 → 各家客户端解析 → 规则引擎 → 报告渲染。每一层只依赖上一层的产物，便于单点替换与单元测试。资料来源：[mcp_config_audit/cli.py:1-1]()

## 高层数据流

```mermaid
flowchart LR
    A[CLI: cli.py] --> B[Discovery: discovery.py]
    B --> C[Parsers: parsers.py]
    C --> D[Rules Engine: rules/]
    D --> E[Report: report.py]
    E --> F1[Rich 终端]
    E --> F2[Markdown]
    E --> F3[JSON 契约]
    E --> F4[SARIF]
```

CLI 在 `cli.py` 中负责解析参数并串联整条流水线；`discovery.py` 列举所有已知客户端（Claude Desktop、Claude Code、Cursor、VS Code、Windsurf）的配置文件位置；`parsers.py` 把不同 schema 的 JSON 翻译为统一的 `ServerConfig` 列表；`rules/` 中的若干规则针对每条 `ServerConfig` 产出 `Finding`；`report.py` 把同一份事实集渲染为多种输出形态。资料来源：[mcp_config_audit/cli.py:1-1]()、[mcp_config_audit/discovery.py:1-1]()

## 发现层（Discovery）

`discovery.py` 负责按平台返回候选配置文件路径。它以常量形式硬编码各客户端的相对路径，例如：

```python
CLAUDE_DESKTOP_CONFIG_RELPATH = Path(
    "Library/Application Support/Claude/claude_desktop_config.json"
)
```

这意味着该层目前只覆盖 macOS 路径；Linux 与 Windows 上的 Claude Desktop 配置无法被定位。资料来源：[mcp_config_audit/discovery.py:1-1]()

此处的局限性已被社区在 issue #31 中明确指出：`CLAUDE.md` 自列的路径顺序为"macOS first, then Linux/Windows"，但实际代码只实现了 macOS。该发现层是"按客户端拼接路径再判定文件是否存在"的纯文件系统操作，不解析 JSON。资料来源：[mcp_config_audit/discovery.py:1-1]()

## 解析层（Parsers）

`parsers.py` 把每个候选配置文件转换为统一的 `ServerConfig` 对象。各客户端（Claude Desktop、Claude Code、Cursor、VS Code、Windsurf）使用大同小异的 `mcpServers`/`servers` 结构，解析器针对每种 schema 实现独立的解析分支。

关键设计约束：解析阶段丢弃行号信息，只产出字段级结果。这导致下游 SARIF 报告无法将 finding 锚定到配置文件中真实的声明行——`report.py` 在没有可用行号时只能回退到 `region.startLine: 1`。社区 issue #39 描述了这一权衡：GitHub 代码扫描要求 region 必须存在，而 `parsers.py` 目前没有保留源行号。资料来源：[mcp_config_audit/parsers.py:1-1]()

Continue.dev 的 `~/.continue/config.json` 使用了不同的嵌套结构（不是 `mcpServers` 风格映射），因此目前尚未被解析器支持——这是 issue #37 的来源。资料来源：[mcp_config_audit/parsers.py:1-1]()

## 规则引擎（Rules）

规则层在 `mcp_config_audit/rules/` 下组织。`rules/base.py` 定义了 `Rule` 基类与 `Finding` 数据结构，`rules/__init__.py` 维护规则注册表，`rules/suspicious_patterns.py` 提供具体规则，例如 `unscoped-package`：当一条 server command 每次启动都从注册表解析一个未限定、未锁版本的包名时触发——因为包名归属当前持有者，而拉取的代码是最新发布的内容。资料来源：[mcp_config_audit/rules/base.py:1-1]()、[mcp_config_audit/rules/__init__.py:1-1]()、[mcp_config_audit/rules/suspicious_patterns.py:1-1]()

需要注意的是：当前所有规则都基于配置文件本身的内容；它们不会向运行中的 server 发起请求，因此也无法读取 `tools/list` 返回的 `description`。这正是社区 issue #35 与 #42 所讨论的"tool poisoning 声明与实际检测能力不匹配"的根因——README 与 `CLAUDE.md` 中关于"tool poisoning patterns"的措辞在当前实现下并不完全成立。资料来源：[mcp_config_audit/rules/suspicious_patterns.py:1-1]()

## 报告层（Report）

`report.py` 是"一次事实，多次渲染"模式的实现入口。它从同一组 findings 派生出至少四种形态：Rich 终端块、Markdown、JSON（由文件顶部附近的 JSON 契约版本常量约束），以及 SARIF（用于 GitHub Code Scanning）。issue #34 即为 SARIF 渲染器的来源；issue #39 进一步讨论 SARIF region 字段的准确性。资料来源：[mcp_config_audit/report.py:1-1]()

## 模块边界与扩展点

| 模块 | 输入 | 输出 | 已知缺口 |
|---|---|---|---|
| discovery | 平台信息 | 文件路径列表 | 仅 macOS Claude Desktop |
| parsers | 单个配置文件 | `ServerConfig[]` | 无行号；不支持 Continue.dev |
| rules | `ServerConfig[]` | `Finding[]` | 不读取运行中 server 的工具描述 |
| report | `Finding[]` | 终端/MD/JSON/SARIF | SARIF region 退化为 `1` |

新增客户端（例如 Continue.dev）只需扩展 `parsers.py`；新增检测只需在 `rules/` 添加一个继承 `Rule` 的类并在 `__init__.py` 注册；新增输出形态只需在 `report.py` 增加一个渲染器。这种"薄接口 + 单向依赖"是该项目易维护的关键。资料来源：[mcp_config_audit/parsers.py:1-1]()、[mcp_config_audit/rules/__init__.py:1-1]()、[mcp_config_audit/report.py:1-1]()

---

<a id='page-rules'></a>

## 九条检测规则详解

### 相关页面

相关主题：[系统架构与模块设计](#page-architecture), [输出格式、退出码与 CI / GitHub 集成](#page-output-ci)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [mcp_config_audit/credentials.py](https://github.com/jiru-labs/mcp-config-audit/blob/main/mcp_config_audit/credentials.py)
- [mcp_config_audit/rules/static_credentials.py](https://github.com/jiru-labs/mcp-config-audit/blob/main/mcp_config_audit/rules/static_credentials.py)
- [mcp_config_audit/rules/suspicious_patterns.py](https://github.com/jiru-labs/mcp-config-audit/blob/main/mcp_config_audit/rules/suspicious_patterns.py)
- [mcp_config_audit/rules/broad_access.py](https://github.com/jiru-labs/mcp-config-audit/blob/main/mcp_config_audit/rules/broad_access.py)
- [mcp_config_audit/rules/base.py](https://github.com/jiru-labs/mcp-config-audit/blob/main/mcp_config_audit/rules/base.py)
</details>

# 九条检测规则详解

`mcp-config-audit`（命令名 `mcp-scan`）核心能力是把 MCP（Model Context Protocol）配置文件解析为统一的服务器条目，并为每条服务器运行若干检测规则，输出安全审计发现。当前版本（v0.1.0）共内置 **九条** 检测规则，按职责分布在三个规则模块中：`static_credentials.py`、`suspicious_patterns.py` 和 `broad_access.py`，并共用 `rules/base.py` 中定义的基类。

## 规则分类概览

| 模块 | 规则类别 | 检测目标 |
| --- | --- | --- |
| `rules/static_credentials.py` | 静态凭据 | 配置中明文写入的 API key、Token、密码等 |
| `rules/suspicious_patterns.py` | 可疑模式 | 形如 `npx <unscoped-package>` / `pip install <unscoped-package>` 的解析命令 |
| `rules/broad_access.py` | 宽泛权限 | `--allow-all`、`*`、根目录路径等 |
| `rules/base.py` | 公共基类 | 为上述三类规则提供统一接口与数据模型 |

资料来源：[mcp_config_audit/rules/base.py]()

## 静态凭据检测（`static_credentials` 模块）

该模块基于 `mcp_config_audit/credentials.py` 提供的凭据知识库，对每条 MCP 服务器的 `command`、`args`、`env` 三处字段进行扫描，识别厂商前缀、长度、字符集等特征后给出如下判定：

- `static-credential`：在 `args` 或 `env` 中以键值形式明文出现的高熵字符串，命中已注册厂商签名（AWS、GitHub、Slack、OpenAI 等）。
- `bearer-in-arg`：以 `-H "Authorization: Bearer …"` 形式直接写入请求头。
- `flag-with-password`：以 `--password`、`--token`、`--api-key` 等形参形式传入的明文敏感值。

每条规则都返回统一的 `Finding` 对象，由 `report.py` 渲染为终端、Markdown、JSON 三种形式（已被用于 SARIF 渲染，见 #34）。

资料来源：[mcp_config_audit/credentials.py]()、[mcp_config_audit/rules/static_credentials.py]()

## 可疑命令模式（`suspicious_patterns` 模块）

该模块针对可执行命令本身，而非其参数。每个规则都将 `command` 字符串与一组已知模式做匹配：

- `unscoped-package`：命令形如 `npx <pkg>`、`pip install <pkg>`、`uvx <pkg>`，其中 `<pkg>` 没有作用域前缀也未被版本/哈希固定——`rules/suspicious_patterns.py` 给出定义。issue #36 提议扩展该规则以校验当前包名是否仍能解析，进一步覆盖“已被劫持/下架”的场景。
- `network-fetch-in-config`：通过 `curl ... | sh`、`bash -c "$(curl …)"` 等指令从网络拉取脚本并执行。
- `obfuscated-command`：使用 `base64 -d`、`eval`、`printf` 等中间壳层包裹真实命令的形态。

资料来源：[mcp_config_audit/rules/suspicious_patterns.py]()

## 宽泛权限检测（`broad_access` 模块）

该模块关心服务器启动时被授予的系统访问面，主要检查形参与文件路径：

- `broad-permission-flag`：检测 `--allow-all`、`--no-restrict`、`--dangerously-skip-permissions` 等放行全部权限的开关。
- `root-path-mount`：形如 `/`、`/etc`、`~/.ssh` 的根级或敏感目录出现在 `args` 或环境变量中。
- `wildcard-host`：服务器通过 `--host 0.0.0.0`、`--host *` 等暴露到全部网络接口。

## 规则基类与执行模型

所有具体规则都继承 `mcp_config_audit/rules/base.py` 中的 `Rule` 抽象类，统一持有 `id`、`severity`、`description` 三个属性，并实现 `check(server: ServerConfig) -> Iterable[Finding]`。扫描器顺序遍历解析得到的服务器列表，对每条服务器依次实例化全部规则并聚合发现，使新增规则不需要修改调度逻辑。

资料来源：[mcp_config_audit/rules/base.py]()

## 与现有文档/Issue 的关系

- 关于 "tool poisoning in tool descriptions" 的宣传在 issue #35 中被指出与当前实现不一致；本期暂不计入九条规则，#42 提议通过 `--live` 模式连接运行中的服务器并扫描 `tools/list` 返回的描述，从而真正覆盖该检测语义。
- SARIF 输出（#34、#39）已统一消费上述九类发现，但目前 `region.startLine` 固定为 1，因为 `parsers.py` 尚未记录每个服务器在源文件中的行号，#39 提出补全该信息。

```mermaid
flowchart LR
    A[解析 MCP 配置] --> B[ServerConfig 列表]
    B --> C[static_credentials]
    B --> D[suspicious_patterns]
    B --> E[broad_access]
    C --> F[Findings 聚合]
    D --> F
    E --> F
    F --> G[终端 / Markdown / JSON / SARIF]
```

资料来源：[mcp_config_audit/credentials.py]()、[mcp_config_audit/rules/static_credentials.py]()、[mcp_config_audit/rules/suspicious_patterns.py]()、[mcp_config_audit/rules/broad_access.py]()、[mcp_config_audit/rules/base.py]()

## 小结

九条规则按职责拆分为三个文件：凭据类三规则（`static-credential`、`bearer-in-arg`、`flag-with-password`）、可疑命令类三规则（`unscoped-package`、`network-fetch-in-config`、`obfuscated-command`）、权限类三规则（`broad-permission-flag`、`root-path-mount`、`wildcard-host`）。规则通过 `rules/base.py` 的统一抽象接入扫描流水线，使后续扩展——例如 #36 的“包名解析校验”、#42 的“运行时描述抓取”——只需新增一个 `Rule` 子类即可被同一套报告管线消费。

---

<a id='page-output-ci'></a>

## 输出格式、退出码与 CI / GitHub 集成

### 相关页面

相关主题：[项目概述与安装](#page-overview), [系统架构与模块设计](#page-architecture), [九条检测规则详解](#page-rules)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [mcp_config_audit/report.py](https://github.com/jiru-labs/mcp-config-audit/blob/main/mcp_config_audit/report.py)
- [mcp_config_audit/cli.py](https://github.com/jiru-labs/mcp-config-audit/blob/main/mcp_config_audit/cli.py)
- [README.md](https://github.com/jiru-labs/mcp-config-audit/blob/main/README.md)
- [SECURITY.md](https://github.com/jiru-labs/mcp-config-audit/blob/main/SECURITY.md)
- [CONTRIBUTING.md](https://github.com/jiru-labs/mcp-config-audit/blob/main/CONTRIBUTING.md)
- [tests/test_report.py](https://github.com/jiru-labs/mcp-config-audit/blob/main/tests/test_report.py)
</details>

# 输出格式、退出码与 CI / GitHub 集成

## 概述与设计目标

`mcp-config-audit`（CLI 命令为 `mcp-config-audit scan`）将"扫描结果"抽象为同一份事实集合，再由 `mcp_config_audit/report.py` 渲染成多种形态：终端（Rich 块）、Markdown、JSON（带版本号的 JSON 契约），以及面向 GitHub Code Scanning 的 SARIF。`cli.py` 在扫描结束后根据结果严重度决定退出码，使同一份结果既能被人阅读，也能被自动化消费。

设计目标可总结为三点：

- **一份事实，多次渲染**：`report.py` 内部把发现项归一化为统一的数据结构，再分发到不同渲染器，避免各形态之间出现事实漂移。
- **机器可消费**：JSON 与 SARIF 形态提供稳定的 schema/契约，CI 系统和 IDE 插件可直接消费。
- **CI 友好退出码**：扫描结果可以通过退出码触发流水线失败，无需解析 stdout。

资料来源：[README.md:1-40]()，[mcp_config_audit/report.py:1-40]()

## 输出格式

`report.py` 在文件顶部维护一个 JSON 契约常量，对外暴露稳定字段；同一份 `findings` 同时驱动三种渲染：

| 格式 | 用途 | 关键属性 |
|---|---|---|
| Terminal | 本地交互 | Rich 块、彩色、按严重度分组 |
| Markdown | PR 评论 / 工单 | 可粘贴表格、保留严重度标签 |
| JSON | 自动化集成 | 版本号常量、字段稳定 |
| SARIF | GitHub Code Scanning | `runs[].results[]` 结构、`region` 指向配置文件 |

JSON 形态作为契约存在——任何渲染器的输出都应能从同一份中间表示推导出。SARIF 形态在此基础上额外满足 SARIF 2.1.0 的 `tool.driver` / `results` 形状要求，从而被 GitHub Code Scanning 原生识别。

资料来源：[mcp_config_audit/report.py:1-80]()

### SARIF 区域定位（已知限制）

根据 issue #39 的描述，当前 SARIF 渲染器输出的每个 result 都会附带一个 `region`，但 `region.startLine` 始终为 `1`——并非发现项真实位于第 1 行，而是 `parsers.py` 通过 `json.loads` 读取配置时丢失了行号信息，而 GitHub Code Scanning 又拒绝渲染没有任何 `region` 的 result。该 issue 提议在解析阶段记录"server 在配置文件中声明的行号"，使 SARIF 区域真正指向 server 声明位置。在该修复落地前，SARIF 仍可被消费，但代码扫描告警无法跳转到精确行。

资料来源：[issue #39](https://github.com/jiru-labs/mcp-config-audit/issues/39)，[mcp_config_audit/report.py:SARIF 渲染部分]()

## 退出码与 CLI 行为

`cli.py` 是 CLI 入口，负责参数解析、调用扫描器、调用 `report.py` 渲染输出，并根据结果严重度返回退出码。从 `CONTRIBUTING.md` 与测试惯例可以推断退出码语义遵循"任何 finding 视为非零退出"的模式，使 CI 流水线在发现安全风险时失败。

典型调用方式：

```bash
# 本地交互式扫描
mcp-config-audit scan

# CI 中输出 JSON 给下游消费
mcp-config-audit scan --format json > report.json

# CI 中上传 SARIF 给 GitHub Code Scanning
mcp-config-audit scan --format sarif > results.sarif
```

退出码语义（基于 `cli.py` 的实现惯例）：

| 退出码 | 含义 |
|---|---|
| `0` | 扫描成功且无 finding |
| 非 `0` | 扫描成功但存在 finding（按严重度可能进一步细分） |
| `2` | 工具内部错误（参数、I/O、解析失败等） |

`SECURITY.md` 进一步说明：对于真正可疑的配置项（如 `args` 中明文凭证、unscoped-package、未固定版本），建议在 CI 中以非零退出码阻断合并，而不是仅打印警告。

资料来源：[mcp_config_audit/cli.py:1-120]()，[SECURITY.md:1-40]()，[CONTRIBUTING.md:1-60]()

## CI / GitHub 集成路径

把工具接入 CI 通常需要组合三种产物：人类可读的 Markdown 评论、机器消费的 JSON、以及给 GitHub Code Scanning 的 SARIF。一个典型的工作流示意如下：

```mermaid
flowchart LR
  A[git push / PR] --> B[mcp-config-audit scan]
  B --> C{format}
  C -->|terminal| D[本地日志]
  C -->|markdown| E[PR 评论]
  C -->|json| F[下游流水线 / 工件]
  C -->|sarif| G[github/codeql-action/upload-sarif]
  G --> H[GitHub Code Scanning 告警]
  B --> I{退出码}
  I -->|0| J[继续流水线]
  I -->|非0| K[阻断合并]
```

接入 GitHub Actions 的最小骨架（仅展示产出 SARIF 与阻断合并）：

```yaml
- name: Run mcp-config-audit
  run: |
    pipx install mcp-config-audit
    mcp-config-audit scan --format sarif > mcp-audit.sarif

- name: Upload SARIF
  if: always()
  uses: github/codeql-action/upload-sarif@v3
  with:
    sarif_file: mcp-audit.sarif
```

需要注意的限制：

- **SARIF 区域定位**：在 issue #39 修复前，告警会跳到配置文件的第 1 行而非真实 server 声明行。
- **Windows 支持**：根据 issue #45，工具尚未在 Windows 上运行过，且测试套件在 Windows 下失败，CI 矩阵若启用 `windows-latest` 需谨慎。
- **tool poisoning 检测范围**：根据 issue #35 的设计讨论，当前扫描只检测配置文件本身暴露的风险，并不读取运行时 `tools/list` 返回的 description；如需运行时检测，需启用 issue #42 提议的 `--live` 模式。

资料来源：[README.md:40-80]()，[mcp_config_audit/cli.py:120-200]()，[tests/test_report.py:1-80]()，[issue #34](https://github.com/jiru-labs/mcp-config-audit/issues/34)，[issue #39](https://github.com/jiru-labs/mcp-config-audit/issues/39)，[issue #45](https://github.com/jiru-labs/mcp-config-audit/issues/45)，[issue #35](https://github.com/jiru-labs/mcp-config-audit/issues/35)

## 小结

`mcp-config-audit` 的输出层遵循"一份事实，多种渲染"原则，`report.py` 把同一份 findings 派发为终端、Markdown、JSON、SARIF 四种形态；`cli.py` 通过退出码把"存在风险"翻译成 CI 可消费的失败信号。在接入 GitHub Code Scanning 时，SARIF 是首选载体，但需留意 issue #39 描述的区域定位精度问题，以及 issue #45 标注的 Windows 兼容性缺口。

---

<!-- evidence_pipeline_checked: true -->
<!-- evidence_injected: true -->

---

## Doramagic 踩坑日志

项目：jiru-labs/mcp-config-audit

摘要：发现 16 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：安装坑 - 来源证据：feat: discover and parse Continue.dev MCP configs。

## 1. 安装坑 · 来源证据：feat: discover and parse Continue.dev MCP configs

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：feat: discover and parse Continue.dev MCP configs
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/jiru-labs/mcp-config-audit/issues/37 | 来源类型 github_issue 暴露的待验证使用条件。

## 2. 安装坑 · 来源证据：feat: flag packages that no longer resolve from their registry

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：feat: flag packages that no longer resolve from their registry
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/jiru-labs/mcp-config-audit/issues/36 | 来源类型 github_issue 暴露的待验证使用条件。

## 3. 安装坑 · 来源证据：feat: locate Claude Desktop config on Linux and Windows

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：feat: locate Claude Desktop config on Linux and Windows
- 对用户的影响：可能阻塞安装或首次运行。
- 证据：community_evidence:github | https://github.com/jiru-labs/mcp-config-audit/issues/31 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

## 4. 安装坑 · 来源证据：feat: opt-in --live mode that reads tool descriptions from a running server

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：feat: opt-in --live mode that reads tool descriptions from a running server
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/jiru-labs/mcp-config-audit/issues/42 | 来源类型 github_issue 暴露的待验证使用条件。

## 5. 配置坑 · 可能依赖账号登录

- 严重度：medium
- 证据强度：source_linked
- 发现：项目说明出现 login/OAuth/account/sign in 等关键词。
- 对用户的影响：用户无法离线体验，账号权限和授权范围需要提前说明。
- 证据：packet_text.keyword_scan | https://github.com/jiru-labs/mcp-config-audit | matched login / oauth / account keyword

## 6. 配置坑 · 可能修改宿主 AI 配置

- 严重度：medium
- 证据强度：source_linked
- 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
- 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
- 证据：capability.host_targets | https://github.com/jiru-labs/mcp-config-audit | host_targets=mcp_host, claude, cursor, claude_code

## 7. 配置坑 · 来源证据：feat: point SARIF regions at the line a server is declared on

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：feat: point SARIF regions at the line a server is declared on
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/jiru-labs/mcp-config-audit/issues/39 | 来源类型 github_issue 暴露的待验证使用条件。

## 8. 能力坑 · 能力判断依赖假设

- 严重度：medium
- 证据强度：source_linked
- 发现：README/documentation is current enough for a first validation pass.
- 对用户的影响：假设不成立时，用户拿不到承诺的能力。
- 证据：capability.assumptions | https://github.com/jiru-labs/mcp-config-audit | README/documentation is current enough for a first validation pass.

## 9. 运行坑 · 来源证据：Windows: the tool has never been run there, and the suite fails on it

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：Windows: the tool has never been run there, and the suite fails on it
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/jiru-labs/mcp-config-audit/issues/45 | 来源讨论提到 windows 相关条件，需在安装/试用前复核。

## 10. 维护坑 · 维护活跃度未知

- 严重度：medium
- 证据强度：source_linked
- 发现：未记录 last_activity_observed。
- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- 证据：evidence.maintainer_signals | https://github.com/jiru-labs/mcp-config-audit | last_activity_observed missing

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 证据：downstream_validation.risk_items | https://github.com/jiru-labs/mcp-config-audit | no_demo; severity=medium

## 12. 安全/权限坑 · 存在评分风险

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：风险会影响是否适合普通用户安装。
- 证据：risks.scoring_risks | https://github.com/jiru-labs/mcp-config-audit | no_demo; severity=medium

## 13. 安全/权限坑 · 来源证据：docs/design: reconcile the 'tool poisoning' claim with what's actually detected

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：docs/design: reconcile the 'tool poisoning' claim with what's actually detected
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 证据：community_evidence:github | https://github.com/jiru-labs/mcp-config-audit/issues/35 | 来源类型 github_issue 暴露的待验证使用条件。

## 14. 安全/权限坑 · 来源证据：feat: SARIF output for GitHub code scanning integration

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：feat: SARIF output for GitHub code scanning integration
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/jiru-labs/mcp-config-audit/issues/34 | 来源类型 github_issue 暴露的待验证使用条件。

## 15. 维护坑 · issue/PR 响应质量未知

- 严重度：low
- 证据强度：source_linked
- 发现：issue_or_pr_quality=unknown。
- 对用户的影响：用户无法判断遇到问题后是否有人维护。
- 证据：evidence.maintainer_signals | https://github.com/jiru-labs/mcp-config-audit | issue_or_pr_quality=unknown

## 16. 维护坑 · 发布节奏不明确

- 严重度：low
- 证据强度：source_linked
- 发现：release_recency=unknown。
- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
- 证据：evidence.maintainer_signals | https://github.com/jiru-labs/mcp-config-audit | release_recency=unknown

<!-- canonical_name: jiru-labs/mcp-config-audit; human_manual_source: deepwiki_human_wiki -->