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

Tool	Source	Config
ESLint	Project's config (if exists) or MCP's embedded	`.eslintrc.` / `eslint.config.` / MCP embedded
Prettier	Project's own	Project's `prettier.config.mjs`

ESLint rules are controlled by MCP for consistent quality gates. Prettier uses project's config so formatting matches project preferences.

Phase 1 Rule Coverage:

Plugin	Rules	Description
SonarJS	201	Security, bugs, code smells
Unicorn	127	Modern JS best practices
ESLint Core	108	JavaScript fundamentals
TypeScript-ESLint	99	TypeScript-specific rules
RegExp	60	Regex best practices
Import	11	Import/export rules
Promise	10	Async/await best practices
Node.js (n)	9	Node.js specific rules
Unused Imports	2	Auto-remove unused imports
Total	627

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.

Variable	When to set
`QUALITY_GATE_CONFIG`	Absolute path to a specific `.quality-gate.yaml` or `.quality-gate.json` (skips walking directories).
`PROJECT_ROOT`	Force project root if auto-detection is wrong for your layout.
`SONAR_HOST_URL`	SonarQube server URL (with Phase 2).
`SONAR_TOKEN`	SonarQube token (with Phase 2).
`SONAR_PROJECT_KEY`	SonarQube project key (with Phase 2).
`SONAR_SCANNER_PATH`	Full path to `sonar-scanner` if not on `PATH`.
`PHASE1_TIMEOUT`	Phase 1 timeout (ms), default `30000`.
`PHASE2_TIMEOUT`	Phase 2 timeout (ms), default `300000`.
`ENABLE_I18N_RULES`	`true` / `false` — stricter JSX literal checks for i18n projects.

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:

yarn build — generates dist/server.js.
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"]
    }
  }
}

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

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

Installing sonar-scanner

Platform	Method	Command
Windows	npm (global)	`npm install -g sonarqube-scanner`
Windows	Chocolatey	`choco install sonar-scanner`
macOS	npm (global)	`npm install -g sonarqube-scanner`
macOS	Homebrew	`brew install sonar-scanner`
Linux	npm (global)	`npm install -g sonarqube-scanner`
Docker	Container	`docker run sonarsource/sonar-scanner-cli`

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:<id> (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). Invalid patterns are skipped at runtime with a log line.

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	Example
`QUALITY_GATE_CONFIG`	Absolute path to a `.quality-gate.yaml` or `.quality-gate.json` file. Skips walking parent directories for config discovery.	`/app/ci/quality-gate.yaml`
`PROJECT_ROOT`	Override detected project root. Default: walk up from the process cwd until `package.json` or `tsconfig.json` is found.	`/Users/me/my-repo`
`SONAR_HOST_URL`	SonarQube server base URL (Phase 2).	`http://localhost:9000`
`SONAR_TOKEN`	SonarQube authentication token (Phase 2). Prefer env / secret store; avoid committing.	`sqa_xxx...`
`SONAR_PROJECT_KEY`	SonarQube project key (Phase 2).	`my-project`
`SONAR_SCANNER_PATH`	Full path to the `sonar-scanner` executable if it is not on `PATH`.	`/opt/sonar-scanner/bin/sonar-scanner`
`PHASE1_TIMEOUT`	Phase 1 subprocess timeout in milliseconds.	`30000` (default)
`PHASE2_TIMEOUT`	Phase 2 (Sonar) timeout in milliseconds.	`300000` (default)
`ENABLE_I18N_RULES`	Set to `true` to enable ESLint rules that flag raw string literals in JSX (for i18n-heavy apps).	`false` (default)

Auto-Fix

Phase 1 automatically fixes these issues:

ESLint Auto-Fix (~100+ rules)

// var → const/let
var x = 1        →  const x = 1

// forEach → for...of (unicorn/no-array-for-each)
arr.forEach(x => f(x))  →  for (const x of arr) f(x)

// Nested ternary → extracted (unicorn/no-nested-ternary)
a ? b : c ? d : e  →  const temp = c ? d : e; a ? b : temp

// Unused imports removed
import { unused } from 'x'  →  (removed)

// Type imports (consistent-type-imports)
import { Type } from 'x'  →  import type { Type } from 'x'

// Optional chain (prefer-optional-chain)
a && a.b && a.b.c  →  a?.b?.c

// Regex optimization (regexp/*)
/[0-9]/  →  /\d/

AST Auto-Fix

// Remove unnecessary curly braces (single-line if)
if (x) { return true }  →  if (x) return true

Prettier Formatting

After ESLint fixes, Prettier runs to ensure consistent formatting:

// ESLint removes braces but leaves awkward format:
if (x) return true

// Prettier fixes to single line:
if (x) return true

Note: Prettier uses project's config, not MCP's.

Everything else: Reported to AI, AI fixes it.

API

Tool: `quality_fix`

// Input
{
  files: string[] // File paths to check
}

// Output
{
  phase: "local" | "server" | "complete",
  success: boolean,
  message: string,
  fixed: {
    eslint: number,          // ESLint auto-fixes
    curlyBraces: number,   // AST: single-statement if braces
    singleLineArrow: number, // AST: arrow body style
    prettier: number,      // Prettier formatting
    json: number           // JSON validation passes counted
  },
  remaining: Issue[],
  timing: {
    phase1: string,
    phase2?: string,
    total: string
  }
}

Feature Flags

`ENABLE_I18N_RULES`

For projects with internationalization (i18n), enable literal string detection:

{
  "env": {
    "ENABLE_I18N_RULES": "true"
  }
}

When enabled:

// ⚠️ Warning
<h1>Hello World</h1>

// ✅ OK
<h1>{t('hello')}</h1>

Troubleshooting

MCP: `quality_fix` does not appear

Node.js 18+ — run node -v and npx --version.
Reload Cursor after editing mcp.json (or use the MCP refresh control).
JSON — the file must be valid JSON (no trailing commas). Copy from the MCP configuration section if unsure.
Global install — if you use "command": "ai-quality-gate", run npm i -g ai-quality-gate once so the binary exists.

Windows

"npx not found" error:

# Node.js must be in PATH
# Check in PowerShell:
where.exe npx

Permission denied:

# Run PowerShell as Administrator

macOS / Linux

"Permission denied" error:

# Fix npm global directory
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrc
source ~/.zshrc

"sonar-scanner not found" error:

# Install via Homebrew
brew install sonar-scanner

# Or via npm
npm install -g sonarqube-scanner

SonarQube

"Insufficient privileges" error:

SonarQube → Administration → Security → Global Permissions
Give Anyone group Browse and Execute Analysis permissions

"Project not found" error:

Create project manually for first analysis: Projects → Create Project → Manually

Clone & build (contributors)

git clone https://github.com/mustafacagri/ai-quality-gate.git
cd ai-quality-gate
yarn install
yarn build

Use Local development (this repository) for MCP pointing at dist/server.js.

Docs

SETUP.md — Local setup (if included in your tree)
AGREEMENTS.md, docs/ARCHITECTURE.md, etc. — optional; some files may be omitted in minimal clones. README + .cursor/mcp.json.example are enough to run the published package.

Principles

✅ 627 ESLint rules (SonarJS, Unicorn, TypeScript-ESLint, etc.)
✅ Prettier integration (uses project's config)
✅ AST-based transforms (no regex)
✅ Verify after each fix
✅ Rollback on error
✅ ESLint config discovery (uses project config if available, otherwise embedded)
✅ Zero workaround
✅ Principal level

License

v0.0.1 — Initial release! MCP quality_fix, Phase 1/2 pipeline, CLI, config files, custom rules (see CHANGELOG)

Name		Name	Last commit message	Last commit date
Latest commit History 19 Commits
.cursor		.cursor
.github/workflows		.github/workflows
.opencode		.opencode
src		src
.gitattributes		.gitattributes
.gitignore		.gitignore
.prettierrc		.prettierrc
.releaserc		.releaserc
CHANGELOG.md		CHANGELOG.md
LICENSE		LICENSE
README.md		README.md
docker-compose.yml		docker-compose.yml
eslint.config.js		eslint.config.js
package.json		package.json
server.json		server.json
sonar-project.properties		sonar-project.properties
tsconfig.json		tsconfig.json
tsup.config.ts		tsup.config.ts
vitest.config.ts		vitest.config.ts
yarn.lock		yarn.lock

Folders and files

Latest commit

History

Repository files navigation

AI Quality Gate

What It Does

Installation

Prerequisites

MCP configuration (Cursor)

A) Recommended: npx (no global install)

B) Optional: global npm install

C) SonarQube (Phase 2)

D) Optional environment variables (any server)

MCP configuration

Cursor, Antigravity, etc..

(OpenCode)

Local development (this repository)

2. Add AI Rule

3. Use It

CLI: interactive config (--setup)

Optional: SonarQube Server (Phase 2)

SonarQube Setup

Docker (Recommended)

Docker Compose

Creating SonarQube Token

Installing sonar-scanner

Configuration

Custom rules (customRules)

JSON validator & i18n locale files

Environment Variables

Auto-Fix

ESLint Auto-Fix (~100+ rules)

AST Auto-Fix

Prettier Formatting

API

Tool: quality_fix

Feature Flags

ENABLE_I18N_RULES

Troubleshooting

MCP: quality_fix does not appear

Windows

macOS / Linux

SonarQube

Clone & build (contributors)

Docs

Principles

License

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 7

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

A) Recommended: `npx` (no global install)

B) Optional: global `npm` install

CLI: interactive config (`--setup`)

Custom rules (`customRules`)

Tool: `quality_fix`

`ENABLE_I18N_RULES`

MCP: `quality_fix` does not appear

Packages