roam_search_hierarchy

Instructions

Implementation Reference

• src/search/hierarchy-search.ts:14-126 (handler)

  Core implementation of the roam_search_hierarchy tool. Executes Datomic queries to retrieve either descendants (children hierarchy) of a parent_uid or ancestors (parent hierarchy) of a child_uid, optionally limited to a specific page. Resolves block references in content and includes depth information.

  export class HierarchySearchHandler extends BaseSearchHandler {
    constructor(
      graph: Graph,
      private params: HierarchySearchParams
    ) {
      super(graph);
    }
  
    async execute(): Promise<SearchResult> {
      const { parent_uid, child_uid, page_title_uid, max_depth = 1 } = this.params;
  
      if (!parent_uid && !child_uid) {
        return {
          success: false,
          matches: [],
          message: 'Either parent_uid or child_uid must be provided'
        };
      }
  
      // Get target page UID if provided
      let targetPageUid: string | undefined;
      if (page_title_uid) {
        targetPageUid = await SearchUtils.findPageByTitleOrUid(this.graph, page_title_uid);
      }
  
      // Define ancestor rule for recursive traversal
      const ancestorRule = `[
        [ (ancestor ?child ?parent) 
            [?parent :block/children ?child] ]
        [ (ancestor ?child ?a) 
            [?parent :block/children ?child] 
            (ancestor ?parent ?a) ]
      ]`;
  
      let queryStr: string;
      let queryParams: any[];
  
      if (parent_uid) {
        // Search for all descendants using ancestor rule
        if (targetPageUid) {
          queryStr = `[:find ?block-uid ?block-str ?depth
                      :in $ % ?parent-uid ?page-uid
                      :where [?p :block/uid ?page-uid]
                             [?parent :block/uid ?parent-uid]
                             (ancestor ?b ?parent)
                             [?b :block/string ?block-str]
                             [?b :block/uid ?block-uid]
                             [?b :block/page ?p]
                             [(get-else $ ?b :block/path-length 1) ?depth]]`;
          queryParams = [ancestorRule, parent_uid, targetPageUid];
        } else {
          queryStr = `[:find ?block-uid ?block-str ?page-title ?depth
                      :in $ % ?parent-uid
                      :where [?parent :block/uid ?parent-uid]
                             (ancestor ?b ?parent)
                             [?b :block/string ?block-str]
                             [?b :block/uid ?block-uid]
                             [?b :block/page ?p]
                             [?p :node/title ?page-title]
                             [(get-else $ ?b :block/path-length 1) ?depth]]`;
          queryParams = [ancestorRule, parent_uid];
        }
      } else {
        // Search for ancestors using the same rule
        if (targetPageUid) {
          queryStr = `[:find ?block-uid ?block-str ?depth
                      :in $ % ?child-uid ?page-uid
                      :where [?p :block/uid ?page-uid]
                             [?child :block/uid ?child-uid]
                             (ancestor ?child ?b)
                             [?b :block/string ?block-str]
                             [?b :block/uid ?block-uid]
                             [?b :block/page ?p]
                             [(get-else $ ?b :block/path-length 1) ?depth]]`;
          queryParams = [ancestorRule, child_uid, targetPageUid];
        } else {
          queryStr = `[:find ?block-uid ?block-str ?page-title ?depth
                      :in $ % ?child-uid
                      :where [?child :block/uid ?child-uid]
                             (ancestor ?child ?b)
                             [?b :block/string ?block-str]
                             [?b :block/uid ?block-uid]
                             [?b :block/page ?p]
                             [?p :node/title ?page-title]
                             [(get-else $ ?b :block/path-length 1) ?depth]]`;
          queryParams = [ancestorRule, child_uid];
        }
      }
  
      const rawResults = await q(this.graph, queryStr, queryParams) as [string, string, string?, number?][];
      
      // Resolve block references and format results to include depth information
      const matches = await Promise.all(rawResults.map(async ([uid, content, pageTitle, depth]) => {
        const resolvedContent = await resolveRefs(this.graph, content);
        return {
          block_uid: uid,
          content: resolvedContent,
          depth: depth || 1,
          ...(pageTitle && { page_title: pageTitle })
        };
      }));
  
      const searchDescription = parent_uid
        ? `descendants of block ${parent_uid}`
        : `ancestors of block ${child_uid}`;
  
      return {
        success: true,
        matches,
        message: `Found ${matches.length} block(s) as ${searchDescription}`
      };
    }
  }

• src/tools/schemas.ts:286-313 (schema)

  Input schema definition for the roam_search_hierarchy tool, including parameters for searching hierarchy up or down from a block.

  [toolName(BASE_TOOL_NAMES.SEARCH_HIERARCHY)]: {
    name: toolName(BASE_TOOL_NAMES.SEARCH_HIERARCHY),
    description: 'Search for parent or child blocks in the block hierarchy. Can search up or down the hierarchy from a given block.',
    inputSchema: {
      type: 'object',
      properties: {
        parent_uid: {
          type: 'string',
          description: 'Optional: UID of the block to find children of'
        },
        child_uid: {
          type: 'string',
          description: 'Optional: UID of the block to find parents of'
        },
        page_title_uid: {
          type: 'string',
          description: 'Optional: Title or UID of the page to search in (UID is preferred for accuracy).'
        },
        max_depth: {
          type: 'integer',
          description: 'Optional: How many levels deep to search (default: 1)',
          minimum: 1,
          maximum: 10
        }
      }
      // Note: Validation for either parent_uid or child_uid is handled in the server code
    }
  },

• src/server/roam-server.ts:249-269 (registration)

  MCP tool registration and dispatching for roam_search_hierarchy in the server request handler, including input validation.

  case BASE_TOOL_NAMES.SEARCH_HIERARCHY: {
    const params = request.params.arguments as {
      parent_uid?: string;
      child_uid?: string;
      page_title_uid?: string;
      max_depth?: number;
    };
  
    // Validate that either parent_uid or child_uid is provided, but not both
    if ((!params.parent_uid && !params.child_uid) || (params.parent_uid && params.child_uid)) {
      throw new McpError(
        ErrorCode.InvalidRequest,
        'Either parent_uid or child_uid must be provided, but not both'
      );
    }
  
    const result = await this.toolHandlers.searchHierarchy(params);
    return {
      content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
    };
  }

• src/tools/tool-handlers.ts:77-84 (registration)

  Tool handler wrapper method that delegates to SearchOperations.searchHierarchy

  async searchHierarchy(params: {
    parent_uid?: string;
    child_uid?: string;
    page_title_uid?: string;
    max_depth?: number;
  }) {
    return this.searchOps.searchHierarchy(params);
  }

• src/tools/schemas.ts:17-17 (helper)

  Constant definition for the base tool name 'roam_search_hierarchy' used in schema and registration.

  SEARCH_HIERARCHY: 'roam_search_hierarchy',