{"id":"c84bc64d-3f1f-4ece-b382-d32cf10122b6","slug":"ai-quality-gate","kind":"mcp","name":"ai-quality-gate","summary":"πŸš€ Kill the Junior AI Era. πŸ€– Level up your AI code to Principal standards. No more sloppy lines or junior mistakes. Automated ESLint ✨ TypeScript πŸ”§ Prettier 🎨 SonarQube πŸ›‘οΈ Security πŸ”’ Complexity οΏ½","owner":"mustafacagri","repoUrl":"https://github.com/mustafacagri/ai-quality-gate","license":"MIT","licenseTier":"permissive","trust":"community","stars":31,"match":null,"fewStars":false,"format":"mcp","createdAt":null,"addedAt":"2026-10-14T05:02:36.358Z","logoUrl":"https://avatars.githubusercontent.com/u/7488394?u=23fe234eaa1a07c7d0f85efba5db98931d0b98da&v=4","linkOnly":false,"collection":null,"skillPath":null,"categories":["developer-tools","cloud-infra"],"tags":["ai","automation","codequality","coding","cursor","devtools","opensource","typescript"],"runtime":"node","local":true,"cloudCapable":false,"cloudCapability":"unknown","cloudReadyOnPlatform":false,"needsApiKey":false,"reviewed":false,"syncedAt":"2026-10-14T05:03:00.172Z","sample":false,"url":"https://conduits.dev/tools/ai-quality-gate","language":"TypeScript","transports":["stdio"],"install":{"npm":"ai-quality-gate"},"requirements":{"env":[],"upstreamMayCharge":false},"tools":null,"readme":"# AI Quality Gate\n\nMCP Server for AI code quality automation.\n\n[![npm version](https://badge.fury.io/js/ai-quality-gate.svg)](https://www.npmjs.com/package/ai-quality-gate)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\n---\n\n## What It Does\n\nAI writes code β†’ calls `quality_fix` β†’ Server fixes what it can β†’ Reports remaining issues to AI.\n\n**Hybrid Approach:**\n\n- **Phase 1:** ESLint + 627 rules + Prettier (~2-8s, always runs)\n- **Phase 2:** SonarQube Server (~30-60s, optional)\n\n**Important: ESLint vs Prettier**\n\n| Tool | Source | Config |\n| ------------ | ---------------------------------------------- | ------------------------------------------------ |\n| **ESLint** | Project's config (if exists) or MCP's embedded | `.eslintrc.*` / `eslint.config.*` / MCP embedded |\n| **Prettier** | **Project's own** | Project's `prettier.config.mjs` |\n\n> ESLint rules are controlled by MCP for consistent quality gates.\n> Prettier uses project's config so formatting matches project preferences.\n\n**Phase 1 Rule Coverage:**\n\n| Plugin | Rules | Description |\n| ----------------- | ------- | --------------------------- |\n| SonarJS | 201 | Security, bugs, code smells |\n| Unicorn | 127 | Modern JS best practices |\n| ESLint Core | 108 | JavaScript fundamentals |\n| TypeScript-ESLint | 99 | TypeScript-specific rules |\n| RegExp | 60 | Regex best practices |\n| Import | 11 | Import/export rules |\n| Promise | 10 | Async/await best practices |\n| Node.js (n) | 9 | Node.js specific rules |\n| Unused Imports | 2 | Auto-remove unused imports |\n| **Total** | **627** | |\n\n---\n\n## Installation\n\n### Prerequisites\n\n- **Node.js 20.10+ or 21.1+** on your PATH (`node -v`).\n- **Cursor**, **Antigravity**, **OpenCode** (or another MCP-capable editor) with MCP enabled.\n\nProject 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.\n\n---\n\n### MCP configuration (Cursor)\n\nOpen **Settings β†’ Tools & MCP β†’ Edit** (user `mcp.json`). Add **one** server block; the examples below match [`.cursor/mcp.json.example`](.cursor/mcp.json.example) (JSONC with comments β€” if your editor rejects comments, copy the JSON blocks below only).\n\n**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`.\n\n#### A) Recommended: `npx` (no global install)\n\nAlways runs the published package; good for teams and CI-like setups.\n\n```json\n{\n \"mcpServers\": {\n \"ai-quality-gate\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"ai-quality-gate\"]\n }\n }\n}\n```\n\n#### B) Optional: global `npm` install\n\nAfter `npm i -g ai-quality-gate`, the `ai-quality-gate` binary is on your PATH:\n\n```json\n{\n \"mcpServers\": {\n \"ai-quality-gate\": {\n \"command\": \"ai-quality-gate\",\n \"args\": []\n }\n }\n}\n```\n\n#### C) SonarQube (Phase 2)\n\nRequires a running SonarQube instance, `sonar-scanner` available (see [SonarQube Setup](#optional-sonarqube-server-phase-2)), and all three variables below. Phase 1 still runs first.\n\n```json\n{\n \"mcpServers\": {\n \"ai-quality-gate\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"ai-quality-gate\"],\n \"env\": {\n \"SONAR_HOST_URL\": \"http://localhost:9000\",\n \"SONAR_TOKEN\": \"your_sonar_token\",\n \"SONAR_PROJECT_KEY\": \"your_project_key\"\n }\n }\n }\n}\n```\n\n#### D) Optional environment variables (any server)\n\nAdd an `\"env\"` object when you need overrides. Merge order for config is **defaults β†’ `.quality-gate.yaml` / `.quality-gate.json` β†’ environment variables**.\n\n| Variable | When to set |\n| --------------------- | ----------------------------------------------------------------------------------------------------- |\n| `QUALITY_GATE_CONFIG` | Absolute path to a specific `.quality-gate.yaml` or `.quality-gate.json` (skips walking directories). |\n| `PROJECT_ROOT` | Force project root if auto-detection is wrong for your layout. |\n| `SONAR_HOST_URL` | SonarQube server URL (with Phase 2). |\n| `SONAR_TOKEN` | SonarQube token (with Phase 2). |\n| `SONAR_PROJECT_KEY` | SonarQube project key (with Phase 2). |\n| `SONAR_SCANNER_PATH` | Full path to `sonar-scanner` if not on `PATH`. |\n| `PHASE1_TIMEOUT` | Phase 1 timeout (ms), default `30000`. |\n| `PHASE2_TIMEOUT` | Phase 2 timeout (ms), default `300000`. |\n| `ENABLE_I18N_RULES` | `true` / `false` β€” stricter JSX literal checks for i18n projects. |\n\n---\n\n### MCP configuration\n\n#### Cursor, Antigravity, etc..\n\n```json\n{\n \"mcpServers\": {\n \"ai-quality-gate\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"ai-quality-gate\"]\n }\n }\n}\n```\n\n#### (OpenCode)\n\nCreate or edit **OpenCode config** (typically `~/.config/opencode/opencode.json` or project-level config):\n\n```json\n{\n \"$schema\": \"https://opencode.ai/config.json\",\n \"mcp\": {\n \"ai-quality-gate\": {\n \"type\": \"local\",\n \"enabled\": true,\n \"command\": [\"npx\", \"-y\", \"ai-quality-gate\"]\n }\n }\n}\n```\n\nEnvironment variables can be added under the server config if needed (see [C) SonarQube (Phase 2)](#c-sonarqube-phase-2) above).\n\n---\n\n### Local development (this repository)\n\nTo dogfood or contribute:\n\n1. **`yarn build`** β€” generates `dist/server.js`.\n2. Point MCP at the built file (absolute paths):\n\n```json\n{\n \"mcpServers\": {\n \"ai-quality-gate-dev\": {\n \"command\": \"node\",\n \"args\": [\"/ABSOLUTE/PATH/TO/ai-quality-gate/dist/server.js\"]\n }\n }\n}\n```\n\n3. Reload MCP. Use `env.PROJECT_ROOT` only if the repo you analyze differs from the inferred root.\n\n---\n\n### 2. Add AI Rule\n\n`Settings` β†’ `Rules and Commands` β†’ `Add Rule`:\n\n```\nAfter every code change, before telling the user \"done\",\nAI must call the quality_fix MCP tool. This is mandatory.\n```\n\n### 3. Use It\n\n```\nAI writes code β†’ calls quality_fix β†’ Fixes errors β†’ \"Done βœ…\"\n```\n\n---\n\n## CLI: interactive config (`--setup`)\n\nThe **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.\n\nAfter `yarn build` (or install from npm), run from the target project (or any path under it):\n\n```bash\nnode dist/server.js --setup\n```\n\n`PROJECT_ROOT` is inferred when unset (see [MCP configuration](#mcp-configuration-cursor)). 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.\n\n**Other CLI modes:** `--check` (read-only Phase 1), `--fix` (default behavior when using CLI quality run), `--phase1-only`, `--phase2-only` β€” see [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md).\n\n---\n\n## Optional: SonarQube Server (Phase 2)\n\nConfigure Sonar env in MCP as in **[C) SonarQube (Phase 2)](#c-sonarqube-phase-2)** above, or copy from [`.cursor/mcp.json.example`](.cursor/mcp.json.example). You need **`sonar-scanner`** on your machine for analysis (see below).\n\n### SonarQube Setup\n\n#### Docker (Recommended)\n\n```bash\n# Start SonarQube\ndocker run -d --name sonarqube -p 9000:9000 sonarqube:community\n\n# First login: admin/admin β†’ change password\n# http://localhost:9000\n```\n\n#### Docker Compose\n\n```yaml\n# docker-compose.yml\nversion: '3'\nservices:\n sonarqube:\n image: sonarqube:community\n ports:\n - '9000:9000'\n volumes:\n - sonarqube_data:/opt/sonarqube/data\n - sonarqube_logs:/opt/sonarqube/logs\n - sonarqube_extensions:/opt/sonarqube/extensions\n\nvolumes:\n sonarqube_data:\n sonarqube_logs:\n sonarqube_extensions:\n```\n\n```bash\ndocker-compose up -d\n```\n\n### Creating SonarQube Token\n\n1. http://localhost:9000 β†’ Login (admin)\n2. **My Account** β†’ **Security** β†’ **Generate Tokens**\n3. Select token type: **Global Analysis Token**\n4. Copy token β†’ use as `SONAR_TOKEN`\n\n### Installing sonar-scanner\n\n| Platform | Method | Command |\n| ----------- | ------------ | ------------------------------------------ |\n| **Windows** | npm (global) | `npm install -g sonarqube-scanner` |\n| **Windows** | Chocolatey | `choco install sonar-scanner` |\n| **macOS** | npm (global) | `npm install -g sonarqube-scanner` |\n| **macOS** | Homebrew | `brew install sonar-scanner` |\n| **Linux** | npm (global) | `npm install -g sonarqube-scanner` |\n| **Docker** | Container | `docker run sonarsource/sonar-scanner-cli` |\n\nFor custom path: `SONAR_SCANNER_PATH` env var\n\n---\n\n## Configuration\n\nOptional 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 }`.\n\nMerge order: **defaults β†’ config file β†’ environment variables** (ENV wins on conflicts).\n\nSet **`QUALITY_GATE_CONFIG`** to an explicit path to skip discovery.\n\n### Custom rules (`customRules`)\n\nOptional **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:\n\n```yaml\ncustomRules:\n - id: no-console\n message: 'Console.log is not allowed'\n pattern: 'console\\\\.log\\\\('\n severity: error\n - id: no-debugger\n message: 'Debugger statement found'\n pattern: 'debugger'\n severity: warning\n```\n\nPatterns use JavaScript `RegExp` source (escape backslashes as in YAML strings). An invalid pattern is skipped, and says so in `warnings`.\n\n### JSON validator & i18n locale files\n\nWhen **`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.\n\n- **Syntax errors, invalid UTF-8 BOM, etc.** β†’ reported as `issues` and **fail** Phase 1 / `quality_fix` until fixed.\n- **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.\n\nTreat `i18nIssues` as advisory unless you add your own CI check on top.\n\n---\n\n## Environment Variables\n\nAll variables are **optional** unless you use Phase 2, which requires **`SONAR_HOST_URL`**, **`SONAR_TOKEN`**, and **`SONAR_PROJECT_KEY`** together.\n\n| Variable | Description | Example |\n| --------------------- | ---------------------------------------------------------------------------------------------------------------------------- | -------------------------------------- |\n| `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` |\n| `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` |\n| `SONAR_HOST_URL` | SonarQube server base URL (Phase 2). | `http://localhost:9000` |\n| `SONAR_TOKEN` | SonarQube authentication token (Phase 2). Prefer env / secret store; avoid committing. | `sqa_xxx...` |\n| `SONAR_PROJECT_KEY` | SonarQube project key (Phase 2). | `my-project` |\n| `SONAR_SCANNER_PATH` | Full path to the `sonar-scanner` executable if it is not on `PATH`. | `/opt/sonar-scanner/bin/sonar-scanner` |\n| `PHASE1_TIMEOUT` | Phase 1 subprocess timeout in milliseconds. | `30000` (default) |\n| `PHASE2_TIMEOUT` | Phase 2 (Sonar) timeout in milliseconds. | `300000` (default) |\n| `ENABLE_I18N_RULES` | Set to `true` to enable ESLint rules that flag raw string literals in JSX (for i18n-heavy apps). | `false` (default) |\n\n---\n\n## Auto-Fix\n\nPhase 1 automatically fixes these issues:\n\n### ESLint Auto-Fix (~100+ rules)\n\n```typescript\n// var β†’ const/let\nvar x = 1 β†’ const x = 1\n\n// forEach β†’ for...of (unicorn/no-array-for-each)\narr.forEach(x => f(x)) β†’ for (const x of arr) f(x)\n\n// Nested ternary β†’ extracted (unicorn/no-nested-ternary)\na ? b : c ? d : e β†’ const temp = c ? d : e; a ? b : temp\n\n// Unused imports removed\nimport { unused } from 'x' β†’ (removed)\n\n// Type imports (consistent-type-imports)\nimport { Type } from 'x' β†’ import type { Type } from 'x'\n\n// Optional chain (prefer-optional-chain)\na && a.b && a.b.c β†’ a?.b?.c\n\n// Regex optimization (regexp/*)\n/[0-9]/ β†’ /\\d/\n```\n\n### AST Auto-Fix\n\n```typescript\n// Remove unnecessary curly braces (single-line if)\nif (x) { return true } β†’ if (x) return true\n```\n\n### Prettier Formatting\n\nAfter ESLint fixes, Prettier runs to ensure consistent formatting:\n\n```typescript\n// ESLint removes braces but leaves awkward format:\nif (x) return true\n\n// Prettier fixes to single line:\nif (x) return true\n```\n\n> **Note:** Prettier uses project's config, not MCP's.\n\n**Everything else:** Reported to AI, AI fixes it.\n\n---\n\n## API\n\n### Tool: `quality_fix`\n\n```typescript\n// Input\n{\n files: string[] // File paths to check\n}\n\n// Output\n{\n phase: \"local\" | \"server\" | \"complete\",\n success: boolean,\n message: string,\n fixed: { // a FixSummary: edits on disk, kept even when findings remain\n eslint: number, // ESLint auto-fixes\n curlyBraces: number, // AST: single-statement if braces\n singleLineArrow: number, // AST: arrow body style\n prettier: number, // Prettier formatting\n json: number // JSON files validated (not an edit, so not part of fixedCount)\n },\n fixedCount: number, // Edits on disk: the sum of `fixed`, without `json`\n attempted?: FixSummary, // same fields as `fixed`: edits tried before a rollback, not on disk after a successful one\n attemptedCount?: number, // The sum of `attempted`\n 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)\n remaining: Issue[], // Findings left to fix by hand. Line numbers refer to the files as they are now (line 0 = location unknown)\n remainingCount: number, // remaining.length\n totalIssues: number, // fixedCount + remainingCount\n error?: { // Set when the run could not finish: e.g. ROLLBACK_FAILED, SONAR_API_ERROR, PERSISTENT_FAILURE\n code: string,\n message: string,\n details?: object // ROLLBACK_FAILED: { unrestoredFiles, restoredFiles }\n },\n checks?: object, // Raw typecheck and lint results, in read-only check mode\n timing: {\n phase1: string,\n phase2?: string,\n total: string\n }\n}\n```\n\n**What a failed run leaves on disk.** The gate applies every fix it can and keeps them. Findings it cannot fix\n(a lint rule, a custom rule, a `==` that is not provably safe to change) come back in `remaining` with\n`success: false`; the kept fixes are counted in `fixed`. The run is rolled back only when the fixers themselves broke\nsomething: a type error after the fix, a Vue file the compiler rejects, ESLint or Prettier failing to run. Then\n`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\nunreachable server, do not undo the verified Phase 1 edits either: they stay and the findings come back in `remaining`.\n\n**Retrying.** If the same failure comes back unchanged three times in a row (same files with the same content, same\nfindings), the MCP server answers with `error.code: \"PERSISTENT_FAILURE\"` and tells the caller to stop retrying and ask\nthe human. Changing a file, or the findings changing, starts the count over. `fixedCount` counts edits only; JSON\nvalidation passes are in `fixed.json` and are not fixes.\n\n**Overlapping calls.** The MCP server runs `quality_fix` calls whose file sets overlap one after the other, in the order\nthey arrived, so one call's rollback can never restore an older copy over another call's kept edits. Calls on different\nfiles still run side by side.\n\n---\n\n## Feature Flags\n\n### `ENABLE_I18N_RULES`\n\nFor projects with internationalization (i18n), enable literal string detection:\n\n```json\n{\n \"env\": {\n \"ENABLE_I18N_RULES\": \"true\"\n }\n}\n```\n\nWhen enabled:\n\n```tsx\n// ⚠️ Warning\n

Hello World

\n\n// βœ… OK\n

{t('hello')}

\n```\n\n---\n\n## Troubleshooting\n\n### MCP: `quality_fix` does not appear\n\n1. **Node.js 20.10+ or 21.1+** β€” run `node -v` and `npx --version`.\n2. **Reload** Cursor after editing `mcp.json` (or use the MCP refresh control).\n3. **JSON** β€” the file must be valid JSON (no trailing commas). Copy from the [MCP configuration](#mcp-configuration-cursor) section if unsure.\n4. **Global install** β€” if you use `\"command\": \"ai-quality-gate\"`, run `npm i -g ai-quality-gate` once so the binary exists.\n\n### Windows\n\n**\"npx not found\" error:**\n\n```bash\n# Node.js must be in PATH\n# Check in PowerShell:\nwhere.exe npx\n```\n\n**Permission denied:**\n\n```bash\n# Run PowerShell as Administrator\n```\n\n### macOS / Linux\n\n**\"Permission denied\" error:**\n\n```bash\n# Fix npm global directory\nmkdir ~/.npm-global\nnpm config set prefix '~/.npm-global'\necho 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrc\nsource ~/.zshrc\n```\n\n**\"sonar-scanner not found\" error:**\n\n```bash\n# Install via Homebrew\nbrew install sonar-scanner\n\n# Or via npm\nnpm install -g sonarqube-scanner\n```\n\n### SonarQube\n\n**\"Insufficient privileges\" error:**\n\n- SonarQube β†’ **Administration** β†’ **Security** β†’ **Global Permissions**\n- Give **Anyone** group **Browse** and **Execute Analysis** permissions\n\n**\"Project not found\" error:**\n\n- Create project manually for first analysis: **Projects** β†’ **Create Project** β†’ **Manually**\n\n---\n\n## Clone & build (contributors)\n\n```bash\ngit clone https://github.com/mustafacagri/ai-quality-gate.git\ncd ai-quality-gate\nyarn install\nyarn build\n```\n\nUse [Local development (this repository)](#local-development-this-repository) for MCP pointing at `dist/server.js`.\n\n---\n\n## Docs\n\n- [SETUP.md](./SETUP.md) β€” Local setup (if included in your tree)\n- [AGREEMENTS.md](./docs/AGREEMENTS.md), [docs/ARCHITECTURE.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.\n\n---\n\n## Principles\n\n- βœ… 627 ESLint rules (SonarJS, Unicorn, TypeScript-ESLint, etc.)\n- βœ… Prettier integration (uses project's config)\n- βœ… AST-based transforms (no regex)\n- βœ… Verify after each fix\n- βœ… Rollback on error\n- βœ… ESLint config discovery (uses project config if available, otherwise embedded)\n- βœ… Zero workaround\n- βœ… Principal level\n\n---\n\n## License\n\nMIT Β© [Mustafa Γ‡ağrΔ± GΓΌven](https://github.com/mustafacagri)\n\n---\n\n**v0.0.1** β€” Initial release! MCP `quality_fix`, Phase 1/2 pipeline, CLI, config files, custom rules (see [CHANGELOG](./CHANGELOG.md))\n\n\n### Readonly local verification\n\nRun `ai-quality-gate --check --phase1-only ` for readonly local\nverification. ESLint checks only the explicitly selected real `.js`, `.jsx`,\n`.mjs`, `.cjs`, `.ts`, `.tsx`, `.mts`, `.cts`, and `.vue` paths, including executable JS\nconfiguration and TS declarations. It never expands lint scope through imports.\nA `.vue` file is linted in place: `vue-eslint-parser` applies script rules to\n`