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

Task	Command
Install	npm install
Build	npm run build (tsc → dist/)
Dev server (watch)	npm run dev
Test	npm test (vitest run)
Test (watch)	npm run test:watch
Lint	npm run lint (eslint src/)
Auto-fix lint/format	npm run lint:fix then npm run format
Format check	npm run format:check

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)
└── types/
    └── index.ts            # Shared types

tests/                       # Vitest specs (*.test.js) — mirror the src module under test
examples/test-vault/         # Sample vault used by examples and manual testing