tehprof/quality-guardian-mcp

# Quality Guardian MCP [](LICENSE) [](package.json) [](https://modelcontextprotocol.io) [](docs/architecture.md) [](CHANGELOG.md) 为团队构建，其 AI 代理编写代码。每个编辑都会提交到已经存在 10,000 个静态分析发现的代码库 — Quality Guardian 让代理的关注点集中在 **他们刚刚修改的内容** 上，而不是遗留基线。 ## 目录 - [为什么选择 Quality Guardian](#why-quality-guardian) - [功能特性](#features) - [安装](#installation) - [配置](#configuration) - [MCP 集成](#mcp-integration) - [架构](#architecture) - [自定义规则](#custom-rules) - [对比](#comparison) - [常见问题](#faq) - [贡献](#contributing) - [安全](#security) - [许可证](#license) ## 为什么选择 Quality Guardian 每一个现代代码质量工具要么： - **单一用途**（Semgrep、PHPStan、Knip、PHPMetrics、Deptrac）——单独使用时很棒，但代理必须分别调用每个工具，重新实现基线逻辑，并将结果粘合在一起。 - **重量级平台**（SonarQube、DeepSource、Codacy、CodeRabbit）——分析出色，但它们存在于代理的循环之外。代理只在 PR 提交后看到问题，此时错误代码已经写好了。 Quality Guardian 是代理与工具之间的 **聚合层**。一个 MCP 服务器，一个基线，一个摘要，一套代理自然调用的工具。 ## 功能特性 | 能力 | Quality Guardian | 说明 | |-----------|:---:|-------| | 聚合 MCP（Semgrep + PHPStan + Knip + PHPMetrics + Deptrac 集成在一个服务器） | ✅ | 现有 MCP 均为单一工具 | | SessionStart 摘要作为 Claude Code 的系统提醒 | ✅ | 代理在会话启动时看到 `CRITICAL=N` | | 跨栈死代码检测：源码 + **数据库列** + **i18n 键** + **CSS 类** | ✅ | 现有工具仅支持源码 | | 基线感知“仅新代码”门禁 | ✅ | 代理仅看到 *新* 违规，而非遗留问题 | | 架构师 ↔ 质量网关，支持多代理工作流 | ✅ | W5 — 按逻辑模块划分发现范围 | | 通用与领域规则分离（`rules/generic/` + `rules/your-project/`） | ✅ | 提交模板，保持本地化定制 | | 零 SaaS、零云端、零 PR 往返 | ✅ | 在本地机器 / CI / localhost 运行 | ### 暴露给代理的 MCP 工具 | 工具 | 代理使用时机 | |------|------------------------| | `qg_digest` | 会话启动时 — “当前有哪些问题？” | | `qg_scan_file` | 编辑文件前 — “该模块是否已脏？” | | `qg_scan_module` | 通过架构读取映射进行模块级发现 | | `qg_scan_full` | 按需重新扫描（开销较大 — 建议使用定时任务） | | `qg_baseline_status` | “我们是在改进还是退化？” | | `qg_list_open` | 按严重程度 / 文件前缀过滤开放问题 | | `qg_info` | 服务器健康状态 + 已启用的分析器 | 此外还提供 **6 个 REST 端点**，供管理 UI 使用：`/api/stats`、`/api/violations`、`/api/runs`、`/api/trends`、`/api/resolve`、`/api/snooze`。 ## 安装 ### 先决条件 - **Node.js ≥ 20** - **Python 3.10+** 并安装 `pipx`（用于 Semgrep MCP） - **PHP 8.x** 并安装 `composer`（可选 — 用于 PHPStan / PHPMetrics / Deptrac 收集器） ### 快速开始 ``` git clone https://github.com/tehprof/quality-guardian-mcp.git cd quality-guardian-mcp # 1. 安装 Node 依赖 npm install # 2. 安装捆绑的 MCP 引擎（一次） pipx install semgrep-mcp # 3. 为项目配置 cp config.default.json config.local.json # 编辑 config.local.json 中的路径 # 4. 播种基线（将当前发现作为技术债务接受） npm run baseline:seed # 5. 启动服务器 npm start # stdio (Claude Code) # 或 QG_TRANSPORT=http npm start # HTTP (Admin UI / remote clients) ``` 请参阅 [`docs/quickstart.md`](docs/quickstart.md) 获取在示例项目中的 5 分钟入门指南。 ## 配置 采用双层文件配置： - **`config.default.json`**（已跟踪） — 随仓库分发的通用默认值。 - **`config.local.json`**（忽略于 git） — 项目特定覆盖：路径、启用的分析器、自定义检测器输入。 最小化 `config.local.json` 示例： ``` { "scan": { "rootPath": "/path/to/your/project", "includeGlobs": ["**/*.php", "**/*.js", "**/*.ts"], "excludeGlobs": ["**/vendor/**", "**/node_modules/**"] }, "tools": { "phpstan": { "level": 4 } }, "customDetectors": { "deadI18nKeys": { "enabled": true, "i18nFiles": ["./locale/en.js", "./locale/fr.js"], "usagePattern": "t\\(['\"]([^'\"]+)['\"]" } } } ``` 完整参考请查阅 [`docs/architecture.md`](docs/architecture.md)。 ## MCP 集成 ### Claude Code（stdio — 推荐） 添加到 `~/.claude.json`： ``` { "mcpServers": { "quality-guardian": { "type": "stdio", "command": "node", "args": ["/absolute/path/to/quality-guardian-mcp/src/index.js"], "env": { "QG_CONFIG": "/absolute/path/to/config.local.json" } } } } ``` 重启 Claude Code。`mcp__quality-guardian__*` 工具将变为可用。 ### SessionStart 摘要钩子 在每个会话启动时将一行质量摘要注入代理上下文。参见 [`docs/mcp-integration.md`](docs/mcp-integration.md#session-start-hook)。 ### Cursor / Windsurf / 其他客户端 相同的 `stdio` 配置 — 三者读取 MCP 服务器定义的方式一致。完整说明请参考 [`docs/mcp-integration.md`](docs/mcp-integration.md)。 ## 架构 ``` ┌───────────────────────────┐ │ Claude Code / Cursor / │ │ any MCP-compatible agent │ └────────────┬──────────────┘ │ stdio / http ┌─────────────────▼──────────────────┐ │ quality-guardian-mcp (this) │ │ core/server.js — tool registry │ │ core/baseline.js — quality.db │ │ core/digest.js — SessionStart │ └─────────────────┬──────────────────┘ │ spawns / IPC ┌───────────────┬───────────────┬────┴─────┬───────────────┬───────────────┐ ▼ ▼ ▼ ▼ ▼ ▼ Semgrep MCP PHPStan MCP Knip jscpd PHPMetrics Deptrac (pipx) (composer) (npm) (npm) (phar) (phar) │ ┌─────────────────▼──────────────────┐ │ Custom detectors (our value-add) │ │ - dead DB columns │ │ - dead i18n keys (cross-stack) │ │ - dead CSS classes │ │ - domain invariants (Semgrep YAML)│ └────────────────────────────────────┘ ``` 完整设计请查阅 [`docs/architecture.md`](docs/architecture.md)。 ## 自定义规则 提供一个 `rules//` 目录，包含： - 用于领域不变量的 Semgrep YAML 文件（“对 `orders` 的每个查询必须包含 `tenant_id`”） - i18n 文件通配符 - 数据库架构源 - CSS 类白名单（用于检测器可能误报的动态选择器） 分步指南： [`docs/custom-rules.md`](docs/custom-rules.md)。 ## 对比 | | Quality Guardian | SonarQube | DeepSource | CodeRabbit | 单工具 MCP | |-|:-:|:-:|:-:|:-:|:-:| | 在代理循环中运行（MCP） | ✅ | ❌ | ❌ | ❌ | ✅ | | 聚合 5+ 工具 | ✅ | ✅ | ✅ | ✅ | ❌ | | 基线感知“仅新代码”门禁 | ✅ | ✅ | ✅ | ⚠️ | ❌ | | 跨栈死代码（数据库/i18n/CSS） | ✅ | ❌ | ❌ | ❌ | ❌ | | 自我托管，零 SaaS | ✅ | ✅ | ❌ | ❌ | ✅ | | 为 AI 代理提供 SessionStart 摘要 | ✅ | ❌ | ❌ | ❌ | ❌ | | 代码行数 | ~2,500 | ~500k | SaaS | SaaS | 各有不同 | ## 常见问题 **没有自定义检测器也能工作吗？** 可以。Semgrep + PHPStan + Knip + PHPMetrics + Deptrac 已能生成有用的摘要。自定义检测器是可选增强。 **运行时开销是多少？** 在约 3,000 个文件的 PHP + JS 代码库上完整扫描约需 65 秒。增量 `qg_scan_file` 小于 1 秒。代理在会话启动时调用 `qg_digest` — 这是数据库读取，即时完成。 **会向我的仓库写入内容吗？** 不会。所有状态保存在 `data/quality.db` 中（默认忽略于 git）。自定义规则在 `rules//` 中，按需提交。 **支持哪些语言？** W1-W6 支持 PHP + JS / TypeScript。添加语言 = 添加收集器（50-100 行代码包装上游工具的 JSON 输出）。参见 [`docs/custom-rules.md#adding-a-collector`](https://img.shields.io/badge/transport-stdio%20%7C%20HTTP-green)。 **能在 CI 中使用吗？** 可以。`npm run scan` 在 `quality.db` 中生成一次运行；`npm run digest -- --format=json` 打印发现结果。结合 `git diff` 可在 PR 上基于新发现进行门禁控制。 **基线机制与 SonarQube 的“仅新代码”相同吗？** 思路相同，但实现更轻量（约 200 行代码 vs. SonarQube 的 Java 服务）。指纹为 `sha256(tool|rule|file|line|msg)` — 在 ±3 行内的代码位移下保持稳定，跨运行一致。 ## 安全 发现漏洞？请参考 [`SECURITY.md`](SECURITY.md) 了解披露策略。**不要**对安全问题公开创建 Issue。 ## 许可证 MIT — 参见 [LICENSE](LICENSE)。 **基于** [Model Context Protocol](https://modelcontextprotocol.io) · 维护者 [TehProf.kz](https://tehprof.kz)

标签：AI编程助手, AI辅助开发, Claude Code, Cursor, Deptrac, GNU通用公共许可证, Knip, MCP服务器, MITM代理, Node.js, PHPMetrics, PHPStan, PHP质量分析, Semgrep, SOC Prime, Windsurf, WordPress安全扫描, 云安全监控, 代码健康, 代码分析, 代码审查, 代码治理, 代码聚合, 代码质量平台, 代码质量门禁, 会话级摘要, 凭证管理, 基线感知, 开发工具, 开源框架, 持续集成, 跨栈死代码检测, 软件质量保障, 逆向工具, 静态分析