skills-mcp-server

Un servidor MCP (Model Context Protocol) de alto rendimiento que expone un catálogo de más de 1300 habilidades de IA mediante búsqueda clasificada por BM25, metadatos estructurados y respuestas eficientes en cuanto a contexto.

Creado para resolver un problema: miles de habilidades destruyen tu ventana de contexto. Este servidor las indexa, las clasifica y sirve solo lo que necesitas.

┌────────────────────────────────────────────────────────────┐
│  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                 │
└────────────────────────────────────────────────────────────┘

Características

Búsqueda clasificada por BM25 — No es coincidencia de palabras clave. Puntuación de relevancia real con ponderación de campos (nombre 3x, descripción 2x, etiquetas 2x, cuerpo 1x)
Eficiente en contexto — Lee metadatos de habilidades (~500 caracteres), resumen (~2K caracteres) o contenido completo (limitado a 25K caracteres). Tú controlas cuánto contexto gastar
Metadatos estructurados — Frontmatter YAML analizado en campos tipados: nombre, descripción, etiquetas, categoría, riesgo, autor, herramientas
Paginación en todas partes — Cada herramienta de lista/búsqueda admite offset y limit
3 modos de transporte — stdio para IDEs locales, HTTP/SSE para acceso remoto, AWS Lambda para serverless
Inicio rápido — Más de 1300 habilidades indexadas en ~1.5 segundos. ~3MB de huella de memoria (frente a 65MB en bruto)
6 herramientas especializadas — Explorar, listar, buscar, leer, inspeccionar, actualizar

Inicio rápido

Requisitos previos

Node.js 18+
El directorio skills/ con archivos SKILL.md (ver Formato de habilidad)

Instalación y compilación

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

Ejecutar localmente (stdio)

node dist/index.js

Ejecutar como servidor HTTP (SSE)

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

Herramientas MCP

`skills_browse_categories`

Lista todas las categorías de habilidades con sus conteos. Usa esto primero.

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

`skills_search`

Búsqueda de texto completo clasificada por BM25 a través de nombres, descripciones, etiquetas y contenido.

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

`skills_list_by_category`

Lista las habilidades dentro de una categoría específica con paginación.

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

`skills_read`

Lee el contenido de la habilidad con control de contexto.

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`

Obtén metadatos estructurados para múltiples habilidades + habilidades relacionadas por superposición de etiquetas.

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

`skills_refresh_index`

Reconstruye el índice en memoria después de añadir/eliminar/modificar habilidades en el disco.

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

Configuración del IDE

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

Remoto (HTTP/SSE) — Cursor, VS Code, cualquier cliente MCP

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

AWS Lambda (después de desplegar)

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

Consulta docs/SETUP.md para obtener guías de configuración paso a paso completas para todos los modos e IDEs.

Modos de despliegue

Modo	Comando	Caso de uso	Streaming SSE
stdio	`node dist/index.js`	IDEs locales (Claude, Cursor, Gemini CLI)	N/A
HTTP	`node dist/http.js`	Servidor de desarrollo, EC2, VPS, Docker	Sí
Lambda	SAM deploy	Serverless, auto-escalado, pago por uso	Sí (streaming de respuesta)

Formato de habilidad

Cada habilidad es un directorio bajo skills/ que contiene al menos un archivo SKILL.md con frontmatter YAML:

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

Estructura de SKILL.md

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

Campos de Frontmatter

Campo	Tipo	Requerido	Descripción
`name`	string	Sí	Identificador de la habilidad
`description`	string	Sí	Descripción de una línea
`tags`	string[]	No	Palabras clave buscables
`risk`	enum	No	`safe`, `critical`, `offensive`, `unknown`, `none`
`source`	string	No	Origen (`community`, `official`)
`author`	string	No	Nombre del creador
`tools`	string[]	No	Herramientas de IA compatibles

Arquitectura

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

Motor de búsqueda

La implementación de BM25 indexa cada habilidad como un documento ponderado:

Campo	Peso	Ejemplo
`name`	3x	"react-patterns" repetido 3 veces
`description`	2x	"Modern React patterns..." repetido 2 veces
`tags`	2x	"react frontend hooks" repetido 2 veces
`category`	1x	"development"
`summary`	1x	Primeros 500 caracteres del cuerpo

La puntuación utiliza BM25 con k1=1.5, b=0.75. Los resultados se ordenan por puntuación de relevancia descendente.

Rendimiento: la búsqueda en más de 1300 habilidades se completa en <10ms.

Variables de entorno

Variable	Predeterminado	Descripción
`SKILLS_DIR`	`~/skills-mcp/skills`	Ruta al directorio de habilidades
`PORT`	`3000`	Puerto del servidor HTTP (solo http.ts)

Stack tecnológico

TypeScript — Modo estricto, ESM
MCP SDK v1.29+ — StreamableHTTPServerTransport, WebStandardStreamableHTTPServerTransport
gray-matter — Análisis de frontmatter YAML
Zod — Esquemas de validación de entrada
BM25 — Implementación personalizada (~80 líneas), cero dependencias externas

Licencia

MIT

skills-mcp-server

skills-mcp-server

Características

Inicio rápido

Requisitos previos

Instalación y compilación

Ejecutar localmente (stdio)

Ejecutar como servidor HTTP (SSE)

Herramientas MCP

`skills_browse_categories`

`skills_search`

`skills_list_by_category`

`skills_read`

`skills_inspect`

`skills_refresh_index`

Configuración del IDE

Claude Desktop / Claude Code

Remoto (HTTP/SSE) — Cursor, VS Code, cualquier cliente MCP

AWS Lambda (después de desplegar)

Modos de despliegue

Formato de habilidad

Estructura de SKILL.md

Campos de Frontmatter

Arquitectura

Motor de búsqueda

Variables de entorno

Stack tecnológico

Licencia

Resources

Looking for Admin?

Latest Blog Posts

MCP directory API