obsidian-mcp-server 1.2.3 → 1.2.5

package/README.md

@@ -20,8 +20,9 @@ Requires the Local REST API plugin in Obsidian.
 - Resource monitoring and cleanup
 
 ### Search System
-- Full-text and JsonLogic search with context control
-- Optimized query processing with token limits
+- Full-text search with configurable context
+- Advanced JsonLogic queries for files, tags, and metadata
+- Support for glob patterns and frontmatter fields
 
 ### Property Management
 - YAML frontmatter parsing and intelligent merging
@@ -75,6 +76,28 @@ Environment configuration:
 - `MAX_TOKENS`: Maximum tokens per response (default: 20000)
 - `TOOL_TIMEOUT_MS`: Tool execution timeout (default: 60000)
 
+Additional configuration options:
+```typescript
+interface ObsidianConfig {
+  apiKey: string;           // Required: API key for authentication
+  verifySSL?: boolean;      // Optional: Enable SSL verification
+  timeout?: number;         // Optional: Request timeout in ms
+  maxContentLength?: number;// Optional: Max response content length
+  maxBodyLength?: number;   // Optional: Max request body length
+}
+
+interface RateLimitConfig {
+  windowMs: number;         // Time window for rate limiting
+  maxRequests: number;      // Max requests per window
+}
+```
+
+Error Handling:
+- All errors include a 5-digit error code
+- HTTP status codes are automatically converted (e.g., 404 -> 40400)
+- Default server error code: 50000
+- Detailed error messages include original error stack traces in development
+
 ## Tools
 
 ### File Management
@@ -103,7 +126,19 @@ obsidian_find_in_file: {
 
 // Advanced search with JsonLogic
 obsidian_complex_search: {
-  query: JsonLogicQuery  // Example: {"glob": ["*.md", {"var": "path"}]}
+  query: JsonLogicQuery
+  // Examples:
+  // Find by tag:
+  // {"in": ["#mytag", {"var": "frontmatter.tags"}]}
+  //
+  // Find markdown files in a directory:
+  // {"glob": ["docs/*.md", {"var": "path"}]}
+  //
+  // Combine conditions:
+  // {"and": [
+  //   {"glob": ["*.md", {"var": "path"}]},
+  //   {"in": ["#mytag", {"var": "frontmatter.tags"}]}
+  // ]}
 }
 ```
 
@@ -122,8 +157,41 @@ obsidian_patch_content: {
 }
 ```
 
+### Command Management
+```typescript
+// List available commands
+obsidian_list_commands: {}
+
+// Execute a command
+obsidian_execute_command: {
+  commandId: string  // Command ID to execute
+}
+```
+
+### File Navigation
+```typescript
+// Open a file in Obsidian
+obsidian_open_file: {
+  filepath: string,   // Path relative to vault root
+  newLeaf?: boolean  // Open in new leaf (default: false)
+}
+
+// Get active file content
+obsidian_get_active_file: {}
+
+// Get periodic note content
+obsidian_get_periodic_note: {
+  period: "daily" | "weekly" | "monthly" | "quarterly" | "yearly"
+}
+```
+
 ### Property Management
 ```typescript
+// Get all tags in vault or directory
+obsidian_get_tags: {
+  path?: string  // Optional: limit to specific directory
+}
+
 // Get note properties
 obsidian_get_properties: {
   filepath: string  // Path relative to vault root
@@ -160,8 +228,10 @@ obsidian_update_properties: {
 - Handle errors and monitor performance
 
 ### Search Implementation
-- Optimize queries and control context size
-- Handle large results within token limits
+- Use appropriate search tool for the task:
+  - obsidian_find_in_file for text search
+  - obsidian_complex_search for metadata/tag filtering
+- Keep context size reasonable (default: 10 chars)
 
 ### Property Management
 - Use appropriate types and validate updates

package/build/obsidian.js

@@ -23,14 +23,19 @@ export class ObsidianClient {
     config;
     constructor(config) {
         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
         };
@@ -61,7 +66,9 @@ export class ObsidianClient {
             decompress: true
         };
         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.");
+            console.warn("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.");
         }
         this.client = axios.create(axiosConfig);
     }
@@ -88,11 +95,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);
+        }
+    }
+    getErrorCode(status) {
+        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;
         }
     }
     async safeRequest(operation) {
@@ -104,17 +133,45 @@ export class ObsidianClient {
                 const axiosError = error;
                 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() {
         return this.safeRequest(async () => {
-            const requestId = crypto.randomUUID();
-            console.debug(`[${requestId}] Listing vault files`);
             const response = await this.client.get("/vault/");
             return response.data.files;
         });
@@ -122,8 +179,6 @@ export class ObsidianClient {
     async listFilesInDir(dirpath) {
         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(`/vault/${dirpath}/`);
             return response.data.files;
         });
@@ -131,33 +186,22 @@ export class ObsidianClient {
     async getFileContents(filepath) {
         this.validateFilePath(filepath);
         return this.safeRequest(async () => {
-            const requestId = crypto.randomUUID();
-            console.debug(`[${requestId}] Getting file contents: ${filepath}`);
             const response = await this.client.get(`/vault/${filepath}`);
             return response.data;
         });
     }
     async search(query, contextLength = 100) {
         return this.safeRequest(async () => {
-            const requestId = crypto.randomUUID();
-            console.debug(`[${requestId}] Performing simple search: ${query}`);
-            const response = await this.client.post("/search/simple/", undefined, {
-                params: {
-                    query,
-                    contextLength
-                }
-            });
+            const response = await this.client.post("/search/simple/", null, { params: { query, contextLength } });
             return response.data;
         });
     }
     async appendContent(filepath, content) {
         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, {
                 headers: {
                     "Content-Type": "text/markdown"
@@ -168,11 +212,9 @@ export class ObsidianClient {
     async updateContent(filepath, content) {
         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, {
                 headers: {
                     "Content-Type": "text/markdown"
@@ -182,16 +224,123 @@ export class ObsidianClient {
     }
     async searchJson(query) {
         return this.safeRequest(async () => {
-            const requestId = crypto.randomUUID();
-            console.debug(`[${requestId}] Performing complex search with query:`, JSON.stringify(query));
+            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 : response.data;
+        });
+    }
+    async getStatus() {
+        return this.safeRequest(async () => {
+            const response = await this.client.get("/");
+            return response.data;
+        });
+    }
+    async listCommands() {
+        return this.safeRequest(async () => {
+            const response = await this.client.get("/commands/");
+            return response.data.commands;
+        });
+    }
+    async executeCommand(commandId) {
+        return this.safeRequest(async () => {
+            await this.client.post(`/commands/${commandId}/`);
+        });
+    }
+    async openFile(filepath, newLeaf = false) {
+        this.validateFilePath(filepath);
+        return this.safeRequest(async () => {
+            await this.client.post(`/open/${filepath}`, null, {
+                params: { newLeaf }
+            });
+        });
+    }
+    async getActiveFile() {
+        return this.safeRequest(async () => {
+            const response = await this.client.get("/active/", {
+                headers: {
+                    "Accept": "application/vnd.olrapi.note+json"
+                }
+            });
+            return response.data;
+        });
+    }
+    async updateActiveFile(content) {
+        return this.safeRequest(async () => {
+            await this.client.put("/active/", content, {
+                headers: {
+                    "Content-Type": "text/markdown"
+                }
+            });
+        });
+    }
+    async deleteActiveFile() {
+        return this.safeRequest(async () => {
+            await this.client.delete("/active/");
+        });
+    }
+    async patchActiveFile(operation, targetType, target, content, options) {
+        return this.safeRequest(async () => {
+            const headers = {
+                "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) {
+        return this.safeRequest(async () => {
+            const response = await this.client.get(`/periodic/${period}/`, {
+                headers: {
+                    "Accept": "application/vnd.olrapi.note+json"
                 }
             });
             return response.data;
         });
     }
+    async updatePeriodicNote(period, content) {
+        return this.safeRequest(async () => {
+            await this.client.put(`/periodic/${period}/`, content, {
+                headers: {
+                    "Content-Type": "text/markdown"
+                }
+            });
+        });
+    }
+    async deletePeriodicNote(period) {
+        return this.safeRequest(async () => {
+            await this.client.delete(`/periodic/${period}/`);
+        });
+    }
+    async patchPeriodicNote(period, operation, targetType, target, content, options) {
+        return this.safeRequest(async () => {
+            const headers = {
+                "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 });
+        });
+    }
 }
 //# sourceMappingURL=obsidian.js.map

package/build/properties.js

@@ -63,18 +63,18 @@ export class PropertyManager {
     /**
      * Merge new properties with existing ones
      */
-    mergeProperties(existing, updates) {
+    mergeProperties(existing, updates, replace = false) {
         const merged = { ...existing };
         for (const [key, value] of Object.entries(updates)) {
             // Skip undefined values and timestamp fields
             if (value === undefined || key === 'created' || key === 'modified')
                 continue;
             const currentValue = merged[key];
-            // Special handling for arrays - merge rather than replace
+            // Handle arrays based on replace flag
             if (Array.isArray(value) && Array.isArray(currentValue)) {
-                merged[key] = [
-                    ...new Set([...currentValue, ...value])
-                ];
+                merged[key] = replace ?
+                    value :
+                    [...new Set([...currentValue, ...value])];
             }
             // Special handling for custom object - deep merge
             else if (key === 'custom' && typeof value === 'object' && value !== null) {
@@ -116,7 +116,7 @@ export class PropertyManager {
     /**
      * Update properties of a note
      */
-    async updateProperties(filepath, newProperties) {
+    async updateProperties(filepath, newProperties, replace = false) {
         try {
             // Validate new properties
             const validation = this.validateProperties(newProperties);
@@ -131,7 +131,7 @@ export class PropertyManager {
             const content = await this.client.getFileContents(filepath);
             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);
             // Replace existing frontmatter or prepend to file

package/build/propertyTools.js

@@ -60,7 +60,7 @@ export class UpdatePropertiesToolHandler extends BaseToolHandler {
     getToolDescription() {
         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",
@@ -74,14 +74,14 @@ export class UpdatePropertiesToolHandler extends BaseToolHandler {
                     }
                 },
                 {
-                    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
                     }
                 },
                 {
@@ -112,23 +112,9 @@ export class UpdatePropertiesToolHandler extends BaseToolHandler {
                         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",
@@ -166,6 +152,10 @@ export class UpdatePropertiesToolHandler extends BaseToolHandler {
                             }
                         },
                         additionalProperties: false
+                    },
+                    replace: {
+                        type: "boolean",
+                        description: "If true, arrays will be replaced instead of merged"
                     }
                 },
                 required: ["filepath", "properties"]
@@ -174,7 +164,7 @@ export class UpdatePropertiesToolHandler extends BaseToolHandler {
     }
     async runTool(args) {
         try {
-            const result = await this.propertyManager.updateProperties(args.filepath, args.properties);
+            const result = await this.propertyManager.updateProperties(args.filepath, args.properties, args.replace);
             return this.createResponse(result);
         }
         catch (error) {

package/build/propertyTypes.js

@@ -1,16 +1,7 @@
 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",
     "in-progress",
@@ -25,7 +16,7 @@ export const ObsidianPropertiesSchema = z.object({
     modified: z.string().datetime().optional(), // Read-only, managed by MCP server
     author: z.string().optional(),
     // Classification
-    type: z.array(PropertyTypeEnum).optional(),
+    type: z.array(PropertyType).optional(),
     // Organization
     tags: z.array(z.string().startsWith("#")).optional(),
     // Technical Metadata
@@ -47,7 +38,7 @@ export const PropertyUpdateSchema = z.object({
     title: z.string().optional(),
     author: z.string().optional(),
     // Classification
-    type: z.array(PropertyTypeEnum).optional(),
+    type: z.array(PropertyType).optional(),
     // Organization
     tags: z.array(z.string().startsWith("#")).optional(),
     // Technical Metadata