obsidian-mcp-server 1.2.3 → 1.2.5

package/src/obsidian.ts

@@ -1,6 +1,21 @@
 import axios from "axios";
 import type { AxiosInstance, AxiosError, AxiosRequestConfig } from "axios";
-import { ObsidianConfig, ObsidianError, ObsidianFile, SearchResult, DEFAULT_OBSIDIAN_CONFIG, ObsidianServerConfig, JsonLogicQuery } from "./types.js";
+import {
+  ObsidianConfig,
+  ObsidianError,
+  ObsidianFile,
+  SearchResult,
+  SimpleSearchResult,
+  SearchResponse,
+  DEFAULT_OBSIDIAN_CONFIG,
+  ObsidianServerConfig,
+  JsonLogicQuery,
+  ObsidianStatus,
+  ObsidianCommand,
+  NoteJson,
+  PeriodType,
+  ApiError
+} from "./types.js";
 import { Agent } from "node:https";
 import { readFileSync } from "fs";
 import { fileURLToPath } from 'url';
@@ -26,15 +41,22 @@ export class ObsidianClient {
 
   constructor(config: ObsidianConfig) {
     if (!config.apiKey) {
-      throw new ObsidianError("API key is required", 401);
+      throw new ObsidianError(
+        "Missing API key. To fix this:\n" +
+        "1. Install the 'Local REST API' plugin in Obsidian\n" +
+        "2. Enable the plugin in Obsidian Settings\n" +
+        "3. Copy your API key from Obsidian Settings > Local REST API\n" +
+        "4. Provide the API key in your configuration",
+        40100 // Unauthorized
+      );
     }
 
     // Combine defaults with provided config
     this.config = {
       ...DEFAULT_OBSIDIAN_CONFIG,
-      verifySSL: config.verifySSL ?? process.env.NODE_ENV === 'production', // Enable SSL verification in production by default
+      verifySSL: config.verifySSL ?? true, // Default to true as required by Obsidian REST API plugin
       apiKey: config.apiKey,
-      timeout: config.timeout ?? 5000,
+      timeout: config.timeout ?? 5000, // 5 second default timeout
       maxContentLength: config.maxContentLength ?? 50 * 1024 * 1024, // 50MB
       maxBodyLength: config.maxBodyLength ?? 50 * 1024 * 1024 // 50MB
     };
@@ -69,8 +91,9 @@ export class ObsidianClient {
 
     if (!this.config.verifySSL) {
       console.warn(
-        "WARNING: SSL verification is disabled. This is not recommended for production use.",
-        process.env.NODE_ENV === 'production' ? "Consider enabling SSL verification." : "This is acceptable for local development only."
+        "WARNING: SSL verification is disabled. The Obsidian REST API plugin requires HTTPS by default.\n" +
+        "Make sure you have configured the certificate as a trusted certificate authority.\n" +
+        "See Obsidian Settings > Local REST API > 'How to Access' for setup instructions."
       );
     }
 
@@ -106,12 +129,33 @@ export class ObsidianClient {
     // Prevent path traversal attacks
     const normalizedPath = filepath.replace(/\\/g, '/');
     if (normalizedPath.includes('../') || normalizedPath.includes('..\\')) {
-      throw new ObsidianError('Invalid file path: Path traversal not allowed', 400);
+      throw new ObsidianError('Invalid file path: Path traversal not allowed', 40001);
     }
     
     // Additional path validations
     if (normalizedPath.startsWith('/') || /^[a-zA-Z]:/.test(normalizedPath)) {
-      throw new ObsidianError('Invalid file path: Absolute paths not allowed', 400);
+      throw new ObsidianError('Invalid file path: Absolute paths not allowed', 40002);
+    }
+  }
+
+  private getErrorCode(status: number): number {
+    switch (status) {
+      case 400: return 40000; // Bad request
+      case 401: return 40100; // Unauthorized
+      case 403: return 40300; // Forbidden
+      case 404: return 40400; // Not found
+      case 405: return 40500; // Method not allowed
+      case 409: return 40900; // Conflict
+      case 429: return 42900; // Too many requests
+      case 500: return 50000; // Internal server error
+      case 501: return 50100; // Not implemented
+      case 502: return 50200; // Bad gateway
+      case 503: return 50300; // Service unavailable
+      case 504: return 50400; // Gateway timeout
+      default:
+        if (status >= 400 && status < 500) return 40000 + (status - 400) * 100;
+        if (status >= 500 && status < 600) return 50000 + (status - 500) * 100;
+        return 50000;
     }
   }
 
@@ -120,21 +164,64 @@ export class ObsidianClient {
       return await operation();
     } catch (error) {
       if (axios.isAxiosError(error)) {
-        const axiosError = error as AxiosError<{ errorCode?: number; message?: string }>;
+        const axiosError = error as AxiosError<ApiError>;
         const response = axiosError.response;
         const errorData = response?.data;
-        const code = errorData?.errorCode ?? response?.status ?? 500;
+
+        // Handle common connection errors with helpful messages
+        if (error.code === 'DEPTH_ZERO_SELF_SIGNED_CERT' || error.code === 'UNABLE_TO_VERIFY_LEAF_SIGNATURE') {
+          throw new ObsidianError(
+            `SSL certificate verification failed. To fix this:\n` +
+            `1. Go to Obsidian Settings > Local REST API\n` +
+            `2. Under 'How to Access', copy the certificate\n` +
+            `3. Configure the certificate as a trusted certificate authority\n` +
+            `4. Ensure you're using HTTPS (HTTP is disabled by default)\n` +
+            `Original error: ${error.message}`,
+            50001, // SSL error code
+            { code: error.code, config: { verifySSL: this.config.verifySSL } }
+          );
+        }
+
+        if (error.code === 'ECONNREFUSED') {
+          throw new ObsidianError(
+            `Connection refused. To fix this:\n` +
+            `1. Ensure Obsidian is running\n` +
+            `2. Verify the 'Local REST API' plugin is enabled in Obsidian Settings\n` +
+            `3. Check that you're using the correct host (${this.config.host}) and port (${this.config.port})\n` +
+            `4. Make sure HTTPS is enabled in the plugin settings`,
+            50002, // Connection refused
+            { code: error.code }
+          );
+        }
+
+        if (response?.status === 401) {
+          throw new ObsidianError(
+            `Authentication failed. To fix this:\n` +
+            `1. Go to Obsidian Settings > Local REST API\n` +
+            `2. Copy your API key from the settings\n` +
+            `3. Update your configuration with the new API key\n` +
+            `Note: The API key changes when you regenerate certificates`,
+            40100, // Unauthorized
+            { code: error.code }
+          );
+        }
+
+        // For other errors, use API error code if available
+        const errorCode = errorData?.errorCode ?? this.getErrorCode(response?.status ?? 500);
         const message = errorData?.message ?? axiosError.message ?? "Unknown error";
-        throw new ObsidianError(message, code, errorData);
+        throw new ObsidianError(message, errorCode, errorData);
       }
-      throw error;
+      
+      if (error instanceof Error) {
+        throw new ObsidianError(error.message, 50000, error);
+      }
+      
+      throw new ObsidianError("Unknown error occurred", 50000, error);
     }
   }
 
   async listFilesInVault(): Promise<ObsidianFile[]> {
     return this.safeRequest(async () => {
-      const requestId = crypto.randomUUID();
-      console.debug(`[${requestId}] Listing vault files`);
       const response = await this.client.get<{ files: ObsidianFile[] }>("/vault/");
       return response.data.files;
     });
@@ -143,8 +230,6 @@ export class ObsidianClient {
   async listFilesInDir(dirpath: string): Promise<ObsidianFile[]> {
     this.validateFilePath(dirpath);
     return this.safeRequest(async () => {
-      const requestId = crypto.randomUUID();
-      console.debug(`[${requestId}] Listing files in directory: ${dirpath}`);
       const response = await this.client.get<{ files: ObsidianFile[] }>(`/vault/${dirpath}/`);
       return response.data.files;
     });
@@ -153,23 +238,18 @@ export class ObsidianClient {
   async getFileContents(filepath: string): Promise<string> {
     this.validateFilePath(filepath);
     return this.safeRequest(async () => {
-      const requestId = crypto.randomUUID();
-      console.debug(`[${requestId}] Getting file contents: ${filepath}`);
       const response = await this.client.get<string>(`/vault/${filepath}`);
       return response.data;
     });
   }
 
-  async search(query: string, contextLength: number = 100): Promise<SearchResult[]> {
+  async search(query: string, contextLength: number = 100): Promise<SimpleSearchResult[]> {
     return this.safeRequest(async () => {
-      const requestId = crypto.randomUUID();
-      console.debug(`[${requestId}] Performing simple search: ${query}`);
-      const response = await this.client.post<SearchResult[]>("/search/simple/", undefined, {
-        params: {
-          query,
-          contextLength
-        }
-      });
+      const response = await this.client.post<SimpleSearchResult[]>(
+        "/search/simple/",
+        null,
+        { params: { query, contextLength } }
+      );
       return response.data;
     });
   }
@@ -177,11 +257,9 @@ export class ObsidianClient {
   async appendContent(filepath: string, content: string): Promise<void> {
     this.validateFilePath(filepath);
     if (!content || typeof content !== 'string') {
-      throw new ObsidianError('Invalid content: Content must be a non-empty string', 400);
+      throw new ObsidianError('Invalid content: Content must be a non-empty string', 40003);
     }
     return this.safeRequest(async () => {
-      const requestId = crypto.randomUUID();
-      console.debug(`[${requestId}] Appending content to: ${filepath}`);
       await this.client.post(
         `/vault/${filepath}`,
         content,
@@ -197,12 +275,10 @@ export class ObsidianClient {
   async updateContent(filepath: string, content: string): Promise<void> {
     this.validateFilePath(filepath);
     if (!content || typeof content !== 'string') {
-      throw new ObsidianError('Invalid content: Content must be a non-empty string', 400);
+      throw new ObsidianError('Invalid content: Content must be a non-empty string', 40003);
     }
 
     return this.safeRequest(async () => {
-      const requestId = crypto.randomUUID();
-      console.debug(`[${requestId}] Updating content in: ${filepath}`);
       await this.client.put(
         `/vault/${filepath}`,
         content,
@@ -215,21 +291,167 @@ export class ObsidianClient {
     });
   }
 
-  async searchJson(query: JsonLogicQuery): Promise<SearchResult[]> {
+  async searchJson(query: JsonLogicQuery): Promise<SearchResponse[]> {
     return this.safeRequest(async () => {
-      const requestId = crypto.randomUUID();
-      console.debug(`[${requestId}] Performing complex search with query:`, JSON.stringify(query));
-      const response = await this.client.post<SearchResult[]>(
+      const isTagSearch = JSON.stringify(query).includes('"contains"') &&
+                         JSON.stringify(query).includes('"#"');
+      
+      const response = await this.client.post(
         "/search/",
         query,
         {
           headers: {
             "Content-Type": "application/vnd.olrapi.jsonlogic+json",
-            "Accept": "application/json"
+            "Accept": "application/vnd.olrapi.note+json"
           }
         }
       );
+
+      return isTagSearch ? response.data as SimpleSearchResult[] : response.data as SearchResult[];
+    });
+  }
+
+  async getStatus(): Promise<ObsidianStatus> {
+    return this.safeRequest(async () => {
+      const response = await this.client.get<ObsidianStatus>("/");
+      return response.data;
+    });
+  }
+
+  async listCommands(): Promise<ObsidianCommand[]> {
+    return this.safeRequest(async () => {
+      const response = await this.client.get<{commands: ObsidianCommand[]}>("/commands/");
+      return response.data.commands;
+    });
+  }
+
+  async executeCommand(commandId: string): Promise<void> {
+    return this.safeRequest(async () => {
+      await this.client.post(`/commands/${commandId}/`);
+    });
+  }
+
+  async openFile(filepath: string, newLeaf: boolean = false): Promise<void> {
+    this.validateFilePath(filepath);
+    return this.safeRequest(async () => {
+      await this.client.post(`/open/${filepath}`, null, {
+        params: { newLeaf }
+      });
+    });
+  }
+
+  async getActiveFile(): Promise<NoteJson> {
+    return this.safeRequest(async () => {
+      const response = await this.client.get<NoteJson>("/active/", {
+        headers: {
+          "Accept": "application/vnd.olrapi.note+json"
+        }
+      });
+      return response.data;
+    });
+  }
+
+  async updateActiveFile(content: string): Promise<void> {
+    return this.safeRequest(async () => {
+      await this.client.put("/active/", content, {
+        headers: {
+          "Content-Type": "text/markdown"
+        }
+      });
+    });
+  }
+
+  async deleteActiveFile(): Promise<void> {
+    return this.safeRequest(async () => {
+      await this.client.delete("/active/");
+    });
+  }
+
+  async patchActiveFile(
+    operation: "append" | "prepend" | "replace",
+    targetType: "heading" | "block" | "frontmatter",
+    target: string,
+    content: string,
+    options?: {
+      delimiter?: string;
+      trimWhitespace?: boolean;
+      contentType?: "text/markdown" | "application/json";
+    }
+  ): Promise<void> {
+    return this.safeRequest(async () => {
+      const headers: Record<string, string> = {
+        "Operation": operation,
+        "Target-Type": targetType,
+        "Target": target,
+        "Content-Type": options?.contentType || "text/markdown"
+      };
+
+      if (options?.delimiter) {
+        headers["Target-Delimiter"] = options.delimiter;
+      }
+      if (options?.trimWhitespace !== undefined) {
+        headers["Trim-Target-Whitespace"] = options.trimWhitespace.toString();
+      }
+
+      await this.client.patch("/active/", content, { headers });
+    });
+  }
+
+  async getPeriodicNote(period: PeriodType["type"]): Promise<NoteJson> {
+    return this.safeRequest(async () => {
+      const response = await this.client.get<NoteJson>(`/periodic/${period}/`, {
+        headers: {
+          "Accept": "application/vnd.olrapi.note+json"
+        }
+      });
       return response.data;
     });
   }
+
+  async updatePeriodicNote(period: PeriodType["type"], content: string): Promise<void> {
+    return this.safeRequest(async () => {
+      await this.client.put(`/periodic/${period}/`, content, {
+        headers: {
+          "Content-Type": "text/markdown"
+        }
+      });
+    });
+  }
+
+  async deletePeriodicNote(period: PeriodType["type"]): Promise<void> {
+    return this.safeRequest(async () => {
+      await this.client.delete(`/periodic/${period}/`);
+    });
+  }
+
+  async patchPeriodicNote(
+    period: PeriodType["type"],
+    operation: "append" | "prepend" | "replace",
+    targetType: "heading" | "block" | "frontmatter",
+    target: string,
+    content: string,
+    options?: {
+      delimiter?: string;
+      trimWhitespace?: boolean;
+      contentType?: "text/markdown" | "application/json";
+    }
+  ): Promise<void> {
+    return this.safeRequest(async () => {
+      const headers: Record<string, string> = {
+        "Operation": operation,
+        "Target-Type": targetType,
+        "Target": target,
+        "Content-Type": options?.contentType || "text/markdown"
+      };
+
+      if (options?.delimiter) {
+        headers["Target-Delimiter"] = options.delimiter;
+      }
+      if (options?.trimWhitespace !== undefined) {
+        headers["Trim-Target-Whitespace"] = options.trimWhitespace.toString();
+      }
+
+      await this.client.patch(`/periodic/${period}/`, content, { headers });
+    });
+  }
 }

package/src/properties.ts

@@ -82,7 +82,8 @@ export class PropertyManager {
    */
   mergeProperties(
     existing: ObsidianProperties,
-    updates: Partial<ObsidianProperties>
+    updates: Partial<ObsidianProperties>,
+    replace: boolean = false
   ): ObsidianProperties {
     const merged = { ...existing };
 
@@ -92,11 +93,11 @@ export class PropertyManager {
 
       const currentValue = merged[key as keyof ObsidianProperties];
 
-      // Special handling for arrays - merge rather than replace
+      // Handle arrays based on replace flag
       if (Array.isArray(value) && Array.isArray(currentValue)) {
-        merged[key as keyof ObsidianProperties] = [
-          ...new Set([...currentValue, ...value])
-        ] as any;
+        merged[key as keyof ObsidianProperties] = replace ?
+          value :
+          [...new Set([...currentValue, ...value])] as any;
       }
       // Special handling for custom object - deep merge
       else if (key === 'custom' && typeof value === 'object' && value !== null) {
@@ -144,7 +145,8 @@ export class PropertyManager {
    */
   async updateProperties(
     filepath: string,
-    newProperties: Partial<ObsidianProperties>
+    newProperties: Partial<ObsidianProperties>,
+    replace: boolean = false
   ): Promise<PropertyManagerResult> {
     try {
       // Validate new properties
@@ -162,7 +164,7 @@ export class PropertyManager {
       const existingProperties = this.parseProperties(content);
 
       // Merge properties
-      const mergedProperties = this.mergeProperties(existingProperties, newProperties);
+      const mergedProperties = this.mergeProperties(existingProperties, newProperties, replace);
 
       // Generate new frontmatter
       const newFrontmatter = this.generateProperties(mergedProperties);

package/src/propertyTools.ts

@@ -16,6 +16,7 @@ interface GetPropertiesArgs {
 interface UpdatePropertiesArgs {
   filepath: string;
   properties: Partial<ObsidianProperties>;
+  replace?: boolean;
 }
 
 export class GetPropertiesToolHandler extends BaseToolHandler<GetPropertiesArgs> {
@@ -79,7 +80,7 @@ export class UpdatePropertiesToolHandler extends BaseToolHandler<UpdatePropertie
   getToolDescription(): Tool {
     return {
       name: this.name,
-      description: "Update properties in an Obsidian note's YAML frontmatter. Intelligently merges arrays (tags, type, status), handles custom fields, and automatically manages timestamps (created by Obsidian, modified by MCP server). Existing properties not included in the update are preserved.",
+      description: "Update properties in an Obsidian note's YAML frontmatter. Intelligently merges arrays (tags, type, status), handles custom fields, and automatically manages timestamps. Valid property types:\n- type: Any string value\n- status: ['draft', 'in-progress', 'review', 'complete']\n- tags: Array of strings starting with '#'\n- Other fields: title, author, version, platform, repository (URI), dependencies, sources, urls (URI), papers, custom (object)",
       examples: [
         {
           description: "Update basic metadata",
@@ -93,14 +94,14 @@ export class UpdatePropertiesToolHandler extends BaseToolHandler<UpdatePropertie
           }
         },
         {
-          description: "Update tags and status",
+          description: "Update tags and status with replace",
           args: {
             filepath: "docs/feature.md",
             properties: {
               tags: ["#feature", "#in-development", "#high-priority"],
-              status: ["in-progress"],
-              version: "2.0.0"
-            }
+              status: ["in-progress"]
+            },
+            replace: true
           }
         },
         {
@@ -131,23 +132,9 @@ export class UpdatePropertiesToolHandler extends BaseToolHandler<UpdatePropertie
             properties: {
               title: { type: "string" },
               author: { type: "string" },
-              // Note: created and modified timestamps are managed automatically
               type: {
                 type: "array",
-                items: {
-                  type: "string",
-                  enum: [
-                    "concept",
-                    "architecture",
-                    "specification",
-                    "protocol",
-                    "api",
-                    "research",
-                    "implementation",
-                    "guide",
-                    "reference"
-                  ]
-                }
+                items: { type: "string" }
               },
               tags: {
                 type: "array",
@@ -185,6 +172,10 @@ export class UpdatePropertiesToolHandler extends BaseToolHandler<UpdatePropertie
               }
             },
             additionalProperties: false
+          },
+          replace: {
+            type: "boolean",
+            description: "If true, arrays will be replaced instead of merged"
           }
         },
         required: ["filepath", "properties"]
@@ -196,7 +187,8 @@ export class UpdatePropertiesToolHandler extends BaseToolHandler<UpdatePropertie
     try {
       const result = await this.propertyManager.updateProperties(
         args.filepath,
-        args.properties
+        args.properties,
+        args.replace
       );
       return this.createResponse(result);
     } catch (error) {

package/src/propertyTypes.ts

@@ -1,17 +1,8 @@
 import { z } from "zod";
 
 // Define validation schemas
-export const PropertyTypeEnum = z.enum([
-  "concept",
-  "architecture",
-  "specification",
-  "protocol",
-  "api",
-  "research",
-  "implementation",
-  "guide",
-  "reference"
-]);
+// Allow any string for type to be more flexible
+export const PropertyType = z.string();
 
 export const StatusEnum = z.enum([
   "draft",
@@ -29,7 +20,7 @@ export const ObsidianPropertiesSchema = z.object({
   author: z.string().optional(),
 
   // Classification
-  type: z.array(PropertyTypeEnum).optional(),
+  type: z.array(PropertyType).optional(),
 
   // Organization
   tags: z.array(z.string().startsWith("#")).optional(),
@@ -57,7 +48,7 @@ export const PropertyUpdateSchema = z.object({
   author: z.string().optional(),
 
   // Classification
-  type: z.array(PropertyTypeEnum).optional(),
+  type: z.array(PropertyType).optional(),
 
   // Organization
   tags: z.array(z.string().startsWith("#")).optional(),
@@ -85,6 +76,7 @@ export interface PropertyOperation {
   operation: 'get' | 'update' | 'patch';
   filepath: string;
   properties?: Partial<ObsidianProperties>;
+  replace?: boolean; // Add replace flag
 }
 
 export interface ValidationResult {