使用说明

MCP技能服务器

生产准备就绪模型上下文协议（MCP）服务器，通过热重新加载支持从已挂载的卷动态加载和公开技能。

📦 可用时间： MCP注册表 -只需一个命令即可安装！

特性

动态技能加载：自动从目录中发现和加载技能
热重新加载：检测SKILL.md文件的更改，并在不重新启动的情况下重新加载
文件夹结构验证：通过明确的错误消息强制实施最佳实践
符合MCP协议：充分落实资源和工具
生产就绪：全面的错误处理、日志记录和验证
Docker支持：在容量安装的容器中运行
类型安全：使用Python 3.13功能的完整类型提示
测试良好：>80%的代码覆盖率和全面的测试套件

技能目录结构

必要条件：每个技能必须在技能目录中的专用文件夹中。服务器将只识别遵循此结构的技能。

✅ 有效结构

your-skills-directory/
├── skill-one/
│   └── SKILL.md          ← Required
├── skill-two/
│   ├── SKILL.md          ← Required
│   └── examples/         ← Optional
│       └── example.py
└── skill-three/
    ├── SKILL.md
    ├── examples/
    │   └── demo.py
    └── templates/
        └── template.txt

❌ 无效结构（将被忽略）

your-skills-directory/
├── SKILL.md                  ❌ Not in a folder - WILL BE SKIPPED
├── random-file.txt           ❌ Not a skill folder
├── .hidden-folder/           ❌ Hidden folder - WILL BE SKIPPED
│   └── SKILL.md
└── __pycache__/              ❌ System folder - WILL BE SKIPPED
    └── SKILL.md

文件夹命名约定

有效文件夹名称：

带连字符的小写字母： my-skill-name
下划线小写： excel_advanced
字母数字： skill-name-v2

无效（将被跳过）：

以开头的隐藏文件夹 .
以开头的私人文件夹 _
系统文件夹： __pycache__, node_modules, .git等等。

快速开始

使用Docker（推荐）

mkdir -p ~/claude-skills/my-first-skill

创建技能档案：

cat > ~/claude-skills/my-first-skill/SKILL.md << 'EOF'
---
name: "my-first-skill"
description: "My first Claude skill"
---

# My First Skill

This is my first skill for Claude!

## Usage

Simply describe what your skill does here.
EOF

运行服务器：

docker run -i --rm \
  -v ~/claude-skills:/skills:ro \
  mcp-skill-hub

运用诗歌（发展）

克隆并安装：

git clone https://github.com/srprasanna/mcp-skill-hub.git
cd mcp-skill-hub
poetry install

mkdir -p ~/claude-skills/my-first-skill
# Create SKILL.md as shown above

运行服务器：

export MCP_SKILLS_DIR=~/claude-skills
poetry run mcp-skills

安装

先决条件

Python 3.13+ （用于发展）
诗歌1.7+ （用于依赖关系管理）
码头工人 （可选，用于容器化部署）

安装诗歌

# Clone the repository
git clone https://github.com/srprasanna/mcp-skill-hub.git
cd mcp-skill-hub

# Install dependencies
poetry install

# Verify installation
poetry run mcp-skills --help

构建Docker镜像

# Build the image
docker build -t mcp-skill-hub .

# Or use docker-compose
docker-compose build

用法

本地运行

# Set the skills directory
export MCP_SKILLS_DIR=/path/to/your/skills

# Run the server
poetry run mcp-skills

使用Docker运行

docker run -i --rm \
  -v /path/to/your/skills:/skills:ro \
  -e MCP_SKILLS_LOG_LEVEL=INFO \
  mcp-skill-hub

使用Docker Compose运行

# Edit docker-compose.yml to set your skills directory path
docker-compose up mcp-skills

与Claude Desktop集成

添加到您的Claude Desktop配置(claude_desktop_config.json):

{
  "mcpServers": {
    "skills": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-v",
        "${HOME}/claude-skills:/skills:ro",
        "mcp-skill-hub"
      ]
    }
  }
}

或者使用诗歌：

{
  "mcpServers": {
    "skills": {
      "command": "poetry",
      "args": ["run", "mcp-skills"],
      "cwd": "/path/to/mcp-skill-hub",
      "env": {
        "MCP_SKILLS_DIR": "/path/to/your/skills"
      }
    }
  }
}

重要提示： 确保你的 ${HOME}/claude-skills 目录包含技能文件夹，而不是松散的skill.md文件！

配置

配置是通过带有前缀的环境变量完成的 MCP_SKILLS_:

变量	默认值	描述
`MCP_SKILLS_DIR`	`/skills`	包含技能文件夹的根目录
`MCP_SKILLS_HOT_RELOAD`	`true`	启用自动重新加载
`MCP_SKILLS_DEBOUNCE_DELAY`	`0.5`	重新加载前的延迟（秒）
`MCP_SKILLS_LOG_LEVEL`	`INFO`	日志级别（调试、信息、警告、错误）
`MCP_SKILLS_SCAN_DEPTH`	`1`	扫描深度（始终为1）

示例.env文件

MCP_SKILLS_DIR=/path/to/skills
MCP_SKILLS_HOT_RELOAD=true
MCP_SKILLS_DEBOUNCE_DELAY=0.5
MCP_SKILLS_LOG_LEVEL=INFO

技能文件格式

技能定义见 SKILL.md 带有YAML frontmatter的文件：

最小示例

---
name: "my-skill"
description: "Brief description"
---

# My Skill

Your skill content here in Markdown.

完整示例

---
# Required fields
name: "excel-advanced"
description: "Advanced Excel automation techniques"

# Version and authorship
version: "1.2.0"
author: "Your Name"
created: "2025-01-15"
updated: "2025-10-23"

# Dependencies
dependencies:
  python: ["openpyxl>=3.0.0", "pandas>=2.0.0"]
  system: ["libreoffice"]

# Categorization
category: "office-automation"
tags: ["excel", "spreadsheet", "automation"]
complexity: "intermediate"  # beginner|intermediate|advanced

# Usage guidance
when_to_use:
  - "Automating Excel report generation"
  - "Processing multiple Excel files"
  - "Creating complex formulas programmatically"

# Relationships
related_skills: ["csv-processing", "data-analysis"]

# Examples
has_examples: true
example_files: ["examples/report_generator.py", "templates/report_template.xlsx"]
---

# Excel Advanced Automation

This skill covers advanced Excel automation techniques...

## Features

- Automated report generation
- Formula creation
- Bulk processing

## Examples

See `examples/report_generator.py` for a working example.

可用元数据字段

必修的：

name：唯一标识符（建议使用烤肉串大小写）
description：简要说明

可选：

version：语义版本
author：创建者名称
created, updated：ISO日期（YYYY-MM-DD）
dependencies：Python包或系统工具
category：分组的主要类别
tags：用于搜索的标签数组
complexity：初级、中级或高级
when_to_use：使用场景数组
related_skills：相关技能名称
has_examples：布尔标志
example_files：示例文件的路径（相对于技能文件夹）

MCP资源和工具

资源

服务器公开这些MCP资源：

skill://catalog -包含元数据的所有技能的JSON目录
skill://{name} -个人技能评分内容

工具

有四种工具可用于与技能互动：

1. `search_skills`

按查询、类别、标签或复杂性搜索技能。

{
  "query": "excel",
  "category": "office-automation",
  "tag": "automation",
  "complexity": "intermediate"
}

2. `reload_skills`

手动触发目录中所有技能的重新加载。

{}

3. `get_skill_info`

在不加载完整内容的情况下获取特定技能的元数据。

{
  "name": "excel-advanced"
}

4. `list_skill_folders`

列出技能目录中找到的所有有效技能文件夹。

{}

发展

设置开发环境

# Clone repository
git clone https://github.com/srprasanna/mcp-skill-hub.git
cd mcp-skill-hub

# Install dependencies (including dev dependencies)
poetry install

# Activate virtual environment
poetry shell

运行测试

# Run all tests
poetry run pytest

# Run with coverage
poetry run pytest --cov=mcp_skills --cov-report=html

# Run specific test file
poetry run pytest tests/test_scanner.py

# Run with verbose output
poetry run pytest -v

代码质量

# Format code
poetry run black .

# Lint code
poetry run ruff check .

# Type checking
poetry run mypy src

# Run all quality checks
poetry run black . && poetry run ruff check . && poetry run mypy src

开发工作流程

创建分支：
```
git checkout -b feature/my-feature
```
进行更改和测试：
```
poetry run pytest
poetry run mypy src
```

格式和lint：

poetry run black .
poetry run ruff check .

承诺并推动：

git commit -m "Add feature: description"
git push origin feature/my-feature

项目结构

mcp-skill-hub/
├── src/mcp_skills/          # Source code
│   ├── models/              # Data models
│   ├── parsers/             # Skill parsers
│   ├── storage/             # Repository pattern
│   ├── scanner.py           # Directory scanning
│   ├── watcher.py           # Hot-reload watcher
│   ├── server.py            # MCP server
│   ├── config.py            # Configuration
│   └── __main__.py          # CLI entry point
├── tests/                   # Test suite
├── examples/                # Example skills
├── docs/                    # Documentation
└── pyproject.toml           # Poetry configuration

故障排除

常见问题

技能未加载

问题： 服务器启动时不会加载任何技能。

解决方案：

检查你的技能是否在专用文件夹中：

/skills/my-skill/SKILL.md  ✓
/skills/SKILL.md           ✗

验证文件夹名称是否以开头 . 或 _
检查日志以获取详细的错误消息

热重载不工作

问题： 未检测到对SKILL.md文件的更改。

解决方案：

确保 MCP_SKILLS_HOT_RELOAD=true
检查文件名称是否准确 SKILL.md
验证文件是否在有效的技能文件夹中
在日志中查找文件监视器错误

解析错误

问题： SKILL.md文件无法解析。

解决方案：

验证YAML frontmatter语法
确保正面位于 --- 分隔符
检查必填字段(name, description)存在
使用YAML验证器检查语法

验证命令

检查您的技能目录结构：

poetry run mcp-skills --validate

预期产量：

✓ /skills/excel-advanced: Valid skill
✓ /skills/python-automation: Valid skill
✗ /skills/SKILL.md: Error - Skills must be in folders
✗ /skills/.hidden: Skipped - Hidden folder
⚠ /skills/empty-folder: Warning - No SKILL.md found

Summary: 2 valid, 1 error, 1 warning, 1 skipped

日志记录

启用调试日志记录以获取详细信息：

export MCP_SKILLS_LOG_LEVEL=DEBUG
poetry run mcp-skills

日志包括：

文件夹结构验证消息
扫描进度和结果
解析成功与失败
热重载事件
详细的错误上下文

贡献

欢迎投稿！请看贡献.md 作为指导方针。

快速贡献指南

分叉存储库
创建要素分支
通过测试进行更改
确保所有测试均已通过，且代码已格式化
提交拉取请求

代码规范

Python 3.13+ 带有类型提示
黑色用于格式化（88个字符行长度）
拉夫对于linting
米皮用于类型检查（严格模式）
Pytest 用于测试（覆盖率>80%）

发布

该项目通过GitHub Actions使用自动发布。

创建发布

首选行动 → 发布工作流
点击 运行工作流
选择版本凹凸类型：
- patch -错误修复（0.1.0→0.1.1）
- minor -新功能（0.1.0→0.2.0）
- major -重大变化（0.1.0→1.0.0）
- 或者指定确切的版本（例如。， 1.2.3)
选择Docker注册表(docker.io 或 ghcr.io)
点击 运行工作流

工作流程将：

✅ 凹凸版本 pyproject.toml
✅ 创建Git标签和GitHub发布
✅ 构建并推送Docker镜像
✅ 运行测试以验证发布

Docker镜像：

Docker Hub： {username}/mcp-skill-hub:{version}
github： ghcr.io/{owner}/mcp-skill-hub:{version}

看发布.md 获取详细的发布文档。

许可证

此项目根据MIT许可证获得许可-请参阅许可证文件以获取详细信息。

致谢

内置 MCP Python SDK
受克劳德对动态技能管理需求的启发
感谢所有贡献者！

注：此服务器通过以下方式使人们无法误解文件夹结构要求：

使用文件夹上下文清除错误消息
综合录井
多层次验证
详细文件
工作示例

每个技能都必须在自己的文件夹中。这一设计决策确保了清晰的组织、易于管理和明确的结构。 🎯

使用说明

MCP技能服务器

特性

目录

技能目录结构

✅ 有效结构

❌ 无效结构（将被忽略）

文件夹命名约定

快速开始

使用Docker（推荐）

运用诗歌（发展）

安装

先决条件

安装诗歌

构建Docker镜像

用法

本地运行

使用Docker运行

使用Docker Compose运行

与Claude Desktop集成

配置

示例.env文件

技能文件格式

最小示例

完整示例

可用元数据字段

MCP资源和工具

资源

工具

1. search_skills

2. reload_skills

3. get_skill_info

4. list_skill_folders

发展

设置开发环境

运行测试

代码质量

开发工作流程

项目结构

故障排除

常见问题

技能未加载

热重载不工作

解析错误

验证命令

日志记录

贡献

快速贡献指南

代码规范

发布

创建发布

许可证

致谢

相关 MCP

Zotero插件开发MCP服务器

MCP服务器脚手架工具

AI编程代理记忆系统

MCP服务器代理

Flutter 应用自动化 MCP 工具包

持久化Julia REPL工具

1. `search_skills`

2. `reload_skills`

3. `get_skill_info`

4. `list_skill_folders`