obsidian-rag-mcp: Instructions file for Claude Code

CLAUDE.md — Project Context for AI Assistants

Project Overview

obsidian-rag-mcp is an MCP server that provides semantic search over Obsidian vaults. It indexes markdown files with vector embeddings (OpenAI/Azure OpenAI) stored in ChromaDB, then exposes search via the Model Context Protocol.

Quick Commands

# Install
uv sync

# Run all tests
uv run pytest

# Run specific test file
uv run pytest tests/test_engine.py -v

# Format
uv run black obsidian_rag_mcp/ tests/

# Lint
uv run ruff check obsidian_rag_mcp/ tests/

# Type check
uv run mypy obsidian_rag_mcp/

# Security scan
uv run bandit -r obsidian_rag_mcp/ -ll -x tests/

# Run all quality checks (CI simulation)
uv run black --check obsidian_rag_mcp/ tests/ && \
uv run ruff check obsidian_rag_mcp/ tests/ && \
uv run mypy obsidian_rag_mcp/ && \
uv run pytest --cov=obsidian_rag_mcp --cov-fail-under=65

# Index sample vault
uv run obsidian-rag index --vault ./vault

# Search
uv run obsidian-rag search "query" --vault ./vault

# Start MCP server
uv run obsidian-rag serve --vault ./vault

Architecture

obsidian_rag_mcp/
├── rag/                 # Core RAG pipeline
│   ├── indexer.py       # Vault scanning, chunking, embedding
│   ├── chunker.py       # Markdown-aware chunking (headers, code blocks, frontmatter)
│   ├── embedder.py      # OpenAI / Azure OpenAI embeddings
│   └── engine.py        # Semantic search engine (query interface)
├── reasoning/           # Conclusion extraction layer
│   ├── extractor.py     # LLM-based conclusion extraction
│   ├── conclusion_store.py  # ChromaDB storage for conclusions
│   └── models.py        # Conclusion, ConclusionType dataclasses
├── mcp/
│   ├── server.py        # MCP server (9 tools)
│   └── __main__.py      # Entry point
├── cli/
│   └── main.py          # Click CLI (index, search, serve, stats)
└── utils/
    └── tokens.py        # Token counting utilities

Key Patterns

• Async everywhere: MCP server is async; engine queries wrapped in run_in_executor
• Global engine instance: server.py initializes a single RAGEngine on startup
• Click CLI: Commands in cli/main.py
• ChromaDB local: Vectors stored locally in .chroma/ directory
• Incremental indexing: Only re-indexes changed files (content hash)
• Azure support: embedder.py has _create_openai_client() factory for OpenAI/Azure