obsidian-mcp-server 1.3.0 → 1.4.1

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,8 +1,8 @@
 # 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.6.1-green.svg)](https://modelcontextprotocol.io/)
+[![Version](https://img.shields.io/badge/Version-1.4.1-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)
@@ -18,6 +18,7 @@ Requires the Local REST API plugin in Obsidian.
 ### 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
@@ -32,12 +33,14 @@ Requires the Local REST API plugin in Obsidian.
 ### 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
@@ -84,7 +87,7 @@ 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)
@@ -101,46 +104,22 @@ Rate Limiting:
 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
-
-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
 
@@ -184,6 +163,11 @@ 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
@@ -201,41 +185,8 @@ 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
@@ -286,6 +237,14 @@ obsidian_update_properties: {
 - 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/index.js

@@ -1,11 +1,20 @@
 #!/usr/bin/env node
-import { run } from "./server.js";
+import { run } from "./mcp/server.js";
+import { createLogger } from "./utils/logging.js";
+// Create a logger for the main entry point
+const logger = createLogger('Main');
 // Main entry point
 if (import.meta.url === `file://${process.argv[1]}`) {
+    logger.info("Starting Obsidian MCP Server");
     run().catch((error) => {
-        console.error("Failed to start server:", error);
+        logger.error("Failed to start server:", error);
         process.exit(1);
     });
 }
-export { run };
+// Export the run function and other important modules
+export { run } from "./mcp/server.js";
+export * from "./obsidian/index.js";
+export * from "./tools/index.js";
+export * from "./resources/index.js";
+export * from "./utils/index.js";
 //# sourceMappingURL=index.js.map

package/build/mcp/handlers.js

@@ -0,0 +1,138 @@
+/**
+ * MCP server request handlers
+ */
+import { ListToolsRequestSchema, CallToolRequestSchema, ListResourcesRequestSchema, ReadResourceRequestSchema } from "@modelcontextprotocol/sdk/types.js";
+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";
+// Create a logger for request handlers
+const logger = createLogger('McpHandlers');
+/**
+ * Set up tool listing handler
+ * @param server The MCP server instance
+ * @param toolHandlers The tool handlers to register
+ */
+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());
+        }
+        return { tools };
+    });
+}
+/**
+ * Set up tool calling handler
+ * @param server The MCP server instance
+ * @param toolHandlers The tool handlers to register
+ */
+export function setupToolCallingHandler(server, toolHandlers) {
+    server.setRequestHandler(CallToolRequestSchema, async (request) => {
+        const { name, arguments: args } = request.params;
+        logger.debug(`Handling CallToolRequest for tool: ${name}`);
+        const handler = toolHandlers.get(name);
+        if (!handler) {
+            logger.error(`Unknown tool requested: ${name}`);
+            throw new ObsidianError(`Unknown tool: ${name}`, 40400); // 40400 = 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;
+        }
+        // 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
+            }, timeoutMs);
+        });
+        try {
+            // Validate arguments against tool's schema
+            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
+                );
+            }
+            // Log the tool execution
+            logger.info(`Executing tool: ${name}`);
+            // Race between tool execution and timeout
+            const content = await Promise.race([
+                handler.runTool(args),
+                timeoutPromise
+            ]);
+            logger.debug(`Tool execution completed successfully: ${name}`);
+            return { content };
+        }
+        catch (error) {
+            if (error instanceof ObsidianError) {
+                // Check if the operation actually succeeded despite the error
+                if (error.errorCode === 20400) { // 20400 = Success with no content
+                    return {
+                        content: [{
+                                type: "text",
+                                text: "Operation completed successfully"
+                            }]
+                    };
+                }
+                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 });
+        }
+    });
+}
+/**
+ * Set up resource listing handler
+ * @param server The MCP server instance
+ * @param resources The resources to register
+ */
+export function setupResourceListingHandler(server, resources) {
+    server.setRequestHandler(ListResourcesRequestSchema, async () => {
+        logger.debug('Handling ListResourcesRequest');
+        return {
+            resources: Object.values(resources).map(resource => resource.getResourceDescription())
+        };
+    });
+}
+/**
+ * Set up resource reading handler
+ * @param server The MCP server instance
+ * @param resources The resources to register
+ */
+export function setupResourceReadingHandler(server, resources) {
+    server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
+        const uri = request.params.uri;
+        logger.debug(`Handling ReadResourceRequest for URI: ${uri}`);
+        const resource = resources[uri];
+        if (resource) {
+            logger.debug(`Found resource for URI: ${uri}`);
+            return {
+                contents: await resource.getContent()
+            };
+        }
+        logger.error(`Resource not found: ${uri}`);
+        throw new ObsidianError(`Resource not found: ${uri}`, 40400); // 40400 = Not found
+    });
+}
+//# sourceMappingURL=handlers.js.map

package/build/mcp/index.js

@@ -0,0 +1,7 @@
+/**
+ * MCP module exports
+ */
+export * from './types.js';
+export * from './handlers.js';
+export * from './server.js';
+//# sourceMappingURL=index.js.map

package/build/mcp/server.js

@@ -0,0 +1,131 @@
+/**
+ * MCP server implementation
+ */
+import { config } from "dotenv";
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { createLogger } from "../utils/logging.js";
+import { rateLimiter } from "../utils/rate-limiting.js";
+import { createTagResource } from "../resources/index.js";
+import { createToolHandlers, createToolHandlerMap } from "../tools/index.js";
+import { ObsidianClient } from "../obsidian/client.js";
+import { setupToolListingHandler, setupToolCallingHandler, setupResourceListingHandler, setupResourceReadingHandler } from "./handlers.js";
+// Create a logger for the server
+const logger = createLogger('McpServer');
+// Load environment variables
+config();
+/**
+ * Initialize MCP server components
+ */
+export async function initializeServer() {
+    // Verify API key exists
+    const API_KEY = process.env.OBSIDIAN_API_KEY;
+    if (!API_KEY) {
+        throw new Error("OBSIDIAN_API_KEY environment variable is required");
+    }
+    // Initialize Obsidian client with environment configuration
+    logger.info('Initializing Obsidian client');
+    const client = new ObsidianClient({
+        apiKey: API_KEY,
+        verifySSL: process.env.VERIFY_SSL === 'true',
+        timeout: parseInt(process.env.REQUEST_TIMEOUT || '5000'),
+        maxContentLength: parseInt(process.env.MAX_CONTENT_LENGTH || String(50 * 1024 * 1024)),
+        maxBodyLength: parseInt(process.env.MAX_BODY_LENGTH || String(50 * 1024 * 1024))
+    });
+    // Initialize tool handlers
+    logger.info('Initializing tool handlers');
+    const toolHandlers = createToolHandlers(client);
+    const toolHandlerMap = createToolHandlerMap(toolHandlers);
+    // Initialize resources
+    logger.info('Initializing resources');
+    const tagResource = createTagResource(client);
+    const resources = {
+        [tagResource.getResourceDescription().uri]: tagResource
+    };
+    // Create MCP server
+    const serverConfig = {
+        name: "obsidian-mcp-server",
+        version: process.env.npm_package_version ?? "1.1.0" // Use version from package.json
+    };
+    logger.info(`Creating MCP server: ${serverConfig.name} v${serverConfig.version}`);
+    const server = new Server(serverConfig, {
+        capabilities: {
+            tools: {},
+            resources
+        }
+    });
+    // Set up request handlers
+    setupToolListingHandler(server, toolHandlerMap);
+    setupToolCallingHandler(server, toolHandlerMap);
+    setupResourceListingHandler(server, resources);
+    setupResourceReadingHandler(server, resources);
+    // Set up error handler
+    server.onerror = (error) => {
+        logger.error("[MCP Error]", error);
+    };
+    return server;
+}
+/**
+ * Set up graceful shutdown handling
+ * @param server The MCP server instance
+ * @param cleanupHandlers Additional cleanup handlers to run on shutdown
+ */
+export function setupShutdownHandling(server, cleanupHandlers = []) {
+    // Cleanup function for graceful shutdown
+    const cleanup = async () => {
+        logger.info('Shutting down server...');
+        // Run cleanup handlers
+        for (const handler of cleanupHandlers) {
+            try {
+                await handler();
+            }
+            catch (error) {
+                logger.error('Error during cleanup:', error);
+            }
+        }
+        // Dispose rate limiter
+        rateLimiter.dispose();
+        // Close server
+        await server.close();
+        process.exit(0);
+    };
+    // Handle various termination signals
+    process.on('SIGINT', cleanup); // Ctrl+C on all platforms
+    process.on('SIGTERM', cleanup); // Termination request
+    if (process.platform === 'win32') {
+        // Windows-specific handling
+        process.on('SIGHUP', cleanup); // Terminal closed
+    }
+    else {
+        // Unix-specific signals
+        process.on('SIGUSR1', cleanup);
+        process.on('SIGUSR2', cleanup);
+    }
+    // Handle uncaught errors
+    process.on('uncaughtException', async (error) => {
+        logger.error('Uncaught exception:', error);
+        await cleanup();
+    });
+    process.on('unhandledRejection', async (error) => {
+        logger.error('Unhandled rejection:', error);
+        await cleanup();
+    });
+}
+/**
+ * Run the MCP server
+ */
+export async function run() {
+    try {
+        const server = await initializeServer();
+        setupShutdownHandling(server, []);
+        // Connect to transport
+        const transport = new StdioServerTransport();
+        await server.connect(transport);
+        logger.info("Obsidian MCP server running on stdio");
+    }
+    catch (error) {
+        logger.error("Failed to start server:", error);
+        process.exit(1);
+    }
+}
+//# sourceMappingURL=server.js.map

package/build/mcp/types.js

@@ -0,0 +1,7 @@
+/**
+ * Default timeout configuration
+ */
+export const DEFAULT_TIMEOUT_CONFIG = {
+    toolExecutionMs: parseInt(process.env.TOOL_TIMEOUT_MS ?? '60000') // 60 second default timeout
+};
+//# sourceMappingURL=types.js.map