obsidian-mcp-plugin: Instructions file for Claude Code

Claude Development Guidelines for Obsidian MCP Plugin

Project Context

This is a hybrid Obsidian plugin that combines:

• Local REST API functionality (from coddingtonbear's plugin)
• Semantic MCP operations (from aaronsb/obsidian-semantic-mcp)
• Direct Obsidian API integration for enhanced performance

The critical architectural pattern is preserving the ObsidianAPI abstraction layer while replacing HTTP calls with direct Obsidian plugin API calls. This allows reuse of all existing MCP server logic while gaining performance benefits.

Code Quality Guidelines

SOLID Principles Application

• Single Responsibility:

  • ObsidianAPI class handles only vault operations abstraction
  • MCPServer class handles only MCP protocol operations
  • HTTPServer class handles only REST endpoint management
  • Plugin main class handles only Obsidian plugin lifecycle

• Open/Closed:

  • ObsidianAPI interface remains stable for extensions
  • MCP operations extensible through semantic router pattern
  • HTTP endpoints extensible without modifying core logic

• Liskov Substitution:

  • New ObsidianAPI implementation must be drop-in replacement
  • All method signatures and return types must match exactly
  • Error handling behavior must be preserved

• Interface Segregation:

  • Separate interfaces for vault operations, search operations, and workspace operations
  • MCP protocol separated from HTTP REST protocol
  • Plugin settings separated from server configuration

• Dependency Inversion:

  • Depend on Obsidian Plugin API abstractions, not concrete implementations
  • MCP server depends on ObsidianAPI interface, not specific implementation
  • HTTP server depends on operation interfaces, not direct vault access

Architecture Patterns

Critical Abstraction Layer

// This interface MUST remain stable
interface IObsidianAPI {
  getFile(path: string): Promise<ObsidianFileResponse>;
  listFiles(directory?: string): Promise<string[]>;
  searchSimple(query: string): Promise<any[]>;
  // ... all existing methods preserved
}

// Implementation changes from HTTP to direct API
class ObsidianAPI implements IObsidianAPI {
  constructor(private app: App) {} // Direct plugin access
  
  async getFile(path: string): Promise<ObsidianFileResponse> {
    // Direct vault access instead of HTTP call
    const file = this.app.vault.getAbstractFileByPath(path);
    // ... implementation
  }
}