AI Quality Gate

AI质量门

用于AI代码质量自动化的MCP服务器。

](https://www.npmjs.com/package/ai-quality-gate) 

______________________________________________________________________

它的作用

AI编写代码→ calls quality_fix → 服务器修复了它所能修复的内容→ 向AI报告剩余问题。

混合方法：

• 第一阶段： ESLint+627条规则+预处理（~2-8秒，始终运行）
• 第二阶段： SonarQube服务器（约30-60s，可选）

重要提示：ESLint与Prettier

ESLint规则由MCP控制，以实现一致的质量门。 Prettier使用项目的配置，因此格式与项目首选项相匹配。

第一阶段规则覆盖范围：

______________________________________________________________________

安装

先决条件

• Node.js 18+ 在你的路上(node -v).
• 光标, 反重力, 开源代码 （或另一个支持MCP的编辑器），启用MCP。

项目根是 自动检测 当 PROJECT_ROOT 省略：服务器从MCP进程工作目录向上走，直到找到 package.json 或 tsconfig.json.Set PROJECT_ROOT 在 env 仅用于分析与推断根不同的树。

______________________________________________________________________

MCP配置（光标）

打开 设置→ 工具和MCP→ Edit （用户 mcp.json).添加 一 服务器阻塞；下面的示例匹配 .cursor/mcp.json.example （带注释的JSONC——如果你的编辑器拒绝注释，只复制下面的JSON块）。

服务器名称与工具名称： 钥匙在下面 mcpServers （例如。 "ai-quality-gate")仅是Cursor中该连接的标签。MCP 工具 你的客服电话总是 quality_fix --该名称由此包固定，与服务器密钥和 ai-quality-gate.

A） 推荐： npx （无全局安装）

始终运行已发布的包；适合团队和CI类设置。

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

B） 可选：全局 npm 安装

之后 npm i -g ai-quality-gate，the ai-quality-gate 二进制文件在您的PATH上：

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

C） SonarQube（第二阶段）

需要一个正在运行的SonarQube实例， sonar-scanner 可用（参见 SonarQube设置)，以及下面的所有三个变量。第一阶段仍然是第一阶段。

{
  "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） 可选环境变量（任何服务器）

添加一个 "env" 当你需要覆盖时，对象。配置的合并顺序为 默认值→ .quality-gate.yaml / .quality-gate.json → 环境变量.

______________________________________________________________________

MCP配置

光标、反重力等。。

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

（OpenCode）

创建或编辑 OpenCode配置 （通常 ~/.config/opencode/opencode.json 或项目级配置）：

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

如果需要，可以在服务器配置下添加环境变量（请参阅 C） SonarQube（第二阶段） 上文）。

______________________________________________________________________

本地开发（此存储库）

给狗粮或捐款：

1. yarn build --生成 dist/server.js.
2. 将MCP指向构建文件（绝对路径）：

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

1. 重新加载MCP。使用 env.PROJECT_ROOT 只有当您分析的repo与推断的根不同时。

______________________________________________________________________

2.添加AI规则

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.使用它

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

______________________________________________________________________

CLI：交互式配置(--setup)

这 交互式向导 创建或更新 .quality-gate.yaml 无需手动编辑：它会引导您浏览项目根目录，可选SonarQube（主机URL+项目密钥； 令牌未保存到磁盘 --使用 SONAR_TOKEN 在您的环境中），要启用哪些阶段1工具（ESLint、花括号/箭头AST修复器、Prettier、JSON验证器）、超时和i18n规则。生成的文件包括 fixers: 您可以稍后进行调整。

之后 yarn build （或从npm安装），从目标项目（或其下的任何路径）运行：

node dist/server.js --setup

PROJECT_ROOT 未设置时推断（参见 MCP配置).使用与MCP服务器相同的入口点(node dist/server.js 或 npx ai-quality-gate)；只有 --setup 标志切换到向导模式。回答终端提示；成功后，您将在项目根目录旁边获得一个即用配置。

其他CLI模式： --check （只读阶段1）， --fix （使用CLI质量运行时的默认行为）， --phase1-only, --phase2-only --看 docs/DEVELOPMENT.md.

______________________________________________________________________

可选：SonarQube服务器（第2阶段）

在MCP中配置声纳环境，如所示 C） SonarQube（第二阶段） 以上，或复制自 .cursor/mcp.json.example你需要 sonar-scanner 在您的机器上进行分析（见下文）。

SonarQube设置

Docker（推荐）

# 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

创建SonarQube代币

1. http://localhost:9000 → 登录（管理员）
2. 我的账户 → 安全 → 生成令牌
3. 选择令牌类型： 全局分析令牌
4. 复制令牌→ 用作 SONAR_TOKEN

安装声纳扫描仪

对于自定义路径： SONAR_SCANNER_PATH env 是

______________________________________________________________________

配置

可选文件（通过从推断的项目根目录向上遍历来发现——算法与 package.json / tsconfig.json --或从 PROJECT_ROOT 设置时）： .quality-gate.yaml （首选）或 .quality-gate.json与环境变量相同的字段（camelCase）；您可以将声纳设置嵌套在 sonar: { hostUrl, token, projectKey, scannerPath }.

合并顺序： 默认值→ 配置文件→ 环境变量 （ENV在冲突中获胜）。

集 QUALITY_GATE_CONFIG 指向跳过发现的明确路径。

自定义规则(customRules)

可选的 基于行的正则表达式 检查可移植文件（第一阶段）。每场比赛都被报告为一个问题 rule 着手 custom: （并包括在 quality_fix remaining).例子：

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

模式使用JavaScript RegExp source（在YAML字符串中转义反斜杠）。在运行时使用日志行跳过无效模式。

JSON验证器和i18n区域设置文件

当 fixers.jsonValidator 启用后，您可以传递与区域设置模式匹配的JSON路径（例如 locales/en.json / locales/tr.json)，该工具会比较这些文件中的密钥。

• 语法错误、UTF-8 BOM无效等。 → 报告为 issues 和 失败 第一阶段/ quality_fix 直到固定。
• 区域设置文件之间缺少或多余的键 → 收集为 i18nIssues 在验证器结果中，并打印为 stderr上的警告 在第一阶段。他们确实如此 不 集 passed: false 并做 不 堵住大门。

对待 i18nIssues 除非你在上面添加自己的CI检查，否则这是一个建议。

______________________________________________________________________

环境变量

所有变量都是 可选的 除非您使用第2阶段，这需要 SONAR_HOST_URL, SONAR_TOKEN，以及 SONAR_PROJECT_KEY 一起。

______________________________________________________________________

自动修正

第一阶段自动修复了这些问题：

ESLint自动修复（~100+条规则）

// 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自动修复

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

预处理格式

ESLint修复后，Prettier会运行以确保格式一致：

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

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

注： Prettier使用项目的配置，而不是MCP的配置。

其他一切： 向AI报告，AI修复了它。

______________________________________________________________________

API

工具： 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
  }
}

______________________________________________________________________

功能标志

ENABLE_I18N_RULES

对于国际化（i18n）的项目，启用文字字符串检测：

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

启用时：

// ⚠️ Warning

Hello World

// ✅ OK

{t('hello')}

______________________________________________________________________

故障排除

MCP： quality_fix 不出现

1. Node.js 18+ --奔跑 node -v 和 npx --version.
2. 重新加载 编辑后的光标 mcp.json （或使用MCP刷新控制）。
3. JSON --文件必须是有效的JSON（没有尾随逗号）。复制自 MCP配置 如果不确定，请参阅部分。
4. 全局安装 --如果你使用 "command": "ai-quality-gate"，跑 npm i -g ai-quality-gate 一旦如此，二进制就存在了。

视窗

“未找到npx”错误：

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

权限被拒绝：

# Run PowerShell as Administrator

macOS/Linux

“权限被拒绝”错误：

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

“未找到声纳扫描仪”错误：

# Install via Homebrew
brew install sonar-scanner

# Or via npm
npm install -g sonarqube-scanner

声纳立方

“权限不足”错误：

• 声纳立方→ 行政 → 安全 → 全局权限
• 给 任何人 群组 浏览 和 执行分析 权限

“找不到项目”错误：

• 手动创建项目以进行首次分析： 项目 → 创建项目 → 手动地

______________________________________________________________________

克隆和构建（贡献者）

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

使用 本地开发（此存储库） MCP指向 dist/server.js.

______________________________________________________________________

文档

• 设置.md --本地设置（如果包含在树中）
• 协议.md, docs/ARCHITECTURE.md等等。--可选；在最小克隆中，某些文件可能会被省略。 自述文件 + .cursor/mcp.json.example 足以运行已发布的包。

______________________________________________________________________

原则

• ✅ 627 ESLint规则（SonarJS、Unicorn、TypeScript ESLint等）
• ✅ 预集成（使用项目的配置）
• ✅ 基于AST的转换（无正则表达式）
• ✅ 每次修复后进行验证
• ✅ 回滚错误
• ✅ ESLint配置发现（如果可用，则使用项目配置，否则嵌入）
• ✅ 零解决方法
• ✅ 特等

______________________________________________________________________

许可证

MIT© 穆斯塔法呼吁信任

______________________________________________________________________

v0.0.1 --首次发布！主控程序 quality_fix，第1/2阶段管道、CLI、配置文件、自定义规则（请参见 更新日志)