obsidian-mcp-server 1.1.0

package/src/server.ts

@@ -0,0 +1,277 @@
+import { config } from "dotenv";
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import {
+  Tool,
+  TextContent,
+  ImageContent,
+  EmbeddedResource,
+  ListToolsRequestSchema,
+  CallToolRequestSchema
+} from "@modelcontextprotocol/sdk/types.js";
+import { ObsidianClient } from "./obsidian.js";
+import { ObsidianError, DEFAULT_RATE_LIMIT_CONFIG, RateLimitConfig } from "./types.js";
+import type { ToolHandler } from "./types.js";
+import {
+  ListFilesInVaultToolHandler,
+  ListFilesInDirToolHandler,
+  GetFileContentsToolHandler,
+  FindInFileToolHandler,
+  AppendContentToolHandler,
+  PatchContentToolHandler,
+  ComplexSearchToolHandler
+} from "./tools.js";
+
+// Load environment variables
+config();
+
+const API_KEY = process.env.OBSIDIAN_API_KEY;
+if (!API_KEY) {
+  throw new Error("OBSIDIAN_API_KEY environment variable is required");
+}
+
+// Get rate limit config from environment or use defaults
+const rateLimitConfig: RateLimitConfig = {
+  windowMs: parseInt(process.env.RATE_LIMIT_WINDOW_MS ?? String(DEFAULT_RATE_LIMIT_CONFIG.windowMs)),
+  maxRequests: parseInt(process.env.RATE_LIMIT_MAX_REQUESTS ?? String(DEFAULT_RATE_LIMIT_CONFIG.maxRequests))
+};
+
+// Request tracking for rate limiting
+const requestCounts = new Map<string, { count: number; resetTime: number }>();
+
+function checkRateLimit(toolName: string): boolean {
+  const now = Date.now();
+  const requestInfo = requestCounts.get(toolName);
+
+  if (!requestInfo || now > requestInfo.resetTime) {
+    // Reset counter for new window
+    requestCounts.set(toolName, {
+      count: 1,
+      resetTime: now + rateLimitConfig.windowMs
+    });
+    return true;
+  }
+
+  if (requestInfo.count >= rateLimitConfig.maxRequests) {
+    return false;
+  }
+
+  requestInfo.count++;
+  return true;
+}
+
+// Clean up expired rate limit entries periodically
+const cleanupInterval = setInterval(() => {
+  const now = Date.now();
+  for (const [tool, info] of requestCounts.entries()) {
+    if (now > info.resetTime) {
+      requestCounts.delete(tool);
+    }
+  }
+}, 60000); // Clean up every minute
+
+// Initialize Obsidian client
+const client = new ObsidianClient({ 
+  apiKey: API_KEY,
+  verifySSL: process.env.NODE_ENV === 'production' // Enable SSL verification in production
+});
+
+// Initialize tool handlers
+type AnyToolHandler = ToolHandler<any>;
+const toolHandlers = new Map<string, AnyToolHandler>();
+
+const handlers: AnyToolHandler[] = [
+  new ListFilesInVaultToolHandler(client),
+  new ListFilesInDirToolHandler(client),
+  new GetFileContentsToolHandler(client),
+  new FindInFileToolHandler(client),
+  new AppendContentToolHandler(client),
+  new PatchContentToolHandler(client),
+  new ComplexSearchToolHandler(client)
+];
+
+handlers.forEach(handler => toolHandlers.set(handler.name, handler));
+
+// Create MCP server
+const server = new Server(
+  {
+    name: "obsidian-mcp-server",
+    version: process.env.npm_package_version ?? "1.1.0" // Use version from package.json
+  },
+  {
+    capabilities: {
+      tools: {},
+      resources: {}
+    }
+  }
+);
+
+// Set up request handlers
+server.setRequestHandler(ListToolsRequestSchema, async () => {
+  const tools: Tool[] = [];
+  for (const handler of toolHandlers.values()) {
+    tools.push(handler.getToolDescription());
+  }
+  return { tools };
+});
+
+// Add validation helper
+function validateToolArguments(args: unknown, schema: any): { valid: boolean; errors: string[] } {
+  if (typeof args !== 'object' || args === null) {
+    return { valid: false, errors: ['Arguments must be an object'] };
+  }
+
+  const errors: string[] = [];
+  const required = schema.required || [];
+  
+  // Check required fields
+  for (const field of required) {
+    if (!(field in args)) {
+      errors.push(`Missing required field: ${field}`);
+    }
+  }
+
+  // Check field types
+  const properties = schema.properties || {};
+  for (const [key, value] of Object.entries(args)) {
+    const propSchema = properties[key];
+    if (!propSchema) {
+      errors.push(`Unknown field: ${key}`);
+      continue;
+    }
+
+    // Skip validation for undefined optional fields
+    if (value === undefined && !required.includes(key)) {
+      continue;
+    }
+
+    // Type validation
+    if (propSchema.type === 'string' && typeof value !== 'string') {
+      errors.push(`Field ${key} must be a string`);
+    } else if (propSchema.type === 'number' && typeof value !== 'number') {
+      errors.push(`Field ${key} must be a number`);
+    } else if (propSchema.type === 'boolean' && typeof value !== 'boolean') {
+      errors.push(`Field ${key} must be a boolean`);
+    } else if (propSchema.type === 'array' && !Array.isArray(value)) {
+      errors.push(`Field ${key} must be an array`);
+    }
+
+    // Enum validation
+    if (propSchema.enum && value !== undefined && !propSchema.enum.includes(value)) {
+      errors.push(`Field ${key} must be one of: ${propSchema.enum.join(', ')}`);
+    }
+
+    // Format validation for paths
+    if (propSchema.format === 'path' && typeof value === 'string') {
+      // Prevent path traversal
+      if (value.includes('../') || value.includes('..\\')) {
+        errors.push(`Field ${key} contains invalid path traversal`);
+      }
+      // Prevent absolute paths
+      if (value.startsWith('/') || /^[a-zA-Z]:/.test(value)) {
+        errors.push(`Field ${key} must be a relative path`);
+      }
+    }
+  }
+
+  return { valid: errors.length === 0, errors };
+}
+
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  const { name, arguments: args } = request.params;
+
+  const handler = toolHandlers.get(name);
+  if (!handler) {
+    throw new ObsidianError(`Unknown tool: ${name}`, 404);
+  }
+
+  // Check rate limit
+  if (!checkRateLimit(name)) {
+    throw new ObsidianError(
+      `Rate limit exceeded for tool: ${name}. Please try again later.`,
+      429
+    );
+  }
+
+  // Add timeout handling
+  const timeoutMs = parseInt(process.env.TOOL_TIMEOUT_MS ?? '60000'); // 60 second default timeout
+  const timeoutPromise = new Promise((_, reject) => {
+    setTimeout(() => {
+      reject(new ObsidianError(`Tool execution timed out after ${timeoutMs}ms`, 408));
+    }, timeoutMs);
+  });
+
+  try {
+    // Validate arguments against tool's schema
+    const toolDescription = handler.getToolDescription();
+    const validationResult = validateToolArguments(args, toolDescription.inputSchema);
+    if (!validationResult.valid) {
+      throw new ObsidianError(
+        `Invalid tool arguments: ${validationResult.errors.join(', ')}`,
+        400
+      );
+    }
+
+    // Race between tool execution and timeout
+    const content = await Promise.race([
+      handler.runTool(args),
+      timeoutPromise
+    ]);
+    return { content };
+  } catch (error) {
+    if (error instanceof ObsidianError) {
+      // Check if the operation actually succeeded despite the error
+      if (error.code === 204) {
+        return {
+          content: [{
+            type: "text",
+            text: "Operation completed successfully"
+          }]
+        };
+      }
+      throw error;
+    }
+    
+    // Enhanced error logging
+    console.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,
+      args
+    });
+
+    if (error instanceof Error) {
+      throw new ObsidianError(
+        `Tool '${name}' execution failed: ${error.message}`,
+        500,
+        { originalError: error.stack }
+      );
+    }
+    
+    throw new ObsidianError(
+      "Tool execution failed with unknown error",
+      500,
+      { error }
+    );
+  }
+});
+
+// Error handler
+server.onerror = (error) => {
+  console.error("[MCP Error]", error);
+};
+
+// Handle shutdown
+process.on("SIGINT", async () => {
+  clearInterval(cleanupInterval); // Clean up rate limit interval
+  await server.close();
+  process.exit(0);
+});
+
+// Export the run function
+export async function run(): Promise<void> {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  console.error("Obsidian MCP server running on stdio");
+}

package/src/tools.ts

@@ -0,0 +1,429 @@
+import { Tool, TextContent } from "@modelcontextprotocol/sdk/types.js";
+import { ObsidianClient } from "./obsidian.js";
+import { encoding_for_model } from "tiktoken";
+import {
+  ToolHandler,
+  PatchContentArgs,
+  AppendContentArgs,
+  SearchArgs,
+  ComplexSearchArgs,
+  FileContentsArgs,
+  ListFilesArgs,
+  ObsidianError
+} from "./types.js";
+
+const TOOL_NAMES = {
+  LIST_FILES_IN_VAULT: "obsidian_list_files_in_vault",
+  LIST_FILES_IN_DIR: "obsidian_list_files_in_dir",
+  GET_FILE_CONTENTS: "obsidian_get_file_contents",
+  FIND_IN_FILE: "obsidian_find_in_file",
+  APPEND_CONTENT: "obsidian_append_content",
+  PATCH_CONTENT: "obsidian_patch_content",
+  COMPLEX_SEARCH: "obsidian_complex_search"
+} as const;
+
+// Load token limits from environment or use defaults
+const MAX_TOKENS = parseInt(process.env.MAX_TOKENS ?? '20000');
+const TRUNCATION_MESSAGE = "\n\n[Response truncated due to length]";
+
+export abstract class BaseToolHandler<T = Record<string, unknown>> implements ToolHandler<T> {
+  private tokenizer = encoding_for_model("gpt-4"); // This is strictly for token counting, not for LLM inference
+  private isShuttingDown = false;
+
+  constructor(
+    public readonly name: string,
+    protected client: ObsidianClient
+  ) {
+    // Clean up tokenizer when process exits
+    const cleanup = () => {
+      if (!this.isShuttingDown) {
+        this.isShuttingDown = true;
+        if (this.tokenizer) {
+          this.tokenizer.free();
+        }
+      }
+    };
+
+    process.on('exit', cleanup);
+    process.on('SIGINT', cleanup);
+    process.on('SIGTERM', cleanup);
+    process.on('uncaughtException', cleanup);
+  }
+
+  protected countTokens(text: string): number {
+    return this.tokenizer.encode(text).length;
+  }
+
+  protected truncateToTokenLimit(text: string): string {
+    const tokens = this.tokenizer.encode(text);
+    if (tokens.length <= MAX_TOKENS) {
+      return text;
+    }
+
+    // Reserve tokens for truncation message
+    const messageTokens = this.tokenizer.encode(TRUNCATION_MESSAGE);
+    const availableTokens = MAX_TOKENS - messageTokens.length;
+    
+    // Decode truncated tokens back to text
+    const truncatedText = this.tokenizer.decode(tokens.slice(0, availableTokens));
+    return truncatedText + TRUNCATION_MESSAGE;
+  }
+
+  abstract getToolDescription(): Tool;
+  abstract runTool(args: T): Promise<Array<TextContent>>;
+
+  protected createResponse(content: unknown): TextContent[] {
+    let text: string;
+
+    // Handle different content types
+    if (typeof content === 'string') {
+      text = content;
+    } else if (content instanceof Buffer) {
+      text = content.toString('utf-8');
+    } else if (Array.isArray(content) && content.every(item => typeof item === 'string')) {
+      text = content.join('\n');
+    } else if (content instanceof Error) {
+      text = `Error: ${content.message}\n${content.stack || ''}`;
+    } else {
+      try {
+        text = JSON.stringify(content, null, 2);
+      } catch (error) {
+        text = String(content);
+      }
+    }
+
+    // Count tokens and truncate if necessary
+    const originalTokenCount = this.countTokens(text);
+    const truncatedText = this.truncateToTokenLimit(text);
+    const finalTokenCount = this.countTokens(truncatedText);
+    
+    if (originalTokenCount > MAX_TOKENS) {
+      console.debug(
+        `[${this.name}] Response truncated:`,
+        `original tokens=${originalTokenCount}`,
+        `truncated tokens=${finalTokenCount}`
+      );
+    }
+    
+    return [{
+      type: "text",
+      text: truncatedText
+    }];
+  }
+
+  protected handleError(error: unknown): never {
+    if (error instanceof ObsidianError) {
+      throw error;
+    }
+    if (error instanceof Error) {
+      throw new ObsidianError(
+        `Tool '${this.name}' execution failed: ${error.message}`,
+        500,
+        { originalError: error.stack }
+      );
+    }
+    throw new ObsidianError(
+      `Tool '${this.name}' execution failed with unknown error`,
+      500,
+      { error }
+    );
+  }
+}
+
+export class ListFilesInVaultToolHandler extends BaseToolHandler<Record<string, never>> {
+  constructor(client: ObsidianClient) {
+    super(TOOL_NAMES.LIST_FILES_IN_VAULT, client);
+  }
+
+  getToolDescription(): Tool {
+    return {
+      name: this.name,
+      description: "Lists all files and directories in the root directory of your Obsidian vault.",
+      examples: [
+        {
+          description: "List all files in vault",
+          args: {}
+        }
+      ],
+      inputSchema: {
+        type: "object",
+        properties: {},
+        required: []
+      }
+    };
+  }
+
+  async runTool(): Promise<Array<TextContent>> {
+    try {
+      const files = await this.client.listFilesInVault();
+      return this.createResponse(files);
+    } catch (error) {
+      return this.handleError(error);
+    }
+  }
+}
+
+export class ListFilesInDirToolHandler extends BaseToolHandler<ListFilesArgs> {
+  constructor(client: ObsidianClient) {
+    super(TOOL_NAMES.LIST_FILES_IN_DIR, client);
+  }
+
+  getToolDescription(): Tool {
+    return {
+      name: this.name,
+      description: "Lists all files and directories that exist in a specific Obsidian directory.",
+      examples: [
+        {
+          description: "List files in Documents folder",
+          args: {
+            dirpath: "Documents"
+          }
+        }
+      ],
+      inputSchema: {
+        type: "object",
+        properties: {
+          dirpath: {
+            type: "string",
+            description: "Path to list files from (relative to your vault root). Note that empty directories will not be returned.",
+            format: "path"
+          }
+        },
+        required: ["dirpath"]
+      }
+    };
+  }
+
+  async runTool(args: ListFilesArgs): Promise<Array<TextContent>> {
+    try {
+      const files = await this.client.listFilesInDir(args.dirpath);
+      return this.createResponse(files);
+    } catch (error) {
+      return this.handleError(error);
+    }
+  }
+}
+
+export class GetFileContentsToolHandler extends BaseToolHandler<FileContentsArgs> {
+  constructor(client: ObsidianClient) {
+    super(TOOL_NAMES.GET_FILE_CONTENTS, client);
+  }
+
+  getToolDescription(): Tool {
+    return {
+      name: this.name,
+      description: "Return the content of a single file in your vault.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          filepath: {
+            type: "string",
+            description: "Path to the relevant file (relative to your vault root).",
+            format: "path"
+          }
+        },
+        required: ["filepath"]
+      }
+    };
+  }
+
+  async runTool(args: FileContentsArgs): Promise<Array<TextContent>> {
+    try {
+      const content = await this.client.getFileContents(args.filepath);
+      return this.createResponse(content);
+    } catch (error) {
+      return this.handleError(error);
+    }
+  }
+}
+
+export class FindInFileToolHandler extends BaseToolHandler<SearchArgs> {
+  constructor(client: ObsidianClient) {
+    super(TOOL_NAMES.FIND_IN_FILE, client);
+  }
+
+  getToolDescription(): Tool {
+    return {
+      name: this.name,
+      description: "Simple search that returns filenames of documents matching a specified text query across all files in the vault.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          query: {
+            type: "string",
+            description: "Text to search for in the vault."
+          },
+          contextLength: {
+            type: "integer",
+            description: "How much context to use for matching (default: 10)",
+            default: 10
+          }
+        },
+        required: ["query"]
+      }
+    };
+  }
+
+  async runTool(args: SearchArgs): Promise<Array<TextContent>> {
+    try {
+      const results = await this.client.search(args.query, args.contextLength);
+      // Extract only unique filenames from search results
+      const filenames = [...new Set(results.map(result => result.filename))].sort();
+      return this.createResponse(filenames);
+    } catch (error) {
+      return this.handleError(error);
+    }
+  }
+}
+
+export class AppendContentToolHandler extends BaseToolHandler<AppendContentArgs> {
+  constructor(client: ObsidianClient) {
+    super(TOOL_NAMES.APPEND_CONTENT, client);
+  }
+
+  getToolDescription(): Tool {
+    return {
+      name: this.name,
+      description: "Append content to a new or existing file in the vault.",
+      examples: [
+        {
+          description: "Append a new task",
+          args: {
+            filepath: "tasks.md",
+            content: "- [ ] New task to complete"
+          }
+        },
+        {
+          description: "Append meeting notes",
+          args: {
+            filepath: "meetings/2025-01-23.md",
+            content: "## Meeting Notes\n\n- Discussed project timeline\n- Assigned tasks"
+          }
+        }
+      ],
+      inputSchema: {
+        type: "object",
+        properties: {
+          filepath: {
+            type: "string",
+            description: "Path to the file (relative to vault root)",
+            format: "path"
+          },
+          content: {
+            type: "string",
+            description: "Content to append to the file"
+          }
+        },
+        required: ["filepath", "content"]
+      }
+    };
+  }
+
+  async runTool(args: AppendContentArgs): Promise<Array<TextContent>> {
+    try {
+      await this.client.appendContent(args.filepath, args.content);
+      return this.createResponse({ message: `Successfully appended content to ${args.filepath}` });
+    } catch (error) {
+      return this.handleError(error);
+    }
+  }
+}
+
+export class PatchContentToolHandler extends BaseToolHandler<PatchContentArgs> {
+  constructor(client: ObsidianClient) {
+    super(TOOL_NAMES.PATCH_CONTENT, client);
+  }
+
+  getToolDescription(): Tool {
+    return {
+      name: this.name,
+      description: "Update the entire content of an existing note or create a new one.",
+      examples: [
+        {
+          description: "Update a note's content",
+          args: {
+            filepath: "project.md",
+            content: "# Project Notes\n\nThis will replace the entire content of the note."
+          }
+        }
+      ],
+      inputSchema: {
+        type: "object",
+        properties: {
+          filepath: {
+            type: "string",
+            description: "Path to the file (relative to vault root)",
+            format: "path"
+          },
+          content: {
+            type: "string",
+            description: "New content for the note (replaces existing content)"
+          }
+        },
+        required: ["filepath", "content"]
+      }
+    };
+  }
+
+  async runTool(args: PatchContentArgs): Promise<Array<TextContent>> {
+    try {
+      await this.client.updateContent(args.filepath, args.content);
+      return this.createResponse({ message: `Successfully updated content in ${args.filepath}` });
+    } catch (error) {
+      return this.handleError(error);
+    }
+  }
+}
+
+export class ComplexSearchToolHandler extends BaseToolHandler<ComplexSearchArgs> {
+  constructor(client: ObsidianClient) {
+    super(TOOL_NAMES.COMPLEX_SEARCH, client);
+  }
+
+  getToolDescription(): Tool {
+    return {
+      name: this.name,
+      description: "Complex search for documents using a JsonLogic query.",
+      examples: [
+        {
+          description: "Find all markdown files",
+          args: {
+            query: {
+              "glob": ["*.md", {"var": "path"}]
+            }
+          }
+        },
+        {
+          description: "Find files modified in last week",
+          args: {
+            query: {
+              ">=": [
+                {"var": "mtime"},
+                {"date": "-7 days"}
+              ]
+            }
+          }
+        }
+      ],
+      inputSchema: {
+        type: "object",
+        properties: {
+          query: {
+            type: "object",
+            description: "JsonLogic query object. Example: {\"glob\": [\"*.md\", {\"var\": \"path\"}]} matches all markdown files"
+          }
+        },
+        required: ["query"]
+      }
+    };
+  }
+
+  async runTool(args: ComplexSearchArgs): Promise<Array<TextContent>> {
+    try {
+      const results = await this.client.searchJson(args.query);
+      return this.createResponse(results);
+    } catch (error) {
+      return this.handleError(error);
+    }
+  }
+}