obsidian-mcp-server 1.4.0 → 1.5.0

package/LICENSE

@@ -1,7 +1,8 @@
 
                                  Apache License
                            Version 2.0, January 2004
-                        http://www.apache.org/licenses/
+                        Copyright 2025 Casey Hand @cyanheads
+                           http://www.apache.org/licenses/
 
    TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
 

package/README.md

@@ -1,10 +1,10 @@
 # Obsidian MCP Server
 
-[![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.3-blue.svg)]()
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.7-blue.svg)](https://www.typescriptlang.org/)
+[![Model Context Protocol](https://img.shields.io/badge/MCP-1.7.0-green.svg)](https://modelcontextprotocol.io/)
+[![Version](https://img.shields.io/badge/Version-1.5.0-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)]()
+[![Status](https://img.shields.io/badge/Status-Stable-green.svg)]()
 [![GitHub](https://img.shields.io/github/stars/cyanheads/obsidian-mcp-server?style=social)](https://github.com/cyanheads/obsidian-mcp-server)
 
 A Model Context Protocol server designed for LLMs to interact with Obsidian vaults. Built with TypeScript and featuring secure API communication, efficient file operations, and comprehensive search capabilities, it enables AI assistants to seamlessly manage knowledge bases through a clean, flexible tool interface.
@@ -16,28 +16,36 @@ Requires the Local REST API plugin in Obsidian.
 ## Features
 
 ### File Operations
+
 - Atomic file/directory operations with validation
 - Resource monitoring and cleanup
+- Error handling and graceful failure
 
 ### Search System
+
 - 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
 - Automatic timestamps (created by Obsidian, modified by server)
 - Custom field support
 
 ### Security & Performance
+
 - API key auth with rate limiting and SSL options
 - Resource monitoring and health checks
+- Graceful shutdown handling
 
 ## Installation
 
-1. Install Node.js (LTS recommended)
-2. Enable Local REST API plugin in Obsidian
-3. Clone and build:
+Note: Requires Node.js
+
+1. Enable Local REST API plugin in Obsidian
+2. Clone and build:
+
 ```bash
 git clone git@github.com:cyanheads/obsidian-mcp-server.git
 cd obsidian-mcp-server
@@ -46,6 +54,7 @@ npm run build
 ```
 
 Or install from npm:
+
 ```bash
 npm install obsidian-mcp-server
 ```
@@ -81,86 +90,70 @@ Add to your MCP client settings (e.g., `claude_desktop_config.json` or `cline_mc
 Environment Variables:
 
 Required:
+
 - `OBSIDIAN_API_KEY`: Your API key from Obsidian's Local REST API plugin settings
 
 Connection Settings:
-- `VERIFY_SSL`: Enable SSL certificate verification (default: false in development)
+
+- `VERIFY_SSL`: Enable SSL certificate verification (default: false) # This must be set to false for self-signed certificates. If you are running locally or don't understand what this means, this should be set to false.
 - `OBSIDIAN_PROTOCOL`: Protocol to use (default: "https")
 - `OBSIDIAN_HOST`: Host address (default: "127.0.0.1")
 - `OBSIDIAN_PORT`: Port number (default: 27124)
 
 Request Limits:
+
 - `REQUEST_TIMEOUT`: Request timeout in milliseconds (default: 5000)
 - `MAX_CONTENT_LENGTH`: Maximum response content length in bytes (default: 52428800 [50MB])
 - `MAX_BODY_LENGTH`: Maximum request body length in bytes (default: 52428800 [50MB])
 
 Rate Limiting:
+
 - `RATE_LIMIT_WINDOW_MS`: Rate limit window in milliseconds (default: 900000 [15 minutes])
 - `RATE_LIMIT_MAX_REQUESTS`: Maximum requests per window (default: 200)
 
 Tool Execution:
-- `TOOL_TIMEOUT_MS`: Tool execution timeout in milliseconds (default: 60000 [1 minute])
 
-SSL Certificate Setup:
-
-For Windows Users:
-1. Development Setup (Not Recommended for Production):
-   - Set `VERIFY_SSL` to "false"
-   - Set `OBSIDIAN_PROTOCOL` to "http"
-   - Enable "Non-encrypted (HTTP) Server" in Obsidian's Local REST API settings
+- `TOOL_TIMEOUT_MS`: Tool execution timeout in milliseconds (default: 60000 [1 minute])
 
-2. Production Setup (Recommended):
-   - Set `VERIFY_SSL` to "true"
-   - Get the certificate from Obsidian Settings > Local REST API > 'How to Access'
-   - Open Windows Certificate Manager (certmgr.msc)
-   - Navigate to "Trusted Root Certification Authorities" > "Certificates"
-   - Right-click > "All Tasks" > "Import" and select the certificate file
+## Project Structure
 
-For Other Systems:
-- macOS: Add certificate to Keychain Access
-- Linux: Add to ca-certificates
+The project follows a modular architecture with clear separation of concerns:
 
-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
+src/
+  ├── index.ts          # Main entry point
+  ├── mcp/              # MCP server implementation
+  ├── obsidian/         # Obsidian API client and types
+  ├── resources/        # MCP resource implementations
+  ├── tools/            # MCP tool implementations
+  │   ├── files/        # File operations tools
+  │   ├── search/       # Search tools
+  │   └── properties/   # Property management tools
+  └── utils/            # Shared utilities
+```
 
 ## Tools
 
 ### File Management
+
 ```typescript
 // List vault contents
-obsidian_list_files_in_vault: {}
+obsidian_list_files_in_vault: {
+}
 
 // List directory contents
 obsidian_list_files_in_dir: {
-  dirpath: string  // Path relative to vault root
+  dirpath: string; // Path relative to vault root
 }
 
 // Get file contents
 obsidian_get_file_contents: {
-  filepath: string  // Path relative to vault root
+  filepath: string; // Path relative to vault root
 }
 ```
 
 ### Search Operations
+
 ```typescript
 // Text search with context
 obsidian_find_in_file: {
@@ -184,9 +177,15 @@ obsidian_complex_search: {
   //   {"in": ["#mytag", {"var": "frontmatter.tags"}]}
   // ]}
 }
+
+// Get all tags in vault or directory
+obsidian_get_tags: {
+  path?: string  // Optional: limit to specific directory
+}
 ```
 
 ### Content Modification
+
 ```typescript
 // Append to file
 obsidian_append_content: {
@@ -201,41 +200,9 @@ 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
-}
 
+```typescript
 // Get note properties
 obsidian_get_properties: {
   filepath: string  // Path relative to vault root
@@ -248,8 +215,8 @@ obsidian_update_properties: {
     title?: string,
     author?: string,
     // Note: created/modified timestamps are managed automatically
-    type?: Array<"concept" | "architecture" | "specification" | 
-      "protocol" | "api" | "research" | "implementation" | 
+    type?: Array<"concept" | "architecture" | "specification" |
+      "protocol" | "api" | "research" | "implementation" |
       "guide" | "reference">,
     tags?: string[],  // Must start with #
     status?: Array<"draft" | "in-progress" | "review" | "complete">,
@@ -268,24 +235,36 @@ obsidian_update_properties: {
 ## Best Practices
 
 ### File Operations
+
 - Use atomic operations with validation
 - Handle errors and monitor performance
 
 ### Search Implementation
+
 - 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
 - Handle arrays and custom fields properly
 - Never set timestamps (managed automatically)
 
 ### Error Prevention
+
 - Validate inputs and handle errors gracefully
 - Monitor patterns and respect rate limits
 
+## Resources
+
+The MCP server exposes the following resources:
+
+```
+obsidian://tags  # List of all tags used across the vault
+```
+
 ## Contributing
 
 1. Fork the repository

package/build/mcp/handlers.js

@@ -5,10 +5,32 @@ import { ListToolsRequestSchema, CallToolRequestSchema, ListResourcesRequestSche
 import { ObsidianError } from "../utils/errors.js";
 import { validateToolArguments } from "../utils/validation.js";
 import { rateLimiter } from "../utils/rate-limiting.js";
-import { createLogger } from "../utils/logging.js";
-import { DEFAULT_TIMEOUT_CONFIG } from "./types.js";
+import { createLogger, ErrorCategoryType } from "../utils/logging.js";
+import { DEFAULT_TIMEOUT_CONFIG, McpErrorCode } from "./types.js";
 // Create a logger for request handlers
 const logger = createLogger('McpHandlers');
+/**
+ * Helper function to safely mask sensitive data
+ */
+function maskSensitiveData(data) {
+    if (!data)
+        return {};
+    const sensitiveFields = ['password', 'token', 'secret', 'key', 'auth', 'credential'];
+    const result = {};
+    for (const [key, value] of Object.entries(data)) {
+        const isSensitive = sensitiveFields.some(field => key.toLowerCase().includes(field.toLowerCase()));
+        if (isSensitive) {
+            result[key] = '********';
+        }
+        else if (value && typeof value === 'object' && !Array.isArray(value)) {
+            result[key] = maskSensitiveData(value);
+        }
+        else {
+            result[key] = value;
+        }
+    }
+    return result;
+}
 /**
  * Set up tool listing handler
  * @param server The MCP server instance
@@ -17,11 +39,27 @@ const logger = createLogger('McpHandlers');
 export function setupToolListingHandler(server, toolHandlers) {
     server.setRequestHandler(ListToolsRequestSchema, async () => {
         logger.debug('Handling ListToolsRequest');
-        const tools = [];
-        for (const handler of toolHandlers.values()) {
-            tools.push(handler.getToolDescription());
+        // Start performance timing
+        logger.startTimer('list_tools');
+        try {
+            const tools = [];
+            for (const handler of toolHandlers.values()) {
+                tools.push(handler.getToolDescription());
+            }
+            // Log success and timing information
+            const elapsedMs = logger.endTimer('list_tools', 'Listed tools');
+            logger.logOperationResult(true, 'list_tools', elapsedMs, {
+                toolCount: tools.length
+            });
+            return { tools };
+        }
+        catch (error) {
+            // Log failure with timing information
+            const elapsedMs = logger.endTimer('list_tools', 'Failed to list tools');
+            logger.logOperationResult(false, 'list_tools', elapsedMs);
+            logger.error('Failed to list available tools', error instanceof Error ? error : undefined);
+            throw error;
         }
-        return { tools };
     });
 }
 /**
@@ -32,26 +70,53 @@ export function setupToolListingHandler(server, toolHandlers) {
 export function setupToolCallingHandler(server, toolHandlers) {
     server.setRequestHandler(CallToolRequestSchema, async (request) => {
         const { name, arguments: args } = request.params;
-        logger.debug(`Handling CallToolRequest for tool: ${name}`);
+        const operationId = `call_tool_${name}_${Date.now()}`;
+        logger.debug(`Handling CallToolRequest for tool: ${name}`, {
+            toolName: name,
+            operationId
+        });
+        // Start performance timing
+        logger.startTimer(operationId);
+        // Handle unknown tool
         const handler = toolHandlers.get(name);
         if (!handler) {
-            logger.error(`Unknown tool requested: ${name}`);
-            throw new ObsidianError(`Unknown tool: ${name}`, 40400); // 40400 = Not found
+            const errorInfo = {
+                toolName: name,
+                errorCode: McpErrorCode.NOT_FOUND,
+                errorCategory: ErrorCategoryType.CATEGORY_VALIDATION
+            };
+            logger.error(`Unknown tool requested: ${name}`, errorInfo);
+            const elapsedMs = logger.endTimer(operationId);
+            logger.logOperationResult(false, 'call_tool', elapsedMs, errorInfo);
+            throw new ObsidianError(`Unknown tool: ${name}`, McpErrorCode.NOT_FOUND);
         }
         // Check rate limit
         try {
             rateLimiter.enforceRateLimit(name);
         }
         catch (error) {
-            // If rate limit is exceeded, log and rethrow the error
-            logger.warn(`Rate limit exceeded for tool: ${name}`);
-            throw error;
+            const errorInfo = {
+                toolName: name,
+                errorCode: McpErrorCode.RATE_LIMIT_EXCEEDED,
+                errorCategory: ErrorCategoryType.CATEGORY_SYSTEM
+            };
+            logger.warn(`Rate limit exceeded for tool: ${name}`, errorInfo);
+            const elapsedMs = logger.endTimer(operationId);
+            logger.logOperationResult(false, 'call_tool', elapsedMs, errorInfo);
+            throw new ObsidianError(`Rate limit exceeded for tool: ${name}`, McpErrorCode.RATE_LIMIT_EXCEEDED);
         }
         // Add timeout handling
         const timeoutMs = DEFAULT_TIMEOUT_CONFIG.toolExecutionMs;
         const timeoutPromise = new Promise((_, reject) => {
             setTimeout(() => {
-                reject(new ObsidianError(`Tool execution timed out after ${timeoutMs}ms`, 40800)); // 40800 = Request timeout
+                const errorInfo = {
+                    toolName: name,
+                    timeoutMs,
+                    errorCode: McpErrorCode.TIMEOUT,
+                    errorCategory: ErrorCategoryType.CATEGORY_SYSTEM
+                };
+                logger.error(`Tool execution timed out after ${timeoutMs}ms`, errorInfo);
+                reject(new ObsidianError(`Tool execution timed out after ${timeoutMs}ms`, McpErrorCode.TIMEOUT));
             }, timeoutMs);
         });
         try {
@@ -59,24 +124,48 @@ export function setupToolCallingHandler(server, toolHandlers) {
             const toolDescription = handler.getToolDescription();
             const validationResult = validateToolArguments(args, toolDescription.inputSchema);
             if (!validationResult.valid) {
-                logger.error(`Invalid tool arguments for ${name}:`, validationResult.errors);
-                throw new ObsidianError(`Invalid tool arguments: ${validationResult.errors.join(', ')}`, 40000 // 40000 = Bad request
-                );
+                const errorInfo = {
+                    toolName: name,
+                    validationErrors: validationResult.errors,
+                    providedArgs: maskSensitiveData(args),
+                    errorCode: McpErrorCode.BAD_REQUEST,
+                    errorCategory: ErrorCategoryType.CATEGORY_VALIDATION
+                };
+                logger.error(`Invalid tool arguments for ${name}:`, errorInfo);
+                const elapsedMs = logger.endTimer(operationId);
+                logger.logOperationResult(false, 'call_tool', elapsedMs, errorInfo);
+                throw new ObsidianError(`Invalid tool arguments: ${validationResult.errors.join(', ')}`, McpErrorCode.BAD_REQUEST);
             }
             // Log the tool execution
-            logger.info(`Executing tool: ${name}`);
+            logger.info(`Executing tool: ${name}`, {
+                toolName: name,
+                args: maskSensitiveData(args)
+            });
             // Race between tool execution and timeout
             const content = await Promise.race([
                 handler.runTool(args),
                 timeoutPromise
             ]);
-            logger.debug(`Tool execution completed successfully: ${name}`);
+            // Log successful execution
+            const elapsedMs = logger.endTimer(operationId);
+            logger.logOperationResult(true, 'call_tool', elapsedMs, {
+                toolName: name,
+                contentLength: content.reduce((sum, item) => {
+                    return sum + (item.type === 'text' ? item.text.length : 0);
+                }, 0)
+            });
             return { content };
         }
         catch (error) {
+            // Handle ObsidianError
             if (error instanceof ObsidianError) {
                 // Check if the operation actually succeeded despite the error
-                if (error.errorCode === 20400) { // 20400 = Success with no content
+                if (error.errorCode === McpErrorCode.SUCCESS_NO_CONTENT) {
+                    const elapsedMs = logger.endTimer(operationId);
+                    logger.logOperationResult(true, 'call_tool', elapsedMs, {
+                        toolName: name,
+                        status: 'success_no_content'
+                    });
                     return {
                         content: [{
                                 type: "text",
@@ -84,21 +173,31 @@ export function setupToolCallingHandler(server, toolHandlers) {
                             }]
                     };
                 }
+                // Log failure for other ObsidianErrors
+                const errorInfo = {
+                    toolName: name,
+                    errorMessage: error.message,
+                    errorCode: error.errorCode,
+                    errorCategory: ErrorCategoryType.CATEGORY_BUSINESS_LOGIC,
+                    details: error.details ? JSON.stringify(error.details) : undefined
+                };
+                const elapsedMs = logger.endTimer(operationId);
+                logger.logOperationResult(false, 'call_tool', elapsedMs, errorInfo);
                 throw error;
             }
-            // Enhanced error logging
-            logger.error("Tool execution error:", {
-                name: error instanceof Error ? error.name : 'Unknown',
-                message: error instanceof Error ? error.message : String(error),
-                stack: error instanceof Error ? error.stack : undefined,
-                toolName: name
-            });
-            if (error instanceof Error) {
-                throw new ObsidianError(`Tool '${name}' execution failed: ${error.message}`, 50000, // 50000 = Internal server error
-                { originalError: error.stack });
-            }
-            throw new ObsidianError("Tool execution failed with unknown error", 50000, // 50000 = Internal server error
-            { error });
+            // Enhanced error logging for other errors
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            const errorStack = error instanceof Error ? error.stack : undefined;
+            const errorInfo = {
+                toolName: name,
+                errorMessage,
+                errorStack,
+                errorCategory: ErrorCategoryType.CATEGORY_SYSTEM
+            };
+            logger.error("Tool execution error:", errorInfo);
+            const elapsedMs = logger.endTimer(operationId);
+            logger.logOperationResult(false, 'call_tool', elapsedMs, errorInfo);
+            throw new ObsidianError(`Tool '${name}' execution failed: ${errorMessage}`, McpErrorCode.INTERNAL_SERVER_ERROR, { originalError: errorMessage, stack: errorStack });
         }
     });
 }
@@ -110,9 +209,24 @@ export function setupToolCallingHandler(server, toolHandlers) {
 export function setupResourceListingHandler(server, resources) {
     server.setRequestHandler(ListResourcesRequestSchema, async () => {
         logger.debug('Handling ListResourcesRequest');
-        return {
-            resources: Object.values(resources).map(resource => resource.getResourceDescription())
-        };
+        // Start performance timing
+        logger.startTimer('list_resources');
+        try {
+            const resourceList = Object.values(resources).map(resource => resource.getResourceDescription());
+            // Log success with timing information
+            const elapsedMs = logger.endTimer('list_resources', 'Listed resources');
+            logger.logOperationResult(true, 'list_resources', elapsedMs, {
+                resourceCount: resourceList.length
+            });
+            return { resources: resourceList };
+        }
+        catch (error) {
+            // Log failure with timing information
+            const elapsedMs = logger.endTimer('list_resources', 'Failed to list resources');
+            logger.logOperationResult(false, 'list_resources', elapsedMs);
+            logger.error('Failed to list available resources', error instanceof Error ? error : undefined);
+            throw error;
+        }
     });
 }
 /**
@@ -123,16 +237,51 @@ export function setupResourceListingHandler(server, resources) {
 export function setupResourceReadingHandler(server, resources) {
     server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
         const uri = request.params.uri;
-        logger.debug(`Handling ReadResourceRequest for URI: ${uri}`);
+        const operationId = `read_resource_${Date.now()}`;
+        logger.debug(`Handling ReadResourceRequest for URI: ${uri}`, {
+            resourceUri: uri,
+            operationId
+        });
+        // Start performance timing
+        logger.startTimer(operationId);
         const resource = resources[uri];
-        if (resource) {
+        if (!resource) {
+            const errorInfo = {
+                resourceUri: uri,
+                errorCode: McpErrorCode.NOT_FOUND,
+                errorCategory: ErrorCategoryType.CATEGORY_DATA_ACCESS
+            };
+            logger.error(`Resource not found: ${uri}`, errorInfo);
+            const elapsedMs = logger.endTimer(operationId);
+            logger.logOperationResult(false, 'read_resource', elapsedMs, errorInfo);
+            throw new ObsidianError(`Resource not found: ${uri}`, McpErrorCode.NOT_FOUND);
+        }
+        try {
             logger.debug(`Found resource for URI: ${uri}`);
-            return {
-                contents: await resource.getContent()
+            const contents = await resource.getContent();
+            // Log success with timing information
+            const elapsedMs = logger.endTimer(operationId);
+            logger.logOperationResult(true, 'read_resource', elapsedMs, {
+                resourceUri: uri,
+                contentItems: contents.length
+            });
+            return { contents };
+        }
+        catch (error) {
+            // Log failure with timing information
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            const errorStack = error instanceof Error ? error.stack : undefined;
+            const errorInfo = {
+                resourceUri: uri,
+                errorMessage,
+                errorStack,
+                errorCategory: ErrorCategoryType.CATEGORY_DATA_ACCESS
             };
+            logger.error(`Error reading resource: ${uri}`, errorInfo);
+            const elapsedMs = logger.endTimer(operationId);
+            logger.logOperationResult(false, 'read_resource', elapsedMs, errorInfo);
+            throw new ObsidianError(`Failed to read resource: ${errorMessage}`, McpErrorCode.INTERNAL_SERVER_ERROR, { originalError: errorMessage, stack: errorStack });
         }
-        logger.error(`Resource not found: ${uri}`);
-        throw new ObsidianError(`Resource not found: ${uri}`, 40400); // 40400 = Not found
     });
 }
 //# sourceMappingURL=handlers.js.map