Quality Guardian MCP
MCP server aggregating Semgrep, PHPStan, Knip, PHPMetrics and Deptrac into a unified code-quality gate for AI agents (Claude Code, Cursor, Windsurf). Baseline-aware, session-level digest, cross-stack dead code.
Ask AI about Quality Guardian MCP
Powered by Claude Β· Grounded in docs
I know everything about Quality Guardian MCP. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
Quality Guardian MCP
A Model Context Protocol server that aggregates Semgrep, PHPStan, Knip, PHPMetrics, Deptrac, and custom detectors into a single, baseline-aware quality gate for AI coding agents (Claude Code, Cursor, Windsurf).
Built for teams whose AI agents write code. Every edit lands in a codebase that already has 10,000 static-analysis findings β Quality Guardian keeps the agent's attention on what they just changed, not the legacy baseline.
Table of Contents
- Why Quality Guardian
- Features
- Installation
- Configuration
- MCP Integration
- Architecture
- Custom Rules
- Comparison
- FAQ
- Contributing
- Security
- License
Why Quality Guardian
Every modern code-quality tool is either:
- Single-purpose (Semgrep, PHPStan, Knip, PHPMetrics, Deptrac) β great alone, but the agent has to call each one separately, re-implement baseline logic, and glue the results together.
- Heavyweight platforms (SonarQube, DeepSource, Codacy, CodeRabbit) β excellent analysis, but they live outside the agent's loop. The agent only sees findings after a PR is opened, by which point the wrong code is already written.
Quality Guardian is the aggregator layer between the agent and the tools. One MCP server, one baseline, one digest, one set of tools the agent calls naturally.
Features
| Capability | Quality Guardian | Notes |
|---|---|---|
| Aggregator MCP (Semgrep + PHPStan + Knip + PHPMetrics + Deptrac in one server) | β | Existing MCPs are single-tool |
| SessionStart digest as System Reminder for Claude Code | β | Agent sees CRITICAL=N at session start |
| Cross-stack dead code: source + DB columns + i18n keys + CSS classes | β | Existing tools are source-only |
| Baseline-aware "new code only" gate | β | Agent sees only new violations, not legacy |
| Architect β Quality bridge for multi-agent workflows | β | W5 β scoped findings per logical module |
Generic + domain rules separation (rules/generic/ + rules/your-project/) | β | Ship templates, keep customisation local |
| Zero SaaS, zero cloud, zero PR round-trip | β | Runs on your machine / CI / localhost |
MCP tools exposed to the agent
| Tool | When the agent uses it |
|---|---|
qg_digest | At session start β "what's broken right now?" |
qg_scan_file | Before editing a file β "is this module already dirty?" |
qg_scan_module | Module-scoped findings via an architect-reader map |
qg_scan_full | Re-scan on demand (expensive β prefer cron) |
qg_baseline_status | "Are we improving or regressing?" |
qg_list_open | Filter open findings by severity / file prefix |
qg_info | Server health + enabled analyzers |
Plus 6 REST endpoints for Admin UI consumption: /api/stats, /api/violations, /api/runs, /api/trends, /api/resolve, /api/snooze.
Installation
Prerequisites
- Node.js β₯ 20
- Python 3.10+ with
pipx(for Semgrep MCP) - PHP 8.x with
composer(optional β for PHPStan / PHPMetrics / Deptrac collectors)
Quick start
git clone https://github.com/tehprof/quality-guardian-mcp.git
cd quality-guardian-mcp
# 1. Install Node deps
npm install
# 2. Install bundled MCP engines (once)
pipx install semgrep-mcp
# 3. Configure for your project
cp config.default.json config.local.json
# edit paths in config.local.json
# 4. Seed baseline (accepts current findings as tech-debt)
npm run baseline:seed
# 5. Start the server
npm start # stdio (Claude Code)
# or
QG_TRANSPORT=http npm start # HTTP (Admin UI / remote clients)
See docs/quickstart.md for a 5-minute walk-through on a sample project.
Configuration
Two-file layering:
config.default.json(tracked) β generic defaults that ship with the repo.config.local.json(gitignored) β your project-specific overrides: paths, enabled analyzers, custom-detector inputs.
Minimal 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\\(['\"]([^'\"]+)['\"]"
}
}
}
Full reference in docs/architecture.md.
MCP Integration
Claude Code (stdio β recommended)
Add to ~/.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" }
}
}
}
Restart Claude Code. The mcp__quality-guardian__* tools become available.
SessionStart digest hook
Drops a one-line quality summary into the agent's context at every session start. See docs/mcp-integration.md.
Cursor / Windsurf / other clients
Same stdio config β all three read MCP server definitions the same way. Full instructions in docs/mcp-integration.md.
Architecture
βββββββββββββββββββββββββββββ
β 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)β
ββββββββββββββββββββββββββββββββββββββ
Full design in docs/architecture.md.
Custom Rules
Ship a rules/<your-project>/ directory with:
- Semgrep YAML files for domain invariants ("every query against
ordersMUST includetenant_id") - i18n file globs
- DB schema sources
- CSS class whitelists (for dynamic selectors that detectors would otherwise flag)
Step-by-step guide: docs/custom-rules.md.
Comparison
| Quality Guardian | SonarQube | DeepSource | CodeRabbit | Single-tool MCPs | |
|---|---|---|---|---|---|
| Runs in agent loop (MCP) | β | β | β | β | β |
| Aggregates 5+ tools | β | β | β | β | β |
| Baseline-aware new-code-only gate | β | β | β | β οΈ | β |
| Cross-stack dead code (DB/i18n/CSS) | β | β | β | β | β |
| Self-hosted, zero SaaS | β | β | β | β | β |
| SessionStart digest for AI agents | β | β | β | β | β |
| LOC | ~2,500 | ~500k | SaaS | SaaS | varies |
FAQ
Does it work without the custom detectors? Yes. Semgrep + PHPStan + Knip + PHPMetrics + Deptrac alone already produce a useful digest. Custom detectors are opt-in.
What's the runtime cost?
Full scan on a ~3,000-file PHP + JS codebase takes ~65 seconds. Incremental qg_scan_file is < 1 second. Agent calls qg_digest at session start β that's a DB read, instant.
Does it write anything to my repo?
No. All state lives in data/quality.db (gitignored by default). Custom rules in rules/<your-project>/ you commit if you want.
What about language X?
W1-W6 ship PHP + JS / TS support. Adding a language = adding a collector (50-100 lines wrapping the upstream tool's JSON output). See docs/custom-rules.md#adding-a-collector.
Can I use this in CI?
Yes. npm run scan produces a run in quality.db; npm run digest -- --format=json prints findings. Combine with git diff to gate PRs on new findings.
Is the baseline mechanism the same as SonarQube's "new code only"?
Same idea, much smaller implementation (~200 LOC vs. SonarQube's Java service). Fingerprint is sha256(tool|rule|file|line|msg) β stable across runs, insensitive to line shifts within Β±3 lines.
Contributing
Pull requests welcome. For non-trivial changes, open an issue first. See CONTRIBUTING.md.
Security
Found a vulnerability? See SECURITY.md for disclosure policy. Do not open a public issue for security matters.
License
MIT β see LICENSE.
Built on Model Context Protocol Β· Maintained by TehProf.kz
