obsidian-mcp-server copilot-instructions.md

Obsidian MCP Server - AI Instructions

Project Overview

This is a Model Context Protocol (MCP) server that provides real-time Claude AI access to Obsidian vaults. The server enables dynamic querying, searching, and reading of notes without token limitations through JSON-RPC 2.0 over stdio.

Key Purpose: Bridge Claude AI with Obsidian knowledge bases through efficient, secure, real-time vault access.

Issue Tracking

This project uses bd (beads) for issue tracking. Run bd prime for workflow context.

Quick reference:

• bd ready - Find unblocked work
• bd create "Title" --description "Description" --type task --priority 2 - Create issue
• bd close <id> - Complete work
• bd sync - Sync with git

Critical Project Context

MCP Architecture (CRITICAL)

• Protocol: JSON-RPC 2.0 over stdio (stdin/stdout), NOT REST/HTTP
• Server Model: Long-running process with structured message communication
• Resources: Vault notes exposed as obsidian://vault/[path] URIs
• Tools: Functions callable by Claude (list_vaults, search_vault, create_note, etc.)
• Multi-Vault: Single server instance serving multiple vaults via vaults config array
• Implementation: TypeScript using @modelcontextprotocol/sdk

Technology Stack

Runtime & Build:

• Node.js 18+ (recommended 20+)
• TypeScript 5.7+ with strict mode
• ES Modules (type: "module" in package.json)

Core Dependencies:

• @modelcontextprotocol/sdk - MCP protocol implementation
• @xenova/transformers - Local embedding generation (Transformers.js)
• vectra - Local vector database for semantic search
• chokidar - File system watcher for automatic index updates
• winston - Structured logging system
• gray-matter - YAML frontmatter parsing
• zod - Runtime type validation

Development:

• tsx - TypeScript execution and hot reload
• prettier - Code formatting
• eslint - Code linting

Project Structure

obsidian-mcp-server/
├── src/
│   ├── index.ts              # Entry point, server initialization
│   ├── obsidian-server.ts    # MCP request handlers (resources, tools)
│   ├── vault-registry.ts    # Multi-vault context management
│   ├── embeddings.ts         # Vector store and embedding generation
│   ├── search.ts             # Keyword search implementation
│   ├── utils.ts              # Config loading, path helpers
│   ├── logger.ts             # Winston logging configuration
│   └── indexing-worker.ts    # Background indexing worker process
├── docs/
│   ├── configuration.md      # Configuration options
│   ├── indexing-workflow.md  # Indexing procedures and troubleshooting
│   ├── semantic-search.md    # Search implementation details
│   └── vector-search.md      # Vector search architecture
├── scripts/
│   └── inspect-yaml-issues.ps1  # YAML frontmatter debugging
├── .github/
│   ├── copilot-instructions.md  # This file
│   ├── obsidian-mcp-server.code-workspace  # VS Code workspace
│   └── README.md             # GitHub folder documentation
├── config.json               # Runtime configuration (gitignored)
├── config.example.json       # Configuration template
└── package.json              # Dependencies and scripts