Roam Research MCP Server

Instructions

Implementation Reference

• src/search/text-search.ts:7-92 (handler)

  Core handler class TextSearchHandler that executes the roam_search_by_text tool logic using Datomic queries to find blocks matching the text (case-insensitive variations), scoped to optional page, with pagination, resolves block refs, and formats results.
  export class TextSearchHandler extends BaseSearchHandler { constructor( graph: Graph, private params: TextSearchParams ) { super(graph); } async execute(): Promise<SearchResult> { const { text, page_title_uid, case_sensitive = false, limit = -1, offset = 0 } = this.params; // Get target page UID if provided for scoped search let targetPageUid: string | undefined; if (page_title_uid) { targetPageUid = await SearchUtils.findPageByTitleOrUid(this.graph, page_title_uid); } const searchTerms: string[] = []; if (case_sensitive) { searchTerms.push(text); } else { searchTerms.push(text); // Add capitalized version (e.g., "Hypnosis") searchTerms.push(text.charAt(0).toUpperCase() + text.slice(1)); // Add all caps version (e.g., "HYPNOSIS") searchTerms.push(text.toUpperCase()); // Add all lowercase version (e.g., "hypnosis") searchTerms.push(text.toLowerCase()); } const whereClauses = searchTerms.map(term => `[(clojure.string/includes? ?block-str "${term}")]`).join(' '); let queryStr: string; let queryParams: (string | number)[] = []; let queryLimit = limit === -1 ? '' : `:limit ${limit}`; let queryOffset = offset === 0 ? '' : `:offset ${offset}`; let queryOrder = `:order ?page-edit-time asc ?block-uid asc`; // Sort by page edit time, then block UID let baseQueryWhereClauses = ` [?b :block/string ?block-str] (or ${whereClauses}) [?b :block/uid ?block-uid] [?b :block/page ?p] [?p :node/title ?page-title] [?p :edit/time ?page-edit-time]`; // Fetch page edit time for sorting if (targetPageUid) { queryStr = `[:find ?block-uid ?block-str ?page-title :in $ ?page-uid ${queryLimit} ${queryOffset} ${queryOrder} :where ${baseQueryWhereClauses} [?p :block/uid ?page-uid]]`; queryParams = [targetPageUid]; } else { queryStr = `[:find ?block-uid ?block-str ?page-title :in $ ${queryLimit} ${queryOffset} ${queryOrder} :where ${baseQueryWhereClauses}]`; } const rawResults = await q(this.graph, queryStr, queryParams) as [string, string, string?][]; // Query to get total count without limit const countQueryStr = `[:find (count ?b) :in $ :where ${baseQueryWhereClauses.replace(/\[\?p :edit\/time \?page-edit-time\]/, '')}]`; // Remove edit time for count query const totalCountResults = await q(this.graph, countQueryStr, queryParams) as number[][]; const totalCount = totalCountResults[0] ? totalCountResults[0][0] : 0; // Resolve block references in content const resolvedResults = await Promise.all( rawResults.map(async ([uid, content, pageTitle]) => { const resolvedContent = await resolveRefs(this.graph, content); return [uid, resolvedContent, pageTitle] as [string, string, string?]; }) ); const searchDescription = `containing "${text}"`; const formattedResults = SearchUtils.formatSearchResults(resolvedResults, searchDescription, !targetPageUid); formattedResults.total_count = totalCount; return formattedResults; } }
• src/tools/schemas.ts:339-371 (schema)

  JSON schema defining the input parameters and description for the 'roam_search_by_text' tool.
  [toolName(BASE_TOOL_NAMES.SEARCH_BY_TEXT)]: { name: toolName(BASE_TOOL_NAMES.SEARCH_BY_TEXT), description: 'Search for blocks containing specific text across all pages or within a specific page. This tool supports pagination via the `limit` and `offset` parameters.', inputSchema: { type: 'object', properties: { text: { type: 'string', description: 'The text to search for' }, page_title_uid: { type: 'string', description: 'Optional: Title or UID of the page to search in (UID is preferred for accuracy). If not provided, searches across all pages.' }, case_sensitive: { type: 'boolean', description: 'Optional: Whether the search should be case-sensitive. If false, it will search for the provided text, capitalized versions, and first word capitalized versions.', default: false }, limit: { type: 'integer', description: 'Optional: The maximum number of results to return. Defaults to 50. Use -1 for no limit, but be aware that very large results sets can impact performance.', default: 50 }, offset: { type: 'integer', description: 'Optional: The number of results to skip before returning matches. Useful for pagination. Defaults to 0.', default: 0 } }, required: ['text'] } },
• src/server/roam-server.ts:281-290 (registration)

  Registration and dispatching logic in the MCP server that routes calls to 'roam_search_by_text' to the ToolHandlers.searchByText method.
  case BASE_TOOL_NAMES.SEARCH_BY_TEXT: { const params = request.params.arguments as { text: string; page_title_uid?: string; }; const result = await this.toolHandlers.searchByText(params); return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }], }; }
• src/tools/tool-handlers.ts:86-91 (registration)

  ToolHandlers class method that delegates 'searchByText' calls to SearchOperations.
  async searchByText(params: { text: string; page_title_uid?: string; }) { return this.searchOps.searchByText(params); }
• src/tools/operations/search/index.ts:92-95 (registration)

  SearchOperations class method that instantiates and executes TextSearchHandlerImpl for text search.
  async searchByText(params: TextSearchParams): Promise<SearchHandlerResult> { const handler = new TextSearchHandlerImpl(this.graph, params); return handler.execute(); }