AI Quality Gate

AI Quality Gate

MCP Server for AI code quality automation.

---

What It Does

AI writes code → calls quality_fix → Server fixes what it can → Reports remaining issues to AI.

Hybrid Approach:

• Phase 1: ESLint + 627 rules + Prettier (~2-8s, always runs)
• Phase 2: SonarQube Server (~30-60s, optional)

Important: ESLint vs Prettier

ESLint rules are controlled by MCP for consistent quality gates.

Prettier uses project's config so formatting matches project preferences.

Phase 1 Rule Coverage:

---

Installation

Prerequisites

• Node.js 20.10+ or 21.1+ on your PATH (node -v).
• Cursor, Antigravity, OpenCode (or another MCP-capable editor) with MCP enabled.

Project root is auto-detected when PROJECT_ROOT is omitted: the server walks up from the MCP process working directory until it finds package.json or tsconfig.json. Set PROJECT_ROOT in env only to analyze a different tree than the inferred root.

---

MCP configuration (Cursor)

Open Settings → Tools & MCP → Edit (user mcp.json). Add one server block; the examples below match .cursor/mcp.json.example (JSONC with comments — if your editor rejects comments, copy the JSON blocks below only).

Server name vs tool name: The key under mcpServers (e.g. "ai-quality-gate") is only the label for that connection in Cursor. The MCP tool your agent calls is always quality_fix — that name is fixed by this package and is separate from the server key and from ai-quality-gate.

A) Recommended: npx (no global install)

Always runs the published package; good for teams and CI-like setups.

{

"mcpServers": { "ai-quality-gate": { "command": "npx", "args": ["-y", "ai-quality-gate"] } } }

B) Optional: global npm install

After npm i -g ai-quality-gate, the ai-quality-gate binary is on your PATH:

{

"mcpServers": { "ai-quality-gate": { "command": "ai-quality-gate", "args": [] } } }

C) SonarQube (Phase 2)

Requires a running SonarQube instance, sonar-scanner available (see SonarQube Setup), and all three variables below. Phase 1 still runs first.

{

"mcpServers": { "ai-quality-gate": { "command": "npx", "args": ["-y", "ai-quality-gate"], "env": { "SONAR_HOST_URL": "http://localhost:9000", "SONAR_TOKEN": "your_sonar_token", "SONAR_PROJECT_KEY": "your_project_key" } } } }

D) Optional environment variables (any server)

Add an "env" object when you need overrides. Merge order for config is defaults → `.quality-gate.yaml` / `.quality-gate.json` → environment variables.

---

MCP configuration

Cursor, Antigravity, etc..

{

"mcpServers": { "ai-quality-gate": { "command": "npx", "args": ["-y", "ai-quality-gate"] } } }

(OpenCode)

Create or edit OpenCode config (typically ~/.config/opencode/opencode.json or project-level config):

{

"$schema": "https://opencode.ai/config.json", "mcp": { "ai-quality-gate": { "type": "local", "enabled": true, "command": ["npx", "-y", "ai-quality-gate"] } } }

Environment variables can be added under the server config if needed (see C) SonarQube (Phase 2) above).

---

Local development (this repository)

To dogfood or contribute:

1. `yarn build` — generates dist/server.js.
2. Point MCP at the built file (absolute paths):

{

"mcpServers": { "ai-quality-gate-dev": { "command": "node", "args": ["/ABSOLUTE/PATH/TO/ai-quality-gate/dist/server.js"] } } }

1. Reload MCP. Use env.PROJECT_ROOT only if the repo you analyze differs from the inferred root.

---

2. Add AI Rule

Settings → Rules and Commands → Add Rule:

After every code change, before telling the user "done",

AI must call the quality_fix MCP tool. This is mandatory.

3. Use It

AI writes code → calls quality_fix → Fixes errors → "Done ✅"

---

CLI: interactive config (--setup)

The interactive wizard creates or updates .quality-gate.yaml without hand-editing: it walks you through project root, optional SonarQube (host URL + project key; token is not saved to disk — use SONAR_TOKEN in your environment), which Phase 1 tools to enable (ESLint, curly-brace / arrow AST fixers, Prettier, JSON validator), timeouts, and i18n rules. The generated file includes a fixers: block you can adjust later.

After yarn build (or install from npm), run from the target project (or any path under it):

node dist/server.js --setup

PROJECT_ROOT is inferred when unset (see MCP configuration). Use the same entrypoint as the MCP server (node dist/server.js or npx ai-quality-gate); only the --setup flag switches to wizard mode. Answer prompts in the terminal; on success you get a ready-to-use config next to your project root.

Other CLI modes: --check (read-only Phase 1), --fix (default behavior when using CLI quality run), --phase1-only, --phase2-only — see docs/DEVELOPMENT.md.

---

Optional: SonarQube Server (Phase 2)

Configure Sonar env in MCP as in [C) SonarQube (Phase 2)](#c-sonarqube-phase-2) above, or copy from .cursor/mcp.json.example. You need `sonar-scanner` on your machine for analysis (see below).

SonarQube Setup

Docker (Recommended)

# Start SonarQube

docker run -d --name sonarqube -p 9000:9000 sonarqube:community

First login: admin/admin → change password

http://localhost:9000

Docker Compose

# docker-compose.yml

version: '3' services: sonarqube: image: sonarqube:community ports:

• '9000:9000' volumes:
• sonarqube_data:/opt/sonarqube/data
• sonarqube_logs:/opt/sonarqube/logs
• sonarqube_extensions:/opt/sonarqube/extensions

volumes: sonarqube_data: sonarqube_logs: sonarqube_extensions:

docker-compose up -d

Creating SonarQube Token

1. http://localhost:9000 → Login (admin)
2. My Account → Security → Generate Tokens
3. Select token type: Global Analysis Token
4. Copy token → use as SONAR_TOKEN

Installing sonar-scanner

For custom path: SONAR_SCANNER_PATH env var

---

Configuration

Optional files (discovered by walking up from the inferred project root — same algorithm as package.json / tsconfig.json — or from PROJECT_ROOT when set): `.quality-gate.yaml` (preferred) or `.quality-gate.json`. Same fields as environment variables (camelCase); you may nest Sonar settings under sonar: { hostUrl, token, projectKey, scannerPath }.

Merge order: defaults → config file → environment variables (ENV wins on conflicts).

Set `QUALITY_GATE_CONFIG` to an explicit path to skip discovery.

Custom rules (customRules)

Optional line-based regex checks on lintable files (Phase 1). Each match is reported as an issue with rule set to custom: (and included in quality_fix remaining). Example:

customRules:

• id: no-console message: 'Console.log is not allowed' pattern: 'console\\.log\\(' severity: error
• id: no-debugger message: 'Debugger statement found' pattern: 'debugger' severity: warning

Patterns use JavaScript RegExp source (escape backslashes as in YAML strings). An invalid pattern is skipped, and says so in warnings.

JSON validator & i18n locale files

When `fixers.jsonValidator` is enabled and you pass JSON paths that match locale patterns (for example locales/en.json / locales/tr.json), the tool compares keys across those files.

• Syntax errors, invalid UTF-8 BOM, etc. → reported as issues and fail Phase 1 / quality_fix until fixed.
• Missing or extra keys between locale files → collected as `i18nIssues` in the validator result and printed as warnings on stderr during Phase 1. They do not set passed: false and do not block the gate.

Treat i18nIssues as advisory unless you add your own CI check on top.

---

Environment Variables

All variables are optional unless you use Phase 2, which requires `SONAR_HOST_URL`, `SONAR_TOKEN`, and `SONAR_PROJECT_KEY` together.

| Variable | Description