TriliumNext Notes' MCP Server

Instructions

Implementation Reference

• src/modules/noteManager.ts:689-841 (handler)

  Core implementation of the search_and_replace_note tool. Fetches note content, validates expectedHash to prevent conflicts, performs search and replace using regex or literal matching, validates new content against note type rules, optionally creates a revision, and updates the note via Trilium API.
  export async function handleSearchReplaceNote( args: NoteOperation, axiosInstance: any ): Promise<NoteSearchReplaceResponse> { const { noteId, searchPattern, replacePattern, useRegex = true, searchFlags = 'g', revision = true, expectedHash } = args; if (!noteId) { throw new Error("noteId is required for search_and_replace operation."); } if (!searchPattern) { throw new Error("searchPattern is required for search_and_replace operation."); } if (!replacePattern) { throw new Error("replacePattern is required for search_and_replace operation."); } if (!expectedHash) { throw new Error("expectedHash is required for search_and_replace operation. You must call get_note first to retrieve the current blobId."); } let revisionCreated = false; try { // Step 1: Get current note state and content const currentNote = await axiosInstance.get(`/notes/${noteId}`); const currentContent = await axiosInstance.get(`/notes/${noteId}/content`, { responseType: 'text' }); // Step 2: Hash validation const currentBlobId = currentNote.data.blobId; if (currentBlobId !== expectedHash) { return { noteId, message: `CONFLICT: Note has been modified by another user. ` + `Current blobId: ${currentBlobId}, expected: ${expectedHash}. ` + `Please get the latest note content and retry.`, matchesFound: 0, replacementsMade: 0, revisionCreated: false, conflict: true, searchPattern, replacePattern, useRegex }; } const noteType = currentNote.data.type; const originalContent = currentContent.data; // Step 3: Execute search and replace const { newContent, replacements } = executeSearchReplace( originalContent, searchPattern, replacePattern, useRegex, searchFlags ); // Step 4: Handle no matches case if (replacements === 0) { return { noteId, message: `No matches found for pattern "${searchPattern}" in note ${noteId}. No changes made.`, matchesFound: 0, replacementsMade: 0, revisionCreated: false, conflict: false, searchPattern, replacePattern, useRegex }; } // Step 5: Validate new content based on note type const validationResult = await validateContentForNoteType( newContent, noteType as NoteType, originalContent ); if (!validationResult.valid) { return { noteId, message: `CONTENT_TYPE_MISMATCH: ${validationResult.error}`, matchesFound: replacements, replacementsMade: 0, revisionCreated: false, conflict: false, searchPattern, replacePattern, useRegex }; } // Use validated/corrected content const finalContent = validationResult.content; // Step 6: Create revision if requested if (revision) { try { await axiosInstance.post(`/notes/${noteId}/revision`); revisionCreated = true; } catch (error) { console.error(`Warning: Failed to create revision for note ${noteId}:`, error); // Continue with update even if revision creation fails } } // Step 7: Update content const contentResponse = await axiosInstance.put(`/notes/${noteId}/content`, finalContent, { headers: { "Content-Type": "text/plain" } }); if (contentResponse.status !== 204) { throw new Error(`Unexpected response status: ${contentResponse.status}`); } // Step 8: Return success response const correctionMsg = (finalContent !== newContent) ? " (content auto-corrected)" : ""; const revisionMsg = revisionCreated ? " (revision created)" : " (no revision)"; return { noteId, message: `Search and replace completed successfully for note ${noteId}. Found ${replacements} match(es) and made ${replacements} replacement(s).${correctionMsg}${revisionMsg}`, matchesFound: replacements, replacementsMade: replacements, revisionCreated, conflict: false, searchPattern, replacePattern, useRegex }; } catch (error) { if ((error as any).response?.status === 404) { throw new Error(`Note ${noteId} not found`); } throw error; } }
• src/modules/toolDefinitions.ts:142-181 (schema)

  Input schema definition for the search_and_replace_note tool, including parameters like noteId, searchPattern, replacePattern, useRegex, expectedHash, etc., with descriptions and validation rules.
  name: "search_and_replace_note", description: "Search and replace content within a single note. When someone wants to replace text in a note, first call get_note to get the current content and hash, then use this function to make the changes. This ensures you're working with the latest version of their note.", inputSchema: { type: "object", properties: { noteId: { type: "string", description: "ID of the note to perform search and replace on" }, searchPattern: { type: "string", description: "What to search for in the note.", }, replacePattern: { type: "string", description: "What to replace it with. For regex: supports patterns like '$1' for captured groups.", }, useRegex: { type: "boolean", description: "Whether to use regex patterns (default: true).", default: true }, searchFlags: { type: "string", description: "Search options. Defaults to 'gi' (global, case-insensitive). Remove 'i' for exact case matching.", default: "gi" }, expectedHash: { type: "string", description: "⚠️ REQUIRED: Content hash from get_note response. Always get the note content first to obtain this hash.", }, revision: { type: "boolean", description: "Whether to create a backup before replacing (default: true for safety).", default: true } }, required: ["noteId", "searchPattern", "replacePattern", "expectedHash"] } },
• src/index.ts:105-106 (registration)

  Registration of the search_and_replace_note tool in the MCP server's CallToolRequest handler switch statement, dispatching calls to the noteHandler's request handler function.
  case "search_and_replace_note": return await handleSearchReplaceNoteRequest(request.params.arguments, this.axiosInstance, this);
• src/modules/noteHandler.ts:310-367 (handler)

  MCP-specific request handler for search_and_replace_note. Performs permission checks, validates input parameters, constructs the NoteOperation object, calls the core handleSearchReplaceNote function, and formats the response in MCP content format.
  export async function handleSearchReplaceNoteRequest( args: any, axiosInstance: any, permissionChecker: PermissionChecker ): Promise<{ content: Array<{ type: string; text: string }> }> { if (!permissionChecker.hasPermission("WRITE")) { throw new McpError(ErrorCode.InvalidRequest, "Permission denied: Not authorized to modify notes."); } // Validate that expectedHash is provided (required for data integrity) if (!args.expectedHash) { throw new McpError( ErrorCode.InvalidParams, "Missing required parameter 'expectedHash'. You must call get_note first to retrieve the current blobId (content hash) before performing search and replace. This ensures data integrity by preventing overwriting changes made by other users." ); } // Validate required parameters if (!args.searchPattern) { throw new McpError( ErrorCode.InvalidParams, "Missing required parameter 'searchPattern'. The pattern to search for is required." ); } if (!args.replacePattern) { throw new McpError( ErrorCode.InvalidParams, "Missing required parameter 'replacePattern'. The replacement pattern is required." ); } try { const noteOperation: NoteOperation = { noteId: args.noteId, searchPattern: args.searchPattern, replacePattern: args.replacePattern, useRegex: args.useRegex !== false, // Default to true searchFlags: args.searchFlags || 'g', revision: args.revision !== false, // Default to true for safety expectedHash: args.expectedHash }; const result = await handleSearchReplaceNote(noteOperation, axiosInstance); return { content: [{ type: "text", text: result.message }] }; } catch (error) { if (error instanceof McpError) { throw error; } throw new McpError(ErrorCode.InvalidParams, error instanceof Error ? error.message : String(error)); } }
• src/modules/noteManager.ts:179-206 (helper)

  Helper function that executes the actual search and replace operation on note content using RegExp.replace, supporting both regex and escaped literal patterns.
  function executeSearchReplace( content: string, searchPattern: string, replacePattern: string, useRegex: boolean = true, flags: string = 'g' ): { newContent: string; replacements: number } { try { let newContent = content; let replacements = 0; if (useRegex) { // Regex-based replacement const regex = new RegExp(searchPattern, flags); replacements = (content.match(regex) || []).length; newContent = content.replace(regex, replacePattern); } else { // Literal string replacement const searchRegex = new RegExp(escapeRegExp(searchPattern), flags); replacements = (content.match(searchRegex) || []).length; newContent = content.replace(searchRegex, replacePattern); } return { newContent, replacements }; } catch (error) { throw new Error(`Search and replace failed: ${error instanceof Error ? error.message : String(error)}`); } }