brain-mcp: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

What this is

An MCP server (streamable-HTTP transport) that exposes a flat, retrieval-first markdown Obsidian vault as seven tools: five read tools plus two constrained write tools (capture, which only ever creates new notes in 00-inbox/, and capture_update, which edits notes still in 00-inbox/). One running container serves exactly one vault; a second vault is a second, independent container built from the same image. Full behavioral spec is in brain-mcp-spec.md.

Commands

# Install (uv is the primary path; a plain venv works too)
uv sync --dev
# or: python3 -m venv .venv && .venv/bin/pip install -e ".[dev]"

# Run the full test suite
uv run pytest
# or: .venv/bin/python -m pytest

# Run a single test file or test
uv run pytest tests/test_vault.py
uv run pytest tests/test_vault.py::test_find_by_bare_filename

# Run the server locally (requires BRAIN_ROOT, BRAIN_NAME, BRAIN_TOKEN)
export BRAIN_ROOT=/path/to/vault BRAIN_NAME=personal BRAIN_TOKEN=dev-token
uv run brain-mcp

# Build and run in Docker
cp .env.example .env   # fill in BRAIN_NAME, BRAIN_VAULT_PATH, BRAIN_TOKEN
docker compose up -d --build
curl http://localhost:3100/health

Tests run entirely against a synthetic fixture vault built fresh per test in tests/conftest.py — never against real vault data. There's no linter configured in this repo.

Module responsibilities

• config.py — env var parsing/validation, fails fast with a clear error.
• vault.py — the index: frontmatter parsing, exclusions, path safety, filename-based identifier resolution, wikilink resolution, CONVENTIONS.md enum parsing, watchfiles-driven live reindexing.
• search.py — ripgrep subprocess wrapper for content search. No content index is built; ripgrep runs against the filesystem on every call.
• capture.py — the write paths (note creation and inbox-note updates, both confined to 00-inbox/), plus frontmatter validation.
• server.py — the seven @mcp.tool() definitions, the bearer-auth ASGI middleware, and process startup/shutdown wiring.