内容
# skillsmp-mcp
[](https://pypi.org/project/skillsmp-mcp/)
Python MCP 服务器，用于 [SkillsMP](https://skillsmp.com)
搜索目录，读取技能的 `SKILL.md` 文件，直接从 GitHub 获取，运行完整的思科 AI 技能扫描器和 LLM 扫描器，并在扫描通过后安装技能。
## 工具
| 工具 | 功能 |
|------|--------------|
| `search_skills(query, limit, sort_by)` | 关键字搜索 (`sort_by`: `stars`/`recent`). |
| `read_skill(repo, skill_name)` | 从 GitHub `owner/repo` 获取 `SKILL.md`，**只读**。永不扫描，永不启动子进程，永不安装。 |
| `scan_skill(repo, skill_name)` | 完整的思科扫描；仅报告发现结果。 |
| `install_skills(skills, force=False)` | 扫描门控批量安装。`skills` 是 `owner/repo:skill_name` 规格的列表（可能跨多个仓库）。每个规格都被独立解析、扫描和门控；除非 `force=True`，否则拒绝 HIGH/CRITICAL。报告每个技能的结果，而不会因一次失败而中止批处理。 |
| `uninstall_skills(skills)` | 删除已安装的技能（批量）。`skills` 是 `owner/repo:skill_name` 规格的列表（可能跨多个仓库）。无扫描/网络；报告每个技能的结果（已删除 / 未安装 / 错误）。 |
## 要求
- **Python 3.10+**
- 一个 **SkillsMP API 密钥** (`sk_live_...`) 来自 [skillsmp.com](https://skillsmp.com) — 唯一硬性要求。
- 对于 `scan_skill` / `install_skills`：安装 [`uv`](https://docs.astral.sh/uv/) （服务器按需通过 `uvx` 运行扫描器）**或** 直接安装 `cisco-ai-skill-scanner` 包。没有这两个条件，扫描返回 `SKIPPED`，安装被阻止。
- 推荐：一个 **Anthropic API 密钥** (`sk-ant-...`) 以启用 LLM 语义分析器。
## 安装
该软件包位于 [PyPI](https://pypi.org/project/skillsmp-mcp/)。最简单的路径是让 [`uvx`](https://docs.astral.sh/uv/) 按需获取并运行它 — 无需安装或更新：
```bash
uvx skillsmp-mcp # 运行服务器（从环境中读取密钥）
```
或安装一个持久命令：
```bash
pipx install skillsmp-mcp # 隔离的全局命令（推荐）
# 或
pip install skillsmp-mcp # 安装到当前环境
```
任一安装都为您提供两种启动方式 — **`skillsmp-mcp`** 控制台脚本和 **`python -m skillsmp_mcp`** （当脚本不在 PATH 中时很有用）。
对于 `scan_skill` / `install_skills`，您还需要思科扫描器可访问：安装 `uv` （服务器按需通过 `uvx` 运行它）或 `pipx install cisco-ai-skill-scanner`。没有它，扫描返回 `SKIPPED`，安装被阻止。
快速烟雾测试（无需密钥 — 完成 MCP 握手，列出 5 个工具，然后退出）：
```bash
printf '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"t","version":"0"}}}\n' \
| SKILLSMP_API_KEY=dummy uvx skillsmp-mcp
```
## 配置和注册 MCP 客户端
密钥通过 MCP 服务器的 `env` 块提供 — 代码从进程环境中读取它们，客户端在启动时注入。没有 `.env` 文件需要管理。大多数客户端共享相同的 `command` / `args` / `env` JSON 模式（Claude Desktop，Claude Code，Cursor）；Codex 使用 TOML。请选择下面的客户端。
### Claude Desktop
添加到 `claude_desktop_config.json` （macOS：`~/Library/Application Support/Claude/claude_desktop_config.json`）。合并到 `mcpServers` — 不要替换该块。
```json
"skillsmp": {
"command": "/Users/you/.local/bin/uvx",
"args": ["skillsmp-mcp"],
"env": {
"SKILLSMP_API_KEY": "sk_live_...",
"SKILL_SCANNER_LLM_API_KEY": "sk-ant-...",
"SKILL_SCANNER_LLM_MODEL": "anthropic/claude-sonnet-5"
}
}
```
`SKILLSMP_API_KEY` 是唯一硬性要求。设置 `SKILL_SCANNER_LLM_API_KEY` 以使语义分析器运行 — 没有它，扫描会回落到静态 + 行为检查，并且可能会错过基于文本的提示注入。所有其他变量（参见下表）都是可选的，并且放在同一个 `env` 块中。
**使用绝对路径的 `command`**。像 Claude Desktop 这样的 GUI 应用程序不会继承您的 shell `PATH`，因此一个裸的 `uvx`（或 `skillsmp-mcp`）通常无法解析。运行 `which uvx` 以获取完整路径并使用它（如下所示）。如果您使用 `pipx` 安装，请直接指向安装的脚本 — 使用 `which skillsmp-mcp` 查找它 — 并删除 `args` 行。
由于相同的 PATH 原因，请设置 `SKILLSMP_SCANNER_CMD` 为绝对的 `uvx` 路径，以便在服务器在客户端下运行时找到扫描器：
```json
"SKILLSMP_SCANNER_CMD": "/Users/you/.local/bin/uvx --from cisco-ai-skill-scanner skill-scanner"
```
在编辑完成后完全退出并重新启动 Claude Desktop。
### Claude Code
Claude Code 与 Claude Desktop 分别存在 — 它**不**读取 `claude_desktop_config.json`。使用 CLI 注册：
```bash
claude mcp add skillsmp \
-e SKILLSMP_API_KEY=sk_live_... \
-e SKILL_SCANNER_LLM_API_KEY=sk-ant-... \
-- uvx skillsmp-mcp
```
默认情况下，服务器的作用域限定在当前项目；添加 `-s user` 以使其在任何地方都可用。或者，在仓库根目录提交一个项目级 `.mcp.json`，使用与上述 Claude Desktop 块相同的 `command`/`args`/`env` 模式。项目 `.mcp.json` 也是设置仓库级安装根的地方 — 例如 `"SKILLSMP_INSTALL_DIR": ".claude/skills"` — 因此安装/卸载写入仓库而不是 `~/.claude/skills`。
### Cursor
Cursor 使用与 Claude Desktop 相同的 JSON 模式，在 `~/.cursor/mcp.json` （全局）或 `.cursor/mcp.json` （项目）中。合并到 `mcpServers`：
```json
{
"mcpServers": {
"skillsmp": {
"command": "/Users/you/.local/bin/uvx",
"args": ["skillsmp-mcp"],
"env": {
"SKILLSMP_API_KEY": "sk_live_...",
"SKILL_SCANNER_LLM_API_KEY": "sk-ant-..."
}
}
}
}
```
像 Claude Desktop 一样，Cursor 是一个 GUI 应用程序，它不会继承您的 shell `PATH` — 使用绝对路径的 `command` 和 `SKILLSMP_SCANNER_CMD`（参见上面的注释）。
### Codex
Codex 在 `~/.codex/config.toml` 处使用 TOML。添加一个 `mcp_servers` 表：
```toml
[mcp_servers.skillsmp]
command = "uvx"
args = ["skillsmp-mcp"]
env = { SKILLSMP_API_KEY = "sk_live_...", SKILL_SCANNER_LLM_API_KEY = "sk-ant-..." }
```
## 环境变量
| 变量 | 是否必需 | 默认值 | 用途 |
|-----|----------|---------|---------|
| `SKILLSMP_API_KEY` | 是 | — | SkillsMP REST 身份验证（仅发送到 skillsmp.com）。 |
| `SKILL_SCANNER_LLM_API_KEY` | 推荐 | — | 启用 LLM 语义分析器。 |
| `SKILL_SCANNER_LLM_MODEL` | 否 | `anthropic/claude-sonnet-5` | LiteLLM 模型字符串。 |
| `GITHUB_TOKEN` | 否 | — | 只读 PAT；提高 GitHub 速率限制。 |
| `SKILLSMP_INSTALL_DIR` | 否 | `~/.claude/skills` | 安装/卸载根目录。对于仓库级技能，将其设置为例如 `.claude/skills` 在项目范围的 `.mcp.json` 中；`install_skills` 和 `uninstall_skills` 都在此根目录下操作。 |
| `SKILLSMP_BLOCK_SEVERITIES` | 否 | `HIGH,CRITICAL` | 阻止安装的严重程度。 |
| `SKILLSMP_SCANNER_CMD` | 否 | 自动检测 | 覆盖扫描器命令。 |
| `SKILLSMP_SCANNER_POLICY` | 否 | — | 思科策略预设（例如 `strict`）。 |
| `SKILLSMP_SCANNER_TIMEOUT` | 否 | `300` | 扫描超时（秒）。 |
| `SKILLSMP_MAX_FILES` / `SKILLSMP_MAX_SINGLE_FILE_BYTES` / `SKILLSMP_MAX_TOTAL_BYTES` | 否 | `100` / `512000` / `5242880` | 获取/扫描大小限制。 |
| `VIRUSTOTAL_API_KEY` / `AI_DEFENSE_API_KEY` | 否 | — | 可选的云引擎。 |
对于在 Claude 客户端外部的独立运行（例如终端测试），只需导出变量即可 — 服务器以相同的方式读取环境。
## 安全模型
- 您的 SkillsMP 密钥仅发送到 `skillsmp.com`。GitHub 获取是未经身份验证的（或使用只读 `GITHUB_TOKEN`）；这两个永远不会混合。
- 技能文件是只读获取的，写入私有临时目录进行扫描，然后删除该目录。思科的分析是静态/AST — 不会执行任何操作。
- `install_skills` 独立扫描和门控每个技能：除非强制，否则拒绝 HIGH/CRITICAL 发现，除非强制，否则拒绝未扫描（缺少扫描器），并且从不静默覆盖 — 重新安装现有技能文件夹也需要 `force=True`。
- 安装以 `<owner>-<repo>__<skill-dir>` 命名空间，因此不同来源的技能不会冲突，精心构造的名称也不会逃逸安装根目录。
- 清洁扫描 **不是** 安全保证 — 它意味着没有已知模式匹配。请自行阅读 `SKILL.md`；`read_skill` 将其标记为不受信任。
## 许可证
MIT — 请参阅 [LICENSE](LICENSE)。
