skill2mcp

skill2mcp ist eine TypeScript-CLI/Bibliothek, die SKILL.md-Dokumente in MCP-fähige Tool-Definitionen konvertiert und ein minimales, bereitstellbares MCP-Server-Paket aus einer einzelnen Datei oder einem gesamten Skill-Verzeichnis generieren kann.

Der generierte Server verwendet das offizielle MCP TypeScript SDK (@modelcontextprotocol/sdk) und unterstützt stdio-, http- oder both-Transporte.

Warum dieses Projekt

SKILL-Dokumente sind normalerweise semistrukturierte Markdown-Dateien (Frontmatter + Fließtext + Tabellen). MCP-Tools erfordern strikte Verträge (name, description, inputSchema).

skill2mcp schließt diese Lücke mit einer mehrschichtigen Pipeline:

1. Parsen von Markdown in eine stabile Intermediate Representation (IR)

2. Transformation der IR in MCP-Tool-Definitionen

3. Generierung eines bereitstellbaren MCP-Server-Pakets mit Handler-Stubs

Related MCP server: Skillz

Aktueller Status

MVP implementiert und funktionsfähig:

• Deterministischer Parser (strict, tolerant)

• Kaskadierender semantischer Modus (semantic) für fehlende Metadaten-Fallback-Lösungen

• Tool-Transformation (SchemaBuilder, ToolMapper, ToolValidator)

• inspect-Ausgabe mit Tool-JSON im MCP-Stil

• build-Ausgabe mit bereitstellbarem MCP-Server-Paket

• Generierter Server unterstützt stdio + http

• build --watch für iterative Neugenerierung

Installation

Voraussetzungen

• Node.js 20+

• npm 10+

Lokale Installation

npm install

CLI bauen

npm run build

Schnellstart

1. Einen einzelnen SKILL parsen

npm run parse -- ./fixtures/skills/valid-skill.md --mode strict

2. Generierte Tool-Definitionen prüfen

npm run inspect -- ./fixtures/skills --mode tolerant

3. Bereitstellbares MCP-Server-Paket generieren

npm run gen -- ./fixtures/skills --out ./generated/mcp-server --transport both --mode tolerant

4. Generierten Server ausführen

cd ./generated/mcp-server
npm install
npm run build
npm run start:stdio
# or
npm run start:http

HTTP-Endpunkt:

POST /mcp

CLI-Referenz

parse

Konvertiert SKILL-Markdown in IR-JSON.

skill2mcp parse <input> [--mode strict|tolerant|semantic]

Argumente:

• <input>: Pfad zu einer .md-Datei oder einem Verzeichnis

Optionen:

• --mode: Parser-Modus (tolerant ist Standard)

• --format: aktuell json

Ausgabe:

• results[] mit geparstem SkillDocument

• diagnostics[] pro Quelldatei

inspect

Konvertiert geparste IR in MCP-ähnliche Tool-Definitionen.

skill2mcp inspect <input> [--mode strict|tolerant|semantic]

Ausgabe:

• tools[]: generierte Tool-Definitionen (name, description, inputSchema)

• results[]: Tool + Diagnosen pro Quelle

build

Generiert ein bereitstellbares MCP-Server-Paket aus einem oder mehreren Skills.

skill2mcp build <input> --out <dir> [--transport stdio|http|both] [--mode strict|tolerant|semantic] [--watch]

Argumente:

• <input>: Pfad zu einer .md-Datei oder einem Verzeichnis

Erforderliche Optionen:

• --out: Ausgabeverzeichnis für das generierte Paket

Optionale Optionen:

• --transport: Standard-Transport für den generierten Server (both ist Standard)

• --mode: Parsing-Modus (tolerant ist Standard)

• --watch: Paket bei Quellenänderungen neu generieren

Ausgabe:

• generierte Paketdateien (package.json, tools.json, src/server.ts, Handler)

• Diagnosezusammenfassung in JSON

Parse-Modi

strict

• Schlägt bei fehlenden erforderlichen Metadaten/Schemas fehl

• Am besten für CI-Qualitäts-Gates geeignet

tolerant

• Fährt mit Warnungen bei fehlenden Feldern fort

• Am besten für die Stapelverarbeitung von Skills mit gemischter Qualität geeignet

semantic

• Startet mit tolerantem Parsing

• Versucht semantische Extraktion über OpenRouter (sofern konfiguriert)

• Wendet deterministische Fallback-Inferenz für nicht aufgelöste Felder an

• Behält Diagnose-Trace bei (SEMANTIC_*-Codes)

OpenRouter-Konfiguration für semantic

Umgebungsvariablen:

• OPENROUTER_API_KEY: aktiviert die Remote-Semantik-Extraktion

• OPENROUTER_MODEL (optional): Standard ist anthropic/claude-3.5-sonnet

• SKILL2MCP_CACHE_DIR (optional): Cache-Verzeichnis überschreiben

• OPENROUTER_HTTP_REFERER (optional): wird als OpenRouter-Header weitergeleitet

• OPENROUTER_X_TITLE (optional): wird als OpenRouter-Header weitergeleitet

Cache-Verhalten:

• Semantische Antworten werden nach Inhalts-Hash in .skill2mcp-cache/semantic-openrouter-cache.json zwischengespeichert

• Wenn ein Cache vorhanden ist, verwendet der semantische Modus den Cache wieder und vermeidet zusätzliche Remote-Aufrufe

Kanonisches SKILL.md-Format (empfohlen)

---
name: docx-generator
version: 1.0.0
description: Generate Word docs from structured markdown
tags: [documents, office]
---

## Parameters
| Name | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| content | string | yes |  | Markdown content |
| title | string | yes |  | Document title |

## Examples
**Input:** `{ content: "# Hello", title: "Report" }`
**Output:** report.docx generated at /outputs/

## Triggers
- "generate document"
- "create report"

Struktur des generierten Pakets

generated/mcp-server/
  package.json
  tsconfig.json
  README.md
  tools.json
  src/
    server.ts
    generated-tools.ts
    handlers/
      index.ts
      <tool_name>.ts

Entwicklung

Skripte

npm run build       # compile TypeScript
npm run test        # run test suite
npm run parse       # parse command entry
npm run inspect     # inspect command entry
npm run gen         # build command entry

Test-Suite

Die aktuelle automatisierte Abdeckung umfasst:

• Parser-Verhalten (strict, tolerant, semantic)

• Schema-Builder und Tool-Mapping

• Vertragsprüfung der inspect-Befehlsausgabe

• End-to-End-Generierung von Build-Artefakten

Engineering-Konventionen

• Befolgen Sie die Regeln für die Zusammenarbeit im Repository in AGENTS.md

• Produkt-/Geschäftsanweisungen werden durch ROADMAP.md geregelt

• Commit-Nachrichten müssen das Präfix [AI] verwenden, wenn sie KI-generiert sind

Release-Artefakte

Dieses Repo enthält:

• Dual-Lizenz-Distribution: MIT OR Apache-2.0

• CHANGELOG.md

• CONTRIBUTING.md

• RELEASE_CHECKLIST.md

Zusammenarbeitsmodell

• Governance- und Entscheidungsregeln: GOVERNANCE.md

• Verhaltenskodex: CODE_OF_CONDUCT.md

• Sicherheitsmeldungen: SECURITY.md

• Support-Kanäle: SUPPORT.md

Bekannte Einschränkungen

• Das Parameter-Parsing geht derzeit von einem Markdown-Tabellenformat unter ## Parameters aus

• Der semantische Modus priorisiert fehlende Metadaten und kann fehlende Parameter anreichern, wenn eine Extraktion verfügbar ist

• Der Watch-Modus verfolgt den aktuellen Baum; wenn später tief verschachtelte Ordner hinzugefügt werden, starten Sie den Watch-Modus neu, um eine vollständige Abdeckung zu gewährleisten

Roadmap-Ausrichtung

Die aktive Implementierung folgt der phasenweisen Bereitstellung in ROADMAP.md.

Die GenAI-Integrationsrichtlinie (sofern aktiviert) priorisiert OpenRouter als Standard-Provider-Strategie, wie in den Roadmap-Richtlinien definiert.

Lizenz

Lizenziert unter einer der folgenden Lizenzen:

• MIT-Lizenz (LICENSE-MIT)

• Apache-Lizenz 2.0 (LICENSE-APACHE)

nach Ihrer Wahl.