jekyll-component-mcp

Model Context Protocol (MCP)-Server, der es KI-Agenten ermöglicht, Jekyll-Komponenten-Frameworks zu verstehen, zu inspizieren, zu erstellen, zu validieren, zu bauen und zu dokumentieren.

GitHub

Dokumentation

jekyll-component-mcp

AI-native development MCP server for Jekyll projects and reusable Liquid/SCSS/JavaScript components.

Production-ready Model Context Protocol (MCP) server that lets AI agents understand, inspect, create, validate, build, and document Jekyll component frameworks.

Features

Jekyll-aware tools — not a generic filesystem wrapper
Component lifecycle — list, get, create, validate, delete
SCSS + design tokens — architecture detection and safe updates
Secure by default — project-root sandbox, allowlisted commands, write modes
Dry-run support — preview mutations before writing
Resources & prompts — structured context and review workflows for agents

Requirements

Node.js 20+
A Jekyll project (optional Gemfile / Bundler)

Install

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

AI Skill

The package includes a skill with instructions for AI agents to install, configure, and use this MCP server. After the package is published, share this URL with an AI agent that can access web links:

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

For repeatable instructions, replace latest with a published version, for example @1.0.0. You can ask the agent: "Read and follow this skill to set up and use jekyll-component-mcp: https://unpkg.com/jekyll-component-mcp@latest/skills/SKILL.md".

Quick start

# 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

Write modes

Mode	Create / Update	Delete / Destructive
`read-only`	❌	❌
`safe-write` (default)	✅	❌
`full-write`	✅	✅ (requires `confirm: true`)

CLI options

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 detects common Jekyll include, Sass, layout, and data directories, then writes a ready-to-use .jekyll-mcp.json. It preserves an existing configuration unless --force is supplied. In an interactive terminal, the detected theme preset can be confirmed or changed.

Configuration file

Optional .jekyll-mcp.json in the project root:

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

Tools (overview)

Tool	Purpose
`jekyll_project_info`	High-level project summary
`jekyll_project_scan`	Full architecture map
`jekyll_config_get`	Sanitized config
`jekyll_component_list`	List components
`jekyll_component_get`	Component details + sources
`jekyll_component_create`	Create component + SCSS + docs
`jekyll_component_validate`	Structured validation
`list_components` / `inspect_component`	Aliases for component discovery and inspection
`create_component` / `validate_component`	Aliases for generation and validation
`jekyll_component_delete`	Destructive delete (full-write + confirm)
`jekyll_build`	Run Jekyll build
`jekyll_doctor`	Run jekyll doctor

Resources

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

Prompts

jekyll_component_review
jekyll_accessibility_review
jekyll_performance_review
jekyll_production_review

Security

Filesystem sandbox: every path is resolved under the project root; traversal and symlink escapes are rejected.
Command allowlist: only jekyll build|clean|doctor (and bundle exec variants). No arbitrary shell.
Write policy: configurable; destructive ops require full-write + confirm: true.
Secrets: config reads redact common secret keys; process output is scrubbed.
stdio: stdout is reserved for MCP JSON-RPC; all logs go to stderr.

Client configuration examples

Claude Desktop / Claude Code

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

Cursor / VS Code

Add an MCP server entry pointing at node /path/to/jekyll-component-mcp/dist/index.js with --root args as needed.

Development

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

License

MIT