Obsidian Semantic MCP Server

Instructions

Input Schema

Input Schema (JSON Schema)

Implementation Reference

• src/semantic/router.ts:503-585 (handler)

  Core handler for 'edit' tool operations - implements window (fuzzy replace), append, patch, at_line (insert/replace), from_buffer actions
  private async executeEditOperation(action: string, params: any): Promise<any> { // Import window edit tools dynamically to avoid circular dependencies const { performWindowEdit } = await import('../tools/window-edit.js'); const buffer = ContentBufferManager.getInstance(); switch (action) { case 'window': const result = await performWindowEdit( this.api, params.path, params.oldText, params.newText, params.fuzzyThreshold ); if (result.isError) { throw new Error(result.content[0].text); } return result; case 'append': return await this.api.appendToFile(params.path, params.content); case 'patch': return await this.api.patchVaultFile(params.path, { operation: params.operation, targetType: params.targetType, target: params.target, content: params.content }); case 'at_line': // Get content to insert let insertContent = params.content; if (!insertContent) { const buffered = buffer.retrieve(); if (!buffered) { throw new Error('No content provided and no buffered content found'); } insertContent = buffered.content; } // Get file and perform line-based edit const file = await this.api.getFile(params.path); if (isImageFile(file)) { throw new Error('Cannot perform line-based edits on image files'); } const content = typeof file === 'string' ? file : file.content; const lines = content.split('\n'); if (params.lineNumber < 1 || params.lineNumber > lines.length + 1) { throw new Error(`Invalid line number ${params.lineNumber}. File has ${lines.length} lines.`); } const lineIndex = params.lineNumber - 1; const mode = params.mode || 'replace'; switch (mode) { case 'before': lines.splice(lineIndex, 0, insertContent); break; case 'after': lines.splice(lineIndex + 1, 0, insertContent); break; case 'replace': lines[lineIndex] = insertContent; break; } await this.api.updateFile(params.path, lines.join('\n')); return { success: true, line: params.lineNumber, mode }; case 'from_buffer': const buffered = buffer.retrieve(); if (!buffered) { throw new Error('No buffered content available'); } return await performWindowEdit( this.api, params.path, params.oldText || buffered.searchText || '', buffered.content, params.fuzzyThreshold ); default: throw new Error(`Unknown edit action: ${action}`); } }
• src/tools/semantic-tools.ts:25-75 (handler)

  MCP tool handler for 'edit' - instantiates SemanticRouter and calls route with operation='edit', action=args.action
  handler: async (api: ObsidianAPI, args: any) => { const router = new SemanticRouter(api); const request: SemanticRequest = { operation, action: args.action, params: args }; const response = await router.route(request); // Format for MCP if (response.error) { return { content: [{ type: 'text', text: JSON.stringify({ error: response.error, workflow: response.workflow, context: response.context }, null, 2) }], isError: true }; } // Check if the result is an image file for vault read operations if (operation === 'vault' && args.action === 'read' && response.result && isImageFile(response.result)) { // Return image content for MCP return { content: [{ type: 'image', data: response.result.base64Data, mimeType: response.result.mimeType }] }; } return { content: [{ type: 'text', text: JSON.stringify({ result: response.result, workflow: response.workflow, context: response.context, efficiency_hints: response.efficiency_hints }, null, 2) }] }; } });
• src/tools/semantic-tools.ts:154-193 (schema)

  Input schema properties for 'edit' tool parameters (path, content, oldText, newText, fuzzyThreshold, lineNumber, mode, operation, targetType, target)
  edit: { ...pathParam, ...contentParam, oldText: { type: 'string', description: 'Text to search for (supports fuzzy matching)' }, newText: { type: 'string', description: 'Text to replace with' }, fuzzyThreshold: { type: 'number', description: 'Similarity threshold for fuzzy matching (0-1)', default: 0.7 }, lineNumber: { type: 'number', description: 'Line number for at_line action' }, mode: { type: 'string', enum: ['before', 'after', 'replace'], description: 'Insert mode for at_line action' }, operation: { type: 'string', enum: ['append', 'prepend', 'replace'], description: 'Patch operation: append (add after), prepend (add before), or replace' }, targetType: { type: 'string', enum: ['heading', 'block', 'frontmatter'], description: 'What to target: heading (by path like "H1::H2"), block (by ID), or frontmatter (field)' }, target: { type: 'string', description: 'Target identifier - e.g., "Daily Notes::Today" for heading, block ID, or frontmatter field name' } },
• src/tools/semantic-tools.ts:89-97 (schema)

  Action enum for 'edit' tool: ['window', 'append', 'patch', 'at_line', 'from_buffer'] used in inputSchema
  const actions: Record<string, string[]> = { vault: ['list', 'read', 'create', 'update', 'delete', 'search', 'fragments'], edit: ['window', 'append', 'patch', 'at_line', 'from_buffer'], view: ['file', 'window', 'active', 'open_in_obsidian'], workflow: ['suggest'], system: ['info', 'commands', 'fetch_web'] }; return actions[operation] || []; }
• src/tools/semantic-tools.ts:227-234 (registration)

  Registration of 'edit' tool via createSemanticTool('edit') in semanticTools export
  // Export the 5 semantic tools export const semanticTools = [ createSemanticTool('vault'), createSemanticTool('edit'), createSemanticTool('view'), createSemanticTool('workflow'), createSemanticTool('system') ];
• src/tools/window-edit.ts:7-88 (helper)

  performWindowEdit helper function used by edit:window and edit:from_buffer for fuzzy text replacement in files
  export async function performWindowEdit( api: ObsidianAPI, path: string, oldText: string, newText: string, fuzzyThreshold: number = 0.7 ) { const buffer = ContentBufferManager.getInstance(); // Get current file content const file = await api.getFile(path); if (isImageFile(file)) { throw new Error('Cannot perform window edits on image files'); } const content = typeof file === 'string' ? file : file.content; // Try exact match first if (content.includes(oldText)) { const newContent = content.replace(oldText, newText); await api.updateFile(path, newContent); return { content: [{ type: 'text', text: `Successfully replaced exact match in ${path}` }] }; } // Buffer the new content for potential recovery buffer.store(newText, undefined, { filePath: path, searchText: oldText }); // Try fuzzy matching const matches = findFuzzyMatches(content, oldText, fuzzyThreshold); if (matches.length === 0) { // No matches found, provide helpful feedback return { content: [{ type: 'text', text: `No matches found for "${oldText}" in ${path}. ` + `Content has been buffered. You can use edit_vault_from_buffer to retry ` + `with different search text or insert_vault_at_line to insert at a specific line.` }], isError: true }; } // If multiple matches, ask for clarification if (matches.length > 1) { const matchList = matches.map(m => `Line ${m.lineNumber} (${Math.round(m.similarity * 100)}% match): "${m.line.trim()}"` ).join('\n'); return { content: [{ type: 'text', text: `Found ${matches.length} potential matches:\n\n${matchList}\n\n` + `Content has been buffered. Use insert_vault_at_line with the specific line number.` }], isError: true }; } // Single match found - replace the entire line const match = matches[0]; const lines = content.split('\n'); lines[match.lineNumber - 1] = newText; const newContent = lines.join('\n'); await api.updateFile(path, newContent); return { content: [{ type: 'text', text: `Successfully replaced line ${match.lineNumber} (${Math.round(match.similarity * 100)}% match) in ${path}` }] }; }