Skill Quality MCP
<!-- mcp-name: io.github.LoveMuZiLi/skill-quality-mcp -->
<div align="center">
<img src="https://raw.githubusercontent.com/LoveMuZiLi/skill-quality-mcp/main/plugins/skill-quality/assets/logo.svg" width="96" alt="Skill Quality logo">
# Skill Quality MCP
**一个 MCP 服务 + 一个 Agent Skill,给 Cursor 和 Codex 装上“质检员”**
检查 Agent Skill 写得对不对 · 依赖有没有坑 · 代码里藏了哪些 Bug · SonarQube 门禁过没过
[](LICENSE)
[](https://www.python.org/downloads/)
[](https://modelcontextprotocol.io)
[](#cursor)
[](#codex)
[](#sonarqube-配置可选)
[](https://github.com/LoveMuZiLi/skill-quality-mcp/stargazers)
[快速开始](#快速开始) · [能做什么](#能做什么) · [报告示例](#报告长什么样) · [工具清单](#工具清单) · [SonarQube](#sonarqube-配置可选) · [常见问题](#常见问题) · [English](#english)
</div>
---
## 能做什么
<table>
<tr>
<td width="50%" valign="top">
### Agent Skills 检查
- `SKILL.md` frontmatter:`name` 格式、与目录名一致、`description` 长度和触发词
- 正文是否超过 500 行
- 失效的相对链接和 `#锚点`
- 文中提到的脚本 / 文件是否真的存在
- 本机多个技能重名
</td>
<td width="50%" valign="top">
### 依赖分析
- **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),并给出建议升级的版本
</td>
</tr>
<tr>
<td width="50%" valign="top">
### Bug 检测与代码质量
- 支持 **Python、JS / TS、React、Vue、Svelte、Java / Spring、Kotlin、Go、C#、PHP**
- 70+ 条本地规则:Bug、漏洞、安全热点、代码异味,外加 Spring 配置和 MyBatis Mapper 检查
- 认知复杂度、超长函数、重复代码、技术债,按 SonarQube 口径给出 **A–E 评级**
- 项目里装了 [ESLint](https://eslint.org/)、[ruff](https://docs.astral.sh/ruff/)、go 时自动合并 ESLint / ruff / go vet 的结果
- `scope=changed` 只扫当前未提交的改动(不限语言;内置规则没覆盖的文件会点名,交给调用方按该语言修改)
</td>
<td width="50%" valign="top">
### SonarQube / SonarCloud
- 拉取未解决的问题、安全热点
- 项目指标与**质量门禁**状态
- 用 sonar-scanner(或 npx)扫描并上传
- 没配置也能用,报告自动只用本地规则
</td>
</tr>
</table>
## 工作原理
```mermaid
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)
```powershell
irm https://raw.githubusercontent.com/LoveMuZiLi/skill-quality-mcp/main/install.ps1 | iex
```
**macOS / Linux**
```bash
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`(换成你的代理端口)。
### 只装其中一边
<details id="codex">
<summary><b>Codex</b></summary>
```bash
codex plugin marketplace add LoveMuZiLi/skill-quality-mcp
codex plugin add skill-quality@skill-quality-mcp
```
或者用安装脚本:Windows 加 `-CodexOnly`,macOS / Linux 加 `--codex-only`。
</details>
<details id="cursor">
<summary><b>Cursor</b></summary>
**方式一:插件(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](https://docs.astral.sh/uv/))
[](https://cursor.com/en/install-mcp?name=skill-quality&config=eyJjb21tYW5kIjoidXZ4IiwiYXJncyI6WyItLWZyb20iLCJnaXQraHR0cHM6Ly9naXRodWIuY29tL0xvdmVNdVppTGkvc2tpbGwtcXVhbGl0eS1tY3AiLCJza2lsbC1xdWFsaXR5LW1jcCJdfQ%3D%3D)
[cursor.directory](https://cursor.directory/plugins/skill-quality-mcp) 的「添加到 Cursor」读的是仓库里的 `.mcp.json`,内容和上面这个按钮一样,都是 `uvx`。添加前先装好 [uv](https://docs.astral.sh/uv/),并确认新开的终端里 `uvx --version` 能通过。Windows 上如果是 Cursor 已经打开之后才装的 uv,要完全退出 Cursor 再打开,否则仍然会报找不到 `uvx`。
**方式三:手写 MCP 配置**(同样需要先装 [uv](https://docs.astral.sh/uv/),命令行里能运行 `uvx --version`)
打开 **Cursor Settings → MCP**,添加全局 MCP,或直接编辑配置文件:
| 系统 | 文件 |
| --- | --- |
| Windows | `%USERPROFILE%\.cursor\mcp.json` |
| macOS / Linux | `~/.cursor/mcp.json` |
把下面这段写入该文件。已有别的服务时,只把 `"skill-quality"` 这一段合并进现有的 `mcpServers`,不要整文件覆盖。
```json
{
"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`。
</details>
<details>
<summary><b>其他 MCP 客户端</b>(Claude Desktop、Windsurf、VS Code…)</summary>
```bash
pip install git+https://github.com/LoveMuZiLi/skill-quality-mcp
```
```json
{
"mcpServers": {
"skill-quality": { "command": "skill-quality-mcp" }
}
}
```
不想安装,也可以用 uv 直接运行:
```json
{
"mcpServers": {
"skill-quality": {
"command": "uvx",
"args": ["--from", "git+https://github.com/LoveMuZiLi/skill-quality-mcp", "skill-quality-mcp"]
}
}
}
```
</details>
## 怎么用
装好后不用记工具名,直接在 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。
<details>
<summary><b>本地检测规则一览</b>(规则 ID 近似对应 SonarQube 同名规则)</summary>
所有语言共用:认知复杂度 > 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 的编译产物不扫描。
</details>
## 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` | 额外的技能搜索目录,多个用系统路径分隔符隔开 |
<details>
<summary>设置示例</summary>
**Windows**(PowerShell,永久生效)
```powershell
setx SONAR_HOST_URL "http://localhost:9000"
setx SONAR_TOKEN "squ_xxxxxxxxxxxxxxxx"
setx SONAR_PROJECT_KEY "my-project"
```
**macOS / Linux**(写进 `~/.zshrc` 或 `~/.bashrc`)
```bash
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`
</details>
## 常见问题
<details>
<summary><b>装完在 Cursor 里看不到?</b></summary>
运行 **Developer: Reload Window**,然后在 **Customize** 里确认 `skill-quality` 插件已启用。Enterprise 团队需要管理员开启 **Allow Local Plugin Imports**。
</details>
<details>
<summary><b>macOS / Linux 提示找不到 python?</b></summary>
插件用 `python` 命令启动。安装脚本会自动把 Cursor 插件里的命令改成你机器上的 `python3`;Codex 插件需要 `python` 可用:
```bash
ln -s "$(command -v python3)" ~/.local/bin/python
```
</details>
<details>
<summary><b>本地规则和 SonarQube 结果有什么区别?</b></summary>
本地规则是 SonarQube 同名规则的近似实现(Python 用语法树,其他语言用词法分析加模式匹配),覆盖日常前后端技术栈,适合没有 SonarQube 时快速自查,不需要装任何额外工具。配置了 SonarQube 后,报告会同时列出两边的结果,以 SonarQube 为准。想要更全的规则,在项目里装好 ESLint 并写好配置,会自动合并它的结果。
</details>
<details>
<summary><b>怎么升级?</b></summary>
重新运行一次安装命令即可,Cursor 和 Codex 会一起更新到最新版。
</details>
## 仓库结构
```text
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.
```bash
# 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](https://docs.astral.sh/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.
```json
{
"mcpServers": {
"skill-quality": {
"command": "uvx",
"args": [
"--from",
"git+https://github.com/LoveMuZiLi/skill-quality-mcp",
"skill-quality-mcp"
]
}
}
}
```
## License
[MIT](LICENSE) © LoveMuZiLi
TDQS
Scored across 9 tools
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.
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.
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.
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.