Mcp Skills Registry

🧩 MCP Skill Registry

A self-hostable Model Context Protocol server that turns a folder of "skills" into tools any MCP client can discover and run.

[](https://github.com/sarveshtalele/mcp-skills-registry/actions/workflows/ci.yml) [](https://www.python.org/downloads/) [](LICENSE) [](https://github.com/psf/black) [](https://sarveshtalele-mcp-skills-registry.hf.space)

[What It Does](#-what-it-does) · [Quick Start](#-quick-start) · [Built-in Skills](#-built-in-skills) · [Connect a Client](#-connect-an-mcp-client) · [Author a Skill](#-authoring-a-skill) · [Deploy](#-deployment) · [Contributing](#-contributing)

---

📖 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](#-quick-start) or [Connect an MCP Client](#-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.

1. 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//   │
   │ 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

| | Feature | Description | |---|---|---| | 🔌 | Dual interface | Every skill is an MCP tool and a REST resource | | 🧭 | Zero-config discovery | Skills are plain folders; no registration code | | 🛡️ | Sandboxed execution | Subprocess isolation, per-skill timeouts, output caps | | 📤 | Live uploads | Install a skill from a ZIP via the API or dashboard; no restart | | 🌐 | Native MCP | Streamable HTTP transport with sessions; no bridge needed | | 🔍 | Search | Keyword out of the box, optional semantic (vector) search | | 🏭 | Engineering Factory | Built-in skill suite for legacy modernization and governance | | 📐 | Spec-Driven Development | SpecKit skills drive a project from idea to backlog | | 🤖 | Agent orchestration | Agents compose skills into multi-step workflows | | 🖥️ | Dashboard UI | Apple-inspired Next.js dashboard for browsing, searching, and uploading | | 📝 | Audit trail | Append-only event log for every execution and catalogue change | | 🧱 | Clean codebase | Layered, typed, 37+ tests, CI on Python 3.10–3.12 |

---

🚀 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:

| Skill | Produces | |---|---| | speckit-constitution | Project principles (constitution.md) | | speckit-specify | A structured spec (spec.md) from a feature description | | speckit-plan | A technical plan (plan.md) from a spec summary | | speckit-tasks | An ordered task backlog (tasks.md) from a plan |

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:

| Skill | Purpose | |---|---| | legacy-discovery | Reverse-engineer a legacy app (scans a repo URL or local path) → spec + architecture + inventory | | topology-planning | Target architecture + phased migration plan + ADRs | | task-decomposition | Spec → dependency-ordered tasks.yaml backlog | | ui-modernization | Legacy UI → React component plan + starter stubs | | test-generation | Unit/integration/e2e test strategy + stubs | | spec-governance | Compliance audit with a pass/fail gate and score |

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:

📋 Click to expand: nopCommerce analysis output (generated by legacy-discovery)

The skill automatically produces:

• System Design Document — full architectural analysis with layered architecture model
• 150+ domain entity inventory — Products, Orders, Customers, Payments, Shipping, etc.
• 50+ service module mapping — ICatalogService, IOrderService, IPaymentService, etc.
• Plugin architecture breakdown — Payment, Shipping, Tax, Auth, Widget plugin taxonomies
• Database schema analysis — entity relationships, migration history (1.90 → 5.00)
• Security architecture — RBAC, AES encryption, GDPR compliance, OWASP headers
• Event system documentation — pub/sub patterns, cache invalidation chains
• 100-point quality score — codebase health metrics

All from a single command:

# 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"}}'

The returned analysis includes architectural diagrams, code patterns, entity relationships, and actionable modernization recommendations — no manual effort required.

---

🤖 Agents

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

| Agent | Orchestrates | Purpose | |---|---|---| | arch-analyst | legacy-discovery → topology-planning | Reverse-engineer & define target architecture | | migration-eng | task-decomposition → ui-modernization → test-generation | Build the modernization solution | | gatekeeper | spec-governance | Governance & compliance enforcement |

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):

| Skill | Creates | Required env vars | | --- | --- | --- | | jira-ticket | a Jira issue | JIRA_BASE_URL, JIRA_EMAIL, JIRA_API_TOKEN | | servicenow-ticket | a ServiceNow incident | SERVICENOW_INSTANCE, SERVICENOW_USER, SERVICENOW_PASSWORD |

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:

``json { "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.

1. 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."}}}'

| Method | Behaviour | |---|---| | POST /mcp | initialize, tools/list, tools/call, ping (single or batch) | | GET /mcp | 405 — no server-initiated stream (spec-permitted) | | DELETE /mcp | Terminate the session in the Mcp-Session-Id header |

---

🧰 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.

| Method & Path | Description | |---|---| | GET / | Service metadata + entry points | | GET /health | Liveness probe + skill count | | GET /api/v1/skills | List / search skills (q, category, limit, offset) | | GET /api/v1/skills/{name} | Full skill manifest | | POST /api/v1/skills/{name}/execute | Run a skill — body {"inputs": {...}} | | POST /api/v1/skills/upload | Install a skill from a ZIP (?overwrite=true) | | POST /api/v1/skills/validate | Validate a skill ZIP without installing | | DELETE /api/v1/skills/{name} | Delete a skill | | GET /api/v1/agents | List all agents | | POST /api/v1/agents/upload | Install an agent from a ZIP | | DELETE /api/v1/agents/{name} | Delete an agent | | POST /api/v1/admin/reload | Re-scan the skills and agents directories |

# 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  │
│     │           ├─ sea

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [sarveshtalele](https://github.com/sarveshtalele)
- **Source:** [sarveshtalele/mcp-skills-registry](https://github.com/sarveshtalele/mcp-skills-registry)
- **License:** MIT
- **Homepage:** https://sarveshtalele-mcp-skills-registry.hf.space

Install and usage instructions live in the source repository linked above.