SkillMCP (Skill-Management-System)

Ein containerisierter, horizontal skalierbarer Model Context Protocol (MCP)-Server zum Verteilen und Verwalten von KI-Agenten-Skills.

Übersicht & Motivation

KI-Agenten sind auf domänenspezifische Skills (Anweisungen, Metadaten, Schemata und Referenz-Assets) angewiesen, um komplexe technische und analytische Aufgaben auszuführen. Die Verwaltung von Skills über verschiedene Teams und Agentenflotten hinweg bringt jedoch häufig kritische betriebliche Herausforderungen mit sich:

• Fragmentierte und veraltete Skills: In verstreuten einzelnen Repositories gespeicherte oder manuell kopierte Skills sind schnell nicht mehr synchron, sodass Agenten veraltete oder inkompatible Workflows ausführen.

• Verteilungs- und Aktualisierungsengpässe: Die Verteilung von Skill-Updates über verteilte Agenteninstanzen erfordert manuelle Synchronisation oder fragile Dateikopierschritte.

• Fehlende Versionierung & Reibungsverluste bei der Diagnose: Wenn Skills ohne unveränderliche Versionierung bearbeitet werden, wird die Diagnose von Regressionen oder Verhaltensänderungen der Agenten nahezu unmöglich.

• Skalierungsgrenzen eines einzelnen Hosts: Herkömmliche stdio-basierte MCP-Server sind an einzelne lokale Host-Prozesse gebunden, was horizontale Skalierung und Hochverfügbarkeit blockiert.

SkillMCP löst diese Herausforderungen, indem es ein zentralisiertes, containerisiertes und horizontal skalierbares Skill-Management-System bereitstellt, das auf zustandslosem Streamable HTTP (mit abwärtskompatibler SSE-Unterstützung) basiert.

Related MCP server: skilldb-mcp

Kernfunktionen & Features

1. Zentralisierte & versionierte Skill-Paketierung

• Unveränderliche Container-Releases: Skills (SKILL.md, references/ und examples/) werden direkt in Docker-Images mit explizitem Semver-Tag (v1.2.0) verpackt, was 100 % reproduzierbare Umgebungen und Auditierbarkeit gewährleistet.

• Einheitliches Skill-Repository: Beseitigt die fragmentierte Multi-Repo-Drift, indem alle domänenspezifischen Skills in einem einzigen wartbaren Repository verwaltet, validiert und gebündelt werden.

• Schnelle Fehlersuche & Nachvollziehbarkeit: Versionierte Container-Tags machen es einfach, Agentenprobleme zu diagnostizieren, historisches Verhalten zu reproduzieren und Änderungen sofort zurückzurollen.

2. Zustandsloses MCP über Streamable HTTP (horizontale Skalierbarkeit)

• Echte zustandslose Request/Response-Architektur: Streamable HTTP verwendet standardmäßige HTTP-POST-Anfragen, bei denen Backend-Instanzen keinen langlebigen In-Memory-Socket-Zustand zwischen Client-Aufrufen aufrechterhalten.

• Session-Entkopplung & horizontale Skalierung: Einzelne Anfragen können ohne Sticky-Sessions an eine beliebige Backend-Container-Replik hinter einem Nginx-Reverse-Proxy oder Load Balancer weitergeleitet werden.

• Kurzlebiges Streaming: Antworten, die Streaming erfordern, werden nur für die Dauer des jeweiligen Payloads auf text/event-stream hochgestuft und sofort geschlossen, sobald die JSON-RPC-Antwort abgeschlossen ist.

• Legacy-SSE-Kompatibilität: Unterstützt Legacy-Server-Sent-Events (/sse) mit konfigurierter Proxy-Pufferumgehung (proxy_buffering off) und erweiterten Read-Timeouts für Clients, die persistente Kanäle benötigen.

• Nginx-Ingress-Lastverteilung: Konfiguriert mit least_conn-Routing, Keepalive-Verbindungspooling und dedizierten /healthz-Healthchecks für Rolling Updates ohne Ausfallzeiten.

[!WARNING] Transport & horizontale Skalierbarkeit:

• Streamable HTTP (default, empfohlen): Wirklich zustandslos. Ermöglicht horizontale Auto-Skalierung und beliebige Lastverteilung über Replicas hinweg ohne Session-Affinität.

• Natives SSE (SKILLMCP_TRANSPORT=sse): Zustandsbehaftet aufgrund der persistenten TCP-Stream-Bindung. Im nativen SSE-Modus führt horizontale Skalierung hinter standardmäßigen Round-Robin-/Least-Connections-Lastverteilern zu POST /messages-Routingfehlern, sofern keine Sticky-Sessions (z. B. Nginx ip_hash oder Cookie-Affinität) verwendet werden oder ein Einzel-Replica-Deployment zum Einsatz kommt.

3. Entwickler- & Agenten-Werkzeuge

• Integrierte Skill-Validator-CLI: skillmcp validate ./skills prüft automatisch Verzeichnisstrukturen, YAML-Frontmatter und Asset-Links vor der Paketierung.

• Dynamische Erkennung & Suche:

  • MCP-Tools: list_skills, get_skill, search_skills, read_skill_reference, read_skill_example.

  • MCP-Ressourcen: skill://{name} zur direkten Inspektion von Markdown-Dokumenten.

• Zwei Compose-Umgebungen: docker-compose.local.yml für sofortige lokale Entwicklung mit per Volume eingebundenem Hot Reloading und docker-compose.yml für Produktionsbereitstellungen.

• TREM-Python-Standard: Entwickelt streng nach den Prinzipien Testable, Readable, Extensible und Maintainable (TREM) mit uv, pydantic-settings, der Standardbibliothek logging und pytest.

• Automatisiertes CI/CD-Publishing: Eine GitHub-Actions-Pipeline, die Tests validiert und bei Versions-Tags (v*.*.*) unveränderliche Semver-Releases zu Docker Hub pusht.

Schnellstart

Voraussetzungen

• Python 3.11+

• uv

• Docker & Docker Compose

Lokale Installation

# Sync dependencies
uv sync

# Run tests
uv run pytest -v

# Validate skills
uv run skillmcp validate ./skills

# List discovered skills
uv run skillmcp list --skills-path ./skills

Server lokal ausführen

# Start MCP server directly (Streamable HTTP on port 8000)
uv run skillmcp serve --host 0.0.0.0 --port 8000

Docker-Topologien

Lokale Entwicklung (Live Reload & Ingress)

docker compose -f docker-compose.local.yml up -d --build

• Nginx-Ingress: http://localhost:8080 (/healthz-Healthcheck)

• Backend-App: http://localhost:8000 (/healthz-Healthcheck)

Produktionsbereitstellung

docker compose up -d

Test-Schnittstellen

• Schnittstelle 1: Domain-Service: tests/test_domain_service.py (Validiert Scanner, Parser, Traversal-Sicherheit und Query-Engine)

• Schnittstelle 2: MCP-Protokoll & Tools: tests/test_mcp_server.py & tests/test_mcp_http.py (Validiert FastMCP-Tools, -Ressourcen und ASGI-Transportrouten)

• Schnittstelle 3: CLI & Integration: tests/test_cli.py (Validiert CLI-Validator-, List- und Serve-Befehle)