Skip to main content
Glama

Skill Quality MCP

一个 MCP 服务 + 一个 Agent Skill,给 Cursor 和 Codex 装上“质检员”

检查 Agent Skill 写得对不对 · 依赖有没有坑 · 代码里藏了哪些 Bug · SonarQube 门禁过没过

License Python MCP Cursor Plugin Codex Plugin SonarQube Stars

快速开始 · 能做什么 · 报告示例 · 工具清单 · SonarQube · 常见问题 · English


能做什么

Agent Skills 检查

  • SKILL.md frontmatter:name 格式、与目录名一致、description 长度和触发词

  • 正文是否超过 500 行

  • 失效的相对链接和 #锚点

  • 文中提到的脚本 / 文件是否真的存在

  • 本机多个技能重名

依赖分析

  • Python:装没装、写没写进 requirements.txt / pyproject.toml,sys.path 私有目录、循环依赖

  • npm:缺失 / 没声明 / 没用到的包,支持 monorepo、tsconfig paths、Vite 别名,读 lock 文件版本

  • Maven / Gradle:属性、dependencyManagement、Spring Boot 父 POM、版本目录、重复声明

  • Go modules / Composer / NuGet:没写进 go.mod 的导入、vendor、Directory.Packages.props

  • OSV 已知漏洞(PyPI、npm、Maven、Go、Packagist、NuGet),并给出建议升级的版本

Bug 检测与代码质量

  • 支持 Python、JS / TS、React、Vue、Svelte、Java / Spring、Kotlin、Go、C#、PHP

  • 70+ 条本地规则:Bug、漏洞、安全热点、代码异味,外加 Spring 配置和 MyBatis Mapper 检查

  • 认知复杂度、超长函数、重复代码、技术债,按 SonarQube 口径给出 A–E 评级

  • 项目里装了 ESLint、ruff、go 时自动合并 ESLint / ruff / go vet 的结果

  • scope=changed 只扫当前未提交的改动(不限语言;内置规则没覆盖的文件会点名,交给调用方按该语言修改)

SonarQube / SonarCloud

  • 拉取未解决的问题、安全热点

  • 项目指标与质量门禁状态

  • 用 sonar-scanner(或 npx)扫描并上传

  • 没配置也能用,报告自动只用本地规则

Related MCP server: tar-engine

工作原理

flowchart LR
    U["你在 Cursor / Codex 里说:<br/>检查一下这个 skill"] --> S["插件自带的 Skill<br/>告诉 Agent 该调哪个工具"]
    S --> M(("skill-quality<br/>MCP 服务"))
    M --> A["Skills 结构检查"]
    M --> B["依赖分析 + OSV 漏洞库"]
    M --> C["本地 Bug / 质量扫描<br/>(+ ESLint / ruff / go vet)"]
    M --> D["SonarQube API<br/>(可选)"]
    A & B & C & D --> R["一份 Markdown 报告<br/>通过 / 有警告 / 未通过"]

快速开始

NOTE

唯一前提:Python 3.10+ 在 PATH 上(Windows 安装时勾选 “Add to PATH”)。MCP SDK 等依赖会自动安装。

一行命令,同时装进 Cursor 和 Codex

Windows(PowerShell)

irm https://raw.githubusercontent.com/LoveMuZiLi/skill-quality-mcp/main/install.ps1 | iex

macOS / Linux

curl -fsSL https://raw.githubusercontent.com/LoveMuZiLi/skill-quality-mcp/main/install.sh | bash

装完之后:Cursor 里运行 Developer: Reload Window;Codex 新开一个对话。

TIP

直连不了 github.com?Windows 脚本会自动沿用系统代理;macOS / Linux 先执行export HTTPS_PROXY=http://127.0.0.1:7890(换成你的代理端口)。

只装其中一边

codex plugin marketplace add LoveMuZiLi/skill-quality-mcp
codex plugin add skill-quality@skill-quality-mcp

或者用安装脚本:Windows 加 -CodexOnly,macOS / Linux 加 --codex-only。

方式一:插件(MCP + Skill,推荐)

把仓库里的 plugins/skill-quality 整个复制到:

系统

目录

Windows

%USERPROFILE%\.cursor\plugins\local\skill-quality

macOS / Linux

~/.cursor/plugins/local/skill-quality

然后 Developer: Reload Window。必须是真实复制,指向别处的符号链接会被 Cursor 忽略。也可以用安装脚本:Windows 加 -CursorOnly,macOS / Linux 加 --cursor-only。

方式二:一键只装 MCP(需要先装 uv)

Add to Cursor

cursor.directory 的「添加到 Cursor」读的是仓库里的 .mcp.json,内容和上面这个按钮一样,都是 uvx。添加前先装好 uv,并确认新开的终端里 uvx --version 能通过。Windows 上如果是 Cursor 已经打开之后才装的 uv,要完全退出 Cursor 再打开,否则仍然会报找不到 uvx。

方式三:手写 MCP 配置(同样需要先装 uv,命令行里能运行 uvx --version)

打开 Cursor Settings → MCP,添加全局 MCP,或直接编辑配置文件:

系统

文件

Windows

%USERPROFILE%\.cursor\mcp.json

macOS / Linux

~/.cursor/mcp.json

把下面这段写入该文件。已有别的服务时,只把 "skill-quality" 这一段合并进现有的 mcpServers,不要整文件覆盖。

{
  "mcpServers": {
    "skill-quality": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/LoveMuZiLi/skill-quality-mcp",
        "skill-quality-mcp"
      ]
    }
  }
}

uvx 会从 GitHub 拉最新代码并启动,不用先 pip install。保存后在 MCP 面板里刷新 skill-quality。第一次启动要下载依赖,稍等即可。

NOTE

报错'uvx' 不是内部或外部命令:本机还没装 uv,或 Cursor 是在安装 uv 之前打开的,没读到新的 PATH。先安装 uv,完全退出 Cursor 再打开。仍找不到时,把 command 改成 uvx 的绝对路径,例如 Windows:C:\\Users\\你的用户名\\.local\\bin\\uvx.exe。

pip install git+https://github.com/LoveMuZiLi/skill-quality-mcp
{
  "mcpServers": {
    "skill-quality": { "command": "skill-quality-mcp" }
  }
}

不想安装,也可以用 uv 直接运行:

{
  "mcpServers": {
    "skill-quality": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/LoveMuZiLi/skill-quality-mcp", "skill-quality-mcp"]
    }
  }
}

怎么用

装好后不用记工具名,直接在 Cursor / Codex 对话里说:

  • “检查一下 drama-commentary 这个 skill 的质量”

  • “扫描 D:\project 的 bug 和依赖漏洞”

  • “这个项目的 SonarQube 质量门禁过了吗?”

  • “列出我电脑上所有的 skill,看看有没有重名的”

插件自带的 Skill 会引导 Agent:先出报告 → 按严重度列问题 → 你同意后再改 → 改完重跑对比。

报告长什么样

下面是对一个故意埋了 Bug 的测试文件跑 full_quality_report 的真实输出(节选):

结论:未通过。本地扫描发现 9 个严重 Bug/漏洞;依赖未完整声明;3 个安全热点待人工确认

1 个文件、32 行代码、5 个函数;重复行 0.0%;技术债约 55 分钟(5.7%)

可靠性

安全性

可维护性

Bug

漏洞

安全热点

代码异味

C

D

B

8

2

3

7

严重度

类型

规则

位置

说明

CRITICAL

漏洞

python:S2068

buggy.py:6

API_TOKEN 疑似硬编码密钥/密码,改为环境变量读取

CRITICAL

漏洞

python:S4830

buggy.py:38

verify=False 关闭了 TLS 证书校验

MAJOR

Bug

python:S5905

buggy.py:17

assert 一个元组永远为真,括号写错了

MAJOR

Bug

python:S1143

buggy.py:33

finally 里的 return/break/continue 会吞掉正在抛出的异常

MAJOR

Bug

local:duplicate-def

buggy.py:41

函数 fetch 在同一作用域重复定义,前一个被覆盖

…

工具清单

分类

工具

作用

一站式

full_quality_report

技能结构 + 依赖 + 本地扫描 + SonarQube,给出 通过 / 有警告 / 未通过

Skills

list_skills

列出 Cursor、Codex、Claude 用户目录和插件里的所有技能,提示重名

inspect_skill

检查单个技能的结构

依赖

analyze_dependencies

依赖分析;check_vulnerabilities=true 时联网查 OSV

代码质量

code_quality_scan

本地 Bug 检测和 A–E 评级。scope=changed 只查当前未提交改动,并标出内置规则没覆盖的语言

SonarQube

sonar_check_connection

检查配置和连通性

sonar_issues

拉取未解决的问题,可按类型、严重度筛选

sonar_project_metrics

指标与质量门禁

sonar_run_scan

扫描并上传(没装 sonar-scanner 时可 use_npx=true)

另附提示词 review_skill:先出报告,再按严重度给修复方案。

省 token 的输出方式:默认返回简版:各类计数完整,问题只逐条列前 15 条(漏洞 → Bug → 安全热点 → 代码异味),其余按规则给出条数;全部明细写进文件,末尾给出路径,Agent 需要时再读。传 detail=true 直接返回完整版。同一份 125 个文件的代码库,简版约 1k token;工具描述本身约 1.2k token。

所有语言共用:认知复杂度 > 15(S3776)、超长函数(S138,JS/TS 200 行,其他 100 行)、参数 > 7 个(S107)、超长文件(S104)、硬编码密钥(S2068)、SQL 拼接(S2077)、明文 HTTP(S5332)、重复字符串(S1192)、空 catch(S2486)、自赋值(S1656)、两侧相同的表达式(S1764)、未用的 import(S1128)、超长行(S103)、TODO(S1135)、重复代码。

语言

专有规则

Python

不可达代码、finally 里 return、is 比较字面量、assert 元组、裸 except、== None、可变默认参数、重复定义、未用变量、f-string 无占位符、open() 不指定编码、yaml.load / pickle.load、verify=False

JavaScript / TypeScript

eval / new Function、debugger、var、==、innerHTML / document.write XSS、rejectUnauthorized: false、弱哈希 / 弱加密、child_process、CORS *、空 .catch()、console.log、any、@ts-ignore

React

Hook 写在条件 / 循环里(S6440)、useEffect(async …)、直接改 this.state、key={index}、map 生成的元素没有 key、dangerouslySetInnerHTML、target="_blank" 没加 rel、<img> 缺 alt

Vue / Svelte

v-html / {@html}、v-for 没有 :key、下标做 key、v-if 与 v-for 同用、data 写成对象

Java / Spring

System.out、printStackTrace、catch Throwable、字符串 ==、new BigDecimal(double)、static SimpleDateFormat、@Transactional 加在 private 方法、字段注入、日志字符串拼接、反序列化、空的 checkServerTrusted、MD5 / DES / ECB、Runtime.exec、@CrossOrigin("*");application.yml 明文密码、MyBatis ${} 注入

Kotlin

!! 非空断言,以及 JVM 通用的加密 / 命令执行 / CORS 规则

Go

InsecureSkipVerify、md5 / sha1、exec.Command、DES / RC4

C#

证书回调返回 true、MD5 / SHA1 / DES、Process.Start、BinaryFormatter、async void、AllowAnyOrigin;appsettings.json 明文密码

PHP

eval、exec / system、unserialize、md5、var_dump、mysql_*、echo $_GET XSS、关闭 cURL 证书校验

测试文件不报安全类问题、重复字符串和超长函数,也不计入重复率;dist、build、target、vendor、node_modules 和带 sourcemap 的编译产物不扫描。

SonarQube 配置(可选)

设置下面的系统环境变量,然后重启 Cursor / Codex:

变量

说明

SONAR_HOST_URL

如 http://localhost:9000;SonarCloud 用 https://sonarcloud.io

SONAR_TOKEN

SonarQube → My Account → Security 生成

SONAR_PROJECT_KEY

默认项目 key,工具参数可覆盖

SONAR_ORGANIZATION

只有 SonarCloud 需要

SONAR_SCANNER

sonar-scanner 不在 PATH 时填完整路径

SKILL_DIRS

额外的技能搜索目录,多个用系统路径分隔符隔开

Windows(PowerShell,永久生效)

setx SONAR_HOST_URL "http://localhost:9000"
setx SONAR_TOKEN "squ_xxxxxxxxxxxxxxxx"
setx SONAR_PROJECT_KEY "my-project"

macOS / Linux(写进 ~/.zshrc 或 ~/.bashrc)

export SONAR_HOST_URL="http://localhost:9000"
export SONAR_TOKEN="squ_xxxxxxxxxxxxxxxx"
export SONAR_PROJECT_KEY="my-project"

还没有 SonarQube?本地起一个:docker run -d -p 9000:9000 sonarqube:community

常见问题

运行 Developer: Reload Window,然后在 Customize 里确认 skill-quality 插件已启用。Enterprise 团队需要管理员开启 Allow Local Plugin Imports。

插件用 python 命令启动。安装脚本会自动把 Cursor 插件里的命令改成你机器上的 python3;Codex 插件需要 python 可用:

ln -s "$(command -v python3)" ~/.local/bin/python

本地规则是 SonarQube 同名规则的近似实现(Python 用语法树,其他语言用词法分析加模式匹配),覆盖日常前后端技术栈,适合没有 SonarQube 时快速自查,不需要装任何额外工具。配置了 SonarQube 后,报告会同时列出两边的结果,以 SonarQube 为准。想要更全的规则,在项目里装好 ESLint 并写好配置,会自动合并它的结果。

重新运行一次安装命令即可,Cursor 和 Codex 会一起更新到最新版。

仓库结构

skill-quality-mcp/
├── .mcp.json                            cursor.directory 仓库根目录安装配置(uvx)
├── .cursor-plugin/marketplace.json      Cursor 插件市场清单
├── .agents/plugins/marketplace.json     Codex 插件市场清单
├── plugins/skill-quality/
│   ├── .cursor-plugin/plugin.json       Cursor 插件清单
│   ├── .codex-plugin/plugin.json        Codex 插件清单
│   ├── mcp.json                         Cursor 的 MCP 启动配置
│   ├── .mcp.json                        cursor.directory 读取的安装配置(uvx)
│   ├── codex-mcp.json                   Codex 插件的本地启动配置
│   ├── server.py                        启动入口(缺 mcp 时自动安装)
│   ├── skill_quality_mcp/               MCP 服务源码
│   └── skills/skill-quality/SKILL.md    教 Agent 何时、如何调用这些工具
├── pyproject.toml                       pip / uvx 安装
├── install.ps1                          Windows 一行安装
└── install.sh                           macOS / Linux 一行安装

English

Skill Quality MCP is an MCP server bundled with an Agent Skill, packaged as both a Cursor plugin and a Codex plugin. It checks Agent Skills (frontmatter, broken links and anchors, missing referenced files), analyzes dependencies for Python, npm, Maven, Gradle, Go modules, Composer and NuGet (missing / undeclared / unused packages, OSV vulnerabilities with fix versions), runs 70+ local bug and code-quality rules for Python, JavaScript / TypeScript, React, Vue, Svelte, Java / Spring, Kotlin, Go, C# and PHP with SonarQube-style A–E ratings (merging ESLint, ruff and go vet results when available), and optionally pulls issues, metrics and quality gates from SonarQube / SonarCloud.

# Windows
irm https://raw.githubusercontent.com/LoveMuZiLi/skill-quality-mcp/main/install.ps1 | iex
# macOS / Linux
curl -fsSL https://raw.githubusercontent.com/LoveMuZiLi/skill-quality-mcp/main/install.sh | bash
# Codex only
codex plugin marketplace add LoveMuZiLi/skill-quality-mcp && codex plugin add skill-quality@skill-quality-mcp

Cursor only, after uv is installed (uvx must be on PATH; restart Cursor if it was already open). Put this in %USERPROFILE%\.cursor\mcp.json on Windows, or ~/.cursor/mcp.json on macOS / Linux. Merge the skill-quality entry if the file already has other servers.

{
  "mcpServers": {
    "skill-quality": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/LoveMuZiLi/skill-quality-mcp",
        "skill-quality-mcp"
      ]
    }
  }
}

License

MIT © LoveMuZiLi

Available Tools

9 tools
analyze_dependenciesA
Read-only

依赖分析:Python(requirements/pyproject)、npm(package.json,含 monorepo)、Maven、Gradle、Go modules、Composer、NuGet。 检查包装没装、用了没声明、声明了没用、重复声明、循环依赖、外部命令是否在 PATH。 check_vulnerabilities:联网查 OSV 漏洞(按锁文件 / 已装版本)。detail:列出每个包的版本、使用文件和全部漏洞编号。

Inputs: path (required), detail, check_vulnerabilities.

code_quality_scanA
Read-only

本地 Bug 与代码质量扫描(无需 SonarQube):Python、JS/TS、React、Vue、Svelte、Java、Kotlin、Go、C#、PHP, 外加 Spring/.NET 配置里写死的密码和 MyBatis ${} 拼接;给出 Bug、漏洞、安全热点、异味、复杂度、重复、技术债和 A–E 评级。 use_linters:合并已装的 ruff、项目里的 ESLint(会加载项目的 ESLint 配置)、go vet。max_issues:简版列出的重要问题条数。detail:列出全部问题。

Inputs: path (required), detail, max_issues, use_linters.

full_quality_reportA

一站式报告:Skill 结构(目标是技能时)+ 依赖 + 本地扫描 + SonarQube,给出 通过/有警告/未通过。 sonar:auto=已配置就拉结果,scan=先扫描再拉,off=不用。check_vulnerabilities:联网查 OSV。 detail:返回完整报告。save_to:完整报告另存路径(.md)。

Inputs: target (required), sonar, detail, save_to, +1 more.

inspect_skillB
Read-only

检查一个 Agent Skill 的结构:frontmatter、正文长度、失效链接/锚点、文中引用的文件。skill:技能名或路径。

Inputs: skill (required), detail.

list_skillsA
Read-only

列出本机 Agent Skills(Cursor、Codex、Claude 用户目录、插件、SKILL_DIRS),区分同名冲突与镜像。 query:按名称/描述过滤,结果带描述和路径。extra_dirs:额外目录,逗号分隔。detail:全部带描述。

Inputs: query, detail, extra_dirs.

sonar_check_connectionA
Read-only

检查 SonarQube/SonarCloud 配置、连通性、令牌和 sonar-scanner 是否可用。

Inputs: no named parameters.

sonar_issuesA
Read-only

拉取 SonarQube 未解决问题。types:BUG,VULNERABILITY,CODE_SMELL;severities:BLOCKER..INFO,空为全部; project_key 空则用 SONAR_PROJECT_KEY。

Inputs: limit, types, detail, severities, +1 more.

sonar_project_metricsC
Read-only

SonarQube 项目指标:质量门禁、三项评级、Bug/漏洞/异味数、覆盖率、重复率。

Inputs: project_key.

sonar_run_scanB

用 sonar-scanner 扫描并上传到 SonarQube,等待分析完成。没装扫描器可 use_npx=true(首次会下载)。

Inputs: path (required), use_npx, project_key.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.4/5.0

    Scored across 9 tools

    Disambiguation4/5

    Most tools have clearly distinct purposes: skill listing/inspection, dependency analysis, local scanning, and a cohesive sonar_* cluster. Some overlap exists between code_quality_scan and sonar_issues (both surface bugs) and between sonar_issues and sonar_project_metrics, and full_quality_report aggregates the others, but descriptions clarify local vs. Sonar and aggregate vs. individual.

    Naming Consistency4/5

    All snake_case throughout, with a predictable pattern: list_/inspect_/analyze_ verbs, sonar_-prefixed cluster, and full_quality_report. Minor deviation where code_quality_scan and sonar_project_metrics use noun-adjective ordering rather than verb_noun, but the grouping remains readable.

    Tool Count4/5

    Nine tools is well within the ideal 3-15 range and each earns its place across skill, dependency, local scan, and Sonar workflows. The aggregate report tool is arguably redundant with the individual tools, but it serves a distinct one-shot use case.

    Completeness4/5

    The surface covers the full quality-check lifecycle: discover skills, inspect structure, analyze dependencies, scan locally, configure and query Sonar, and produce a consolidated pass/fail report. Minor gaps exist (e.g. no dedicated tool to fix or auto-remediate skill structure issues, no cross-skill content search), but core workflows have no dead ends.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      B
      maintenance
      Audits AI agent skills for safety using static, semantic, adversarial, and supply-chain analysis, providing scores and risk flags. Can be run via CLI, CI, or as an MCP tool from Claude Code, Cursor, and Codex.
      5
      170 PyPI
      2
      Apache 2.0
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables authorized security auditing of AI-agent supply chains and agent-facing surfaces: deterministic local skill-bundle audits against eight attack patterns, secrets scanning, and scope-gated read-only recon of agent endpoints and MCP surfaces.
      MIT
    • F
      license
      Not graded
      quality
      B
      maintenance
      Enables AI coding agents to inspect a project's design tokens and component catalog, audit React/Tailwind files against seven static UI quality rules, score overall UI health, and apply auto-fixes that are re-audited and reverted on regression. It works both locally over filesystem access and remotely on raw TSX/JSX or CSS snippets passed directly as strings.
      -