obsidian-mcp-server 1.3.0 → 1.4.0

package/src/obsidian/types.ts

@@ -0,0 +1,124 @@
+/**
+ * Type definitions for Obsidian client
+ */
+
+/**
+ * Configuration for the Obsidian client
+ */
+export interface ObsidianConfig {
+  apiKey: string;
+  verifySSL?: boolean;
+  timeout?: number;
+  maxContentLength?: number;
+  maxBodyLength?: number;
+}
+
+/**
+ * Server configuration for Obsidian
+ */
+export interface ObsidianServerConfig {
+  protocol: "http" | "https";
+  host: string;
+  port: number;
+}
+
+/**
+ * Default configuration for Obsidian server
+ */
+export const DEFAULT_OBSIDIAN_CONFIG: ObsidianServerConfig = {
+  protocol: "https", // HTTPS required by default in Obsidian REST API plugin
+  host: "127.0.0.1",
+  port: 27124
+} as const;
+
+/**
+ * JSON representation of an Obsidian note
+ */
+export interface NoteJson {
+  content: string;
+  frontmatter: Record<string, unknown>;
+  path: string;
+  stat: {
+    ctime: number;
+    mtime: number;
+    size: number;
+  };
+  tags: string[];
+}
+
+/**
+ * Obsidian file/folder information
+ */
+export interface ObsidianFile {
+  path: string;
+  type: "file" | "folder";
+  children?: ObsidianFile[];
+}
+
+/**
+ * Obsidian command
+ */
+export interface ObsidianCommand {
+  id: string;
+  name: string;
+}
+
+/**
+ * Obsidian server status
+ */
+export interface ObsidianStatus {
+  authenticated: boolean;
+  ok: string;
+  service: string;
+  versions: {
+    obsidian: string;
+    self: string;
+  };
+}
+
+/**
+ * Period type for periodic notes
+ */
+export interface PeriodType {
+  type: "daily" | "weekly" | "monthly" | "quarterly" | "yearly";
+}
+
+/**
+ * Search match with context
+ */
+export interface SearchMatch {
+  context: string;
+  match: {
+    start: number;
+    end: number;
+  };
+}
+
+/**
+ * Standard search result
+ */
+export interface SearchResult {
+  filename: string;
+  result: unknown;
+}
+
+/**
+ * Simple search result with context
+ */
+export interface SimpleSearchResult {
+  filename: string;
+  score: number;
+  matches: SearchMatch[];
+}
+
+/**
+ * Union type for search responses
+ */
+export type SearchResponse = SearchResult | SimpleSearchResult;
+
+/**
+ * JSON Logic query for complex searches
+ */
+export interface JsonLogicQuery {
+  [operator: string]: unknown;
+}

package/src/resources/index.ts

@@ -0,0 +1,17 @@
+/**
+ * Resources module exports
+ */
+export * from './types.js';
+export * from './tags.js';
+
+import { ObsidianClient } from '../obsidian/client.js';
+import { TagResource } from './tags.js';
+
+/**
+ * Create and return the tag resource
+ * @param client The ObsidianClient instance
+ * @returns The tag resource
+ */
+export function createTagResource(client: ObsidianClient): TagResource {
+  return new TagResource(client);
+}

package/src/{resources.ts → resources/tags.ts}

@@ -1,9 +1,20 @@
+/**
+ * Tag resource implementation
+ */
 import { Resource, TextContent } from "@modelcontextprotocol/sdk/types.js";
-import { ObsidianClient } from "./obsidian.js";
-import { TagResponse, ObsidianFile, JsonLogicQuery } from "./types.js";
-import { PropertyManager } from "./properties.js";
+import { ObsidianClient } from "../obsidian/client.js";
+import { JsonLogicQuery } from "../obsidian/types.js";
+import { PropertyManager } from "../tools/properties/manager.js";
 import { join, sep } from "path";
+import { createLogger } from "../utils/logging.js";
+import { TagResponse } from "./types.js";
 
+// Create a logger for tag resources
+const logger = createLogger('TagResource');
+
+/**
+ * Resource for providing tags used in the Obsidian vault
+ */
 export class TagResource {
   private tagCache: Map<string, Set<string>> = new Map();
   private propertyManager: PropertyManager;
@@ -16,6 +27,9 @@ export class TagResource {
     this.initializeCache();
   }
 
+  /**
+   * Get resource description for the MCP server
+   */
   getResourceDescription(): Resource {
     return {
       uri: "obsidian://tags",
@@ -25,8 +39,13 @@ export class TagResource {
     };
   }
 
+  /**
+   * Initialize the tag cache
+   */
   private async initializeCache() {
     try {
+      logger.info('Initializing tag cache');
+      
       // Get all markdown files using platform-agnostic path pattern
       const query: JsonLogicQuery = {
         "glob": [`**${sep}*.md`.replace(/\\/g, '/'), { "var": "path" }]
@@ -50,18 +69,22 @@ export class TagResource {
             });
           }
         } catch (error) {
-          console.error(`Failed to process file ${result.filename}:`, error);
+          logger.error(`Failed to process file ${result.filename}:`, error);
         }
       }
 
       this.isInitialized = true;
       this.lastUpdate = Date.now();
+      logger.info(`Tag cache initialized with ${this.tagCache.size} unique tags`);
     } catch (error) {
-      console.error("Failed to initialize tag cache:", error);
+      logger.error("Failed to initialize tag cache:", error);
       throw error;
     }
   }
 
+  /**
+   * Add a tag to the cache
+   */
   private addTag(tag: string, filepath: string) {
     if (!this.tagCache.has(tag)) {
       this.tagCache.set(tag, new Set());
@@ -69,16 +92,24 @@ export class TagResource {
     this.tagCache.get(tag)!.add(filepath);
   }
 
+  /**
+   * Update the cache if needed
+   */
   private async updateCacheIfNeeded() {
     const now = Date.now();
     if (now - this.lastUpdate > this.updateInterval) {
+      logger.debug('Tag cache needs update, refreshing...');
       await this.initializeCache();
     }
   }
 
+  /**
+   * Get the content for the resource
+   */
   async getContent(): Promise<TextContent[]> {
     try {
       if (!this.isInitialized) {
+        logger.info('Tag cache not initialized, initializing now');
         await this.initializeCache();
       } else {
         await this.updateCacheIfNeeded();
@@ -104,13 +135,14 @@ export class TagResource {
         }
       };
 
+      logger.debug(`Returning tag resource with ${response.tags.length} tags`);
       return [{
         type: "text",
         text: JSON.stringify(response, null, 2),
         uri: this.getResourceDescription().uri
       }];
     } catch (error) {
-      console.error("Failed to get tags:", error);
+      logger.error("Failed to get tags:", error);
       throw error;
     }
   }

package/src/resources/types.ts

@@ -0,0 +1,30 @@
+/**
+ * Resource types for the MCP server
+ */
+
+/**
+ * Tag information structure
+ */
+export interface TagInfo {
+  name: string;
+  count: number;
+  files: string[];
+}
+
+/**
+ * Tag metadata structure
+ */
+export interface TagMetadata {
+  totalOccurrences: number;
+  uniqueTags: number;
+  scannedFiles: number;
+  lastUpdate: number;  // Timestamp of last cache update
+}
+
+/**
+ * Tag resource response structure
+ */
+export interface TagResponse {
+  tags: TagInfo[];
+  metadata: TagMetadata;
+}

package/src/tools/base.ts

@@ -0,0 +1,112 @@
+/**
+ * Base class for all tool handlers
+ */
+import { Tool, TextContent, ImageContent, EmbeddedResource } from "@modelcontextprotocol/sdk/types.js";
+import { ObsidianClient } from "../obsidian/client.js";
+import { ObsidianError } from "../utils/errors.js";
+import { tokenCounter } from "../utils/tokenization.js";
+import { createLogger } from "../utils/logging.js";
+
+// Create a logger for tool operations
+const logger = createLogger('Tools');
+
+/**
+ * Interface that all tool handlers must implement
+ */
+export interface ToolHandler<T = any> {
+  name: string;
+  getToolDescription(): Tool;
+  runTool(args: T): Promise<Array<TextContent>>;
+}
+
+/**
+ * Base class for all tool handlers with common functionality
+ */
+export abstract class BaseToolHandler<T = Record<string, unknown>> implements ToolHandler<T> {
+  /**
+   * Create a new tool handler
+   * @param name The name of the tool
+   * @param client The ObsidianClient instance
+   */
+  constructor(
+    public readonly name: string,
+    protected client: ObsidianClient
+  ) {}
+
+  /**
+   * Get the tool description for MCP server
+   */
+  abstract getToolDescription(): Tool;
+
+  /**
+   * Run the tool with the provided arguments
+   */
+  abstract runTool(args: T): Promise<Array<TextContent>>;
+
+  /**
+   * Create a standardized response from any content type
+   * @param content The content to format for response
+   * @returns An array of TextContent objects
+   */
+  protected createResponse(content: unknown): TextContent[] {
+    let text: string;
+
+    // Handle different content types
+    if (typeof content === 'string') {
+      text = content;
+    } else if (content instanceof Buffer) {
+      text = content.toString('utf-8');
+    } else if (Array.isArray(content) && content.every(item => typeof item === 'string')) {
+      text = content.join('\n');
+    } else if (content instanceof Error) {
+      text = `Error: ${content.message}\n${content.stack || ''}`;
+    } else {
+      try {
+        text = JSON.stringify(content, null, 2);
+      } catch (error) {
+        text = String(content);
+      }
+    }
+
+    // Count tokens and truncate if necessary
+    const originalTokenCount = tokenCounter.countTokens(text);
+    const truncatedText = tokenCounter.truncateToTokenLimit(text);
+    const finalTokenCount = tokenCounter.countTokens(truncatedText);
+    
+    if (originalTokenCount > finalTokenCount) {
+      logger.debug(
+        `[${this.name}] Response truncated:`,
+        `original tokens=${originalTokenCount}`,
+        `truncated tokens=${finalTokenCount}`
+      );
+    }
+    
+    return [{
+      type: "text",
+      text: truncatedText
+    }];
+  }
+
+  /**
+   * Standard error handling for tool execution
+   * @param error The error to handle
+   * @throws ObsidianError
+   */
+  protected handleError(error: unknown): never {
+    if (error instanceof ObsidianError) {
+      throw error;
+    }
+    if (error instanceof Error) {
+      throw new ObsidianError(
+        `Tool '${this.name}' execution failed: ${error.message}`,
+        50000, // Internal server error
+        { originalError: error.stack }
+      );
+    }
+    throw new ObsidianError(
+      `Tool '${this.name}' execution failed with unknown error`,
+      50000, // Internal server error
+      { error }
+    );
+  }
+}

package/src/tools/files/content.ts

@@ -0,0 +1,206 @@
+/**
+ * File content manipulation tools implementation
+ */
+import { Tool } from "@modelcontextprotocol/sdk/types.js";
+import { ObsidianClient } from "../../obsidian/client.js";
+import { BaseToolHandler } from "../base.js";
+import { createLogger } from "../../utils/logging.js";
+
+// Create a logger for file content operations
+const logger = createLogger('FileContentTools');
+
+/**
+ * Tool names for file content operations
+ */
+export const FILE_CONTENT_TOOL_NAMES = {
+  GET_FILE_CONTENTS: "obsidian_get_file_contents",
+  APPEND_CONTENT: "obsidian_append_content",
+  PATCH_CONTENT: "obsidian_patch_content"
+} as const;
+
+/**
+ * Arguments for file content operations
+ */
+export interface FileContentsArgs {
+  filepath: string;
+}
+
+/**
+ * Arguments for appending content to a file
+ */
+export interface AppendContentArgs {
+  filepath: string;
+  content: string;
+}
+
+/**
+ * Arguments for updating content of a file
+ */
+export interface PatchContentArgs {
+  filepath: string;
+  content: string;
+}
+
+/**
+ * Tool handler for getting file contents
+ */
+export class GetFileContentsToolHandler extends BaseToolHandler<FileContentsArgs> {
+  constructor(client: ObsidianClient) {
+    super(FILE_CONTENT_TOOL_NAMES.GET_FILE_CONTENTS, client);
+  }
+
+  getToolDescription(): Tool {
+    return {
+      name: this.name,
+      description: "Return the content of a single file in your vault. Supports markdown files, text files, and other readable formats. Returns the raw content including any YAML frontmatter.",
+      examples: [
+        {
+          description: "Get content of a markdown note",
+          args: {
+            filepath: "Projects/research.md"
+          }
+        },
+        {
+          description: "Get content of a configuration file",
+          args: {
+            filepath: "configs/settings.yml"
+          }
+        }
+      ],
+      inputSchema: {
+        type: "object",
+        properties: {
+          filepath: {
+            type: "string",
+            description: "Path to the relevant file (relative to your vault root).",
+            format: "path"
+          }
+        },
+        required: ["filepath"]
+      }
+    };
+  }
+
+  async runTool(args: FileContentsArgs): Promise<Array<any>> {
+    try {
+      logger.debug(`Getting contents of file: ${args.filepath}`);
+      const content = await this.client.getFileContents(args.filepath);
+      return this.createResponse(content);
+    } catch (error) {
+      return this.handleError(error);
+    }
+  }
+}
+
+/**
+ * Tool handler for appending content to a file
+ */
+export class AppendContentToolHandler extends BaseToolHandler<AppendContentArgs> {
+  constructor(client: ObsidianClient) {
+    super(FILE_CONTENT_TOOL_NAMES.APPEND_CONTENT, client);
+  }
+
+  getToolDescription(): Tool {
+    return {
+      name: this.name,
+      description: "Append content to a new or existing file in the vault.",
+      examples: [
+        {
+          description: "Append a new task",
+          args: {
+            filepath: "tasks.md",
+            content: "- [ ] New task to complete"
+          }
+        },
+        {
+          description: "Append meeting notes",
+          args: {
+            filepath: "meetings/2025-01-23.md",
+            content: "## Meeting Notes\n\n- Discussed project timeline\n- Assigned tasks"
+          }
+        }
+      ],
+      inputSchema: {
+        type: "object",
+        properties: {
+          filepath: {
+            type: "string",
+            description: "Path to the file (relative to vault root)",
+            format: "path"
+          },
+          content: {
+            type: "string",
+            description: "Content to append to the file"
+          }
+        },
+        required: ["filepath", "content"]
+      }
+    };
+  }
+
+  async runTool(args: AppendContentArgs): Promise<Array<any>> {
+    try {
+      logger.debug(`Appending content to file: ${args.filepath}`);
+      await this.client.appendContent(args.filepath, args.content);
+      return this.createResponse({ 
+        message: `Successfully appended content to ${args.filepath}`,
+        success: true
+      });
+    } catch (error) {
+      return this.handleError(error);
+    }
+  }
+}
+
+/**
+ * Tool handler for updating file content
+ */
+export class PatchContentToolHandler extends BaseToolHandler<PatchContentArgs> {
+  constructor(client: ObsidianClient) {
+    super(FILE_CONTENT_TOOL_NAMES.PATCH_CONTENT, client);
+  }
+
+  getToolDescription(): Tool {
+    return {
+      name: this.name,
+      description: "Update the entire content of an existing note or create a new one.",
+      examples: [
+        {
+          description: "Update a note's content",
+          args: {
+            filepath: "project.md",
+            content: "# Project Notes\n\nThis will replace the entire content of the note."
+          }
+        }
+      ],
+      inputSchema: {
+        type: "object",
+        properties: {
+          filepath: {
+            type: "string",
+            description: "Path to the file (relative to vault root)",
+            format: "path"
+          },
+          content: {
+            type: "string",
+            description: "New content for the note (replaces existing content)"
+          }
+        },
+        required: ["filepath", "content"]
+      }
+    };
+  }
+
+  async runTool(args: PatchContentArgs): Promise<Array<any>> {
+    try {
+      logger.debug(`Updating content of file: ${args.filepath}`);
+      await this.client.updateContent(args.filepath, args.content);
+      return this.createResponse({ 
+        message: `Successfully updated content in ${args.filepath}`,
+        success: true
+      });
+    } catch (error) {
+      return this.handleError(error);
+    }
+  }
+}

package/src/tools/files/index.ts

@@ -0,0 +1,31 @@
+/**
+ * File operation tools exports
+ */
+export * from './list.js';
+export * from './content.js';
+
+import { ObsidianClient } from '../../obsidian/client.js';
+import { 
+  ListFilesInVaultToolHandler, 
+  ListFilesInDirToolHandler 
+} from './list.js';
+import { 
+  GetFileContentsToolHandler, 
+  AppendContentToolHandler, 
+  PatchContentToolHandler 
+} from './content.js';
+
+/**
+ * Create all file-related tool handlers
+ * @param client The ObsidianClient instance
+ * @returns Array of file tool handlers
+ */
+export function createFileToolHandlers(client: ObsidianClient) {
+  return [
+    new ListFilesInVaultToolHandler(client),
+    new ListFilesInDirToolHandler(client),
+    new GetFileContentsToolHandler(client),
+    new AppendContentToolHandler(client),
+    new PatchContentToolHandler(client)
+  ];
+}