{
  "markdown": "# MCP Skills Server\n\n[![Python 3.13+](https://img.shields.io/badge/python-3.13+-blue.svg)](https://www.python.org/downloads/)\n[![Poetry](https://img.shields.io/badge/poetry-1.7+-blue.svg)](https://python-poetry.org/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![MCP Registry](https://img.shields.io/badge/MCP-Registry-purple.svg)](https://registry.modelcontextprotocol.io/v0.1/servers/io.github.srprasanna%2Fmcp-skill-hub/versions)\n[![Docker](https://img.shields.io/docker/v/srprasanna/mcp-skill-hub?label=docker)](https://hub.docker.com/r/srprasanna/mcp-skill-hub)\n[![Docker Pulls](https://img.shields.io/docker/pulls/srprasanna/mcp-skill-hub)](https://hub.docker.com/r/srprasanna/mcp-skill-hub)\n\nA production-ready [Model Context Protocol (MCP)](https://modelcontextprotocol.io) server that dynamically loads and exposes skills from a mounted volume with hot-reloading support.\n\n> 📦 **Available on [MCP Registry](https://registry.modelcontextprotocol.io/v0.1/servers/io.github.srprasanna%2Fmcp-skill-hub/versions)** - Install with one command!\n\n## Features\n\n- **Dynamic Skill Loading**: Automatically discovers and loads skills from a directory\n- **Hot-Reloading**: Detects changes to SKILL.md files and reloads without restart\n- **Folder Structure Validation**: Enforces best practices with clear error messages\n- **MCP Protocol Compliant**: Full implementation of resources and tools\n- **Production Ready**: Comprehensive error handling, logging, and validation\n- **Docker Support**: Run in containers with volume mounting\n- **Type Safe**: Full type hints using Python 3.13 features\n- **Well Tested**: >80% code coverage with comprehensive test suite\n\n## Table of Contents\n\n- [Skills Directory Structure](#skills-directory-structure)\n- [Quick Start](#quick-start)\n- [Installation](#installation)\n- [Usage](#usage)\n- [Configuration](#configuration)\n- [Skill File Format](#skill-file-format)\n- [MCP Resources and Tools](#mcp-resources-and-tools)\n- [Development](#development)\n- [Troubleshooting](#troubleshooting)\n- [Contributing](#contributing)\n- [License](#license)\n\n## Skills Directory Structure\n\n**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.\n\n### ✅ Valid Structure\n\n```\nyour-skills-directory/\n├── skill-one/\n│   └── SKILL.md          ← Required\n├── skill-two/\n│   ├── SKILL.md          ← Required\n│   └── examples/         ← Optional\n│       └── example.py\n└── skill-three/\n    ├── SKILL.md\n    ├── examples/\n    │   └── demo.py\n    └── templates/\n        └── template.txt\n```\n\n### ❌ Invalid Structures (Will Be Ignored)\n\n```\nyour-skills-directory/\n├── SKILL.md                  ❌ Not in a folder - WILL BE SKIPPED\n├── random-file.txt           ❌ Not a skill folder\n├── .hidden-folder/           ❌ Hidden folder - WILL BE SKIPPED\n│   └── SKILL.md\n└── __pycache__/              ❌ System folder - WILL BE SKIPPED\n    └── SKILL.md\n```\n\n### Folder Naming Conventions\n\n**Valid folder names:**\n- Lowercase with hyphens: `my-skill-name`\n- Lowercase with underscores: `excel_advanced`\n- Alphanumeric: `skill-name-v2`\n\n**Invalid (will be skipped):**\n- Hidden folders starting with `.`\n- Private folders starting with `_`\n- System folders: `__pycache__`, `node_modules`, `.git`, etc.\n\n## Quick Start\n\n### Using Docker (Recommended)\n\n1. **Create your skills directory:**\n\n```bash\nmkdir -p ~/claude-skills/my-first-skill\n```\n\n2. **Create a skill file:**\n\n```bash\ncat > ~/claude-skills/my-first-skill/SKILL.md << 'EOF'\n---\nname: \"my-first-skill\"\ndescription: \"My first Claude skill\"\n---\n\n# My First Skill\n\nThis is my first skill for Claude!\n\n## Usage\n\nSimply describe what your skill does here.\nEOF\n```\n\n3. **Run the server:**\n\n```bash\ndocker run -i --rm \\\n  -v ~/claude-skills:/skills:ro \\\n  mcp-skill-hub\n```\n\n### Using Poetry (Development)\n\n1. **Clone and install:**\n\n```bash\ngit clone https://github.com/srprasanna/mcp-skill-hub.git\ncd mcp-skill-hub\npoetry install\n```\n\n2. **Create your skills directory:**\n\n```bash\nmkdir -p ~/claude-skills/my-first-skill\n# Create SKILL.md as shown above\n```\n\n3. **Run the server:**\n\n```bash\nexport MCP_SKILLS_DIR=~/claude-skills\npoetry run mcp-skills\n```\n\n## Installation\n\n### Prerequisites\n\n- **Python 3.13+** (for development)\n- **Poetry 1.7+** (for dependency management)\n- **Docker** (optional, for containerized deployment)\n\n### Install with Poetry\n\n```bash\n# Clone the repository\ngit clone https://github.com/srprasanna/mcp-skill-hub.git\ncd mcp-skill-hub\n\n# Install dependencies\npoetry install\n\n# Verify installation\npoetry run mcp-skills --help\n```\n\n### Build Docker Image\n\n```bash\n# Build the image\ndocker build -t mcp-skill-hub .\n\n# Or use docker-compose\ndocker-compose build\n```\n\n## Usage\n\n### Running Locally\n\n```bash\n# Set the skills directory\nexport MCP_SKILLS_DIR=/path/to/your/skills\n\n# Run the server\npoetry run mcp-skills\n```\n\n### Running with Docker\n\n```bash\ndocker run -i --rm \\\n  -v /path/to/your/skills:/skills:ro \\\n  -e MCP_SKILLS_LOG_LEVEL=INFO \\\n  mcp-skill-hub\n```\n\n### Running with Docker Compose\n\n```bash\n# Edit docker-compose.yml to set your skills directory path\ndocker-compose up mcp-skills\n```\n\n### Integrating with Claude Desktop\n\nAdd to your Claude Desktop configuration (`claude_desktop_config.json`):\n\n```json\n{\n  \"mcpServers\": {\n    \"skills\": {\n      \"command\": \"docker\",\n      \"args\": [\n        \"run\",\n        \"-i\",\n        \"--rm\",\n        \"-v\",\n        \"${HOME}/claude-skills:/skills:ro\",\n        \"mcp-skill-hub\"\n      ]\n    }\n  }\n}\n```\n\n**Or using Poetry:**\n\n```json\n{\n  \"mcpServers\": {\n    \"skills\": {\n      \"command\": \"poetry\",\n      \"args\": [\"run\", \"mcp-skills\"],\n      \"cwd\": \"/path/to/mcp-skill-hub\",\n      \"env\": {\n        \"MCP_SKILLS_DIR\": \"/path/to/your/skills\"\n      }\n    }\n  }\n}\n```\n\n**Important:** Make sure your `${HOME}/claude-skills` directory contains skill folders, not loose SKILL.md files!\n\n## Configuration\n\nConfiguration is done via environment variables with the prefix `MCP_SKILLS_`:\n\n| Variable | Default | Description |\n|----------|---------|-------------|\n| `MCP_SKILLS_DIR` | `/skills` | Root directory containing skill folders |\n| `MCP_SKILLS_HOT_RELOAD` | `true` | Enable automatic reloading |\n| `MCP_SKILLS_DEBOUNCE_DELAY` | `0.5` | Delay (seconds) before reload |\n| `MCP_SKILLS_LOG_LEVEL` | `INFO` | Log level (DEBUG, INFO, WARNING, ERROR) |\n| `MCP_SKILLS_SCAN_DEPTH` | `1` | Scan depth (always 1) |\n\n### Example .env File\n\n```bash\nMCP_SKILLS_DIR=/path/to/skills\nMCP_SKILLS_HOT_RELOAD=true\nMCP_SKILLS_DEBOUNCE_DELAY=0.5\nMCP_SKILLS_LOG_LEVEL=INFO\n```\n\n## Skill File Format\n\nSkills are defined in `SKILL.md` files with YAML frontmatter:\n\n### Minimal Example\n\n```markdown\n---\nname: \"my-skill\"\ndescription: \"Brief description\"\n---\n\n# My Skill\n\nYour skill content here in Markdown.\n```\n\n### Complete Example\n\n```markdown\n---\n# Required fields\nname: \"excel-advanced\"\ndescription: \"Advanced Excel automation techniques\"\n\n# Version and authorship\nversion: \"1.2.0\"\nauthor: \"Your Name\"\ncreated: \"2025-01-15\"\nupdated: \"2025-10-23\"\n\n# Dependencies\ndependencies:\n  python: [\"openpyxl>=3.0.0\", \"pandas>=2.0.0\"]\n  system: [\"libreoffice\"]\n\n# Categorization\ncategory: \"office-automation\"\ntags: [\"excel\", \"spreadsheet\", \"automation\"]\ncomplexity: \"intermediate\"  # beginner|intermediate|advanced\n\n# Usage guidance\nwhen_to_use:\n  - \"Automating Excel report generation\"\n  - \"Processing multiple Excel files\"\n  - \"Creating complex formulas programmatically\"\n\n# Relationships\nrelated_skills: [\"csv-processing\", \"data-analysis\"]\n\n# Examples\nhas_examples: true\nexample_files: [\"examples/report_generator.py\", \"templates/report_template.xlsx\"]\n---\n\n# Excel Advanced Automation\n\nThis skill covers advanced Excel automation techniques...\n\n## Features\n\n- Automated report generation\n- Formula creation\n- Bulk processing\n\n## Examples\n\nSee `examples/report_generator.py` for a working example.\n```\n\n### Available Metadata Fields\n\n**Required:**\n- `name`: Unique identifier (kebab-case recommended)\n- `description`: Brief description\n\n**Optional:**\n- `version`: Semantic version\n- `author`: Creator name\n- `created`, `updated`: ISO dates (YYYY-MM-DD)\n- `dependencies`: Python packages or system tools\n- `category`: Main category for grouping\n- `tags`: Array of tags for search\n- `complexity`: beginner, intermediate, or advanced\n- `when_to_use`: Array of usage scenarios\n- `related_skills`: Names of related skills\n- `has_examples`: Boolean flag\n- `example_files`: Paths to example files (relative to skill folder)\n\n## MCP Resources and Tools\n\n### Resources\n\nThe server exposes these MCP resources:\n\n1. **`skill://catalog`** - JSON catalog of all skills with metadata\n2. **`skill://{name}`** - Individual skill markdown content\n\n### Tools\n\nFour tools are available for interacting with skills:\n\n#### 1. `search_skills`\n\nSearch for skills by query, category, tag, or complexity.\n\n```json\n{\n  \"query\": \"excel\",\n  \"category\": \"office-automation\",\n  \"tag\": \"automation\",\n  \"complexity\": \"intermediate\"\n}\n```\n\n#### 2. `reload_skills`\n\nManually trigger a reload of all skills from the directory.\n\n```json\n{}\n```\n\n#### 3. `get_skill_info`\n\nGet metadata for a specific skill without loading full content.\n\n```json\n{\n  \"name\": \"excel-advanced\"\n}\n```\n\n#### 4. `list_skill_folders`\n\nList all valid skill folders found in the skills directory.\n\n```json\n{}\n```\n\n## Development\n\n### Setup Development Environment\n\n```bash\n# Clone repository\ngit clone https://github.com/srprasanna/mcp-skill-hub.git\ncd mcp-skill-hub\n\n# Install dependencies (including dev dependencies)\npoetry install\n\n# Activate virtual environment\npoetry shell\n```\n\n### Running Tests\n\n```bash\n# Run all tests\npoetry run pytest\n\n# Run with coverage\npoetry run pytest --cov=mcp_skills --cov-report=html\n\n# Run specific test file\npoetry run pytest tests/test_scanner.py\n\n# Run with verbose output\npoetry run pytest -v\n```\n\n### Code Quality\n\n```bash\n# Format code\npoetry run black .\n\n# Lint code\npoetry run ruff check .\n\n# Type checking\npoetry run mypy src\n\n# Run all quality checks\npoetry run black . && poetry run ruff check . && poetry run mypy src\n```\n\n### Development Workflow\n\n1. **Create a branch:**\n   ```bash\n   git checkout -b feature/my-feature\n   ```\n\n2. **Make changes and test:**\n   ```bash\n   poetry run pytest\n   poetry run mypy src\n   ```\n\n3. **Format and lint:**\n   ```bash\n   poetry run black .\n   poetry run ruff check .\n   ```\n\n4. **Commit and push:**\n   ```bash\n   git commit -m \"Add feature: description\"\n   git push origin feature/my-feature\n   ```\n\n### Project Structure\n\n```\nmcp-skill-hub/\n├── src/mcp_skills/          # Source code\n│   ├── models/              # Data models\n│   ├── parsers/             # Skill parsers\n│   ├── storage/             # Repository pattern\n│   ├── scanner.py           # Directory scanning\n│   ├── watcher.py           # Hot-reload watcher\n│   ├── server.py            # MCP server\n│   ├── config.py            # Configuration\n│   └── __main__.py          # CLI entry point\n├── tests/                   # Test suite\n├── examples/                # Example skills\n├── docs/                    # Documentation\n└── pyproject.toml           # Poetry configuration\n```\n\n## Troubleshooting\n\n### Common Issues\n\n#### Skills Not Loading\n\n**Problem:** No skills are loaded when the server starts.\n\n**Solution:**\n1. Check that your skills are in dedicated folders:\n   ```\n   /skills/my-skill/SKILL.md  ✓\n   /skills/SKILL.md           ✗\n   ```\n2. Verify folder names don't start with `.` or `_`\n3. Check logs for detailed error messages\n\n#### Hot-Reload Not Working\n\n**Problem:** Changes to SKILL.md files aren't detected.\n\n**Solution:**\n1. Ensure `MCP_SKILLS_HOT_RELOAD=true`\n2. Check file is named exactly `SKILL.md`\n3. Verify file is in a valid skill folder\n4. Look for file watcher errors in logs\n\n#### Parsing Errors\n\n**Problem:** SKILL.md files fail to parse.\n\n**Solution:**\n1. Validate YAML frontmatter syntax\n2. Ensure frontmatter is between `---` delimiters\n3. Check required fields (`name`, `description`) are present\n4. Use a YAML validator to check syntax\n\n### Validation Command\n\nCheck your skills directory structure:\n\n```bash\npoetry run mcp-skills --validate\n```\n\nExpected output:\n```\n✓ /skills/excel-advanced: Valid skill\n✓ /skills/python-automation: Valid skill\n✗ /skills/SKILL.md: Error - Skills must be in folders\n✗ /skills/.hidden: Skipped - Hidden folder\n⚠ /skills/empty-folder: Warning - No SKILL.md found\n\nSummary: 2 valid, 1 error, 1 warning, 1 skipped\n```\n\n### Logging\n\nEnable debug logging for detailed information:\n\n```bash\nexport MCP_SKILLS_LOG_LEVEL=DEBUG\npoetry run mcp-skills\n```\n\nLogs include:\n- Folder structure validation messages\n- Scan progress and results\n- Parse successes and failures\n- Hot-reload events\n- Detailed error context\n\n## Contributing\n\nContributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.\n\n### Quick Contributing Guide\n\n1. Fork the repository\n2. Create a feature branch\n3. Make your changes with tests\n4. Ensure all tests pass and code is formatted\n5. Submit a pull request\n\n### Code Standards\n\n- **Python 3.13+** with type hints\n- **Black** for formatting (88 char line length)\n- **Ruff** for linting\n- **Mypy** for type checking (strict mode)\n- **Pytest** for testing (>80% coverage)\n\n## Releases\n\nThis project uses automated releases via GitHub Actions.\n\n### Creating a Release\n\n1. Go to **Actions** → **Release** workflow\n2. Click **Run workflow**\n3. Choose version bump type:\n   - `patch` - Bug fixes (0.1.0 → 0.1.1)\n   - `minor` - New features (0.1.0 → 0.2.0)\n   - `major` - Breaking changes (0.1.0 → 1.0.0)\n   - Or specify exact version (e.g., `1.2.3`)\n4. Select Docker registry (`docker.io` or `ghcr.io`)\n5. Click **Run workflow**\n\nThe workflow will:\n- ✅ Bump version in `pyproject.toml`\n- ✅ Create Git tag and GitHub release\n- ✅ Build and push Docker image\n- ✅ Run tests to verify release\n\n**Docker Images:**\n- Docker Hub: `{username}/mcp-skill-hub:{version}`\n- GitHub: `ghcr.io/{owner}/mcp-skill-hub:{version}`\n\nSee [RELEASING.md](docs/RELEASING.md) for detailed release documentation.\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## Acknowledgments\n\n- Built with [MCP Python SDK](https://github.com/anthropics/python-mcp-sdk)\n- Inspired by the need for dynamic skill management in Claude\n- Thanks to all contributors!\n\n---\n\n**Note:** This server makes it impossible to misunderstand the folder structure requirement through:\n- Clear error messages with folder context\n- Comprehensive logging\n- Validation at multiple levels\n- Detailed documentation\n- Working examples\n\nEach skill MUST be in its own folder. This design decision ensures clean organization, easy management, and unambiguous structure. 🎯\n",
  "bytes": 14816,
  "sha": "932af86c20b195f5fc9fc498d8ce8c52a069b3cc12ff7a8c7172e2ac64194f42",
  "repo_slug": "srprasanna/mcp-skill-hub",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_srprasanna_mcp_skill_hub_45bc5f82/readme"
}