MCP Skillkit

mcp技能组合

](https://badge.fury.io/py/mcp-skillset) ](https://pypi.org/project/mcp-skillset/)  

通过模型上下文协议（MCP）为代码助理提供动态RAG技能

mcp-skillset是一个独立的Python应用程序，通过混合RAG（向量+知识图）为代码助理提供智能、上下文感知技能。与启动时加载的静态技能不同，mcp技能集支持运行时技能发现、基于项目工具链的自动推荐以及针对工作流优化的动态加载。

主要特点

• 🚀 零配置: mcp-skillset setup 自动处理一切
• 🧠 智能：自动检测项目的工具链（Python、TypeScript、Rust、Go等）
• 🔍 动态发现：向量相似度+知识图，更好地发现技能
• 📦 多源：从多个git存储库中提取技能
• ⚡ 按需加载：技能在需要时加载，并非全部在启动时加载
• 🔌 MCP本地：一流的模型上下文协议集成
• 🔒 安全第一：多层防御快速注入和恶意技能
• 🌐 agentskills.io兼容：支持本地和 agentskills.io 网站 规范格式

安全

MCP Skillset实施了全面的安全验证，以防止来自公共存储库的恶意技能。

安全特性

• 🛡️ 快速注射检测：自动检测指令覆盖尝试、角色劫持和上下文转义
• 🔍 威胁分类：多级威胁检测（受阻、危险、可疑）
• 🏷️ 存储库信任级别：信任（官方）、验证（社区）、不信任（公众）
• 📏 大小限制：通过内容大小强制实施DoS防御
• 🎯 内容消毒：所有技能都有明确的界限，以防止上下文逃逸

信任级别

快速安全检查

# Skills from public repos are automatically validated
mcp-skillset search "python testing"

# View security details in logs
mcp-skillset --debug search "python testing"

有关详细的安全信息、威胁模型和最佳实践，请参阅 安全.md.

安装

先决条件

• Python 3.11或更高版本
• Claude Code（用于Claude Code集成） claude CLI可用

使用Homebrew（macOS/Linux）

在macOS或Linux上安装的最简单方法：

brew tap bobmatnyc/tools
brew install mcp-skillset

紫外线（推荐-最快）

紫外线 是安装Python应用程序的最快方法：

uv tool install mcp-skillset

使用pipx（替代）

pipx 是安装Python CLI应用程序的可靠替代方案：

pipx install mcp-skillset

有pip（回退）

标准pip安装（不建议用于CLI工具）：

pip install mcp-skillset

来源

git clone https://github.com/bobmatnyc/mcp-skillset.git
cd mcp-skillset
uv sync

本地开发（无安装）

对于开发，您可以直接从源代码运行mcp技能集，而无需安装：

# Use the development script
./mcp-skillset-dev --help
./mcp-skillset-dev search "python testing"
./mcp-skillset-dev setup --auto

这 mcp-skillset-dev 脚本：

• 从源代码（未安装的版本）运行包
• 使用本地虚拟环境（如果可用）
• 自动设置PYTHONPATH
• 将所有参数传递给CLI

这有助于：

• 无需重新安装即可测试更改
• 开发新功能
• 使用源代码进行调试
• 为项目做出贡献

备注：对于生产使用，请正常安装包装 uv tool install mcp-skillset 或 pipx install mcp-skillset.

首次运行要求

重要：第一次运行时，mcp技能集将自动下载一个~90MB的句子转换器模型(all-MiniLM-L6-v2)用于语义搜索。这发生在初始阶段 mcp-skillset setup 或者当你第一次运行任何需要索引的命令时。

需求:

• ✅ 活动互联网连接
• ✅ ~100MB可用磁盘空间
• ✅ 初始下载2-5分钟（取决于连接速度）

模型缓存:

• 模型缓存在 ~/.cache/huggingface/ 以备将来使用
• 后续运行使用缓存的模型（无需下载）
• 缓存在mcp技能集更新期间持续存在

培养进步技能

mcp技能集现在包括以下能力 创建自定义渐进技能 Claude Code和其他人工智能助手可以立即使用。技能存储在 ~/.claude/skills/ 并自动加载。

什么是进步技能？

渐进式技能是模块化能力，可以：

• 分两个阶段加载：启动时轻量级元数据（~100个令牌），激活时全身（\> ~/.bashrc

source ~/.bashrc

**原有的质量** （macOS默认设置）：

eval "$(_MCP_SKILLS_COMPLETE=zsh_source mcp-skillset)" >> ~/.zshrc source ~/.zshrc

**鱼**:

echo 'eval (env _MCP_SKILLS_COMPLETE=fish_source mcp-skillset)' >> ~/.config/fish/config.fish source ~/.config/fish/config.fish

### 特性

- ✅ 完成所有命令和子命令
- ✅ 完成选项标志(`--help`, `--limit`等等）
- ✅ 适用于 `mcp-skillset`, `mcp-skillset repo`，以及所有其他命令

### 验证

测试完成正在进行中：

mcp-skillset # Shows: config health index info list mcp recommend repo search setup stats mcp-skillset repo # Shows: add list update mcp-skillset search -- # Shows: --category --help --limit

### 文档

有关详细的安装说明、故障排除和高级用法，请参阅 [docs/SHELL_COMPLETIONS.md](docs/SHELL_COMPLETIONS.md).

## MCP工具

mcp技能集为AI助手提供了7个mcp工具：

1. **技能_搜索** -基于混合RAG（向量+知识图）的语义搜索
1. **煎锅** -按ID检索完整的技能详细信息
1. **技能_推荐** -基于项目工具链的情境感知技能推荐
1. **技能_类别** -浏览可用的技能类别和工具链
1. **技能\_ reindex** -重建搜索索引（向量存储+知识图）
1. **技能模板列表** -列出可用于渐进式技能创建的技能模板
1. **技能_创建** -从模板创建渐进式技能，并部署到~/.claude/stkills/

### 工具详细信息

#### 1.技能_搜索

使用混合RAG对所有索引技能进行自然语言语义搜索。

**参数**:

- `query` （必填）：搜索查询字符串
- `limit` （可选）：最大结果数（默认值：10）
- `category` （可选）：按技能类别筛选

**退货**：一系列具有相关性得分的匹配技能

**示例**:

Search for testing skills

results = await skills_search( query="python unit testing frameworks", limit=5 )

Search with category filter

results = await skills_search( query="debugging", category="Python" )

#### 2.煎锅

按技能ID检索完整的技能详细信息和说明。

**参数**:

- `skill_id` （必填）：唯一技能标识符

**退货**：带有说明、元数据和示例的全技能对象

**示例**:

Get specific skill details

skill = await skill_get(skill_id="pytest-fixtures")

Use skill instructions

print(skill.instructions)

#### 3.技能_推荐

基于项目工具链检测获得智能技能建议。

**参数**：无（自动检测当前项目）

**退货**：按与检测到的工具链的相关性排名的推荐技能数组

**示例**:

Get recommendations for current project

recommendations = await skills_recommend()

Returns skills relevant to detected languages, frameworks, and tools

#### 4.技能_类别

列出所有可用的技能类别和工具链关联。

**参数**：无

**退货**：包含技能计数的类别名称数组

**示例**:

List all categories

categories = await skill_categories()

Returns: ["Python", "Testing", "Debugging", "Web Development", ...]

#### 5.技能\_ reindex

从技能库中重建向量存储和知识图索引。

**参数**:

- `force` （可选）：强制完全重新索引（默认值：false）

**退货**：索引状态和统计数据

**示例**:

Incremental reindex (only new/changed skills)

status = await skills_reindex()

Force full reindex

status = await skills_reindex(force=True)

#### 6.技能模板列表

列出可用的技能模板，并附上描述和用例。

**参数**：无

**退货**：包含元数据（名称、描述、best_for、use_cases）的模板数组

**示例**:

templates = await skill_templates_list()

Returns: [

{

"name": "web-development",

"description": "Full-stack web development patterns",

"best_for": "Web applications",

"use_cases": ["Frontend", "Backend", "Full-stack"]

},

...

]

#### 7.技能_创造

从模板创建渐进式技能。技能被部署到 `~/.claude/skills/` 立即使用。

**参数**:

- `name` （必填）：技能名称
- `description` （必填）：该技能的功能是什么
- `domain` （必填）：类别（例如，“网络开发”）
- `tags` （可选）：关键字列表
- `template` （可选）：模板选择（web开发、api开发、测试、基础）
- `deploy` （可选）：是否部署（默认值：true）

**退货**：状态、技能id、技能路径、验证结果

**示例**:

result = await skill_create( name="FastAPI Testing", description="Comprehensive testing strategies for FastAPI applications", domain="web development", tags=["fastapi", "pytest", "testing"], template="web-development", deploy=True )

## 发展

### 需求

- Python 3.11+
- Git
- uv（推荐）或pip

### 设置开发环境

git clone https://github.com/bobmatnyc/mcp-skillset.git cd mcp-skillset

Recommended: Use uv for fastest setup

uv sync

Alternative: Use pip

pip install -e ".[dev]"

### 源代码运行（开发模式）

使用 `./mcp-skillset-dev` 直接从源代码运行命令而无需安装的脚本：

Run any CLI command

./mcp-skillset-dev --version ./mcp-skillset-dev search "debugging" ./mcp-skillset-dev serve --dev

All arguments pass through

./mcp-skillset-dev info systematic-debugging

**运作原理**:

1. 集合 `PYTHONPATH` 包括 `src/` 目录
1. 激活本地 `.venv` 如存在
1. 跑 `python -m mcp_skills.cli.main` 所有的论点

**何时使用**:

- ✅ 开发过程中的快速迭代
- ✅ 无需重新安装即可测试更改
- ✅ 通过修改源代码进行调试
- ❌ 生产部署（使用 `pip install` 相反）

**已安装与源**:

Installed version (from pip install -e .)

mcp-skillset search "testing"

Source version (no installation required)

./mcp-skillset-dev search "testing"

### 运行测试

With uv (recommended)

uv run pytest

With coverage

uv run pytest --cov

Or use make

make quality

### 性能基准

mcp技能集包括跟踪和防止退化的全面性能基准：

Run all benchmarks (includes slow tests)

make benchmark

Run fast benchmarks only (skip 10k skill tests)

make benchmark-fast

Compare current performance with baseline

make benchmark-compare

**基准类别**:

- **索引性能**：测量索引100、1000和10000项技能的时间
- **搜索性能**：跟踪向量和混合搜索的查询延迟（p50、p95、p99）
- **数据库性能**：基准SQLite操作（查找、查询、批量插入）
- **内存使用**：监控大规模操作期间的内存消耗

**基线阈值**:

- 指数100技能：\/dev/null

   # Add to PATH in your shell profile (~/.zshrc, ~/.bashrc, etc.)
   export PATH="/path/to/claude/bin:$PATH"

1. 验证CLI是否正常工作:

   claude --version
   claude mcp list

1. 回退选项：使用 --skip-agents 手动标记和配置：

   mcp-skillset setup --skip-agents
   # Then use: mcp-skillset install --agent claude-desktop

模型下载问题

如果在首次运行时下载嵌入模型时遇到问题：

1.检查互联网连接

该模型可从HuggingFace Hub下载。验证您是否可以联系到：

curl -I https://huggingface.co

2.手动模型下载

如果自动下载失败，请手动预下载模型：

python -c "from sentence_transformers import SentenceTransformer; SentenceTransformer('sentence-transformers/all-MiniLM-L6-v2')"

这将模型下载到 ~/.cache/huggingface/ 并验证其工作正常。

3.代理配置

如果位于公司代理之后，请配置环境变量：

export HTTP_PROXY=http://proxy.example.com:8080
export HTTPS_PROXY=http://proxy.example.com:8080
export HF_ENDPOINT=https://huggingface.co  # Or your mirror

4.离线/气隙安装

对于没有互联网接入的环境：

在有互联网的机器上：

1. 下载模型：

   python -c "from sentence_transformers import SentenceTransformer; SentenceTransformer('sentence-transformers/all-MiniLM-L6-v2')"

1. 打包模型缓存：

   cd ~/.cache/huggingface
   tar -czf sentence-transformers-model.tar.gz hub/

在气隙式机器上：

1. 转移 sentence-transformers-model.tar.gz 到目标机器

1. 解压缩到HuggingFace缓存目录：

   mkdir -p ~/.cache/huggingface
   cd ~/.cache/huggingface
   tar -xzf /path/to/sentence-transformers-model.tar.gz

1. 安装mcp技能套件（如果需要，可使用传送轮）：

   pip install mcp-skillset  # Or install from wheel

1. 验证设置：

   mcp-skillset doctor

5.自定义缓存位置

如果需要使用其他缓存目录：

export HF_HOME=/custom/path/to/cache
export TRANSFORMERS_CACHE=/custom/path/to/cache
mcp-skillset setup

6.磁盘空间问题

检查缓存目录中的可用空间：

df -h ~/.cache/huggingface

该型号需要约90MB，但在下载过程中允许约100MB的临时文件。

7.许可问题

确保缓存目录可写：

mkdir -p ~/.cache/huggingface
chmod 755 ~/.cache/huggingface

常见问题

模型下载过程中的“连接超时”

• 检查互联网连接和防火墙设置
• 尝试手动下载（见上述步骤2）
• 如果位于公司网络后面，则配置代理（请参阅上述步骤3）

“设备上没有剩余空间”

• 检查磁盘空间： df -h ~/.cache
• 清除旧的HuggingFace缓存： rm -rf ~/.cache/huggingface/*
• 使用自定义缓存位置（见上述步骤5）

缓存目录上的“权限被拒绝”

• 修复权限： chmod 755 ~/.cache/huggingface
• 或者使用具有适当权限的自定义缓存位置

初始设置缓慢

• 首次运行下载约90MB并构建索引
• 预计时间：2-10分钟，具体取决于连接速度和技能数量
• 后续运行使用缓存模型，速度更快

获取帮助

如果您遇到此处未涵盖的问题：

1. 检查
2. 审核日志： ~/.mcp-skillset/logs/
3. 运行健康检查： mcp-skillset doctor
4. 通过以下方式打开新问题：

- 错误消息和堆栈跟踪 - 输出 mcp-skillset --version - 操作系统和Python版本 - 重现步骤

贡献

欢迎投稿！请先阅读我们的投稿指南。

1. 分叉存储库
2. 创建要素分支
3. 进行更改
4. 跑 make quality 确保测试通过
5. 提交拉取请求

许可证

MIT许可证-请参阅 许可证 了解详情。

致谢

• 建立在 模型上下文协议
• 灵感源自 克劳德技能
• 用途 色度数据库 用于矢量搜索
• 嵌入通过 句子变换器

链接

• PyPI包: PyPI上的mcp技能集
• 文档:
• 问题追踪器:
• MCP注册表: MCP服务器
• 出版指南: docs/publishing.md

______________________________________________________________________

状态: ✅ v0.5.0-生产就绪| 测试覆盖率: 85-96% | 测试：77通过（48单元+29安保）