内容
# 技能MP MCP服务器（精简版）
一个轻量级的MCP服务器，使AI助手能够从[技能MP](https://skillsmp.com)市场搜索和读取技能。
## 功能
- **关键词搜索** — 通过短关键词查找技能（例如“PDF”，“网页爬虫”）
- **AI语义搜索** — 使用自然语言查找技能，由Cloudflare AI提供支持
- **读取技能** — 通过REST API从GitHub获取技能内容（无需`git clone`，无需本地文件）
- **安全扫描** — 通过内存ZIP上传自动进行[Cisco Skill Scanner](https://github.com/cisco/ai-skill-scanner)分析（零磁盘写入）
## 先决条件
| 要求 | 目的 | 是否必需 |
|---|---|---|
| Node.js ≥ 20 | 运行环境 | 是 |
| [技能MP API密钥](https://skillsmp.com/docs/api) | 身份验证 | 是 |
| [uv](https://docs.astral.sh/uv/getting-started/installation/)（提供`uvx`） | 安全扫描 | 否 |
> 如果未设置`SKILLSMP_API_KEY`，服务器将**退出**。
## 快速设置
### 自动配置
运行单个命令以自动检测MCP客户端并写入配置：
```bash
npx -y skillsmp-mcp-lite --setup
```
该命令检测已安装的客户端（VS Code，Cursor，Claude Desktop，Claude Code）并将`skillsmp`服务器条目添加到每个配置文件中。对于VS Code，还会添加一个用于输入API密钥的安全提示。
要仅配置特定客户端，请设置`SKILLSMP_MCP_CLIENT`环境变量：
```bash
# Windows（PowerShell）
$env:SKILLSMP_MCP_CLIENT="cursor"; npx -y skillsmp-mcp-lite --setup
# macOS / Linux
SKILLSMP_MCP_CLIENT=cursor npx -y skillsmp-mcp-lite --setup
```
支持的值：`vscode`，`cursor`，`claude-desktop`，`claude-code`，`all`。
> 如果客户端已经具有`skillsmp`条目，则跳过 — 多次运行`--setup`是安全的。
### 手动配置
所有客户端运行相同的命令 — 只有配置文件位置和JSON密钥不同。
**服务器定义**（跨所有客户端共享）：
```json
"skillsmp": {
"command": "npx",
"args": ["-y", "skillsmp-mcp-lite"],
"env": {
"SKILLSMP_API_KEY": "您的API密钥"
}
}
```
#### VS Code / GitHub Copilot
打开`Ctrl+Shift+P` → *MCP: 打开用户配置*，然后添加：
```json
{
"servers": {
"skillsmp": { "type": "stdio", "command": "npx", "args": ["-y", "skillsmp-mcp-lite"], "env": { "SKILLSMP_API_KEY": "您的API密钥" } }
}
}
```
> VS Code需要额外的`"type": "stdio"`字段。
#### Cursor / Claude Desktop
| 客户端 | 配置文件 |
|---|---|
| Cursor | `~/.cursor/mcp.json` |
| Claude Desktop（macOS） | `~/Library/Application Support/Claude/claude_desktop_config.json` |
| Claude Desktop（Windows） | `%APPDATA%\Claude\claude_desktop_config.json` |
```json
{
"mcpServers": {
"skillsmp": { "command": "npx", "args": ["-y", "skillsmp-mcp-lite"], "env": { "SKILLSMP_API_KEY": "您的API密钥" } }
}
}
```
#### Claude Code
```bash
claude mcp add skillsmp -- npx -y skillsmp-mcp-lite --env SKILLSMP_API_KEY=您的API密钥
```
## 环境变量
| 变量 | 默认值 | 描述 |
|---|---|---|
| `SKILLSMP_API_KEY` | — | **必需。** 来自[skillsmp.com/docs/api](https://skillsmp.com/docs/api)的API密钥 |
| `GITHUB_TOKEN` | — | 可选。 将GitHub API速率限制从60提高到5,000 req/hour |
| `SKILL_SCANNER_API_URL` | — | 可选。 外部技能扫描器API服务器的URL |
| `SKILL_SCANNER_API_PORT` | `8000` | 可选。 自动管理的扫描器服务器端口 |
| `SKILLSMP_MCP_CLIENT` | — | 可选。 强制`--setup`配置特定客户端（`vscode`，`cursor`，`claude-desktop`，`claude-code`，`all`） |
## 可用工具
### `skillsmp_search_skills`
使用关键词搜索技能。
| 参数 | 类型 | 是否必需 | 描述 |
|---|---|---|---|
| `query` | 字符串 | 是 | 搜索关键词（最多200个字符） |
| `page` | 数字 | 否 | 页码（默认：1） |
| `limit` | 数字 | 否 | 每页项目数（默认：20，最大：100） |
| `sortBy` | 字符串 | 否 | `"stars"`或`"recent"` |
### `skillsmp_ai_search_skills`
使用自然语言描述查找技能。
| 参数 | 类型 | 是否必需 | 描述 |
|---|---|---|---|
| `query` | 字符串 | 是 | 自然语言描述（最多500个字符） |
### `skillsmp_read_skill`
从GitHub获取技能内容并可选地运行安全扫描。
| 参数 | 类型 | 是否必需 | 描述 |
|---|---|---|---|
| `repo` | 字符串 | 是 | GitHub仓库（`owner/repo`） |
| `skillName` | 字符串 | 是 | 技能名称（最多100个字符，字母数字/连字符/下划线） |
| `enableScan` | 布尔值 | 否 | 运行Cisco技能扫描器（默认：`true`，需要`uv`） |
## 安全扫描
当`skillsmp_read_skill`被调用且`enableScan: true`（默认）时，服务器：
1. 通过REST API从GitHub获取技能文件
2. 使用GitHub树`size`应用**三层扫描限制**（在下载之前）：
- **最大文件数**：每扫描100个文件
- **最大单个文件大小**：每个文件500 KB
- **最大总大小**：所有文件共5 MB
3. 从接受的文件构建内存ZIP存档
4. 将ZIP上传到Cisco技能扫描器API（`/scan-upload`）并使用`use_behavioral=true`
5. 如果没有运行的扫描器服务器，则自动启动本地扫描器服务器（后续扫描重用，退出时关闭）
如果文件因扫描限制而被排除，则**扫描备注**将包含在结果中，显示已排除的文件和字节数。
如果未安装`uvx`，则跳过扫描并显示警告 — 服务器继续正常工作。
### 不信任内容通知
从第三方仓库获取的所有技能内容都包含**不信任内容通知**。内容可以读取和显示，但**不得**在未经明确用户确认的情况下自动执行或遵循为指令。请始终查看内容和扫描结果，然后再执行。
要手动管理扫描器服务器：
```bash
# 自己启动
npm run scanner-api
# 或指向外部实例
SKILL_SCANNER_API_URL=http://your-server:8000
```
## AGENTS.md集成
将[`AGENTS.example.md`](./AGENTS.example.md)中的内容复制到`AGENTS.md`的顶部，以启用自动技能发现。
**工作流程**：AI接收任务 → 使用`skillsmp_search_skills`（短关键词）搜索 → 在需要时回落到`skillsmp_ai_search_skills` → 使用`skillsmp_read_skill`读取最佳匹配 → 遵循技能的说明。
### 搜索提示
- **关键词搜索**：1–3个词 — `"代码审查"`，`"TypeScript"`，`"PDF"`
- **语义搜索**：完整句子 — `"如何使用React构建一个着陆页"`
## 使用示例
询问您的AI助手：
- "搜索PDF操作技能"
- "查找用于构建网页抓取器的技能"
- "从existential-birds/beagle读取python-code-review技能"
## 许可证
MIT
