obsidian-mcp-server 1.2.2 → 1.2.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "obsidian-mcp-server",
-  "version": "1.2.2",
+  "version": "1.2.4",
   "description": "Model Context Protocol server for Obsidian integration with token-aware response handling",
   "main": "build/index.js",
   "type": "module",
@@ -18,7 +18,7 @@
     "format": "prettier --write \"src/**/*.ts\""
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.4.0",
+    "@modelcontextprotocol/sdk": "^1.4.1",
     "axios": "^1.7.9",
     "dotenv": "^16.4.7",
     "tiktoken": "^1.0.18",
@@ -29,7 +29,7 @@
     "@types/node": "^22.10.10",
     "@typescript-eslint/eslint-plugin": "^8.21.0",
     "@typescript-eslint/parser": "^8.21.0",
-    "eslint": "^9.18.0",
+    "eslint": "^9.19.0",
     "eslint-config-prettier": "^10.0.1",
     "eslint-plugin-prettier": "^5.2.3",
     "prettier": "^3.4.2",

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,7 +41,7 @@ export class ObsidianClient {
 
   constructor(config: ObsidianConfig) {
     if (!config.apiKey) {
-      throw new ObsidianError("API key is required", 401);
+      throw new ObsidianError("API key is required", 40100); // 40100 = Unauthorized
     }
 
     // Combine defaults with provided config
@@ -34,7 +49,7 @@ export class ObsidianClient {
       ...DEFAULT_OBSIDIAN_CONFIG,
       verifySSL: config.verifySSL ?? process.env.NODE_ENV === 'production', // Enable SSL verification in production by default
       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
     };
@@ -106,12 +121,39 @@ 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); // 40001 = Path traversal error
     }
     
     // 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); // 40002 = Invalid path format
+    }
+  }
+
+  private getErrorCode(status: number): number {
+    // Convert HTTP status codes to 5-digit error codes
+    switch (status) {
+      // Client errors (400-499)
+      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
+      
+      // Server errors (500-599)
+      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 cases
+      default:
+        if (status >= 400 && status < 500) return 40000 + (status - 400) * 100;
+        if (status >= 500 && status < 600) return 50000 + (status - 500) * 100;
+        return 50000; // Default to internal server error
     }
   }
 
@@ -120,14 +162,28 @@ 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;
-        const message = errorData?.message ?? axiosError.message ?? "Unknown error";
-        throw new ObsidianError(message, code, errorData);
+        
+        // If the API returns a proper 5-digit error code, use it
+        // Otherwise, convert HTTP status to 5-digit code
+        const errorCode = errorData?.errorCode ??
+          this.getErrorCode(response?.status ?? 500);
+        
+        const message = errorData?.message ??
+          axiosError.message ??
+          "Unknown error";
+        
+        throw new ObsidianError(message, errorCode, errorData);
       }
-      throw error;
+      
+      // For non-Axios errors, use a generic server error code
+      if (error instanceof Error) {
+        throw new ObsidianError(error.message, 50000, error);
+      }
+      
+      throw new ObsidianError("Unknown error occurred", 50000, error);
     }
   }
 
@@ -160,16 +216,17 @@ export class ObsidianClient {
     });
   }
 
-  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,7 +234,7 @@ 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); // 40003 = Invalid content
     }
     return this.safeRequest(async () => {
       const requestId = crypto.randomUUID();
@@ -197,7 +254,7 @@ 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); // 40003 = Invalid content
     }
 
     return this.safeRequest(async () => {
@@ -215,21 +272,187 @@ 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[]>(
+      
+      // Check if this is a tag-based search
+      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"
           }
         }
       );
+
+      if (isTagSearch) {
+        return response.data as SimpleSearchResult[];
+      }
+      return response.data as SearchResult[];
+    });
+  }
+
+  async getStatus(): Promise<ObsidianStatus> {
+    return this.safeRequest(async () => {
+      const requestId = crypto.randomUUID();
+      console.debug(`[${requestId}] Getting server status`);
+      const response = await this.client.get<ObsidianStatus>("/");
       return response.data;
     });
   }
+
+  async listCommands(): Promise<ObsidianCommand[]> {
+    return this.safeRequest(async () => {
+      const requestId = crypto.randomUUID();
+      console.debug(`[${requestId}] Listing available commands`);
+      const response = await this.client.get<{commands: ObsidianCommand[]}>("/commands/");
+      return response.data.commands;
+    });
+  }
+
+  async executeCommand(commandId: string): Promise<void> {
+    return this.safeRequest(async () => {
+      const requestId = crypto.randomUUID();
+      console.debug(`[${requestId}] Executing command: ${commandId}`);
+      await this.client.post(`/commands/${commandId}/`);
+    });
+  }
+
+  async openFile(filepath: string, newLeaf: boolean = false): Promise<void> {
+    this.validateFilePath(filepath);
+    return this.safeRequest(async () => {
+      const requestId = crypto.randomUUID();
+      console.debug(`[${requestId}] Opening file: ${filepath}`);
+      await this.client.post(`/open/${filepath}`, null, {
+        params: { newLeaf }
+      });
+    });
+  }
+
+  async getActiveFile(): Promise<NoteJson> {
+    return this.safeRequest(async () => {
+      const requestId = crypto.randomUUID();
+      console.debug(`[${requestId}] Getting active file`);
+      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 () => {
+      const requestId = crypto.randomUUID();
+      console.debug(`[${requestId}] Updating active file`);
+      await this.client.put("/active/", content, {
+        headers: {
+          "Content-Type": "text/markdown"
+        }
+      });
+    });
+  }
+
+  async deleteActiveFile(): Promise<void> {
+    return this.safeRequest(async () => {
+      const requestId = crypto.randomUUID();
+      console.debug(`[${requestId}] Deleting active file`);
+      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 requestId = crypto.randomUUID();
+      console.debug(`[${requestId}] Patching active file: ${operation} ${targetType} ${target}`);
+      
+      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 requestId = crypto.randomUUID();
+      console.debug(`[${requestId}] Getting ${period} note`);
+      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 () => {
+      const requestId = crypto.randomUUID();
+      console.debug(`[${requestId}] Updating ${period} note`);
+      await this.client.put(`/periodic/${period}/`, content, {
+        headers: {
+          "Content-Type": "text/markdown"
+        }
+      });
+    });
+  }
+
+  async deletePeriodicNote(period: PeriodType["type"]): Promise<void> {
+    return this.safeRequest(async () => {
+      const requestId = crypto.randomUUID();
+      console.debug(`[${requestId}] Deleting ${period} note`);
+      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 requestId = crypto.randomUUID();
+      console.debug(`[${requestId}] Patching ${period} note: ${operation} ${targetType} ${target}`);
+      
+      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

@@ -1,10 +1,11 @@
 import { parse, stringify } from 'yaml';
 import { ObsidianClient } from './obsidian.js';
-import { 
-  ObsidianProperties, 
-  ObsidianPropertiesSchema, 
+import {
+  ObsidianProperties,
+  ObsidianPropertiesSchema,
+  PropertyUpdateSchema,
   PropertyManagerResult,
-  ValidationResult 
+  ValidationResult
 } from './propertyTypes.js';
 
 export class PropertyManager {
@@ -62,7 +63,7 @@ export class PropertyManager {
    * Validate property values
    */
   validateProperties(properties: Partial<ObsidianProperties>): ValidationResult {
-    const result = ObsidianPropertiesSchema.safeParse(properties);
+    const result = PropertyUpdateSchema.safeParse(properties);
     
     if (result.success) {
       return { valid: true, errors: [] };
@@ -70,7 +71,7 @@ export class PropertyManager {
 
     return {
       valid: false,
-      errors: result.error.errors.map(err => 
+      errors: result.error.errors.map(err =>
         `${err.path.join('.')}: ${err.message}`
       )
     };
@@ -81,20 +82,22 @@ export class PropertyManager {
    */
   mergeProperties(
     existing: ObsidianProperties,
-    updates: Partial<ObsidianProperties>
+    updates: Partial<ObsidianProperties>,
+    replace: boolean = false
   ): ObsidianProperties {
     const merged = { ...existing };
 
     for (const [key, value] of Object.entries(updates)) {
-      if (value === undefined) continue;
+      // Skip undefined values and timestamp fields
+      if (value === undefined || key === 'created' || key === 'modified') continue;
 
       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) {
@@ -109,7 +112,7 @@ export class PropertyManager {
       }
     }
 
-    // Always update modified date
+    // Always update modified date (this is the only place we set it)
     merged.modified = new Date().toISOString();
 
     return merged;
@@ -142,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
@@ -160,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 updates the modified timestamp. 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
           }
         },
         {
@@ -130,25 +131,10 @@ export class UpdatePropertiesToolHandler extends BaseToolHandler<UpdatePropertie
             description: "Properties to update",
             properties: {
               title: { type: "string" },
-              created: { type: "string", format: "date-time" },
-              modified: { type: "string", format: "date-time" },
               author: { type: "string" },
               type: {
                 type: "array",
-                items: {
-                  type: "string",
-                  enum: [
-                    "concept",
-                    "architecture",
-                    "specification",
-                    "protocol",
-                    "api",
-                    "research",
-                    "implementation",
-                    "guide",
-                    "reference"
-                  ]
-                }
+                items: { type: "string" }
               },
               tags: {
                 type: "array",
@@ -186,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"]
@@ -197,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",
@@ -20,15 +11,44 @@ export const StatusEnum = z.enum([
   "complete"
 ]);
 
+// Schema for reading properties (includes timestamps)
 export const ObsidianPropertiesSchema = z.object({
+  // Basic Metadata
+  // Note: Timestamps are managed automatically
+  title: z.string().optional(),
+  modified: z.string().datetime().optional(), // Read-only, managed by MCP server
+  author: z.string().optional(),
+
+  // Classification
+  type: z.array(PropertyType).optional(),
+
+  // Organization
+  tags: z.array(z.string().startsWith("#")).optional(),
+
+  // Technical Metadata
+  status: z.array(StatusEnum).optional(),
+  version: z.string().optional(),
+  platform: z.string().optional(),
+  repository: z.string().url().optional(),
+  dependencies: z.array(z.string()).optional(),
+
+  // References
+  sources: z.array(z.string()).optional(),
+  urls: z.array(z.string().url()).optional(),
+  papers: z.array(z.string()).optional(),
+
+  // Custom Fields
+  custom: z.record(z.unknown()).optional()
+});
+
+// Schema for validating property updates (excludes timestamps)
+export const PropertyUpdateSchema = z.object({
   // Basic Metadata
   title: z.string().optional(),
-  created: z.string().datetime().optional(),
-  modified: z.string().datetime().optional(),
   author: z.string().optional(),
 
   // Classification
-  type: z.array(PropertyTypeEnum).optional(),
+  type: z.array(PropertyType).optional(),
 
   // Organization
   tags: z.array(z.string().startsWith("#")).optional(),
@@ -50,11 +70,13 @@ export const ObsidianPropertiesSchema = z.object({
 });
 
 export type ObsidianProperties = z.infer<typeof ObsidianPropertiesSchema>;
+export type PropertyUpdate = z.infer<typeof PropertyUpdateSchema>;
 
 export interface PropertyOperation {
   operation: 'get' | 'update' | 'patch';
   filepath: string;
   properties?: Partial<ObsidianProperties>;
+  replace?: boolean; // Add replace flag
 }
 
 export interface ValidationResult {