obsidian-mcp-server 1.2.2 → 1.2.4

package/README.md

@@ -2,7 +2,7 @@
 
 [![TypeScript](https://img.shields.io/badge/TypeScript-5.3-blue.svg)](https://www.typescriptlang.org/)
 [![Model Context Protocol](https://img.shields.io/badge/MCP-1.4.0-green.svg)](https://modelcontextprotocol.io/)
-[![Version](https://img.shields.io/badge/Version-1.2.2-blue.svg)]()
+[![Version](https://img.shields.io/badge/Version-1.2.3-blue.svg)]()
 [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
 [![Status](https://img.shields.io/badge/Status-Stable-blue.svg)]()
 [![GitHub](https://img.shields.io/github/stars/cyanheads/obsidian-mcp-server?style=social)](https://github.com/cyanheads/obsidian-mcp-server)
@@ -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,14 @@ export class ObsidianClient {
     config;
     constructor(config) {
         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
         this.config = {
             ...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
         };
@@ -88,11 +88,37 @@ 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
+        }
+    }
+    getErrorCode(status) {
+        // 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
         }
     }
     async safeRequest(operation) {
@@ -104,11 +130,20 @@ export class ObsidianClient {
                 const axiosError = error;
                 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);
+            }
+            // For non-Axios errors, use a generic server error code
+            if (error instanceof Error) {
+                throw new ObsidianError(error.message, 50000, error);
             }
-            throw error;
+            throw new ObsidianError("Unknown error occurred", 50000, error);
         }
     }
     async listFilesInVault() {
@@ -141,11 +176,8 @@ export class ObsidianClient {
         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;
         });
@@ -153,7 +185,7 @@ export class ObsidianClient {
     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); // 40003 = Invalid content
         }
         return this.safeRequest(async () => {
             const requestId = crypto.randomUUID();
@@ -168,7 +200,7 @@ 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); // 40003 = Invalid content
         }
         return this.safeRequest(async () => {
             const requestId = crypto.randomUUID();
@@ -184,14 +216,151 @@ export class ObsidianClient {
         return this.safeRequest(async () => {
             const requestId = crypto.randomUUID();
             console.debug(`[${requestId}] Performing complex search with query:`, JSON.stringify(query));
+            // 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;
+            }
+            return response.data;
+        });
+    }
+    async getStatus() {
+        return this.safeRequest(async () => {
+            const requestId = crypto.randomUUID();
+            console.debug(`[${requestId}] Getting server status`);
+            const response = await this.client.get("/");
+            return response.data;
+        });
+    }
+    async listCommands() {
+        return this.safeRequest(async () => {
+            const requestId = crypto.randomUUID();
+            console.debug(`[${requestId}] Listing available commands`);
+            const response = await this.client.get("/commands/");
+            return response.data.commands;
+        });
+    }
+    async executeCommand(commandId) {
+        return this.safeRequest(async () => {
+            const requestId = crypto.randomUUID();
+            console.debug(`[${requestId}] Executing command: ${commandId}`);
+            await this.client.post(`/commands/${commandId}/`);
+        });
+    }
+    async openFile(filepath, newLeaf = false) {
+        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() {
+        return this.safeRequest(async () => {
+            const requestId = crypto.randomUUID();
+            console.debug(`[${requestId}] Getting active file`);
+            const response = await this.client.get("/active/", {
+                headers: {
+                    "Accept": "application/vnd.olrapi.note+json"
+                }
+            });
+            return response.data;
+        });
+    }
+    async updateActiveFile(content) {
+        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() {
+        return this.safeRequest(async () => {
+            const requestId = crypto.randomUUID();
+            console.debug(`[${requestId}] Deleting active file`);
+            await this.client.delete("/active/");
+        });
+    }
+    async patchActiveFile(operation, targetType, target, content, options) {
+        return this.safeRequest(async () => {
+            const requestId = crypto.randomUUID();
+            console.debug(`[${requestId}] Patching active file: ${operation} ${targetType} ${target}`);
+            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 requestId = crypto.randomUUID();
+            console.debug(`[${requestId}] Getting ${period} note`);
+            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 () => {
+            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) {
+        return this.safeRequest(async () => {
+            const requestId = crypto.randomUUID();
+            console.debug(`[${requestId}] Deleting ${period} note`);
+            await this.client.delete(`/periodic/${period}/`);
+        });
+    }
+    async patchPeriodicNote(period, operation, targetType, target, content, options) {
+        return this.safeRequest(async () => {
+            const requestId = crypto.randomUUID();
+            console.debug(`[${requestId}] Patching ${period} note: ${operation} ${targetType} ${target}`);
+            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

@@ -1,5 +1,5 @@
 import { parse, stringify } from 'yaml';
-import { ObsidianPropertiesSchema } from './propertyTypes.js';
+import { ObsidianPropertiesSchema, PropertyUpdateSchema } from './propertyTypes.js';
 export class PropertyManager {
     client;
     constructor(client) {
@@ -51,7 +51,7 @@ export class PropertyManager {
      * Validate property values
      */
     validateProperties(properties) {
-        const result = ObsidianPropertiesSchema.safeParse(properties);
+        const result = PropertyUpdateSchema.safeParse(properties);
         if (result.success) {
             return { valid: true, errors: [] };
         }
@@ -63,17 +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)) {
-            if (value === undefined)
+            // 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) {
@@ -87,7 +88,7 @@ export class PropertyManager {
                 merged[key] = value;
             }
         }
-        // Always update modified date
+        // Always update modified date (this is the only place we set it)
         merged.modified = new Date().toISOString();
         return merged;
     }
@@ -115,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);
@@ -130,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 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",
@@ -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
                     }
                 },
                 {
@@ -111,25 +111,10 @@ export class UpdatePropertiesToolHandler extends BaseToolHandler {
                         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",
@@ -167,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"]
@@ -175,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,30 +1,44 @@
 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",
     "review",
     "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(),
     // Technical Metadata

package/build/resources.js

@@ -0,0 +1,69 @@
+export class TagResource {
+    client;
+    static TAG_PATTERN = /#[a-zA-Z0-9_-]+/g;
+    constructor(client) {
+        this.client = client;
+    }
+    getResourceDescription() {
+        return {
+            uri: "obsidian://tags",
+            name: "Obsidian Tags",
+            description: "List of all tags used across the Obsidian vault with their usage counts",
+            mimeType: "application/json"
+        };
+    }
+    async getContent() {
+        try {
+            // Search for files containing #
+            const query = {
+                "contains": [{ "var": "content" }, "#"]
+            };
+            const results = await this.client.searchJson(query);
+            // Process results to extract tags
+            const tagMap = new Map();
+            let totalOccurrences = 0;
+            let scannedFiles = 0;
+            results.forEach((result) => {
+                scannedFiles++;
+                if ('matches' in result) {
+                    result.matches.forEach((match) => {
+                        const tags = match.context.match(TagResource.TAG_PATTERN);
+                        if (tags) {
+                            tags.forEach((tag) => {
+                                if (!tagMap.has(tag)) {
+                                    tagMap.set(tag, new Set());
+                                }
+                                tagMap.get(tag).add(result.filename);
+                                totalOccurrences++;
+                            });
+                        }
+                    });
+                }
+            });
+            // Convert to sorted response format
+            const response = {
+                tags: Array.from(tagMap.entries())
+                    .map(([name, files]) => ({
+                    name,
+                    count: files.size,
+                    files: Array.from(files).sort()
+                }))
+                    .sort((a, b) => b.count - a.count || a.name.localeCompare(b.name)),
+                metadata: {
+                    totalOccurrences,
+                    uniqueTags: tagMap.size,
+                    scannedFiles
+                }
+            };
+            return [{
+                    type: "text",
+                    text: JSON.stringify(response, null, 2)
+                }];
+        }
+        catch (error) {
+            console.error("Failed to fetch tags:", error);
+            throw error;
+        }
+    }
+}
+//# sourceMappingURL=resources.js.map