# markdown-frontmatter-mcp

A [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server that queries Markdown files by front matter metadata. Designed for Obsidian vaults and other Markdown-based knowledge bases.

## The Problem

You have a Markdown knowledge base (Obsidian, etc.) with front matter like:

```yaml
---
created: 2025-12-09
updated: 2025-12-11
tags: [ai-systems, strategy]
---
```

You want to ask an AI: *"What have I been thinking about [X] lately?"*

Existing tools can search by keywords or do semantic search, but none let you query by **front matter metadata** — filtering by tags AND recency.

## The Solution

This MCP server exposes one tool: `query_recent_notes`

```
query_recent_notes(
  tags: ["ai-systems"],     # Filter by these tags (matches ANY)
  days: 7,                  # How far back to look
  folders: ["thoughts"],    # Which folders to search
  limit: 10                 # Max results
)
```

Returns:
- File path
- Title (from H1 or filename)
- Tags
- Created/updated dates
- Excerpt (first ~200 chars)

## Installation

### From PyPI (coming soon)

```bash
pip install markdown-frontmatter-mcp
```

### From Source

```bash
git clone https://github.com/caffeinatedwes/markdown-frontmatter-mcp
cd markdown-frontmatter-mcp
pip install -e .
```

## Configuration

### Environment Variable

Set `KB_PATH` to point to your knowledge base:

```bash
export KB_PATH=/path/to/your/obsidian/vault
```

### MCP Client Configuration

#### TypingMind

Add to your MCP config:

```json
{
  "mcpServers": {
    "markdown-kb": {
      "command": "python3",
      "args": ["/path/to/markdown-frontmatter-mcp/src/server.py"],
      "env": {
        "KB_PATH": "/path/to/your/obsidian/vault"
      }
    }
  }
}
```

#### Claude Desktop

Add to `~/.config/Claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "markdown-kb": {
      "command": "python3",
      "args": ["/path/to/markdown-frontmatter-mcp/src/server.py"],
      "env": {
        "KB_PATH": "/path/to/your/obsidian/vault"
      }
    }
  }
}
```

## Usage Examples

Once configured, you can ask the AI:

> "Get my recent thinking on AI systems"

The AI will call:
```
query_recent_notes(tags=["ai-systems"], days=7)
```

> "What personal growth stuff have I been working on?"

```
query_recent_notes(tags=["personal-growth", "therapy"], days=14)
```

> "Catch me up on what's been on my mind"

```
query_recent_notes(days=3, limit=5)
```

## Front Matter Requirements

For files to be queryable, they need YAML front matter with:

- `created` or `date`: When the note was created (YYYY-MM-DD)
- `updated` (optional): When last meaningfully edited (YYYY-MM-DD)
- `tags` (optional): List of tags for filtering

Example:
```yaml
---
created: 2025-12-09
updated: 2025-12-11
tags:
  - ai-systems
  - knowledge-management
---

# My Note Title

Content here...
```

## How It Works

1. Walks the specified folders in your knowledge base
2. Parses YAML front matter from each `.md` file
3. Filters by:
   - Date: `created` or `updated` within the `days` window
   - Tags: matches ANY of the specified tags
4. Returns results sorted by most recently touched

## Skipped Directories

The server automatically skips:
- `.obsidian`
- `.git`
- `.smart-env`
- `.versiondb`
- `node_modules`
- Any directory starting with `.`

## Development

### Testing Locally

```bash
# Set your KB path
export KB_PATH=~/your-obsidian-vault

# Run the server directly (for testing)
python3 src/server.py
```

Then send JSON-RPC messages via stdin:

```json
{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}
{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}
{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"query_recent_notes","arguments":{"tags":["ai-systems"],"days":7}}}
```

## License

MIT