skills-mcp-server

Ein leistungsstarker MCP-Server (Model Context Protocol), der einen Katalog von über 1300 KI-Skills durch BM25-gerankte Suche, strukturierte Metadaten und kontexteffiziente Antworten bereitstellt.

Entwickelt, um ein Problem zu lösen: Tausende von Skills zerstören Ihr Kontextfenster. Dieser Server indiziert sie, bewertet sie und liefert nur das, was Sie benötigen.

┌────────────────────────────────────────────────────────────┐
│  IDE / AI Client                                           │
│  (Claude, Cursor, Gemini, Copilot, Windsurf, ...)         │
│                                                            │
│  "find me a skill for React dashboards"                    │
└──────────────────────┬─────────────────────────────────────┘
                       │ MCP Protocol
                       ▼
┌────────────────────────────────────────────────────────────┐
│  skills-mcp-server                                         │
│                                                            │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐                │
│  │ Indexer   │  │ BM25     │  │ 6 MCP    │                │
│  │ 1300+    │──│ Search   │──│ Tools    │                │
│  │ skills   │  │ Engine   │  │          │                │
│  └──────────┘  └──────────┘  └──────────┘                │
│                                                            │
│  Transports: stdio | HTTP/SSE | AWS Lambda                 │
└────────────────────────────────────────────────────────────┘

Funktionen

BM25-gerankte Suche — Kein einfaches Keyword-Matching. Echte Relevanzbewertung mit Feldgewichtung (Name 3x, Beschreibung 2x, Tags 2x, Inhalt 1x)
Kontexteffizient — Lesen Sie Skill-Metadaten (~500 Zeichen), Zusammenfassungen (~2K Zeichen) oder den vollständigen Inhalt (begrenzt auf 25K Zeichen). Sie steuern, wie viel Kontext verbraucht wird
Strukturierte Metadaten — YAML-Frontmatter, geparst in typisierte Felder: Name, Beschreibung, Tags, Kategorie, Risiko, Autor, Tools
Überall Paginierung — Jedes Listen-/Such-Tool unterstützt offset und limit
3 Transportmodi — stdio für lokale IDEs, HTTP/SSE für Fernzugriff, AWS Lambda für Serverless
Schneller Start — Über 1300 Skills in ~1,5 Sekunden indiziert. ~3MB Speicherbedarf (im Vergleich zu 65MB roh)
6 spezialisierte Tools — Durchsuchen, Auflisten, Suchen, Lesen, Inspizieren, Aktualisieren

Schnellstart

Voraussetzungen

Node.js 18+
Das Verzeichnis skills/ mit SKILL.md-Dateien (siehe Skill-Format)

Installieren & Bauen

git clone https://github.com/LucasRomanzin/skills-mcp-server.git
cd skills-mcp-server
npm install
npm run build

Lokal ausführen (stdio)

node dist/index.js

Als HTTP-Server ausführen (SSE)

node dist/http.js
# Server starts on http://localhost:3000
# MCP endpoint: http://localhost:3000/mcp
# Health check: http://localhost:3000/health

MCP-Tools

`skills_browse_categories`

Listet alle Skill-Kategorien mit Anzahl auf. Verwenden Sie dies zuerst.

Input:  { response_format?: "markdown" | "json" }
Output: Table with 9 categories and skill counts

`skills_search`

BM25-gerankte Volltextsuche über Namen, Beschreibungen, Tags und Inhalte.

Input:  { query: string, category?: string, risk?: string, offset?: 0, limit?: 10 }
Output: Ranked results with name, description, category, tags, score

`skills_list_by_category`

Listet Skills innerhalb einer bestimmten Kategorie mit Paginierung auf.

Input:  { category: string, offset?: 0, limit?: 20 }
Output: Paginated skill list with metadata

`skills_read`

Liest Skill-Inhalte mit Kontextsteuerung.

Input:  { slug: string, section?: "metadata" | "summary" | "full", file?: string }

section="metadata"  →  ~500 chars   (frontmatter fields + file list)
section="summary"   →  ~2500 chars  (metadata + first 2000 chars of body)
section="full"      →  up to 25000 chars (complete content, truncated if larger)

`skills_inspect`

Ruft strukturierte Metadaten für mehrere Skills ab + verwandte Skills durch Tag-Überschneidungen.

Input:  { slugs: string[] (1-10), response_format?: "json" }
Output: Metadata + related_skills for each slug

`skills_refresh_index`

Erstellt den In-Memory-Index neu, nachdem Skills auf der Festplatte hinzugefügt, entfernt oder geändert wurden.

Input:  {}
Output: Previous count, new count, duration

IDE-Konfiguration

Claude Desktop / Claude Code

{
  "mcpServers": {
    "skills": {
      "command": "node",
      "args": ["/path/to/skills-mcp-server/dist/index.js"],
      "env": {
        "SKILLS_DIR": "/path/to/skills-mcp-server/skills"
      }
    }
  }
}

Remote (HTTP/SSE) — Cursor, VS Code, jeder MCP-Client

{
  "mcpServers": {
    "skills": {
      "url": "http://localhost:3000/mcp"
    }
  }
}

AWS Lambda (nach dem Deployment)

{
  "mcpServers": {
    "skills": {
      "url": "https://<function-url-id>.lambda-url.<region>.on.aws/mcp"
    }
  }
}

Siehe docs/SETUP.md für vollständige Schritt-für-Schritt-Anleitungen für alle Modi und IDEs.

Deployment-Modi

Modus	Befehl	Anwendungsfall	SSE-Streaming
stdio	`node dist/index.js`	Lokale IDEs (Claude, Cursor, Gemini CLI)	N/A
HTTP	`node dist/http.js`	Dev-Server, EC2, VPS, Docker	Ja
Lambda	SAM deploy	Serverless, Auto-Scaling, Pay-per-Use	Ja (Antwort-Streaming)

Skill-Format

Jeder Skill ist ein Verzeichnis unter skills/, das mindestens eine SKILL.md-Datei mit YAML-Frontmatter enthält:

skills/
├── CATALOG.md              # Category-to-skill mapping (auto-generated)
├── my-skill/
│   ├── SKILL.md            # Required: frontmatter + content
│   ├── references/         # Optional: additional .md files
│   └── scripts/            # Optional: helper scripts

SKILL.md-Struktur

---
name: my-skill
description: What this skill does in one sentence.
tags:
  - react
  - dashboard
  - frontend
risk: safe
source: community
author: your-name
tools:
  - claude-code
  - cursor
---

# My Skill

## Overview
...

## When to Use This Skill
...

Frontmatter-Felder

Feld	Typ	Erforderlich	Beschreibung
`name`	string	Ja	Skill-Bezeichner
`description`	string	Ja	Einzeilige Beschreibung
`tags`	string[]	Nein	Suchbare Schlüsselwörter
`risk`	enum	Nein	`safe`, `critical`, `offensive`, `unknown`, `none`
`source`	string	Nein	Herkunft (`community`, `official`)
`author`	string	Nein	Name des Erstellers
`tools`	string[]	Nein	Kompatible KI-Tools

Architektur

src/
├── index.ts              # stdio entry point
├── http.ts               # Express HTTP/SSE entry point
├── lambda.ts             # AWS Lambda handler
├── server.ts             # McpServer factory (shared)
├── constants.ts          # CHARACTER_LIMIT, pagination defaults
├── types.ts              # TypeScript interfaces
├── indexer.ts            # Frontmatter parser + skill index builder
├── catalog.ts            # CATALOG.md parser → category mapping
├── search.ts             # BM25 scoring engine
├── tools/
│   ├── browse.ts         # skills_browse_categories
│   ├── list.ts           # skills_list_by_category
│   ├── search.ts         # skills_search
│   ├── read.ts           # skills_read
│   ├── inspect.ts        # skills_inspect
│   └── refresh.ts        # skills_refresh_index
└── utils/
    ├── frontmatter.ts    # gray-matter wrapper + tag normalization
    ├── format.ts         # Markdown/JSON response formatters
    ├── truncate.ts       # CHARACTER_LIMIT enforcement
    └── paginate.ts       # Generic pagination

Suchmaschine

Die BM25-Implementierung indiziert jeden Skill als gewichtetes Dokument:

Feld	Gewichtung	Beispiel
`name`	3x	"react-patterns" 3-mal wiederholt
`description`	2x	"Modern React patterns..." 2-mal wiederholt
`tags`	2x	"react frontend hooks" 2-mal wiederholt
`category`	1x	"development"
`summary`	1x	Erste 500 Zeichen des Inhalts

Die Bewertung verwendet BM25 mit k1=1.5, b=0.75. Die Ergebnisse werden nach absteigendem Relevanz-Score sortiert.

Leistung: Die Suche über 1300+ Skills erfolgt in <10ms.

Umgebungsvariablen

Variable	Standardwert	Beschreibung
`SKILLS_DIR`	`~/skills-mcp/skills`	Pfad zum Skills-Verzeichnis
`PORT`	`3000`	HTTP-Server-Port (nur http.ts)

Tech-Stack

TypeScript — Strict Mode, ESM
MCP SDK v1.29+ — StreamableHTTPServerTransport, WebStandardStreamableHTTPServerTransport
gray-matter — YAML-Frontmatter-Parsing
Zod — Eingabevalidierungsschemata
BM25 — Eigene Implementierung (~80 Zeilen), keine externen Abhängigkeiten

Lizenz

MIT

skills-mcp-server

skills-mcp-server

Funktionen

Schnellstart

Voraussetzungen

Installieren & Bauen

Lokal ausführen (stdio)

Als HTTP-Server ausführen (SSE)

MCP-Tools

`skills_browse_categories`

`skills_search`

`skills_list_by_category`

`skills_read`

`skills_inspect`

`skills_refresh_index`

IDE-Konfiguration

Claude Desktop / Claude Code

Remote (HTTP/SSE) — Cursor, VS Code, jeder MCP-Client

AWS Lambda (nach dem Deployment)

Deployment-Modi

Skill-Format

SKILL.md-Struktur

Frontmatter-Felder

Architektur

Suchmaschine

Umgebungsvariablen

Tech-Stack

Lizenz

Resources

Looking for Admin?

Latest Blog Posts

MCP directory API