# Librarian MCP Server

A local MCP server that gives AI agents structured access to a personal Obsidian knowledge vault. Notes remain portable Markdown, while Librarian enforces organization, provenance, deduplication, and git-backed history.

## What it does

- Stores OKF-compatible Markdown notes in a flat Obsidian vault.
- Organizes concepts through Maps of Content (MOCs).
- Combines local semantic search with lexical matching and exact filters.
- Rejects duplicate concepts, invalid notes, and edits to immutable source notes.
- Commits every mutation to the vault's git history.
- Reports broken links, orphaned notes, malformed frontmatter, and WikiLinks.

All search and storage are local. The first semantic search downloads the `BAAI/bge-small-en-v1.5` model (about 130 MB); later searches run offline.

## Install

Requires Python 3.11+.

```bash
pip install .
```

Or with [uv](https://docs.astral.sh/uv/):

```bash
uv sync
```

## Run

```bash
librarian --vault /path/to/vault
```

You can also set the vault path with `LIBRARIAN_VAULT`:

```bash
LIBRARIAN_VAULT=/path/to/vault librarian
```

On first run, Librarian creates the vault, initializes git, and adds a root MOC. Configure your MCP client to launch the server over stdio, for example:

```json
{
  "mcpServers": {
    "librarian": {
      "command": "librarian",
      "args": ["--vault", "/path/to/vault"]
    }
  }
}
```

## Tools

| Tool | Purpose |
|---|---|
| `get_vault_seed` | Return a bounded overview of MOCs and recent notes |
| `query_knowledge` | Search notes semantically and lexically |
| `read_concept` | Read a complete note |
| `create_concept` | Create a validated note and wire it into an MOC |
| `enrich_concept` | Append content to a named section |
| `lint_graph` | Report graph and formatting problems |

See [`spec.md`](spec.md) for the full contracts and design decisions.

## Development

```bash
uv sync --extra dev
uv run --extra dev pytest
```