Roam Research MCP Server

Instructions

Implementation Reference

• src/search/block-ref-search.ts:20-92 (handler)

  Core handler logic: Executes Datomic queries to find blocks referencing a specific block UID or containing any block references ((uid)) within a page or graph-wide. Resolves embedded references and formats results.
  async execute(): Promise<SearchResult> { const { block_uid, page_title_uid } = this.params; // Get target page UID if provided let targetPageUid: string | undefined; if (page_title_uid) { targetPageUid = await SearchUtils.findPageByTitleOrUid(this.graph, page_title_uid); } // Build query based on whether we're searching for references to a specific block // or all block references within a page/graph let queryStr: string; let queryParams: any[]; if (block_uid) { // Search for references to a specific block if (targetPageUid) { queryStr = `[:find ?block-uid ?block-str :in $ ?ref-uid ?page-uid :where [?p :block/uid ?page-uid] [?b :block/page ?p] [?b :block/string ?block-str] [?b :block/uid ?block-uid] [(clojure.string/includes? ?block-str ?ref-uid)]]`; queryParams = [`((${block_uid}))`, targetPageUid]; } else { queryStr = `[:find ?block-uid ?block-str ?page-title :in $ ?ref-uid :where [?b :block/string ?block-str] [?b :block/uid ?block-uid] [?b :block/page ?p] [?p :node/title ?page-title] [(clojure.string/includes? ?block-str ?ref-uid)]]`; queryParams = [`((${block_uid}))`]; } } else { // Search for any block references if (targetPageUid) { queryStr = `[:find ?block-uid ?block-str :in $ ?page-uid :where [?p :block/uid ?page-uid] [?b :block/page ?p] [?b :block/string ?block-str] [?b :block/uid ?block-uid] [(re-find #"\\(\\([^)]+\\)\\)" ?block-str)]]`; queryParams = [targetPageUid]; } else { queryStr = `[:find ?block-uid ?block-str ?page-title :where [?b :block/string ?block-str] [?b :block/uid ?block-uid] [?b :block/page ?p] [?p :node/title ?page-title] [(re-find #"\\(\\([^)]+\\)\\)" ?block-str)]]`; queryParams = []; } } const rawResults = await q(this.graph, queryStr, queryParams) as [string, string, string?][]; // 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 = block_uid ? `referencing block ((${block_uid}))` : 'containing block references'; return SearchUtils.formatSearchResults(resolvedResults, searchDescription, !targetPageUid); }
• src/tools/schemas.ts:269-285 (schema)

  Defines the tool schema including name, description, and input schema for 'roam_search_block_refs'.
  [toolName(BASE_TOOL_NAMES.SEARCH_BLOCK_REFS)]: { name: toolName(BASE_TOOL_NAMES.SEARCH_BLOCK_REFS), description: 'Search for block references within a page or across the entire graph. Can search for references to a specific block or find all block references.', inputSchema: { type: 'object', properties: { block_uid: { type: 'string', description: 'Optional: UID of the block to find references to' }, 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.' } } } },
• src/server/roam-server.ts:238-247 (registration)

  Registers the tool handler in the MCP server request handler switch statement, delegating to ToolHandlers.searchBlockRefs.
  case BASE_TOOL_NAMES.SEARCH_BLOCK_REFS: { const params = request.params.arguments as { block_uid?: string; page_title_uid?: string; }; const result = await this.toolHandlers.searchBlockRefs(params); return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }], }; }
• src/tools/tool-handlers.ts:73-75 (helper)

  Wrapper method in ToolHandlers class that delegates to SearchOperations.searchBlockRefs.
  async searchBlockRefs(params: { block_uid?: string; page_title_uid?: string }) { return this.searchOps.searchBlockRefs(params); }
• src/tools/operations/search/index.ts:82-85 (helper)

  Method in SearchOperations class that instantiates and executes BlockRefSearchHandlerImpl.
  async searchBlockRefs(params: BlockRefSearchParams): Promise<SearchHandlerResult> { const handler = new BlockRefSearchHandlerImpl(this.graph, params); return handler.execute(); }