skill2mcp

skill2mcp es una CLI/biblioteca de TypeScript que convierte documentos SKILL.md en definiciones de herramientas listas para MCP y puede generar un paquete de servidor MCP desplegable mínimo a partir de un solo archivo o de un directorio completo de habilidades.

El servidor generado utiliza el SDK oficial de MCP para TypeScript (@modelcontextprotocol/sdk) y admite transportes stdio, http o both.

Por qué este proyecto

Los documentos SKILL suelen ser archivos markdown semiestructurados (frontmatter + prosa + tablas). Las herramientas MCP requieren contratos estrictos (name, description, inputSchema).

skill2mcp cierra esa brecha con una canalización en capas:

1. Analizar markdown en una Representación Intermedia (IR) estable

2. Transformar la IR en definiciones de herramientas MCP

3. Generar un paquete de servidor MCP desplegable con stubs de controladores

Related MCP server: Skillz

Estado actual

MVP implementado y funcional:

• Analizador determinista (strict, tolerant)

• Modo semántico en cascada (semantic) para la recuperación de metadatos faltantes

• Transformación de herramientas (SchemaBuilder, ToolMapper, ToolValidator)

• Salida inspect con JSON de herramientas al estilo MCP

• Salida build con paquete de servidor MCP desplegable

• El servidor generado admite stdio + http

• build --watch para regeneración iterativa

Instalación

Requisitos

• Node.js 20+

• npm 10+

Instalación local

npm install

Construir CLI

npm run build

Inicio rápido

1. Analizar un SKILL individual

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

2. Inspeccionar las definiciones de herramientas generadas

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

3. Generar un paquete de servidor MCP desplegable

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

4. Ejecutar el servidor generado

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

Endpoint HTTP:

POST /mcp

Referencia de la CLI

parse

Convierte markdown SKILL a JSON de IR.

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

Argumentos:

• <input>: ruta a un archivo .md o directorio

Opciones:

• --mode: modo del analizador (tolerant por defecto)

• --format: actualmente json

Salida:

• results[] con SkillDocument analizado

• diagnostics[] por archivo fuente

inspect

Convierte la IR analizada en definiciones de herramientas tipo MCP.

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

Salida:

• tools[]: definiciones de herramientas generadas (name, description, inputSchema)

• results[]: herramienta + diagnósticos por fuente

build

Genera un paquete de servidor MCP desplegable a partir de una o varias habilidades.

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

Argumentos:

• <input>: ruta a un archivo .md o directorio

Opciones requeridas:

• --out: directorio de salida para el paquete generado

Opciones opcionales:

• --transport: transporte del servidor generado por defecto (both por defecto)

• --mode: modo de análisis (tolerant por defecto)

• --watch: regenerar paquete ante cambios en la fuente

Salida:

• archivos del paquete generado (package.json, tools.json, src/server.ts, controladores)

• resumen de diagnósticos en JSON

Modos de análisis

strict

• Falla ante brechas en metadatos/esquemas requeridos

• Ideal para puertas de calidad en CI

tolerant

• Continúa con advertencias ante campos faltantes

• Ideal para procesamiento por lotes de habilidades de calidad mixta

semantic

• Comienza desde un análisis tolerante

• Intenta la extracción semántica a través de OpenRouter (cuando está configurado)

• Aplica inferencia de respaldo determinista para campos no resueltos

• Mantiene el rastro de diagnósticos (códigos SEMANTIC_*)

Configuración de OpenRouter para semantic

Variables de entorno:

• OPENROUTER_API_KEY: habilita la extracción semántica remota

• OPENROUTER_MODEL (opcional): por defecto anthropic/claude-3.5-sonnet

• SKILL2MCP_CACHE_DIR (opcional): sobrescribe el directorio de caché

• OPENROUTER_HTTP_REFERER (opcional): reenviado como encabezado de OpenRouter

• OPENROUTER_X_TITLE (opcional): reenviado como encabezado de OpenRouter

Comportamiento de la caché:

• Las respuestas semánticas se almacenan en caché por hash de contenido en .skill2mcp-cache/semantic-openrouter-cache.json

• Si la caché está presente, el modo semántico reutiliza la caché y evita llamadas remotas adicionales

Formato canónico SKILL.md (recomendado)

---
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"

Estructura del paquete generado

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

Desarrollo

Scripts

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

Suite de pruebas

La cobertura automatizada actual incluye:

• comportamiento del analizador (strict, tolerant, semantic)

• constructor de esquemas y mapeo de herramientas

• contrato de salida del comando inspect

• generación de artefactos de construcción de extremo a extremo

Convenciones de ingeniería

• Siga las reglas de colaboración del repositorio en AGENTS.md

• Las directivas de producto/negocio se rigen por ROADMAP.md

• Los mensajes de confirmación (commit) deben usar el prefijo [AI] cuando sean generados por IA

Artefactos de lanzamiento

Este repositorio incluye:

• Distribución con doble licencia: MIT OR Apache-2.0

• CHANGELOG.md

• CONTRIBUTING.md

• RELEASE_CHECKLIST.md

Modelo de colaboración

• Reglas de gobernanza y decisión: GOVERNANCE.md

• Código de conducta: CODE_OF_CONDUCT.md

• Reporte de seguridad: SECURITY.md

• Canales de soporte: SUPPORT.md

Limitaciones conocidas

• El análisis de parámetros actualmente asume el formato de tabla markdown en ## Parameters

• El modo semántico prioriza los metadatos faltantes y puede enriquecer los parámetros faltantes cuando la extracción está disponible

• El modo watch rastrea el árbol actual; si se añaden carpetas profundamente anidadas más tarde, reinicie el watch para una cobertura completa

Alineación con la hoja de ruta

La implementación activa sigue la entrega por fases en ROADMAP.md.

La política de integración de GenAI (cuando está habilitada) prioriza a OpenRouter como estrategia de proveedor predeterminada, según lo definido en las directivas de la hoja de ruta.

Licencia

Licenciado bajo cualquiera de:

• Licencia MIT (LICENSE-MIT)

• Licencia Apache 2.0 (LICENSE-APACHE)

a su elección.