How do I use code-guardian?

1. Click on "Deploy Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@code-guardian run full health check on src/views/Home.vue" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

code-guardian

by xueca

Overview Schema Source Related Servers Discussions Admin

TypeScript

Local

Code Guardian

GitHub Packages License: MIT Node.js >= 18

Code Guardian 是一个 MCP (Model Context Protocol) Server，为 AI 编码助手（如 Claude Code、Trae、Cursor、Windsurf 等）提供代码质量检查能力。它能在 AI 修改代码前后自动检查文件大小、ESLint、架构分层合规、反模式扫描和注释规范，确保 AI 生成的代码符合项目团队的编码标准。

前置要求

Node.js >= 18.0.0（MCP SDK 依赖）
ESLint >= 9.0.0（可选，run_eslint 工具需要）
项目需要有一个 .code-guardian.json 配置文件（详见配置参考）

安装

方式一：从 GitHub Packages 安装（推荐）

首次使用需配置 scope registry（一次性操作）：

# 配置 @xueca scope 指向 GitHub Packages
npm config set @xueca:registry https://npm.pkg.github.com

# 配置认证 Token（需 GitHub Personal Access Token，勾选 read:packages 权限）
npm config set //npm.pkg.github.com/:_authToken YOUR_GITHUB_TOKEN

安装：

npm install @xueca/code-guardian --save-dev

Token 生成地址：https://github.com/settings/tokens（Classic Token，勾选 read:packages）

方式二：从 GitHub 源码安装

npm install --save-dev github:xueca/code-guardian

需要 Git 已安装且可访问 GitHub。

方式三：本地开发安装

git clone https://github.com/xueca/code-guardian.git
cd code-guardian
npm install

快速开始

1. 创建项目配置文件

在项目根目录创建 .code-guardian.json：

{
  "version": "1.0",
  "fileSizeLimits": {
    "**/controllers/**/*.js": 150,
    "**/routes/**/*.js": 50,
    "**/*.vue": 200,
    "**/*.js": 150
  },
  "antiPatterns": {
    "directApiInView": true,
    "bareAsync": true,
    "resourceLeak": true
  }
}

完整配置项见下方配置参考。

2. 配置 MCP 客户端

Claude Code（.claude/settings.json）：

{
  "mcpServers": {
    "code-guardian": {
      "command": "npx",
      "args": [
        "-y",
        "@xueca/code-guardian",
        "--project-root",
        "."
      ]
    }
  }
}

Trae（.trae/mcp.json）：

{
  "mcpServers": {
    "code-guardian": {
      "command": "npx",
      "args": [
        "-y",
        "@xueca/code-guardian",
        "--project-root",
        "/absolute/path/to/project"
      ]
    }
  }
}

Cursor / Windsurf（.cursor/mcp.json 或 .windsurf/mcp.json）：

{
  "mcpServers": {
    "code-guardian": {
      "command": "npx",
      "args": [
        "-y",
        "@xueca/code-guardian",
        "--project-root",
        "."
      ]
    }
  }
}

关于 npx -y @xueca/code-guardian：首次使用前需完成方式一中的 scope registry 配置。-y 参数表示自动确认安装。如果你更倾向于使用 node 直接运行，可将 args 替换为 ["./node_modules/@xueca/code-guardian/dist/index.js", "--project-root", "."]。

关于 --project-root：Code Guardian 需要知道项目根目录来定位 .code-guardian.json 配置文件和待检查的文件。如果省略此参数，默认使用 Node.js 进程的当前工作目录（process.cwd()）。对于 Trae 等需要绝对路径的客户端，必须显式指定。

3. 使用

在 AI 对话中直接调用 Tool：

code-guardian:full_health_check({ filePath: "src/views/Home.vue" })
code-guardian:check_file_size({ filePath: "backend/controllers/userController.js" })

工作原理

Code Guardian 是一个基于 JSON-RPC 2.0 协议、通过 stdio 传输的 MCP Server。它的工作流程如下：

AI 编码助手（Client）
  │
  │  JSON-RPC Request（via stdio）
  ▼
index.ts（MCP Server 入口）
  │
  │  解析 --project-root → 定位项目根目录
  │  路由 Tool Name → 对应 handler
  ▼
tools/*.ts（检查执行层）
  │
  │  读取 .code-guardian.json 配置
  │  读取目标文件内容
  │  执行检查逻辑
  ▼
结构化 JSON 报告 → 返回给 AI 编码助手

关键设计决策：

无状态：每次 Tool 调用独立执行，不维护跨调用状态
配置驱动：所有检查参数（行数上限、分层规则、反模式开关）均从 .code-guardian.json 读取，不硬编码
Glob 模式匹配：文件路径通过 glob 模式匹配对应配置项，支持 **/ 和 /** 通配符
Graceful Degradation：ESLint 不可用时（未安装或配置缺失），run_eslint 返回 { ok: true, skipped: true } 而非报错

7 个检查工具

工具	功能	输入	输出
`check_file_size`	检查文件行数是否超限	`filePath`	`{ ok, lines, limit, exceeded }`
`run_eslint`	运行 ESLint 检查	`filePath`	`{ ok, errorCount, warningCount, messages }`
`validate_architecture`	检查分层与依赖方向	`filePath`	`{ ok, issues: [...] }`
`detect_anti_patterns`	扫描 16 种反模式	`filePath`	`{ ok, findings: [...] }`
`check_comment_compliance`	检查注释规范	`filePath`	`{ ok, issues: [...] }`
`full_health_check`	一键运行全部检查	`filePath`	`{ ok, summary, details }`
`auto_fix`	自动修复代码规范问题	`filePath`	`{ ok, summary, fixes, postCheck }`

check_file_size

检查文件是否超过 .code-guardian.json 中 fileSizeLimits 定义的行数上限。使用 glob 模式从上到下匹配，第一个匹配的规则生效。

返回示例：

{
  "ok": true,
  "filePath": "src/views/Home.vue",
  "lines": 165,
  "limit": 200,
  "exceeded": 0
}

匹配逻辑：例如文件 src/views/Home.vue 会依次匹配 fileSizeLimits 中的 glob 模式：

**/controllers/**/*.js → 不匹配，跳过
**/routes/**/*.js → 不匹配，跳过
**/*.vue → 匹配，限制 = 200

run_eslint

对文件运行 ESLint 检查。ESLint 及其插件为可选依赖（peerDependencies），Code Guardian 通过 Module.globalPaths 确保 ESLint 能正确解析插件依赖。支持 ESLint 9 flat config（eslint.config.js）：生成的临时配置会自动将 @eslint/js、eslint-plugin-vue、globals 等裸导入改写为基于项目 node_modules 解析的绝对 file URL，避免从系统临时目录解析失败。

前置条件：项目需安装 eslint 及相关插件，并在 .code-guardian.json 中配置 eslint.configPath 和 eslint.frontendDir。

返回示例：

{
  "ok": true,
  "filePath": "src/views/Home.vue",
  "errorCount": 0,
  "warningCount": 3,
  "messages": [
    { "line": 42, "severity": "warning", "message": "...", "ruleId": "vue/attributes-order" }
  ]
}

如果 ESLint 未安装或配置缺失：

{
  "ok": true,
  "skipped": true,
  "reason": "ESLint 未安装或配置缺失"
}

validate_architecture

检查架构分层合规性，基于 .code-guardian.json 中 architecture.layers 配置：

视图层检查（forbidden）：检测匹配文件中是否包含禁止的 API 调用关键字（如 fetch、axios、EventSource）
依赖方向检查（forbiddenImports）：检测匹配文件中是否 import 了禁止的模块路径前缀
资源泄露检测：检测 composable / views 中是否存在 timer/SSE/AbortController 未配对清理

返回示例：

{
  "ok": false,
  "filePath": "src/views/Home.vue",
  "issues": [
    {
      "type": "forbidden_api_call",
      "message": "视图层禁止直接调用 fetch",
      "line": 42
    }
  ]
}

detect_anti_patterns

扫描 16 种反模式，每种可通过 .code-guardian.json 中 antiPatterns 配置独立开关：

反模式	检测内容	严重程度	配置键
视图层直接 API 调用	.vue 文件中直接调用 fetch/axios/EventSource	P0	`directApiInView`
裸 async 无 catch	async 函数缺少 try-catch 包裹	P0	`bareAsync`
资源未清理	setInterval/EventSource/AbortController 未在 onUnmounted 中清理	P0	`resourceLeak`
模块级状态变量	composable 文件顶层存在模块级响应式状态变量	P1	`moduleLevelState`
组件内长数据转换	组件内存在超过 3 行的链式数据转换（map/filter/reduce）	P1	`longTransformInView`
重复代码块	script 中存在 4 行以上的重复代码块	P2	`duplicateCode`
const 应改 let	声明后重新赋值的变量使用了 const	P2	`constLet`
命名规范	变量/函数命名不符合 camelCase 或 PascalCase 规范	P2	`naming`
同步方法	使用了 fs.writeFileSync 等同步 I/O 方法	P1	`syncMethod`
禁止 fs.promises	应使用 require('fs').promises 而非 fs.promises	P2	`noFsPromises`
下标直接操作	使用 obj['key'] 而非 obj.key 访问属性	P2	`bracketAccess`
JSON 深拷贝	使用 JSON.parse(JSON.stringify()) 进行深拷贝	P2	`deepCopy`
空值保底	缺少 \|\| [] 或 \|\| {} 空值保底	P2	`nullGuard`
数据清洗	在视图层做 API 返回值清洗（应在 composable 中处理）	P1	`dataCleansing`
行尾分号	代码行末尾有多余分号	P2	`semi`
Tab 缩进	使用 Tab 而非空格进行缩进	P2	`indent`

返回示例：

{
  "ok": false,
  "filePath": "src/views/Home.vue",
  "findings": [
    {
      "type": "bareAsync",
      "severity": "P0",
      "message": "async 函数缺少 try-catch 错误处理",
      "line": 28
    }
  ]
}

check_comment_compliance

检查文件头注释和函数注释是否符合项目注释规范（参考 .code-guardian.json 中 commentStandard 配置）：

.vue 文件：检查 HTML 文件头注释（）
.js 文件：检查文件头注释（// 文件功能: xxx | 数据流: xxx）
函数注释：检查函数定义前是否有注释（支持单行 // 和块注释 /** */）

返回示例：

{
  "ok": false,
  "filePath": "src/views/Home.vue",
  "issues": [
    {
      "type": "missing_file_header",
      "message": "缺少文件头注释"
    },
    {
      "type": "missing_function_comment",
      "function": "handleSubmit",
      "line": 42
    }
  ]
}

full_health_check

聚合以上 5 项检查，输出结构化的一键报告：

{
  "ok": false,
  "filePath": "src/views/Home.vue",
  "summary": {
    "fileSize": "✅",
    "eslint": "✅",
    "architecture": "❌",
    "antiPatterns": "❌",
    "comments": "✅"
  },
  "details": {
    "size": { "ok": true, "lines": 165, "limit": 200 },
    "eslint": { "ok": true, "errorCount": 0 },
    "architecture": { "ok": false, "issues": [...] },
    "antiPatterns": { "ok": false, "findings": [...] },
    "comments": { "ok": true, "issues": [] }
  }
}

注意：full_health_check 使用 Promise.all 并行执行 5 项检查，以提高性能。

auto_fix

自动修复代码规范问题。基于 full_health_check 的基线报告，依次应用 4 个修复器，修复后自动进行语法校验和兜底检查。

修复器列表：

修复器	修复内容	是否改变行数
`semi_fixer`	删除行尾多余分号	否
`const_to_let_fixer`	将重新赋值的 const 改为 let	否
`trim_fixer`	添加空值保底 \|\| [] 或 \|\| {}	否
`chain_call_fixer`	拆分过长的链式调用为多行	是（可能增加）

安全机制：

修复前自动创建备份文件，语法校验失败时自动回滚
修复后重新运行 full_health_check 验证修复效果
不可自动修复的问题列入 manualAttention 供手动处理
修复后如果文件超行，在 manualAttention 中给出提示
.vue 文件分段处理：semi 检测/修复排除 <style> 块内 CSS，script 定位按文件级行号，修复写盘前校验 template/style 原样保留，异常时中止不写入

返回示例：

{
  "ok": true,
  "filePath": "src/views/Home.vue",
  "summary": {
    "totalIssues": 5,
    "fixed": 3,
    "skipped": 2,
    "remaining": 2
  },
  "fixes": [
    { "content": "...", "fixed": 2, "skipped": 0 }
  ],
  "syntaxVerified": true,
  "postCheck": { "ok": true, "summary": {...} },
  "manualAttention": [
    { "line": 42, "pattern": "bare-async", "message": "async 函数缺少 try-catch 错误处理" }
  ]
}

配置参考

完整 .code-guardian.json 配置项：

{
  "version": "1.0",
  "fileSizeLimits": {
    "**/controllers/**/*.js": 150,
    "**/routes/**/*.js": 50,
    "**/middleware/**/*.js": 80,
    "**/*.vue": 200,
    "**/*.js": 150
  },
  "architecture": {
    "layers": [
      {
        "name": "views",
        "path": "**/*.vue",
        "forbidden": ["fetch", "axios", "EventSource"]
      },
      {
        "name": "api",
        "path": "**/api/**/*.js",
        "forbiddenImports": ["composables/", "stores/"]
      },
      {
        "name": "composables",
        "path": "**/composables/**/*.js",
        "forbiddenImports": ["views/"]
      },
      {
        "name": "backend",
        "path": "**/controllers/**/*.js",
        "forbiddenImports": ["views/", "stores/", "composables/"]
      }
    ]
  },
  "antiPatterns": {
    "directApiInView": true,
    "longTransformInView": true,
    "bareAsync": true,
    "resourceLeak": true,
    "moduleLevelState": true,
    "duplicateCode": true,
    "constLet": true,
    "naming": true,
    "syncMethod": true,
    "noFsPromises": true,
    "bracketAccess": true,
    "deepCopy": true,
    "nullGuard": true,
    "dataCleansing": true,
    "semi": true,
    "indent": true
  },
  "eslint": {
    "configPath": "frontend/eslint.config.js",
    "frontendDir": "frontend"
  },
  "commentStandard": {
    "fileHeaderRequired": true,
    "functionCommentRequired": true,
    "vueTemplateCommentRecommended": true
  }
}

fileSizeLimits

键：glob 模式，支持 **/ 匹配任意前缀目录，/** 匹配任意后缀目录
值：最大行数（整数）
匹配规则：从上到下，第一个匹配的模式生效。建议将更具体的规则放在前面，通用规则放在最后
默认值（当无匹配时）：**/*.js = 150, **/*.vue = 200
注意：路径分隔符统一使用 /（Windows 路径中的 \ 会被自动转换）

architecture.layers

字段	类型	必填	说明
`name`	`string`	是	分层名称（用于报告中的标识）
`path`	`string`	是	glob 模式，匹配该层包含的文件
`forbidden`	`string[]`	否	禁止在匹配文件中出现的关键字列表
`forbiddenImports`	`string[]`	否	禁止在匹配文件中 import 的路径前缀列表

forbidden 检测：逐行扫描文件内容，检测是否包含禁止关键字。适用于检测直接 API 调用（fetch、axios、EventSource）。

forbiddenImports 检测：扫描 import 语句和 require() 调用，检测是否引用了禁止的模块路径前缀。适用于检测反向依赖。

antiPatterns

每个键值对："检测项名称": true/false
设为 false 可关闭某项检测
默认全部开启
如果配置中缺少某个键，则该检测项默认开启

eslint

字段	类型	必填	说明
`configPath`	`string`	是	ESLint 配置文件相对于项目根目录的路径
`frontendDir`	`string`	是	前端代码目录（`run_eslint` 仅处理此目录下的文件）

commentStandard

字段	类型	默认值	说明
`fileHeaderRequired`	`boolean`	`true`	是否要求文件头注释；`false` 时跳过 .js/.ts/.tsx/.vue 文件头检查
`functionCommentRequired`	`boolean`	`true`	是否要求函数注释；`false` 时跳过函数注释检查
`vueTemplateCommentRecommended`	`boolean`	`true`	是否建议 Vue 模板区域注释；`false` 时不检查模板区域注释

字段缺省或未配置 commentStandard 时按上表默认值生效（与旧版硬编码行为一致）。

与 AI 规则联动

推荐在项目中创建 AI 规则文件，强制 AI 在修改代码时调用 Code Guardian。以下为各 AI 编码助手的规则文件路径：

Trae（.trae/rules/07-mcp-code-guardian.md）：

# MCP Code Guardian 强制调用规则

修改任何 .vue / .js 文件时：
1. 修改前：调用 full_health_check 了解当前状态
2. 修改中：调用 check_file_size 防止超行
3. 修改后：调用 full_health_check 验证无新问题
4. 如果 ok: false，先修复再报告完成

Claude Code（.claude/rules/code-guardian.md）：

# Code Guardian — Mandatory Pre/Post Code Change Checks

Before modifying any .vue / .js file:
- Call code-guardian:full_health_check({ filePath }) to baseline

After modifying:
- Call code-guardian:full_health_check({ filePath }) to verify
- If any check fails, fix before marking task complete

通用规则（适用于 Cursor、Windsurf 等）：将上述规则文件放置在项目的 .cursorrules 或 .windsurfrules 中。

四层防御体系

Code Guardian 设计为多层防御，确保代码质量检查不会遗漏：

层级	机制	触发方式	失败行为
Layer 1	MCP Tools	AI 主动调用	返回 `ok: false` + 详细问题列表
Layer 2	after-write Hook	文件写入后自动触发	`process.exit(1)` 阻止写入
Layer 3	`/review` Command	用户手动触发	输出结构化报告
Layer 4	Husky pre-commit	`git commit` 前触发	阻止提交

Layer 1（MCP Tools） 是最核心的防御层，由 AI 在修改代码前后主动调用，提供即时反馈。

Layer 2（after-write Hook） 是兜底机制，当 AI 忘记调用 Code Guardian 时，文件写入后自动触发检查。实现方式：在 .claude/hooks/after-write.cjs 中调用 code-guardian:full_health_check。

Layer 3（/review Command） 允许用户随时手动触发全面检查，无需等待 AI 自动调用。

Layer 4（Husky pre-commit） 是最后一道防线，在代码提交前确保所有文件通过检查。

运行测试

# 运行所有测试（含编译）
npm run test

# 运行指定测试文件
npm run build && node --test dist/__tests__/check_file_size.test.js

# 带覆盖率
npm run test:coverage

测试框架：Node.js 原生 node:test（无需额外依赖）。

测试文件：

check_file_size.test.ts：文件大小检查
validate_architecture.test.ts：架构合规检查
detect_anti_patterns.test.ts：反模式扫描
auto_fix.test.ts：自动修复
extreme_boundary.test.ts：边界条件极限测试
extreme_detectors.test.ts：检测器极限测试
extreme_config_utils.test.ts：配置工具极限测试
extreme_resource_arch.test.ts：资源与架构极限测试
new_detectors.test.ts：新增检测器测试
mcp_integration.test.ts：MCP 集成测试
eslint_integration.test.ts：真实 ESLint 集成（flat config 裸导入改写）
vue_line_offset.test.ts：.vue script 行号补偿
comment_standard.test.ts：注释规范配置开关

当前共 319 个测试用例（46 个 suite），覆盖检测器、修复器、MCP 入口与真实 ESLint 集成。

项目结构

code-guardian/
├── .code-guardian.json          # 自带默认配置
├── .github/
│   └── workflows/
│       └── ci.yml               # GitHub Actions CI 配置
├── .gitignore                   # Git 忽略规则
├── CHANGELOG.md                 # 变更日志
├── CODE_OF_CONDUCT.md           # 行为准则
├── CONTRIBUTING.md              # 贡献指南
├── SECURITY.md                  # 安全策略
├── index.ts                     # MCP Server 入口（JSON-RPC over stdio）
├── package.json
├── README.md
├── tsconfig.json                # TypeScript 编译配置
├── __tests__/                   # 测试（node:test 框架）
│   ├── check_file_size.test.ts
│   ├── validate_architecture.test.ts
│   ├── detect_anti_patterns.test.ts
│   ├── auto_fix.test.ts
│   ├── extreme_boundary.test.ts
│   ├── extreme_detectors.test.ts
│   ├── extreme_config_utils.test.ts
│   ├── extreme_resource_arch.test.ts
│   ├── new_detectors.test.ts
│   └── mcp_integration.test.ts
└── tools/
    ├── auto_fix.ts                   # 自动修复主入口
    ├── check_file_size.ts            # 行数检查
    ├── check_comment_compliance.ts   # 注释规范检查
    ├── detect_anti_patterns.ts       # 反模式扫描（入口）
    ├── full_health_check.ts          # 一键聚合检查
    ├── run_eslint.ts                 # ESLint 集成
    ├── types.ts                      # 共享类型定义
    ├── validate_architecture.ts      # 架构分层检查
    └── lib/
        ├── ast-parser.ts             # AST 解析引擎
        ├── ast-utils.ts              # AST 遍历工具
        ├── bare_async_detector.ts    # 裸 async 无 catch 检测
        ├── bracket_access_detector.ts # 下标直接操作检测
        ├── config-loader.ts          # 配置加载 + glob 匹配引擎
        ├── config-migrator.ts        # 配置版本迁移
        ├── config-schema.ts          # 配置 schema 校验
        ├── const_let_detector.ts     # const 应改 let 检测
        ├── data_cleansing_detector.ts # 数据清洗检测
        ├── deep_copy_detector.ts     # JSON 深拷贝检测
        ├── direct_api_detector.ts    # 视图层直接 API 调用检测
        ├── duplicate_code_detector.ts # 重复代码块检测
        ├── eslint-helpers.ts         # ESLint 辅助工具
        ├── fix-utils.ts              # 修复工具函数
        ├── function_body.ts          # 函数体提取工具
        ├── indent_detector.ts        # Tab 缩进检测
        ├── logger.ts                 # 日志工具
        ├── long_transform_detector.ts # 组件内长数据转换检测
        ├── module_state_detector.ts  # 模块级状态变量检测
        ├── naming_detector.ts        # 命名规范检测
        ├── no_fs_promises_detector.ts # 禁止 fs.promises 检测
        ├── null_guard_detector.ts    # 空值保底检测
        ├── resource_leak_detector.ts # 资源未清理检测
        ├── semi_detector.ts          # 行尾分号检测
        ├── sync_method_detector.ts   # 同步方法检测
        └── fixers/
            ├── chain_call_fixer.ts   # 链式调用拆分修复器
            ├── const_to_let_fixer.ts # const 转 let 修复器
            ├── semi_fixer.ts         # 行尾分号删除修复器
            └── trim_fixer.ts         # 空值保底修复器

贡献指南

欢迎贡献！请遵循以下流程：

Fork 本仓库
创建分支：git checkout -b feat/your-feature
编写代码：确保通过所有现有测试
添加测试：新功能或 bug 修复需要添加对应测试用例
运行测试：npm run test
提交 PR：提交前请确保：
- 所有测试通过
- 代码符合项目编码规范（文件头注释、函数注释）
- 新工具或配置变更需要更新 README.md

开发环境

# 克隆仓库
git clone https://github.com/xueca/code-guardian.git
cd code-guardian

# 安装依赖
npm install

# 运行测试
npm run test

# 本地测试 MCP Server
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}' | node dist/index.js --project-root .

新增检查工具

在 tools/ 下创建新的检查模块，导出 async function(projectRoot, filePath)
在 tools/lib/ 下创建检测器子模块（如需要）
在 index.ts 中注册工具（添加到 TOOLS 数组和 handleToolCall switch）
在 full_health_check.ts 中集成
在 __tests__/ 中添加测试
更新 README.md 的工具列表

常见问题

Q: Code Guardian 和 ESLint/Prettier 有什么区别？

A: Code Guardian 不是 ESLint 的替代品，而是互补层。ESLint 检查 JavaScript 语法和风格规则，Code Guardian 检查更高层次的架构问题（分层合规、反模式、文件行数）。Code Guardian 的 run_eslint 工具实际上是对 ESLint 的封装，将其集成到 AI 工作流中。

Q: 为什么选择 MCP 协议而不是直接作为 CLI 工具？

A: MCP（Model Context Protocol）是 AI 编码助手的标准协议。通过 MCP Server，AI 可以在修改代码时主动调用检查工具，无需人工干预。这比传统的 CLI 工具（需要手动运行）更高效，也比 Hook 机制（只能被动触发）更灵活。

Q: 必须在每个项目中配置 `.code-guardian.json` 吗？

A: 是的。Code Guardian 的设计原则是"每个项目有自己的编码标准"。.code-guardian.json 允许团队根据项目特点自定义文件行数限制、分层架构规则和反模式开关。Code Guardian 自带一个默认配置作为参考模板。

Q: `run_eslint` 工具报错怎么办？

A: 首先确认项目已安装 ESLint 及其插件：

npm install --save-dev eslint @eslint/js eslint-plugin-vue globals

然后检查 .code-guardian.json 中 eslint.configPath 是否指向了正确的 ESLint 配置文件。如果不需要 ESLint 检查，可以移除 eslint 配置项使其优雅降级。

Q: 如何自定义文件行数限制？

A: 在 .code-guardian.json 的 fileSizeLimits 中添加或修改 glob 模式。例如，如果希望 Vue 组件的行数上限为 300 行：

{
  "fileSizeLimits": {
    "**/*.vue": 300
  }
}

注意：规则从上到下匹配，第一个匹配的生效。建议将更具体的规则放在前面。

Q: 如何关闭某个反模式检测？

A: 在 .code-guardian.json 的 antiPatterns 中将对应检测项设为 false：

{
  "antiPatterns": {
    "duplicateCode": false
  }
}

Q: 支持哪些文件类型？

A: 支持 .vue、.js、.ts、.tsx 文件。ESLint 和注释检查针对 .vue 和 .js 文件功能完整，.ts / .tsx 文件的 check_file_size、validate_architecture、detect_anti_patterns 均可正常工作。

License

MIT

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivitySlowing

ResponsivenessNo issues

Resources

Need Help?

Related Servers

Related MCP Connectors

OpenZeppelin Solidity Contracts A
com.openzeppelin.mcp
The OpenZeppelin Solidity Contracts MCP server integrates OpenZeppelin's security and style rules into AI-driven development workflows, enabling AI assistants to generate safe, correct, and production-ready smart contracts. It automatically validates generated code against OpenZeppelin standards (including imports, modifiers, naming conventions, and security checks) and supports various contract types including ERC-20, ERC-721, ERC-1155, Stablecoins, RWA, Governor, and Account contracts through prompt-driven workflows.
Developer Tools Blockchain Code Analysis
82
anotherai
dev.anotherai
MCP server for building and testing AI agents with multi-model experimentation and insights.
Agent Orchestration Autonomous Agents Testing & QA Tools
2
secureflows-mcp A
io.github.michal-lefler
MCP server for secureFlows: token-free URL builders and integration-linting tools for AI agents.
Code Analysis Developer Tools Security
181
noteit-mcpOAuth
io.github.bahfahh
MCP server for AI agent profiles and smart notes. 60+ coding prompt packs with expert personas.
Note Taking Developer Tools Coding Agents
25

Related MCP Servers

code-review-mcp
Code Analysis Developer Tools
AlanNiew
A
license
A
quality
D
maintenance
An MCP server that provides local code quality analysis for AI coding assistants, supporting file analysis, git diff review, and full project scanning with quality scoring.
Updated 3 months ago (2026-06-18 03:29 UTC)
4
3
MIT
Deslopify
veroxsity
-
license
Not graded
quality
Not graded
maintenance
A universal MCP server that acts as a code quality gate for AI assistants, providing pre-generation guidance, post-generation review, and root cause analysis to improve code quality.
Updated 6 months ago (2026-03-31 00:44 UTC)
-
S.C.R.U.B.
Code Analysis Developer Tools CI/CD & DevOps
zombat
A
license
Not graded
quality
C
maintenance
A code quality MCP server with 22 tools for deterministic linting, formatting, security scanning, and AI-assisted improvements, designed to reduce cloud LLM costs and enforce best practices.
Updated 6 months ago (2026-03-30 14:47 UTC)
1
MIT
Scopewalker MCP
Code Analysis Developer Tools
timohaa
A
license
B
quality
A
maintenance
MCP server providing codebase analysis tools for AI assistants, including line counts, function metrics, threshold checks, and code quality detection.
Updated a day ago (2026-09-15 09:19 UTC)
9
72 npm
MIT

Code Guardian

目录

前置要求

安装

方式一：从 GitHub Packages 安装（推荐）

方式二：从 GitHub 源码安装

方式三：本地开发安装

快速开始

1. 创建项目配置文件

2. 配置 MCP 客户端

3. 使用

工作原理

7 个检查工具

check_file_size

run_eslint

validate_architecture

detect_anti_patterns

check_comment_compliance

full_health_check

auto_fix

配置参考

fileSizeLimits

architecture.layers

antiPatterns

eslint

commentStandard

与 AI 规则联动

四层防御体系

运行测试

项目结构

贡献指南

开发环境

新增检查工具

常见问题

Q: Code Guardian 和 ESLint/Prettier 有什么区别？

Q: 为什么选择 MCP 协议而不是直接作为 CLI 工具？

Q: 必须在每个项目中配置 .code-guardian.json 吗？

Q: run_eslint 工具报错怎么办？

Q: 如何自定义文件行数限制？

Q: 如何关闭某个反模式检测？

Q: 支持哪些文件类型？

License

Maintenance

Resources

Related MCP Connectors

Related MCP Servers

code-review-mcp

Deslopify

S.C.R.U.B.

Scopewalker MCP

Q: 必须在每个项目中配置 `.code-guardian.json` 吗？

Q: `run_eslint` 工具报错怎么办？