obsidian-mcp-server: Instructions file for Claude Code

Obsidian MCP Server — Project Conventions

A Model Context Protocol server that lets AI assistants interact with an Obsidian vault (notes, frontmatter, tags, search, links) over an SSE transport.

Stack

• Language: TypeScript 5.x, ES modules ("type": "module"). Use import/export, never require.
• Runtime: Node.js >= 20.19. Build target is dist/ via tsc.
• HTTP: Express 5.
• MCP: @modelcontextprotocol/sdk.
• Frontmatter: gray-matter.
• Tests: Vitest. Lint: ESLint + Prettier (Prettier rules are enforced through ESLint).

Commands

Always run npm test and npm run lint before opening a PR — both must pass clean. Prettier violations surface as ESLint errors, so npm run lint:fix resolves most formatting issues.

Layout

src/
├── index.ts                # Express server entrypoint & wiring
├── server/
│   ├── mcp.ts              # MCP protocol handling (SSE connection, message routing)
│   └── middleware.ts       # Express middleware (auth, etc.)
├── tools/
│   ├── definitions.ts      # Tool schemas (JSON Schema inputSchema)
│   ├── handlers.ts         # Tool execution → dispatches to VaultManager
│   └── index.ts            # Re-exports
├── vault/
│   ├── VaultManager.ts     # Core vault operations (the real logic lives here)
│   └── frontmatter.ts      # YAML frontmatter utilities (gray-matter)
├── index/                  # Optional semantic search (pgvector + Ollama); gated on DATABASE_URL
│   ├── config.ts           # Env → IndexConfig (null when DATABASE_URL unset)
│   ├── exclusions.ts       # Paths the indexer never reads (tested)
│   ├── chunker.ts          # Heading-aware chunking (tested, pure)
│   ├── embedder.ts         # Ollama client + FakeEmbedder for tests
│   ├── ranking.ts          # Configurable fusion, weights and per-note cap
│   ├── store.ts            # All SQL: schema, upserts, hybrid search
│   ├── scanner.ts          # Vault walk, change detection, one reconcile pass
│   └── SearchService.ts    # What the tools call
├── maintain/               # Maintenance configuration, decisions, reports and worker
├── maintain.ts             # Report-only maintenance CLI
├── learn/                  # Learn log, redaction, configuration and report assembly
├── learn-report.ts         # Read-only learn-report CLI entrypoint
├── eval/                   # Golden schema, metrics and ranking grid
├── eval.ts                 # Read-only brain-eval CLI entrypoint
├── indexer.ts              # Indexer entrypoint (same image, second container)
└── types/
    └── index.ts            # Shared types

sql/001_schema.sql           # Index DDL; __DIM__ substituted at start
sql/002_learning.sql         # Learn log DDL; applied even when logging is disabled
sql/003_maintenance.sql      # Additive maintenance schema; history and decisions
tests/                       # Vitest specs (*.test.js) — mirror the src module under test
examples/test-vault/         # Sample vault used by examples and manual testing