obsidian-mcp-server 1.3.0 → 1.4.0

package/examples/list-files-in-vault.md

@@ -0,0 +1,53 @@
+# List Files in Vault Tool Example
+
+## Request
+```json
+{
+  "type": "object",
+  "properties": {}
+}
+```
+
+## Response
+```
+Areas/
+  Areas/Work/
+  Areas/Personal/
+  Areas/Projects/
+Resources/
+  Resources/Templates/
+  Resources/Attachments/
+Daily Notes/
+  Daily Notes/2024-01-25.md
+Projects/
+  Projects/Project Alpha/
+  Projects/Project Beta/
+Archive/
+README.md
+index.md
+```
+
+## Example Use Cases
+
+1. **Vault Organization**
+   - Get a complete overview of your vault structure
+   - Identify main areas and categories
+   - Plan content organization
+
+2. **Content Management**
+   - Find important directories and files
+   - Review vault hierarchy
+   - Locate specific resources
+
+3. **Navigation**
+   - Quick access to key areas
+   - Browse through project directories
+   - Find templates and resources
+
+## Notes
+- The tool returns both files and directories at the root level
+- Directory paths end with a forward slash (/)
+- File extensions are preserved in the output
+- Results are alphabetically sorted
+- Special characters in filenames are preserved
+- Provides a hierarchical view of your vault structure

package/examples/patch-content.md

@@ -0,0 +1,60 @@
+# Patch Content Tool Example
+
+## Request 1 (Update Existing Note)
+```json
+{
+  "filepath": "Projects/Project Alpha/Documentation/Architecture.md",
+  "content": "---\ntitle: System Architecture\ntags: [architecture, documentation]\nstatus: [complete]\nmodified: 2024-01-25\n---\n\n# System Architecture\n\n## Overview\nThis document describes the high-level architecture of Project Alpha.\n\n## Components\n\n### Frontend\n- React-based web application\n- Material UI components\n- Redux state management\n\n### Backend\n- Node.js REST API\n- PostgreSQL database\n- Redis caching layer\n\n### Infrastructure\n- AWS cloud hosting\n- Docker containerization\n- CI/CD pipeline\n\n## System Diagram\n![[architecture-diagram.png]]\n\n## Integration Points\n- Authentication service\n- Payment processing\n- Email service\n- Analytics platform\n\n#project-alpha #architecture #technical"
+}
+```
+
+## Response 1
+```json
+{
+  "success": true,
+  "message": "File content updated successfully"
+}
+```
+
+## Request 2 (Create New Note)
+```json
+{
+  "filepath": "Templates/Meeting Note.md",
+  "content": "---\ntitle: {{title}}\ndate: {{date}}\nattendees: \ntags: [meeting]\nstatus: [draft]\n---\n\n# {{title}}\n\n## Agenda\n1. \n2. \n3. \n\n## Discussion Points\n- \n\n## Decisions\n- \n\n## Action Items\n- [ ] \n- [ ] \n- [ ] \n\n## Next Steps\n- \n\n## Notes\n- "
+}
+```
+
+## Response 2
+```json
+{
+  "success": true,
+  "message": "File created successfully"
+}
+```
+
+## Example Use Cases
+
+1. **Document Updates**
+   - Complete revision of documentation
+   - Update outdated content
+   - Replace temporary content with final version
+
+2. **Template Creation**
+   - Create note templates
+   - Define standardized formats
+   - Set up reusable structures
+
+3. **Content Migration**
+   - Move and reformat content
+   - Update note structure
+   - Implement new organization systems
+
+## Notes
+- Replaces entire file content or creates new file
+- Supports YAML frontmatter
+- Handles template variables
+- Preserves markdown formatting
+- Creates parent directories if needed
+- Validates content structure
+- File path is relative to vault root
+- Useful for major content revisions

package/examples/update-properties.md

@@ -0,0 +1,126 @@
+# Update Properties Tool Example
+
+## Request 1 (Update Multiple Properties)
+```json
+{
+  "filepath": "Projects/Project Alpha/Documentation/Requirements.md",
+  "properties": {
+    "status": ["in-review"],
+    "tags": ["project", "requirements", "documentation", "technical"],
+    "modified": "2024-01-25",
+    "reviewers": ["Tech Lead", "Product Manager", "Security Team"],
+    "version": "1.1"
+  }
+}
+```
+
+## Response 1
+```json
+{
+  "success": true,
+  "message": "Properties updated successfully"
+}
+```
+
+## Request 2 (Merge Array Properties)
+```json
+{
+  "filepath": "Projects/Project Beta/Specifications.md",
+  "properties": {
+    "tags": ["api", "backend"],
+    "status": ["draft"]
+  },
+  "replace": false
+}
+```
+
+## Response 2
+```json
+{
+  "success": true,
+  "message": "Properties merged successfully"
+}
+```
+
+## Example Use Cases
+
+1. **Document Management**
+   - Update document status
+   - Add or remove tags
+   - Track document versions
+   - Manage review process
+
+2. **Project Tracking**
+   - Update task status
+   - Assign reviewers
+   - Track modifications
+   - Version control
+
+3. **Content Organization**
+   - Categorize content
+   - Update metadata
+   - Manage document lifecycle
+   - Track document history
+
+## Notes
+- Updates YAML frontmatter properties
+- Supports property merging or replacement
+- Handles various property types:
+  * Strings
+  * Arrays
+  * Dates
+  * Numbers
+  * Boolean values
+- Preserves existing properties not specified in update
+- Automatically updates modified timestamp
+- Creates properties if they don't exist
+
+## Property Handling
+
+1. **Array Merging (replace: false)**
+```yaml
+# Original
+tags: [project, draft]
+status: [review]
+
+# Update
+tags: [technical, draft]
+status: [complete]
+
+# Result
+tags: [project, draft, technical]
+status: [review, complete]
+```
+
+2. **Array Replacement (replace: true)**
+```yaml
+# Original
+reviewers: [Alice, Bob]
+tags: [draft]
+
+# Update (replace: true)
+reviewers: [Charlie]
+tags: [final]
+
+# Result
+reviewers: [Charlie]
+tags: [final]
+```
+
+3. **Property Types**
+```yaml
+# String properties
+title: "Updated Title"
+author: "New Author"
+
+# Date properties
+modified: 2024-01-25
+due: 2024-02-01
+
+# Number properties
+version: 2.0
+priority: 1
+
+# Boolean properties
+published: true
+confidential: false

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "obsidian-mcp-server",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "description": "Model Context Protocol server for Obsidian integration with token-aware response handling",
   "main": "build/index.js",
   "type": "module",

package/src/index.ts

@@ -1,12 +1,22 @@
 #!/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";

package/src/mcp/handlers.ts

@@ -0,0 +1,183 @@
+/**
+ * MCP server request handlers
+ */
+import {
+  Tool,
+  TextContent,
+  ListToolsRequestSchema,
+  CallToolRequestSchema,
+  ListResourcesRequestSchema,
+  ReadResourceRequestSchema
+} from "@modelcontextprotocol/sdk/types.js";
+import { Server } from "@modelcontextprotocol/sdk/server/index.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";
+import { BaseToolHandler } from "../tools/base.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: Server,
+  toolHandlers: Map<string, BaseToolHandler<any>>
+): void {
+  server.setRequestHandler(ListToolsRequestSchema, async () => {
+    logger.debug('Handling ListToolsRequest');
+    const tools: Tool[] = [];
+    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: Server,
+  toolHandlers: Map<string, BaseToolHandler<any>>
+): void {
+  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<never>((_, 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: Server,
+  resources: Record<string, any>
+): void {
+  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: Server,
+  resources: Record<string, any>
+): void {
+  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
+  });
+}

package/src/mcp/index.ts

@@ -0,0 +1,6 @@
+/**
+ * MCP module exports
+ */
+export * from './types.js';
+export * from './handlers.js';
+export * from './server.js';

package/src/mcp/server.ts

@@ -0,0 +1,162 @@
+/**
+ * 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";
+import { McpServerConfig, ResourceMap } from "./types.js";
+
+// Create a logger for the server
+const logger = createLogger('McpServer');
+
+// Load environment variables
+config();
+
+/**
+ * Initialize MCP server components
+ */
+export async function initializeServer(): Promise<Server> {
+  // 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: ResourceMap = {
+    [tagResource.getResourceDescription().uri]: tagResource
+  };
+
+  // Create MCP server
+  const serverConfig: McpServerConfig = {
+    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: Server,
+  cleanupHandlers: (() => Promise<void> | void)[] = []
+): void {
+  // 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(): Promise<void> {
+  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);
+  }
+}

package/src/mcp/types.ts

@@ -0,0 +1,46 @@
+/**
+ * MCP server type definitions
+ */
+import { TextContent, Tool } from "@modelcontextprotocol/sdk/types.js";
+import { BaseToolHandler } from "../tools/base.js";
+import { TagResource } from "../resources/tags.js";
+
+/**
+ * MCP server configuration
+ */
+export interface McpServerConfig extends Record<string, unknown> {
+  name: string;
+  version: string;
+}
+
+/**
+ * Timeout configuration for tool execution
+ */
+export interface TimeoutConfig {
+  toolExecutionMs: number; // Default: 60000 (60 seconds)
+}
+
+/**
+ * Map of resources by URI
+ */
+export interface ResourceMap {
+  [uri: string]: {
+    getContent(): Promise<TextContent[]>;
+    getResourceDescription(): any;
+  };
+}
+
+/**
+ * Server capabilities configuration
+ */
+export interface ServerCapabilities {
+  tools: Record<string, Tool>;
+  resources: ResourceMap;
+}
+
+/**
+ * Default timeout configuration
+ */
+export const DEFAULT_TIMEOUT_CONFIG: TimeoutConfig = {
+  toolExecutionMs: parseInt(process.env.TOOL_TIMEOUT_MS ?? '60000') // 60 second default timeout
+};