# knowledge-mcp

A personal MCP server that lets Claude (Claude Code, Claude Desktop, etc.)
export knowledge and experience into a personal knowledge corpus — a folder
of markdown files that acts as your knowledge base.

Entries are markdown files with YAML frontmatter (created/updated timestamps,
tags, source), organized into category folders. Every write regenerates an
`index.md` at the corpus root listing all entries by category.

## Tools

| Tool | Purpose |
|------|---------|
| `save_knowledge` | Write an entry to `<category>/<slug>.md`. Modes: `create` (default, fails on collision), `overwrite`, `append` (adds a dated section). |
| `list_knowledge` | List all entries grouped by category. |
| `search_knowledge` | Case-insensitive text search with line snippets — use before saving to avoid duplicates. |
| `read_knowledge` | Read one entry by relative path, e.g. `projects/my-project.md`. |
| `reindex_knowledge` | Regenerate `index.md` manually. |

Writes are confined to the knowledge base root — path traversal outside it is
rejected. Only markdown files directly inside category folders (and the root)
are indexed.

## Setup

Requires [uv](https://docs.astral.sh/uv/). Install dependencies once:

```bash
cd /path/to/knowledge-mcp
uv sync
```

### Claude Code

```bash
claude mcp add --scope user knowledge \
  --env KNOWLEDGE_MCP_ROOT=/path/to/your/Knowledge -- \
  uv run --directory /path/to/knowledge-mcp knowledge-mcp
```

(`--scope user` makes it available in every project; drop it for
project-only.)

### Claude Desktop

Add to `~/Library/Application Support/Claude/claude_desktop_config.json`
(macOS) or the equivalent on your platform:

```json
{
  "mcpServers": {
    "knowledge": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/path/to/knowledge-mcp",
        "knowledge-mcp"
      ],
      "env": {
        "KNOWLEDGE_MCP_ROOT": "/path/to/your/Knowledge"
      }
    }
  }
}
```

Then restart Claude Desktop.

## Configuration

| Env var | Default | Purpose |
|---------|---------|---------|
| `KNOWLEDGE_MCP_ROOT` | `~/Documents/Personal/Notes/Knowledge` | Knowledge base root directory. Must already exist. |
| `KNOWLEDGE_MCP_TITLE` | `Knowledge Base` | Heading used for the generated `index.md`. |

## Manual run / smoke test

```bash
uv run knowledge-mcp   # starts the stdio server (Ctrl-C to stop)
```