How minhao-zhang/obsidian-mcp-server works
Project Type and Purpose
• This is an Obsidian plugin (“Obsidian MCP Server”) written in TypeScript.
• It embeds a local SSE‑based MCP (Model Context Protocol) server inside Obsidian to expose vault‑interaction tools to external clients (AI assistants, scripts).
• It indexes Markdown notes via an Orama vector database and uses an OpenAI‑compatible embedding service for semantic search.
File Structure Analysis
• Top‐level config files: tsconfig.json, esbuild.config.mjs, eslint.config.mjs, manifest.json (Obsidian plugin manifest).
• Entrypoint: main.ts (registers plugin with Obsidian).
• Core modules:
• src/mcp-server.ts – SSE server implementation and MCP protocol handling
• src/orama-db.ts – Vector store wrapper around OramaDB
• src/settings.ts – Plugin settings panel logic
• Commands: src/commands/*Command.ts – Obsidian command handlers (start/stop server, index vault, save DB)
• Tools: src/tools/*.ts – Individual MCP “tools” (list, read, create, edit files, vector search, count entries)
• Utilities: src/utils/*.ts – Embedding calls, Orama operations, file‑exclude logic (.gitignore support)
• Static assets: styles.css, locales/*.json for multi‑language support
Key README Insights
• Describes the MCP tools and how they map to vault operations and semantic search.
• Highlights external dependencies: OpenAI‑compatible embedding endpoint, OramaDB limitations.
• Explains plugin lifecycle: settings panel → commands → server start/index → external client connections.
a. Main Components
• Obsidian Host (Electron-based app)
• MCP Server Module (src/mcp-server.ts) running SSE on configurable port
• Obsidian Plugin UI
– Settings Pane (src/settings.ts)
• Orama Vector Database (src/orama-db.ts + orama.json storage)
• Embedding Service (external OpenAI‑compatible API)
• File System Vault (user’s markdown files)
• MCP Client (external AI assistant or script)
b. Relationships & Data Flows
1. Plugin UI → Settings changes → settings.ts → persisted to Obsidian data store
2. Command Palette → command handler → may trigger:
• Vault indexing: scan vault (src/tools/list_files), chunk & embed text (embeddings.ts), store vectors in OramaDB
• MCP server start/stop: initialize mcp-server.ts SSE endpoint
3. MCP Client ↔ SSE endpoint (mcp-server.ts) → routes requests to appropriate tool in src/tools → uses:
• OramaDB for vector_search/count_entries
• FS utilities for list_files, read_file, create_file, edit_file
4. Tools use src/utils/orama_operations.ts and src/utils/embeddings.ts to coordinate DB and external embedding calls
c. Architectural Patterns & Principles
• Modular command & tool handlers (separation of concerns)
• Single SSE endpoint dispatching to named tools (MCP protocol)
• Configurable dependency injection for embedding provider (via settings)
• Use of .gitignore‑style patterns for vault exclusion (rAGignore logic)
d. Key Technologies & Frameworks
• TypeScript, esbuild for bundling
• Obsidian plugin API
• Server‐Sent Events (SSE) for MCP communication
• OramaDB for vector storage
• External REST API for embeddings (OpenAI or Ollama)