Quality Guardian Mcp

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

[](LICENSE) [](package.json) [](https://modelcontextprotocol.io) [](docs/architecture.md) [](CHANGELOG.md)

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](#why-quality-guardian)
• [Features](#features)
• [Installation](#installation)
• [Configuration](#configuration)
• [MCP Integration](#mcp-integration)
• [Architecture](#architecture)
• [Custom Rules](#custom-rules)
• [Comparison](#comparison)
• [FAQ](#faq)
• [Contributing](#contributing)
• [Security](#security)
• [License](#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](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](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](docs/mcp-integration.md#session-start-hook).

Cursor / Windsurf / other clients

Same stdio config — all three read MCP server definitions the same way. Full instructions in [docs/mcp-integration.md](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](docs/architecture.md).

Custom Rules

Ship a rules// 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](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 /` 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](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](CONTRIBUTING.md).

Security

Found a vulnerability? See [SECURITY.md](SECURITY.md) for disclosure policy. Do not open a public issue for security matters.

License

MIT — see [LICENSE](LICENSE).

---

Built on Model Context Protocol · Maintained by TehProf.kz

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: tehprof
• Source: tehprof/quality-guardian-mcp
• License: MIT
• Homepage: https://github.com/ilay25-coder/quality-guardian-mcp

Install and usage instructions live in the source repository linked above.