π Kill the Junior AI Era. π€ Level up AI code to automatically Principal standards. π‘οΈ Quality Gate β¨
io.github.mustafacagri/ai-quality-gate MCP Server
This MCP server automates AI-driven code quality checks. It fits a workflow where AI writes code, calls quality_fix, the server applies fixes where possible, and then reports remaining issues back to the AI. It uses a hybrid approach combining ESLint plus Prettier and an optional SonarQube run.
π οΈ Key Features
Tool: quality_fix for server-side code quality fixes
Phase 1: ESLint with 627 rules plus Prettier (about 2β8s, always runs)
Phase 2: SonarQube Server (about 30β60s, optional)
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 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.
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):
bash
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 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 }.
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_fixremaining). Example:
yaml
customRules:-id:no-consolemessage:'Console.log is not allowed'pattern:'console\\.log\\('severity:error-id:no-debuggermessage:'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
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.
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)
typescript
// var β const/letvar 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 removedimport { unused } from'x' β (removed)
// Type imports (consistent-type-imports)import { Type } from'x' β importtype { Type } from'x'// Optional chain (prefer-optional-chain)
a && a.b && a.b.c β a?.b?.c// Regex optimization (regexp/*)
/[0-9]/ β /\d/
After ESLint fixes, Prettier runs to ensure consistent formatting:
typescript
// ESLint removes braces but leaves awkward format:if (x) returntrue// Prettier fixes to single line:if (x) returntrue
Note: Prettier uses project's config, not MCP's.
Everything else: Reported to AI, AI fixes it.
API
Tool: quality_fix
typescript
// Input
{
files: string[] // File paths to check
}
// Output
{
phase: "local" | "server" | "complete",
success: boolean,
message: string,
fixed: { // a FixSummary: edits on disk, kept even when findings remaineslint: number, // ESLint auto-fixescurlyBraces: number, // AST: single-statement if bracessingleLineArrow: number, // AST: arrow body styleprettier: number, // Prettier formattingjson: number// JSON files validated (not an edit, so not part of fixedCount)
},
fixedCount: number, // Edits on disk: the sum of `fixed`, without `json`attempted?: FixSummary, // same fields as `fixed`: edits tried before a rollback, not on disk after a successful oneattemptedCount?: number, // The sum of `attempted`warnings?: string[], // Things the gate could not do that do not fail the run (a file a fixer skipped, a custom rule it could not apply)remaining: Issue[], // Findings left to fix by hand. Line numbers refer to the files as they are now (line 0 = location unknown)remainingCount: number, // remaining.lengthtotalIssues: number, // fixedCount + remainingCounterror?: { // Set when the run could not finish: e.g. ROLLBACK_FAILED, SONAR_API_ERROR, PERSISTENT_FAILUREcode: string,
message: string,
details?: object// ROLLBACK_FAILED: { unrestoredFiles, restoredFiles }
},
checks?: object, // Raw typecheck and lint results, in read-only check modetiming: {
phase1: string,
phase2?: string,
total: string
}
}
What a failed run leaves on disk. The gate applies every fix it can and keeps them. Findings it cannot fix
(a lint rule, a custom rule, a == that is not provably safe to change) come back in remaining with
success: false; the kept fixes are counted in fixed. The run is rolled back only when the fixers themselves broke
something: a type error after the fix, a Vue file the compiler rejects, ESLint or Prettier failing to run. Then
fixed is zero and the edits that were tried are listed in attempted. If that rollback itself fails, the response is ROLLBACK_FAILED: error.details.unrestoredFiles lists the files that may still hold the edits, phase is the phase that failed, and remaining is what failed, without locations. SonarQube (Phase 2) findings, or an
unreachable server, do not undo the verified Phase 1 edits either: they stay and the findings come back in remaining.
Retrying. If the same failure comes back unchanged three times in a row (same files with the same content, same
findings), the MCP server answers with error.code: "PERSISTENT_FAILURE" and tells the caller to stop retrying and ask
the human. Changing a file, or the findings changing, starts the count over. fixedCount counts edits only; JSON
validation passes are in fixed.json and are not fixes.
Overlapping calls. The MCP server runs quality_fix calls whose file sets overlap one after the other, in the order
they arrived, so one call's rollback can never restore an older copy over another call's kept edits. Calls on different
files still run side by side.
Feature Flags
ENABLE_I18N_RULES
For projects with internationalization (i18n), enable literal string detection:
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.
Run ai-quality-gate --check --phase1-only <selected-file ...> for readonly local
verification. ESLint checks only the explicitly selected real .js, .jsx,
.mjs, .cjs, .ts, .tsx, .mts, .cts, and .vue paths, including executable JS
configuration and TS declarations. It never expands lint scope through imports.
A .vue file is linted in place: vue-eslint-parser applies script rules to
<script> and <script setup> only. Template and style are not JavaScript, and
no extracted script file is written. @vue/compiler-sfcparse() and
compileScript() failures are diagnostics. A structurally invalid SFC fails
before ESLint, so a missing end tag is not reported as an unused binding.
AST edits keep arrow signatures and terminate a brace-less if with a semicolon.
Prettier, when enabled, formats the whole SFC. Deleted and old rename endpoints must first be
materialized as real files in an isolated snapshot by the caller, with their base
content and endpoint identity retained.
TypeScript checks the full nearest tsconfig.json project context with --noEmit;
this can include imports and other project files and does not expand ESLint's
selected scope. A .vue file with a TypeScript script (lang="ts" or tsx) is checked with
vue-tsc, which also checks its template expressions. A project that compiles .vue files uses vue-tsc for
its .ts files too, so they can import .vue modules; a project counts as one that compiles .vue files when its
include matches any, or when the nearest package.json depends on vue. The project is the tsconfig that includes the
file: for a create-vue style root config that only lists references, that is the referenced project, and a file such as
a shared helper that no project lists but a referenced project imports is checked in that project. A .vue file that no
tsconfig includes fails instead of passing unchecked. A plain-JavaScript .vue file is not type checked, as a .js
file is not. This holds for .ts files too: a file that no tsconfig includes, directly or through imports, fails with
"Not included by " instead of passing unchecked. Type errors anywhere in the program fail the check and are all
reported (those in the selected files first, at most 50). A plain-JavaScript <script> is linted with the rules a .js file gets, and a lang="ts" one with
the TypeScript rules. Type-aware ESLint rules (such as no-floating-promises) are not applied to .vue files: that is a
deliberate choice, not a limit of the parser. TypeScript incremental metadata is redirected to a temporary
folder outside the project and removed after the check. No source, configuration,
lockfile, or control file is rewritten by check mode. The MCP quality_fix tool
continues to be a mutating operation; use the CLI check interface for readonly work.
The embedded config uses typescript-eslint's recommendedTypeChecked and
projectService for TS sources. TS files must belong to a real tsconfig project.
JavaScript files use the non-typed lint profile. Named import aliases, including
type aliases, are checked by an AST rule; unchanged named imports are allowed.
Warnings fail strict verification (--max-warnings 0). Local check JSON includes
checks.typecheck and, when reached, checks.lint, with PASS/FAIL/ERROR status,
checked projects, and actual lint result paths. The existing fail-fast pipeline
can stop before lint after a failed typecheck or custom rule.
Exit 0 means all reached checks succeeded; exit 1 reports real code findings;
exit 2 reports configuration, process, parser, or coverage errors. Empty/malformed
lint output, missing selected files, unexpected/duplicate result paths, fatal
parser failures, and failed subprocesses cannot become a successful check.
The installed package carries its embedded parser, lint plugins/resolver, and
TypeScript runtime dependencies. Supported Node versions are ^20.10.0 || >=21.1.0,
the intersection required by the retained lint dependency baseline.
Install
Configuration
Environment variables
PROJECT_ROOT
Absolute path to the project root for analysis (auto-detected if omitted)
SONAR_HOST_URL
SonarQube server base URL (e.g., http://localhost:9000)
SONAR_TOKENsecret
SonarQube authentication token
SONAR_PROJECT_KEY
SonarQube project key
ENABLE_I18N_RULES
Enable stricter JSX literal checks for i18n projects (true/false)