MCP Skills Server

MCP Skills Server

A production-ready Model Context Protocol (MCP) server that dynamically loads and exposes skills from a mounted volume with hot-reloading support.

📦 Available on [MCP Registry](https://registry.modelcontextprotocol.io/v0.1/servers/io.github.srprasanna%2Fmcp-skill-hub/versions) - Install with one command!

Features

• Dynamic Skill Loading: Automatically discovers and loads skills from a directory
• Hot-Reloading: Detects changes to SKILL.md files and reloads without restart
• Folder Structure Validation: Enforces best practices with clear error messages
• MCP Protocol Compliant: Full implementation of resources and tools
• Production Ready: Comprehensive error handling, logging, and validation
• Docker Support: Run in containers with volume mounting
• Type Safe: Full type hints using Python 3.13 features
• Well Tested: >80% code coverage with comprehensive test suite

Table of Contents

• Skills Directory Structure
• Quick Start
• Installation
• Usage
• Configuration
• Skill File Format
• MCP Resources and Tools
• Development
• Troubleshooting
• Contributing
• License

Skills Directory Structure

CRITICAL REQUIREMENT: Each skill MUST be in its own dedicated folder within the skills directory. The server will ONLY recognize skills that follow this structure.

✅ Valid Structure

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

❌ Invalid Structures (Will Be Ignored)

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

Folder Naming Conventions

Valid folder names:

• Lowercase with hyphens: my-skill-name
• Lowercase with underscores: excel_advanced
• Alphanumeric: skill-name-v2

Invalid (will be skipped):

• Hidden folders starting with .
• Private folders starting with _
• System folders: __pycache__, node_modules, .git, etc.

Quick Start

Using Docker (Recommended)

1. Create your skills directory:

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

1. Create a skill file:

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

1. Run the server:

docker run -i --rm \

-v ~/claude-skills:/skills:ro \ mcp-skill-hub

Using Poetry (Development)

1. Clone and install:

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

cd mcp-skill-hub poetry install

1. Create your skills directory:

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

Create SKILL.md as shown above

1. Run the server:

export MCP_SKILLS_DIR=~/claude-skills

poetry run mcp-skills

Installation

Prerequisites

• Python 3.13+ (for development)
• Poetry 1.7+ (for dependency management)
• Docker (optional, for containerized deployment)

Install with Poetry

# 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

Build Docker Image

# Build the image

docker build -t mcp-skill-hub .

Or use docker-compose

docker-compose build

Usage

Running Locally

# Set the skills directory

export MCP_SKILLS_DIR=/path/to/your/skills

Run the server

poetry run mcp-skills

Running with Docker

docker run -i --rm \

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

Running with Docker Compose

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

docker-compose up mcp-skills

Integrating with Claude Desktop

Add to your Claude Desktop configuration (claude_desktop_config.json):

{

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

Or using Poetry:

{

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

Important: Make sure your ${HOME}/claude-skills directory contains skill folders, not loose SKILL.md files!

Configuration

Configuration is done via environment variables with the prefix MCP_SKILLS_:

Example .env File

MCP_SKILLS_DIR=/path/to/skills

MCP_SKILLS_HOT_RELOAD=true MCP_SKILLS_DEBOUNCE_DELAY=0.5 MCP_SKILLS_LOG_LEVEL=INFO

Skill File Format

Skills are defined in SKILL.md files with YAML frontmatter:

Minimal Example

---

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

---

My Skill

Your skill content here in Markdown.

Complete Example

---

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.

Available Metadata Fields

Required:

• name: Unique identifier (kebab-case recommended)
• description: Brief description

Optional:

• version: Semantic version
• author: Creator name
• created, updated: ISO dates (YYYY-MM-DD)
• dependencies: Python packages or system tools
• category: Main category for grouping
• tags: Array of tags for search
• complexity: beginner, intermediate, or advanced
• when_to_use: Array of usage scenarios
• related_skills: Names of related skills
• has_examples: Boolean flag
• example_files: Paths to example files (relative to skill folder)

MCP Resources and Tools

Resources

The server exposes these MCP resources:

1. `skill://catalog` - JSON catalog of all skills with metadata
2. `skill://{name}` - Individual skill markdown content

Tools

Four tools are available for interacting with skills:

1. search_skills

Search for skills by query, category, tag, or complexity.

{

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

2. reload_skills

Manually trigger a reload of all skills from the directory.

{}

3. get_skill_info

Get metadata for a specific skill without loading full content.

{

"name": "excel-advanced" }

4. list_skill_folders

List all valid skill folders found in the skills directory.

{}

Development

Setup Development Environment

# 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

Running Tests

# 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

Code Quality

# 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

Development Workflow

1. Create a branch:

   git checkout -b feature/my-feature

1. Make changes and test:

   poetry run pytest

poetry run mypy src

1. Format and lint:

   poetry run black .

poetry run ruff check .

1. Commit and push:

   git commit -m "Add feature: description"

git push origin feature/my-feature

Project Structure

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

Troubleshooting

Common Issues

Skills Not Loading

Problem: No skills are loaded when the server starts.

Solution:

1. Check that your skills are in dedicated folders:

   /skills/my-skill/SKILL.md  ✓

/skills/SKILL.md ✗

2. Verify folder names don't start with `.` or `_`

1. Check logs for detailed error messages

Hot-Reload Not Working

Problem: Changes to SKILL.md files aren't detected.

Solution:

1. Ensure MCP_SKILLS_HOT_RELOAD=true
2. Check file is named exactly SKILL.md
3. Verify file is in a valid skill folder
4. Look for file watcher errors in logs

Parsing Errors

Problem: SKILL.md files fail to parse.

Solution:

1. Validate YAML frontmatter syntax
2. Ensure frontmatter is betwee