# Mcp Skills Registry

> Self-hostable Model Context Protocol (MCP) server that turns folders of skills & agents into tools any MCP client can discover and run. FastAPI + Next.js, deployable to Hugging Face.

- **Type:** MCP server
- **Install:** `agentstack add mcp-sarveshtalele-mcp-skills-registry`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [sarveshtalele](https://agentstack.voostack.com/s/sarveshtalele)
- **Installs:** 0
- **Category:** [Developer Tools](https://agentstack.voostack.com/c/developer-tools)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [sarveshtalele](https://github.com/sarveshtalele)
- **Source:** https://github.com/sarveshtalele/mcp-skills-registry
- **Website:** https://sarveshtalele-mcp-skills-registry.hf.space

## Install

```sh
agentstack add mcp-sarveshtalele-mcp-skills-registry
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 🧩 MCP Skill Registry

### A self-hostable [Model Context Protocol](https://modelcontextprotocol.io) 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](https://modelcontextprotocol.io) 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.
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**.

```text
   ┌─────────────┐     "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

```bash
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
```

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

### Docker

```bash
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](https://github.com/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](https://github.com/nopSolutions/nopCommerce) — 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:

```bash
# 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](https://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

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

Verify inside a session:

```text
/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.

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

### VS Code (GitHub Copilot / Continue)

Create `.vscode/mcp.json`:

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

```bash
# 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 |

```bash
# 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.

```text
┌──────────────────────────────────────────────────────────────────────┐
│                     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.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** yes
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-sarveshtalele-mcp-skills-registry
- Seller: https://agentstack.voostack.com/s/sarveshtalele
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.