obsidian-mcp-server AGENTS.md

AGENTS.md

Context file for AI coding agents working on this repository.

Essential Commands

# Install dependencies (ALWAYS uv, NEVER pip)
make install          # uv sync

# Run MCP server locally
make dev              # uv run obsidian-mcp-server

# Testing
make test             # uv run pytest tests/
make coverage         # uv run pytest --cov=obsidian_mcp --cov-report=term-missing tests/

# Linting & formatting
make lint             # uv run ruff check . && uv run pyright .
make format           # uv run ruff check --fix . && uv run ruff format .

# Pre-commit hooks (ruff, pyright, pylint, bandit + general checks)
make hooks            # uv run pre-commit install
make check            # uv run pre-commit run --all-files

Package Management — CRITICAL

• ONLY use uv, NEVER pip or uv pip install
• Add dependencies: uv add package
• Add dev dependencies: uv add --dev package
• Add optional RAG deps: uv sync --extra rag
• Run tools: uv run tool
• FORBIDDEN: pip install, uv pip install, @latest syntax

Testing

• Framework: pytest with anyio for async tests (NOT asyncio)
• Single test: uv run pytest tests/test_basic.py::TestClassName::test_name -v
• Coverage: uv run pytest tests/ --cov=obsidian_mcp
• CI minimum coverage: 25%
• All async tests must use anyio fixtures, not asyncio

Architecture

Core Concept

MCP (Model Context Protocol) server built with FastMCP that exposes Obsidian vault operations as tools, resources, and prompts. Acts as a bridge between AI assistants (Claude Desktop, Cursor, Claude Code, Cline, etc.) and a user's Obsidian knowledge base.

Key Principles

1. Vault-Agnostic: Auto-detects vault structure. User config lives in {vault}/.agents/vault.yaml, not here.
2. Skills System: AI personas loaded from the user's vault at {vault}/.agents/skills/. Each skill has SKILL.md with YAML frontmatter.
3. Separation of Concerns: Tool registration (tools/*.py) → Business logic (tools/*_logic.py) → Utilities (utils/*.py).
4. Security Model: Path validation via .forbidden_paths and vault config. All file ops go through utils/security.py.
5. Optional RAG: Semantic search requires extra deps (uv sync --extra rag). ChromaDB-based vector indexing in semantic/.