jekyll-component-mcp

Servidor de Model Context Protocol (MCP) que permite a los agentes de IA comprender, inspeccionar, crear, validar, compilar y documentar marcos de componentes de Jekyll.

GitHub

Documentación

jekyll-component-mcp

Servidor MCP de desarrollo nativo para IA, orientado a proyectos Jekyll y componentes reutilizables de Liquid/SCSS/JavaScript.

Servidor MCP (Model Context Protocol) listo para producción que permite a los agentes de IA comprender, inspeccionar, crear, validar, compilar y documentar marcos de componentes Jekyll.

Características

Herramientas conscientes de Jekyll — no es un envoltorio genérico del sistema de archivos
Ciclo de vida de componentes — listar, obtener, crear, validar, eliminar
SCSS + tokens de diseño — detección de arquitectura y actualizaciones seguras
Seguro por defecto — sandbox en la raíz del proyecto, comandos en lista blanca, modos de escritura
Soporte de simulación (dry-run) — previsualiza mutaciones antes de escribir
Recursos y avisos — contexto estructurado y flujos de revisión para agentes

Requisitos

Node.js 20+
Un proyecto Jekyll (opcional Gemfile / Bundler)

Instalación

npm install -g jekyll-component-mcp
# or use locally
npx jekyll-component-mcp --root /path/to/jekyll-project

Habilidad de IA

El paquete incluye una habilidad con instrucciones para que los agentes de IA instalen, configuren y usen este servidor MCP. Después de publicar el paquete, comparte esta URL con un agente de IA que pueda acceder a enlaces web:

https://unpkg.com/jekyll-component-mcp@latest/skills/SKILL.md

Para instrucciones repetibles, reemplaza latest con una versión publicada, por ejemplo @1.0.0. Puedes pedirle al agente: "Lee y sigue esta habilidad para configurar y usar jekyll-component-mcp: https://unpkg.com/jekyll-component-mcp@latest/skills/SKILL.md".

Inicio rápido

# Generate .jekyll-mcp.json (detects standard Jekyll, Chirpy, or Minimal Mistakes)
jekyll-component-mcp init

# From your Jekyll project root
jekyll-component-mcp --root .

# Or via environment
JEKYLL_PROJECT_ROOT=/path/to/project jekyll-component-mcp

Inspector MCP

npm run build
npx @modelcontextprotocol/inspector node dist/index.js --root /path/to/jekyll-project

Modos de escritura

Modo	Crear / Actualizar	Eliminar / Destructivo
`read-only`	❌	❌
`safe-write` (predeterminado)	✅	❌
`full-write`	✅	✅ (requiere `confirm: true`)

Opciones de CLI

jekyll-component-mcp init [--root <path>] [--preset auto|standard|chirpy|minimal-mistakes] [--force] [--yes]

--root <path>           Project root
--readonly              read-only mode
--safe-write            safe-write mode (default)
--full-write            full-write mode
--timeout <ms>          Build timeout (default 120000)
--max-file-size <bytes> Max file size (default 2MiB)
--debug                 Debug logging to stderr

init detecta directorios comunes de includes, Sass, layouts y datos de Jekyll, y luego escribe un .jekyll-mcp.json listo para usar. Conserva una configuración existente a menos que se proporcione --force. En una terminal interactiva, el ajuste preestablecido de tema detectado puede confirmarse o cambiarse.

Archivo de configuración

.jekyll-mcp.json opcional en la raíz del proyecto:

{
  "root": ".",
  "writeMode": "safe-write",
  "build": {
    "command": "bundle exec jekyll build",
    "timeout": 120000
  },
  "paths": {
    "components": "_includes/components",
    "scss": "assets/scss",
    "docs": "docs",
    "layouts": "_layouts"
  }
}

Herramientas (resumen)

Herramienta	Propósito
`jekyll_project_info`	Resumen del proyecto de alto nivel
`jekyll_project_scan`	Mapa completo de arquitectura
`jekyll_config_get`	Configuración saneada
`jekyll_component_list`	Listar componentes
`jekyll_component_get`	Detalles del componente + fuentes
`jekyll_component_create`	Crear componente + SCSS + documentación
`jekyll_component_validate`	Validación estructurada
`list_components` / `inspect_component`	Alias para descubrimiento e inspección de componentes
`create_component` / `validate_component`	Alias para generación y validación
`jekyll_component_delete`	Eliminación destructiva (escritura completa + confirmación)
`jekyll_build`	Ejecutar compilación de Jekyll
`jekyll_doctor`	Ejecutar jekyll doctor

Recursos

jekyll://project
jekyll://components
jekyll://config

Avisos

jekyll_component_review
jekyll_accessibility_review
jekyll_performance_review
jekyll_production_review

Seguridad

Sandbox del sistema de archivos: cada ruta se resuelve bajo la raíz del proyecto; se rechazan escapes de traversal y symlinks.
Lista blanca de comandos: solo jekyll build|clean|doctor (y variantes de bundle exec). Sin shell arbitrario.
Política de escritura: configurable; las operaciones destructivas requieren full-write + confirm: true.
Secretos: las lecturas de configuración redactan claves secretas comunes; la salida del proceso se depura.
stdio: stdout está reservado para MCP JSON-RPC; todos los registros van a stderr.

Ejemplos de configuración de cliente

Claude Desktop / Claude Code

{
  "mcpServers": {
    "jekyll-component": {
      "command": "npx",
      "args": ["-y", "jekyll-component-mcp", "--root", "/path/to/jekyll-project"]
    }
  }
}

Cursor / VS Code

Agrega una entrada de servidor MCP que apunte a node /path/to/jekyll-component-mcp/dist/index.js con los argumentos de --root según sea necesario.

Desarrollo

npm install
npm run typecheck
npm run build
npm test
npm run dev -- --root ./examples/jekyll-component-framework

Licencia

MIT