Quality Guardian

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).

License: MIT Node MCP Protocol Transport Status

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 orders MUST include tenant_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