mcp-compliant vault bridging via stdio and http transports
Implements dual-transport MCP server architecture (stdio for local CLI/IDE integration, HTTP for remote agents) that translates MCP protocol messages into Obsidian Local REST API calls. Uses @modelcontextprotocol/sdk with a layered transport abstraction pattern, maintaining separate Server instances per transport mode while sharing a unified service layer for vault operations. Stdio transport creates persistent process-based communication for tools like Claude Desktop; HTTP transport exposes the same MCP tools over REST with configurable CORS and authentication.
Unique: Dual-transport architecture with shared service layer enables both local (stdio) and remote (HTTP) MCP clients to access the same vault operations without code duplication. Uses @modelcontextprotocol/sdk's transport abstraction pattern to decouple protocol handling from business logic, allowing transport-agnostic tool definitions.
vs alternatives: Supports both local IDE integration (stdio) and remote agent access (HTTP) in a single server, whereas most MCP implementations are transport-specific or require separate deployments.
vault-aware note reading with metadata extraction
Implements obsidian_read_note tool that retrieves file content and YAML frontmatter metadata via the Obsidian REST API's /vault/read endpoint, with automatic parsing of frontmatter using YAML deserialization. Supports reading by file path with optional directory filtering and returns structured output containing raw content, parsed frontmatter object, and file metadata (creation/modification timestamps). Uses schema validation to ensure path safety and prevent directory traversal attacks.
Unique: Combines content retrieval with automatic YAML frontmatter deserialization and returns structured metadata alongside raw content, enabling agents to reason about both note text and its semantic properties (tags, custom fields) in a single call. Uses Obsidian's REST API /vault/read endpoint rather than direct file system access, ensuring consistency with Obsidian's internal state.
vs alternatives: Provides structured frontmatter parsing out-of-the-box (unlike raw file readers), and integrates with Obsidian's REST API for consistency, whereas direct file system access could read stale or partially-written content.
input sanitization and schema validation with redos prevention
Implements multi-layer input validation using JSON Schema validation for all MCP tool parameters, regex pattern analysis to detect ReDoS vulnerabilities, and path traversal prevention via path normalization and allowlist checking. Validates file paths against vault root to prevent directory traversal attacks, sanitizes regex patterns before passing to Obsidian's search engine, and enforces content size limits. Uses zod or similar schema validation library with custom validators for domain-specific constraints.
Unique: Combines JSON Schema validation, regex ReDoS detection, and path traversal prevention in a unified validation layer that runs before any Obsidian REST API calls. Uses heuristic-based ReDoS detection to identify potentially dangerous patterns without executing them.
vs alternatives: Multi-layer validation (schema + regex analysis + path checking) provides defense-in-depth, whereas single-layer validation may miss edge cases. ReDoS detection prevents performance attacks without requiring regex execution.
vault state caching with invalidation strategy
Implements VaultCacheService that maintains an in-memory cache of frequently accessed vault metadata (file listings, search results, frontmatter) with configurable TTL-based invalidation. Supports manual cache invalidation on write operations (note updates, deletions) to maintain consistency. Uses LRU eviction policy to prevent unbounded memory growth. Cache keys are based on operation parameters (path, search query, etc.) enabling fine-grained invalidation.
Unique: Implements LRU-based in-memory caching with TTL invalidation and manual invalidation on write operations, enabling fast repeated access to vault data without polling Obsidian REST API. Cache keys are based on operation parameters enabling fine-grained invalidation.
vs alternatives: In-memory caching provides sub-millisecond latency for cached queries (vs 50-200ms for REST API calls), with automatic TTL-based invalidation ensuring eventual consistency. Manual invalidation on writes prevents serving stale data after updates.
modular tool registration and extensibility framework
Implements tool registration system where each MCP tool (obsidian_read_note, obsidian_update_note, etc.) is defined as a separate module with standardized interface: name, description, input schema, and handler function. Tools are registered with the MCP server via a registry pattern, enabling dynamic tool discovery and addition of custom tools without modifying core server code. Each tool module exports its schema and handler independently, allowing tools to be tested, versioned, and deployed separately.
Unique: Uses modular tool registration pattern where each tool is a separate module with standardized interface, enabling independent testing, versioning, and deployment. Tools are registered dynamically at server startup via a registry, allowing custom tools to be added without modifying core code.
vs alternatives: Modular architecture enables independent tool development and testing (unlike monolithic tool implementations), supports dynamic registration enabling plugin-like extensibility, and allows tools to be versioned and deployed separately.
vault-wide full-text search with regex and content filtering
Implements obsidian_global_search tool that executes vault-wide content searches via Obsidian REST API's /search/simple endpoint, supporting both plain-text and regex pattern matching with optional result filtering by file type, path prefix, or tag. Returns ranked search results with file paths, matching line snippets, and match positions. Uses schema validation to sanitize regex patterns and prevent ReDoS attacks, with configurable result limits to prevent memory exhaustion.
Unique: Leverages Obsidian's native search index and regex engine via REST API, enabling vault-wide searches without re-indexing or maintaining a separate search backend. Supports both plain-text and regex patterns with configurable result filtering and limits, integrated into the MCP tool schema with input validation to prevent ReDoS attacks.
vs alternatives: Uses Obsidian's built-in search index (faster than external indexing) and integrates directly with Obsidian's regex dialect, whereas external search tools would require maintaining a separate index and may have different regex semantics.
content-aware note updating with append/prepend/overwrite modes
Implements obsidian_update_note tool that modifies note content via Obsidian REST API's /vault/modify endpoint with three distinct modes: append (add content to end), prepend (add content to start), or overwrite (replace entire content). Preserves YAML frontmatter during updates and supports atomic multi-line insertions. Uses schema validation to prevent path traversal and enforces content size limits to prevent vault corruption.
Unique: Provides three distinct update modes (append/prepend/overwrite) in a single tool with automatic frontmatter preservation, enabling flexible content modification patterns without requiring separate tools. Uses Obsidian's /vault/modify endpoint for atomic updates, ensuring consistency with Obsidian's internal state and file watchers.
vs alternatives: Supports append/prepend modes natively (unlike simple file overwrite tools), preserves frontmatter automatically, and integrates with Obsidian's file system watchers, whereas direct file writes could corrupt frontmatter or trigger race conditions.
regex-based search and replace with validation
Implements obsidian_search_replace tool that performs targeted text and regex replacements within a single note via Obsidian REST API's /vault/modify endpoint with search pattern validation. Supports both literal string and regex pattern matching with optional case-insensitive and global flags. Validates regex patterns before execution to prevent ReDoS attacks, and returns match count and preview of changes before applying. Uses atomic updates to ensure consistency.
Unique: Integrates regex pattern validation with atomic replacements via Obsidian's REST API, preventing ReDoS attacks while supporting both literal and regex patterns. Returns match count and change preview before applying, enabling safer bulk operations than raw file replacement.
vs alternatives: Validates regex patterns server-side to prevent ReDoS attacks (unlike naive regex tools), integrates with Obsidian's file system for consistency, and supports both literal and regex patterns in a single tool.
+5 more capabilities