Obsidian Semantic MCP Server

Instructions

Implementation Reference

• src/index.ts:80-100 (registration)

  Registers the 'system' tool by setting up MCP server request handlers for listing and calling tools from the semanticTools array, which includes the 'system' tool.
  server.setRequestHandler(ListToolsRequestSchema, async () => { return { tools: semanticTools.map(tool => ({ name: tool.name, description: tool.description, inputSchema: tool.inputSchema })) }; }); // Handle tool execution server.setRequestHandler(CallToolRequestSchema, async (request) => { const { name, arguments: args } = request.params; const tool = semanticTools.find(t => t.name === name); if (!tool) { throw new Error(`Tool not found: ${name}`); } return await tool.handler(obsidianAPI, args); });
• src/tools/semantic-tools.ts:10-75 (handler)

  Defines the handler function for the 'system' tool (shared across semantic tools), which routes the request to SemanticRouter and formats the MCP response.
  const createSemanticTool = (operation: string) => ({ name: operation, description: getOperationDescription(operation), inputSchema: { type: 'object', properties: { action: { type: 'string', description: 'The specific action to perform', enum: getActionsForOperation(operation) }, ...getParametersForOperation(operation) }, required: ['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:77-225 (schema)

  Defines the input schema, description, actions enum, and parameters for the 'system' tool.
  function getOperationDescription(operation: string): string { const descriptions: Record<string, string> = { vault: 'File and folder operations - list, read, create, update, delete, search', edit: 'Smart editing operations - window (auto-buffers content), append, patch, at_line, from_buffer', view: 'Content viewing and navigation - file, window, active, open_in_obsidian', workflow: 'Workflow guidance and suggestions based on current context', system: 'System operations - info, commands, fetch_web' }; return descriptions[operation] || 'Unknown operation'; } function getActionsForOperation(operation: string): string[] { 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] || []; } function getParametersForOperation(operation: string): Record<string, any> { // Common parameters across operations const pathParam = { path: { type: 'string', description: 'Path to the file or directory' } }; const contentParam = { content: { type: 'string', description: 'Content to write or append' } }; // Operation-specific parameters const operationParams: Record<string, Record<string, any>> = { vault: { ...pathParam, directory: { type: 'string', description: 'Directory path for list operations' }, query: { type: 'string', description: 'Search query' }, page: { type: 'number', description: 'Page number for paginated results' }, pageSize: { type: 'number', description: 'Number of results per page' }, strategy: { type: 'string', enum: ['auto', 'adaptive', 'proximity', 'semantic'], description: 'Fragment retrieval strategy (default: auto)' }, maxFragments: { type: 'number', description: 'Maximum number of fragments to return (default: 5)' }, returnFullFile: { type: 'boolean', description: 'Return full file instead of fragments (WARNING: large files can consume significant context)' }, includeContent: { type: 'boolean', description: 'Include file content in search results (slower but more thorough)' }, ...contentParam }, 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' } }, view: { ...pathParam, searchText: { type: 'string', description: 'Text to search for and highlight' }, lineNumber: { type: 'number', description: 'Line number to center view around' }, windowSize: { type: 'number', description: 'Number of lines to show', default: 20 } }, workflow: { type: { type: 'string', description: 'Type of analysis or workflow' } }, system: { url: { type: 'string', description: 'URL to fetch and convert to markdown' } } }; return operationParams[operation] || {}; }
• src/tools/semantic-tools.ts:228-234 (handler)

  Creates and exports the 'system' tool instance.
  export const semanticTools = [ createSemanticTool('vault'), createSemanticTool('edit'), createSemanticTool('view'), createSemanticTool('workflow'), createSemanticTool('system') ];
• src/semantic/router.ts:663-676 (handler)

  Implements the core logic for 'system' tool actions: info (server info), commands (list commands), fetch_web (delegates to fetch tool). Called by the semantic tool handler.
  private async executeSystemOperation(action: string, params: any): Promise<any> { switch (action) { case 'info': return await this.api.getServerInfo(); case 'commands': return await this.api.getCommands(); case 'fetch_web': // Import fetch tool dynamically const { fetchTool } = await import('../tools/fetch.js'); return await fetchTool.handler(this.api, params); default: throw new Error(`Unknown system action: ${action}`); } }