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 18+ 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"]
    }
  }
}

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