# Jekyll MCP Server

A [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server that indexes and searches Jekyll blog content, enabling AI assistants like Claude to interact with your blog posts.

## Features

- Index Jekyll blog posts and drafts with front matter parsing
- Search posts by keyword, category, or tags
- Retrieve full post content by slug
- Compare draft content against published posts to detect duplicates
- List all categories and tags with post counts
- Support for both Markdown (.md) and AsciiDoc (.adoc) formats
- Fast keyword-based search

## Installation

### Using uv (recommended)

```bash
uv pip install jekyll-mcp-server
```

### Using pip

```bash
pip install jekyll-mcp-server
```

### From source

```bash
git clone https://github.com/jottinger/jekyll-mcp-server.git
cd jekyll-mcp-server
uv pip install -e .
```

## Configuration

The server needs to know where your Jekyll blog content is located. There are two ways to configure this:

### Option 1: Environment Variables

Set these environment variables before running the server:

```bash
export JEKYLL_POSTS_DIR="/path/to/your/blog/_posts"
export JEKYLL_DRAFTS_DIR="/path/to/your/blog/_drafts"  # Optional
```

### Option 2: Run from Jekyll Project Directory

If you run the server from your Jekyll project root (where `_posts` and `_drafts` directories exist), it will automatically detect them.

## Usage

### With Claude Code

Add to your Claude Code MCP configuration:

```json
{
  "mcpServers": {
    "jekyll-blog": {
      "command": "jekyll-mcp-server",
      "env": {
        "JEKYLL_POSTS_DIR": "/path/to/your/blog/_posts",
        "JEKYLL_DRAFTS_DIR": "/path/to/your/blog/_drafts"
      }
    }
  }
}
```

Then restart Claude Code. The server will start automatically when needed.

### Manual Launch

Create a launch script (see `examples/launch-server.sh`):

```bash
#!/bin/bash
export JEKYLL_POSTS_DIR="/path/to/your/blog/_posts"
export JEKYLL_DRAFTS_DIR="/path/to/your/blog/_drafts"
jekyll-mcp-server
```

Make it executable and run:

```bash
chmod +x launch-server.sh
./launch-server.sh
```

## Available MCP Tools

Once connected, the server provides these tools to AI assistants:

### search_posts

Search for blog posts by keyword, category, or tags.

**Parameters:**
- `query` (string, optional): Search term to find in title, content, or slug
- `category` (string, optional): Filter by category
- `tags` (string, optional): Comma-separated list of tags
- `limit` (number, optional): Maximum results (default: 10)

**Example:**
```
Search for posts about "AI writing" in the "blog" category
```

### get_post

Retrieve full content of a specific post by slug.

**Parameters:**
- `slug` (string, required): The post slug

**Example:**
```
Get the post with slug "working-with-the-machine"
```

### list_categories

List all blog categories with post counts.

**Example:**
```
Show me all categories
```

### list_tags

List all blog tags with post counts.

**Example:**
```
What tags do I use?
```

### compare_draft

Compare draft content against published posts to find similar content (helps avoid duplicate posts).

**Parameters:**
- `draft_content` (string, required): The draft text to compare
- `limit` (number, optional): Maximum similar posts to return (default: 5)

**Example:**
```
Compare this draft against my published posts:
[paste draft content]
```

## Example Workflow

Here's how you might use this with Claude Code:

1. **Before writing a new post:**
   ```
   Search my posts for "AI writing process"
   ```

2. **Check if you've covered a topic:**
   ```
   Have I written about MCP servers before?
   ```

3. **Prevent duplicate content:**
   ```
   Compare this draft against my published posts:
   [paste draft]
   ```

4. **Retrieve existing content:**
   ```
   Get the full content of my post "working-with-the-machine"
   ```

5. **Analyze your blog:**
   ```
   What categories do I write about most?
   ```

## Reindexing Content

The server indexes content on startup. After publishing new posts or making significant changes:

1. Stop the server (if running standalone)
2. Restart it to refresh the index

With Claude Code, the server restarts automatically when needed.

## Development

### Setup

```bash
git clone https://github.com/jottinger/jekyll-mcp-server.git
cd jekyll-mcp-server
uv venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
uv pip install -e ".[dev]"
```

### Running Tests

```bash
pytest
```

### Project Structure

```
jekyll-mcp-server/
├── jekyll_mcp/
│   ├── __init__.py
│   ├── server.py       # MCP server implementation
│   ├── indexer.py      # Post indexing logic
│   ├── parser.py       # Front matter parsing
│   └── tools.py        # MCP tool implementations
├── examples/
│   ├── claude-code-config.json
│   └── launch-server.sh
├── tests/
├── LICENSE
├── README.md
└── pyproject.toml
```

## Requirements

- Python 3.10 or higher
- Jekyll blog with standard `_posts` directory structure
- Posts with YAML front matter

## License

MIT License - see [LICENSE](LICENSE) file for details.

## Contributing

Contributions welcome! Please feel free to submit a Pull Request.

## Acknowledgments

Built using the [Model Context Protocol](https://modelcontextprotocol.io/) by Anthropic.

Created with assistance from Claude Code.