Skill Quality MCP

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

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

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

能做什么

Agent Skills 检查

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

• 正文是否超过 500 行

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

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

• 本机多个技能重名

依赖分析

• 第三方包：装没装、写没写进 requirements.txt / pyproject.toml

• 声明了却没用到的包

• 代码自己往 sys.path 塞的私有目录（换机器就失效）

• 模块循环依赖、外部命令（ffmpeg、git…）是否在 PATH

• OSV 已知漏洞，并给出建议升级的版本

Bug 检测与代码质量

• 28 条本地规则：Bug、漏洞、安全热点、代码异味

• 认知复杂度、超长函数、重复代码、技术债

• 按 SonarQube 口径给出 A–E 评级

• 装了 ruff 会自动合并它的结果

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/>（+ ruff）"]
    M --> D["SonarQube API<br/>（可选）"]
    A & B & C & D --> R["一份 Markdown 报告<br/>通过 / 有警告 / 未通过"]

快速开始

一行命令，同时装进 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 新开一个对话。

只装其中一边

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 整个复制到：

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

方式二：一键只装 MCP（需要先装 uv）

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 在同一作用域重复定义，前一个被覆盖
…

工具清单

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

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

SonarQube 配置（可选）

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

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

本地规则只覆盖 Python，是 SonarQube 同名规则的近似实现，适合没有 SonarQube 时快速自查。配置了 SonarQube 后，报告会同时列出两边的结果，以 SonarQube 为准。其他语言请用 SonarQube。

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

仓库结构

skill-quality-mcp/
├── .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                        Codex 的 MCP 启动配置
│   ├── 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 (missing / undeclared / unused packages, OSV vulnerabilities with fix versions), runs 28 local bug and code-quality rules with SonarQube-style A–E ratings, 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

License

MIT © LoveMuZiLi