📖 About

MCP Skill Registry is an open-source, self-hostable Model Context Protocol server that turns plain folders of skills and agents into tools any MCP client — Claude Code, Claude Desktop, GitHub Copilot — can discover and run. It ships with a curated catalogue (spec-driven development, legacy modernization, and ITSM integrations), a one-click Hugging Face deployment, and an Apple-inspired upload dashboard.

• Live demo: https://sarveshtalele-mcp-skills-registry.hf.space
• MCP endpoint: https://sarveshtalele-mcp-skills-registry.hf.space/mcp
• License: MIT · Status: active · Stack: FastAPI · Pydantic · Next.js

New here? Jump to Quick Start or Connect an MCP Client.

🎯 What It Does

MCP Skill Registry is one server that hosts many skills and exposes each one as a callable tool.

A skill is just a folder containing a SKILL.md manifest and a small script. Drop the folder in, and the server:

1. Discovers it automatically (reads the manifest at startup).
2. Publishes it on two interfaces at once:
   • as an MCP tool — usable from Claude Code, Claude Desktop, VS Code, Cursor, or any MCP client;
   • as a REST endpoint — usable from curl, scripts, or any HTTP app.
3. Executes it safely in an isolated subprocess with a hard timeout.

You add capabilities by adding folders or uploading a ZIP — never by editing the server.

   ┌─────────────┐     "list/run tools"      ┌────────────────────┐
   │  MCP client │ ────────────────────────► │                    │
   │ Claude Code │                           │   MCP Skill        │
   │ Claude Dsk. │ ◄──────────────────────── │   Registry server  │
   │  VS Code    │      tool results         │                    │
   └─────────────┘                           │   discovers every  │
   ┌─────────────┐     POST /api/v1/...      │   skills/<name>/   │
   │ REST caller │ ◄────────────────────────►│   folder           │
   └─────────────┘                           └─────────┬──────────┘
                                                       │ runs in
                                                       ▼ subprocess
                                          skills/text-statistics/
                                          skills/your-skill/ ...

🏗️ Architecture

        MCP clients                         REST clients
   (Claude Code / Desktop,            (curl, scripts, the
    GitHub Copilot, VS Code)            Next.js dashboard)
            │                                   │
            ▼  Streamable HTTP                  ▼  /api/v1
   ┌──────────────────────────────────────────────────────┐
   │                FastAPI application                    │
   │  api → mcp → services → repositories → db → models    │
   │  discovery · validation · sandboxed execution · audit │
   └──────────────────────────────────────────────────────┘
            │ discovers + runs                  │ persists
            ▼                                   ▼
   skills/ + agents/  (self-contained folders)   SQLite (history, audit)

Skills and agents are self-contained folders the FastAPI server auto-discovers and exposes as MCP tools (Streamable HTTP) and REST endpoints. Skills run in isolated subprocesses with a hard timeout; uploads can auto-publish to GitHub, which redeploys the Hugging Face Space.

✨ Features

🚀 Quick Start

Local development

git clone https://github.com/sarveshtalele/mcp-skills-registry.git
cd mcp-skills-registry

python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"

skill-registry          # serves on http://localhost:7860

curl http://localhost:7860/health
# {"status":"ok","version":"0.2.0","skills_loaded":1}

Docker

docker build -t mcp-skill-registry .
docker run -p 7860:7860 -v "$(pwd)/data:/data" mcp-skill-registry

Live demo

A public instance runs at https://sarveshtalele-mcp-skills-registry.hf.space — try the dashboard, browse skills, or connect your MCP client directly.

🏗️ Built-in Skills

The registry ships with production-ready skill suites out of the box.

📐 SpecKit — Spec-Driven Development

Inspired by GitHub Spec Kit, these skills drive a project from idea to backlog — usable from any MCP client:

Flow: constitution → specify → plan → tasks, committing each artifact as you go.

🏭 Factory — Governed Engineering

A modernization suite that takes a legacy system from discovery to a governed release:

Flow: legacy-discovery → topology-planning → task-decomposition → ui-modernization → test-generation → spec-governance

🔍 Change Impact Analysis

A graph-driven change impact analysis skill that builds dependency graphs, finds directly and transitively affected modules, validates API contracts for breaking changes, parses CODEOWNERS, and computes a 0–100 deployment risk score.

📊 Text Statistics

A simple, worked example skill — computes word count, character count, sentence count, and reading level for any text.

🔬 Real-World Example: Reverse-Engineering nopCommerce

The legacy-discovery skill can reverse-engineer entire codebases. Here's what it produces when pointed at the nopCommerce repository — a 3M+ download, enterprise-grade e-commerce platform:

# Via MCP client
"Reverse engineer https://github.com/nopSolutions/nopCommerce"

# Via REST API
curl -X POST http://localhost:7860/api/v1/skills/legacy-discovery/execute \
  -H 'Content-Type: application/json' \
  -d '{"inputs": {"repo_url": "https://github.com/nopSolutions/nopCommerce"}}'

🤖 Agents

Agents orchestrate skills through multi-step workflows. Load one in your MCP client to drive an end-to-end process:

GET /api/v1/agents lists them; upload your own via the dashboard or POST /api/v1/agents/upload.

🔌 External Integrations

Skills under skills/integrations/ call external systems (creds via Space env vars, never hard-coded; mutating skills require approval):

Add your own connector (Slack, GitHub issues, PagerDuty, …) the same way: a skill folder whose scripts/main.py reads credentials from the environment and calls the target API with the standard library. Missing credentials return a clear error.

🖥️ Dashboard UI

An Apple-inspired Next.js dashboard is the landing page (static export built into the image; served by FastAPI). It lets you:

• Browse all skills and agents with search
• Upload a skill, a speckit skill, or an agent — Validate format first, then Upload & Publish
• Delete skills and agents directly from the UI

With SKILLREG_GITHUB_TOKEN set, publishing also commits to the repo's skills/ or agents/ folder, redeploying the Space.

Live: sarveshtalele-mcp-skills-registry.hf.space

🔗 Connect an MCP Client

The server speaks Streamable HTTP MCP transport at /mcp. Use your local URL (http://localhost:7860/mcp) or the hosted one (https://sarveshtalele-mcp-skills-registry.hf.space/mcp).

Claude Code

claude mcp add --transport http skill-registry \
  https://sarveshtalele-mcp-skills-registry.hf.space/mcp

Verify inside a session:

/mcp          # lists connected servers and their tools

Remove with claude mcp remove skill-registry.

Claude Desktop

1. Open Settings → Developer → Edit Config (opens claude_desktop_config.json).

2. Add the server:

   {
     "mcpServers": {
       "skill-registry": {
         "command": "npx",
         "args": [
           "-y", "mcp-remote",
           "https://sarveshtalele-mcp-skills-registry.hf.space/mcp"
         ]
       }
     }
   }
   

   Claude Desktop launches MCP servers as local processes, so it reaches a remote HTTP server through the mcp-remote bridge (npx fetches it automatically; requires Node.js). Alternatively, Settings → Connectors → Add custom connector accepts the /mcp URL directly on supported plans.

3. Restart Claude Desktop. The skills appear as tools (look for the 🔌 icon).

VS Code (GitHub Copilot / Continue)

Create .vscode/mcp.json:

{
  "servers": {
    "skill-registry": {
      "type": "http",
      "url": "https://sarveshtalele-mcp-skills-registry.hf.space/mcp"
    }
  }
}

Any MCP client (raw protocol)

The endpoint is JSON-RPC 2.0 over HTTP POST.

# 1. initialize — returns an Mcp-Session-Id header
curl -i -X POST http://localhost:7860/mcp \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}'

# 2. list tools
curl -X POST http://localhost:7860/mcp \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'

# 3. call a tool
curl -X POST http://localhost:7860/mcp \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":3,"method":"tools/call",
       "params":{"name":"text-statistics","arguments":{"text":"Hello world."}}}'

🧰 REST API

Every skill is reachable without MCP. Interactive API docs (/docs, /redoc, /openapi.json) are disabled by default for safety — enable with SKILLREG_ENABLE_DOCS=true in trusted environments.

# Example: run a skill
curl -X POST http://localhost:7860/api/v1/skills/text-statistics/execute \
  -H 'Content-Type: application/json' \
  -d '{"inputs": {"text": "The quick brown fox jumps over the lazy dog."}}'

⚙️ Architecture

The server is a small, layered FastAPI application. Each layer depends only on the layers beneath it, keeping it testable and easy to extend.

┌──────────────────────────────────────────────────────────────────────┐
│                     FastAPI application  (port 7860)                │
│                                                                     │
│   api/        Routers:  /  ·  /health  ·  /mcp  ·  /api/v1/skills  │  ← transport
│     │                                                               │
│   mcp/        Streamable HTTP transport · JSON-RPC 2.0 · sessions   │  ← MCP protocol
│     │                                                               │
│   services/   SkillRegistry (facade)                                │  ← application
│     │           ├─ loader      parse & validate SKILL.md            │     logic
│     │           ├─ validator   check inputs against the manifest    │
│     │           ├─ executor    run skill in a sandboxed subprocess  │
│     │           ├─ search      keyword / optional semantic ranking  │
│     │           ├─ installer   safe ZIP upload (zip-slip/bomb guard)│
│     │           ├─ publisher   auto-commit to GitHub on upload      │
│     │           └─ audit       append-only event log                │
│     │                                                               │
│   repositories/  execution history · audit trail                    │  ← persistence
│     │                                                               │
│   db/  models/  config/  container/  main                           │  ← storage, types,
│         SQLite + schema.sql · pydantic models · settings · wiring   │     wiring
└───────────────────────────────────┬──────────────────────────────────┘
                                    │ discovers & executes
                                    ▼
                       skills/   self-contained skill folders
                         └─ <name>/  SKILL.md · scripts/ · references/ · assets/

Request lifecycle (running a tool)

client → tools/call (MCP)  or  POST /api/v1/skills/{name}/execute (REST)
   │
   ├─ 1. look up the skill in the in-memory catalogue        (404 if unknown)
   ├─ 2. validate inputs against SKILL.md                    (types, required, enums)
   ├─ 3. spawn subprocess: python _runner.py <skill> run     (isolated, timed)
   │         inputs → JSON via stdin   ·   output → JSON via stdout
   ├─ 4. enforce timeout + output-size cap                   (kill child on overrun)
   ├─ 5. record execution + audit entry                      (SQLite)
   └─ 6. return { status, output | error, duration_ms }

Why subprocesses? Process-level isolation, a clean import namespace per call, and a reliable hard timeout — a misbehaving skill can never hang or crash the server.

🧩 Authoring a Skill

A skill is one self-contained folder:

skill-name/
├── SKILL.md          # Required: YAML frontmatter (manifest) + instructions
├── scripts/          # Optional: code — entrypoint exposes run(inputs) -> dict
├── references/       # Optional: supporting docs
├── assets/           # Optional: templates, resources, extra requirements.txt
└── ...               # Any additional files

1. Scaffold

python scripts/new_skill.py my-skill

2. Define SKILL.md

---
name: my-skill
version: 1.0.0
description: What it does and the phrases that should trigger it.
execution:
  type: python-script
  entrypoint: scripts/main.py:run
  timeout_seconds: 30
inputs:
  - name: text
    type: string
    required: true
    description: Text to process.
outputs:
  - name: result
    type: string
    description: Processed text.
---

# My Skill
Instructions for the agent.

3. Implement scripts/main.py

def run(inputs: dict) -> dict:
    return {"result": inputs["text"].upper()}

4. Register

# Option A: reload the running server
curl -X POST http://localhost:7860/api/v1/admin/reload

# Option B: upload a packaged skill (no restart needed)
zip -r my-skill.zip my-skill/
curl -X POST http://localhost:7860/api/v1/skills/upload -F '[email protected]'

📖 Full guide: docs/ADDING_A_SKILL.md

🌍 Deployment

Hugging Face Spaces (recommended)

The project is designed for Hugging Face Docker Spaces out of the box.

GitHub (source of truth)  ──push main──►  HF Space (Docker build)  ──►  live MCP server
        │                                         │
   CI: lint + test                        Dockerfile → uvicorn :7860

1. Create a Docker Space on huggingface.co/new-space
2. Add HF_TOKEN secret and HF_USERNAME/HF_SPACE variables to your GitHub repo
3. Push to main — CI runs lint + tests, then auto-deploys to the Space

Docker (anywhere)

docker build -t mcp-skill-registry .
docker run -p 7860:7860 -v "$(pwd)/data:/data" mcp-skill-registry

Manual deploy

pip install huggingface_hub
huggingface-cli login
huggingface-cli upload <user>/mcp-skill-registry . . --repo-type space

📖 Full guide: docs/DEPLOYMENT.md

🔧 Configuration

All settings are environment variables with the SKILLREG_ prefix (see .env.example):

🧪 Development

make install   # editable install with dev extras
make test      # pytest (37+ tests)
make lint      # ruff + black --check
make format    # ruff --fix + black
make run       # local dev server

CI runs lint + tests on every push and PR across Python 3.10, 3.11, and 3.12.

Running tests

pytest -q                     # all tests
pytest tests/test_api.py      # specific test module
pytest -k "test_upload"       # by name pattern

Code quality

📁 Project Structure

mcp-skills-registry/
├── src/skill_registry/         # the server (layered package)
│   ├── api/                    # HTTP routers (health, mcp, rest)
│   ├── mcp/                    # JSON-RPC 2.0 protocol handler
│   ├── services/               # business logic
│   │   ├── registry.py         # facade: coordinates all services
│   │   ├── loader.py           # SKILL.md parser & skill discovery
│   │   ├── validator.py        # input validation against manifests
│   │   ├── executor.py         # subprocess execution + timeout
│   │   ├── _runner.py          # child process skill runner
│   │   ├── search.py           # keyword & semantic search
│   │   ├── installer.py        # ZIP upload (zip-slip/bomb guards)
│   │   ├── github_publisher.py # auto-commit uploads to GitHub
│   │   ├── agent_loader.py     # AGENT.md parser & agent discovery
│   │   └── audit.py            # append-only audit trail
│   ├── repositories/           # execution history & audit persistence
│   ├── db/                     # SQLite wrapper + schema.sql
│   ├── models/                 # pydantic domain models
│   ├── config.py               # env-driven settings (SKILLREG_*)
│   ├── container.py            # composition root (build_container)
│   └── main.py                 # app factory + CLI entrypoint
│
├── skills/                     # self-contained skills (auto-discovered)
│   ├── _template/              # scaffold skeleton for new skills
│   ├── text-statistics/        # worked example
│   ├── change-impact-analysis/ # graph-driven deployment risk analysis
│   ├── speckit/                # spec-driven development suite
│   │   ├── constitution/
│   │   ├── specify/
│   │   ├── plan/
│   │   └── tasks/
│   └── factory/                # governed engineering suite
│       ├── legacy-discovery/
│       ├── topology-planning/
│       ├── task-decomposition/
│       ├── ui-modernization/
│       ├── test-generation/
│       └── spec-governance/
│
├── agents/                     # agent orchestration definitions
│   ├── arch-analyst/
│   ├── migration-eng/
│   └── gatekeeper/
│
├── frontend/                   # Next.js dashboard (static export)
│   ├── app/                    # Next.js app router pages
│   └── out/                    # built static files (served by FastAPI)
│
├── scripts/                    # utilities
│   ├── new_skill.py            # scaffold a new skill
│   └── hf_entrypoint.sh        # Hugging Face Spaces boot script
│
├── tests/                      # pytest suite
│   ├── test_api.py             # REST API tests
│   ├── test_mcp_transport.py   # MCP protocol tests
│   ├── test_loader.py          # skill loader tests
│   ├── test_validator.py       # input validation tests
│   ├── test_executor.py        # subprocess execution tests
│   ├── test_upload.py          # ZIP upload + install tests
│   ├── test_agents.py          # agent loading + API tests
│   └── test_github_publisher.py # GitHub auto-publish tests
│
├── docs/                       # extended documentation
│   ├── ARCHITECTURE.md         # layered design & execution model
│   ├── ADDING_A_SKILL.md       # full skill authoring guide
│   ├── DEPLOYMENT.md           # GitHub → HF Spaces pipeline
│   └── SKILL_AND_AGENT_REFERENCE.md  # file-by-file reference
│
├── .github/workflows/
│   ├── ci.yml                  # lint + test on Python 3.10–3.12
│   └── deploy-hf.yml          # auto-deploy to Hugging Face Spaces
│
├── Dockerfile                  # multi-stage: Node (frontend) + Python (server)
├── pyproject.toml              # project metadata, deps, tool config
├── requirements.txt            # HF Spaces runtime deps
├── Makefile                    # dev shortcuts (install, test, lint, run)
├── app.py                      # thin ASGI entrypoint shim
├── CONTRIBUTING.md             # contributor guide
└── LICENSE                     # MIT

🗺️ Roadmap

• Authentication & API keys — per-skill access control
• Skill versioning — run multiple versions side-by-side
• Execution analytics dashboard — visualize usage, latency, and error rates
• Webhook notifications — trigger on skill execution events
• Plugin marketplace — community skill discovery and one-click install
• Rate limiting — configurable per-skill and global throttling
• Async / streaming execution — long-running skills with progress updates
• Multi-language runtimes — support Node.js, Go, Rust skill scripts

🤝 Contributing

Contributions are welcome! See CONTRIBUTING.md for guidelines.

# Dev setup
python -m venv .venv && source .venv/bin/activate
make install

# Before opening a PR
make format         # ruff --fix + black
make lint           # ruff + black --check
make test           # pytest

Adding a skill

Submit a PR that adds a single skills/<name>/ folder with:

• A valid SKILL.md with YAML frontmatter
• An entrypoint exposing run(inputs) -> dict
• At least one test

Conventions

• Layered architecture: api → services → repositories → db → models — don't reach across layers
• Type-hint public functions; keep modules small and single-purpose
• Line length 100; formatting by black; linting by ruff

📖 Documentation

📄 License

MIT — see LICENSE.