jekyll-component-mcp

Servidor Model Context Protocol (MCP) que permite que agentes de IA entendam, inspecionem, criem, validem, construam e documentem frameworks de componentes Jekyll.

GitHub

Documentação

jekyll-component-mcp

Servidor MCP de desenvolvimento nativo para IA, voltado a projetos Jekyll e componentes reutilizáveis em Liquid/SCSS/JavaScript.

Servidor MCP (Model Context Protocol) pronto para produção que permite a agentes de IA entender, inspecionar, criar, validar, compilar e documentar frameworks de componentes Jekyll.

Recursos

Ferramentas cientes de Jekyll — não é um wrapper genérico de sistema de arquivos
Ciclo de vida de componentes — listar, obter, criar, validar, excluir
SCSS + design tokens — detecção de arquitetura e atualizações seguras
Seguro por padrão — sandbox na raiz do projeto, comandos na lista de permissões, modos de escrita
Suporte a dry-run — pré-visualize mutações antes de gravar
Recursos e prompts — contexto estruturado e fluxos de revisão para agentes

Requisitos

Node.js 20+
Um projeto Jekyll (Gemfile / Bundler opcional)

Instalação

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

Habilidade de IA

O pacote inclui uma habilidade com instruções para agentes de IA instalarem, configurarem e usarem este servidor MCP. Após a publicação do pacote, compartilhe esta URL com um agente de IA que possa acessar links da web:

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

Para instruções repetíveis, substitua latest por uma versão publicada, por exemplo @1.0.0. Você pode pedir ao agente: "Leia e siga esta habilidade para configurar e usar jekyll-component-mcp: https://unpkg.com/jekyll-component-mcp@latest/skills/SKILL.md".

Início 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

MCP Inspector

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

Modos de escrita

Modo	Criar / Atualizar	Excluir / Destrutivo
`read-only`	❌	❌
`safe-write` (padrão)	✅	❌
`full-write`	✅	✅ (requer `confirm: true`)

Opções 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 diretórios comuns de includes, Sass, layouts e dados do Jekyll e, em seguida, grava um .jekyll-mcp.json pronto para uso. Ele preserva uma configuração existente, a menos que --force seja fornecido. Em um terminal interativo, o preset de tema detectado pode ser confirmado ou alterado.

Arquivo de configuração

.jekyll-mcp.json opcional na raiz do projeto:

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

Ferramentas (visão geral)

Ferramenta	Finalidade
`jekyll_project_info`	Resumo do projeto em alto nível
`jekyll_project_scan`	Mapa completo da arquitetura
`jekyll_config_get`	Configuração sanitizada
`jekyll_component_list`	Listar componentes
`jekyll_component_get`	Detalhes do componente + fontes
`jekyll_component_create`	Criar componente + SCSS + documentação
`jekyll_component_validate`	Validação estruturada
`list_components` / `inspect_component`	Aliases para descoberta e inspeção de componentes
`create_component` / `validate_component`	Aliases para geração e validação
`jekyll_component_delete`	Exclusão destrutiva (gravação completa + confirmação)
`jekyll_build`	Executar build do Jekyll
`jekyll_doctor`	Executar jekyll doctor

Recursos

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

Prompts

jekyll_component_review
jekyll_accessibility_review
jekyll_performance_review
jekyll_production_review

Segurança

Sandbox de sistema de arquivos: cada caminho é resolvido sob a raiz do projeto; travessias e escapes por symlink são rejeitados.
Lista de permissões de comandos: apenas jekyll build|clean|doctor (e variantes bundle exec). Sem shell arbitrário.
Política de escrita: configurável; operações destrutivas exigem full-write + confirm: true.
Segredos: a leitura de configuração oculta chaves secretas comuns; a saída do processo é limpa.
stdio: stdout é reservado para MCP JSON-RPC; todos os logs vão para stderr.

Exemplos de configuração de cliente

Claude Desktop / Claude Code

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

Cursor / VS Code

Adicione uma entrada de servidor MCP apontando para node /path/to/jekyll-component-mcp/dist/index.js com argumentos --root conforme necessário.

Desenvolvimento

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

Licença

MIT