Roam Research MCP Server

Instructions

Implementation Reference

• src/tools/operations/block-retrieval.ts:8-89 (handler)

  Implements the core logic to fetch a Roam block by UID and its children recursively up to a specified depth using Datomic queries on the Roam graph.

  async fetchBlockWithChildren(block_uid_raw: string, depth: number = 4): Promise<RoamBlock | null> {
    if (!block_uid_raw) {
      throw new McpError(ErrorCode.InvalidRequest, 'block_uid is required.');
    }
  
    const block_uid = block_uid_raw.replace(/^\(\((.*)\)\)$/, '$1');
  
    const fetchChildren = async (parentUids: string[], currentDepth: number): Promise<Record<string, RoamBlock[]>> => {
      if (currentDepth >= depth || parentUids.length === 0) {
        return {};
      }
  
      const childrenQuery = `[:find ?parentUid ?childUid ?childString ?childOrder ?childHeading
                              :in $ [?parentUid ...]
                              :where [?parent :block/uid ?parentUid]
                                     [?parent :block/children ?child]
                                     [?child :block/uid ?childUid]
                                     [?child :block/string ?childString]
                                     [?child :block/order ?childOrder]
                                     [(get-else $ ?child :block/heading 0) ?childHeading]]`;
  
      const childrenResults = await q(this.graph, childrenQuery, [parentUids]) as [string, string, string, number, number | null][];
  
      const childrenByParent: Record<string, RoamBlock[]> = {};
      const allChildUids: string[] = [];
  
      for (const [parentUid, childUid, childString, childOrder, childHeading] of childrenResults) {
        if (!childrenByParent[parentUid]) {
          childrenByParent[parentUid] = [];
        }
        childrenByParent[parentUid].push({
          uid: childUid,
          string: childString,
          order: childOrder,
          heading: childHeading || undefined,
          children: [],
        });
        allChildUids.push(childUid);
      }
  
      const grandChildren = await fetchChildren(allChildUids, currentDepth + 1);
  
      for (const parentUid in childrenByParent) {
        for (const child of childrenByParent[parentUid]) {
          child.children = grandChildren[child.uid] || [];
        }
        childrenByParent[parentUid].sort((a, b) => a.order - b.order);
      }
  
      return childrenByParent;
    };
  
    try {
      const rootBlockQuery = `[:find ?string ?order ?heading
                               :in $ ?blockUid
                               :where [?b :block/uid ?blockUid]
                                      [?b :block/string ?string]
                                      [?b :block/order ?order]
                                      [(get-else $ ?b :block/heading 0) ?heading]]`;
      const rootBlockResult = await q(this.graph, rootBlockQuery, [block_uid]) as [string, number, number | null] | null;
  
      if (!rootBlockResult) {
        return null;
      }
  
      const [rootString, rootOrder, rootHeading] = rootBlockResult;
      const childrenMap = await fetchChildren([block_uid], 0);
  
      return {
        uid: block_uid,
        string: rootString,
        order: rootOrder,
        heading: rootHeading || undefined,
        children: childrenMap[block_uid] || [],
      };
    } catch (error) {
      throw new McpError(
        ErrorCode.InternalError,
        `Failed to fetch block with children: ${error instanceof Error ? error.message : String(error)}`
      );
    }
  }

• src/tools/schemas.ts:556-575 (schema)

  Defines the input schema, description, and name for the 'roam_fetch_block_with_children' tool.

  [toolName(BASE_TOOL_NAMES.FETCH_BLOCK_WITH_CHILDREN)]: {
    name: toolName(BASE_TOOL_NAMES.FETCH_BLOCK_WITH_CHILDREN),
    description: 'Fetch a block by its UID along with its hierarchical children down to a specified depth. Returns a nested object structure containing the block\'s UID, text, order, and an array of its children.',
    inputSchema: {
      type: 'object',
      properties: {
        block_uid: {
          type: 'string',
          description: 'The UID of the block to fetch.'
        },
        depth: {
          type: 'integer',
          description: 'Optional: The number of levels deep to fetch children. Defaults to 4.',
          minimum: 0,
          maximum: 10
        }
      },
      required: ['block_uid']
    },
  },

• src/server/roam-server.ts:340-349 (registration)

  Registers the tool by handling the CallToolRequest in the MCP server, dispatching to ToolHandlers.fetchBlockWithChildren based on the base tool name.

  case BASE_TOOL_NAMES.FETCH_BLOCK_WITH_CHILDREN: {
    const { block_uid, depth } = request.params.arguments as {
      block_uid: string;
      depth?: number;
    };
    const result = await this.toolHandlers.fetchBlockWithChildren(block_uid, depth);
    return {
      content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
    };
  }