v2.10.0 feat(search): add namespace prefix search for page titles

Add scope parameter to roam_search_by_text that enables searching for
pages by namespace prefix (e.g., "Convention/" finds all Convention/*
pages). Includes CLI --namespace flag and documentation updates.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Author: 2b3pro

.mcp.json

@@ -37,6 +37,9 @@ echo "Buy milk" | roam save --todo
 # Search your graph and pipe results to another tool
 roam search "important" --json | jq .
 
+# Search for pages by namespace prefix
+roam search --namespace "Convention"    # Finds all Convention/* pages
+
 # Fetch a page by title
 roam get "Roam Research"
 
@@ -84,7 +87,7 @@ The MCP server exposes these tools to AI assistants (like Claude), enabling them
 | `roam_fetch_block_with_children` | Fetch a block and its nested children by UID (resolves refs). |
 | `roam_create_page` | Create new pages, optionally with mixed text and table content. |
 | `roam_update_page_markdown` | Update a page using smart diff (preserves block UIDs). |
-| `roam_search_by_text` | Full-text search across the graph or within specific pages. |
+| `roam_search_by_text` | Full-text search across the graph or within specific pages. Supports namespace prefix search for page titles. |
 | `roam_search_block_refs` | Find blocks that reference a page, tag, or block UID. |
 | `roam_search_by_status` | Find TODO or DONE items. |
 | `roam_search_for_tag` | Find blocks containing specific tags (supports exclusion). |

README.md

@@ -1,6 +1,6 @@
 {
   "name": "roam-research-mcp",
-  "version": "2.9.1",
+  "version": "2.10.0",
   "description": "MCP server and CLI for Roam Research",
   "private": false,
   "repository": {

package.json

@@ -41,6 +41,7 @@ interface SearchOptions extends GraphOptions {
   regex?: string;
   regexFlags?: string;
   any?: boolean;
+  namespace?: string;
 }
 
 export function createSearchCommand(): Command {
@@ -67,12 +68,17 @@ export function createSearchCommand(): Command {
     .option('--inputs <json>', 'JSON array of inputs for Datalog query')
     .option('--regex <pattern>', 'Client-side regex filter on Datalog results')
     .option('--regex-flags <flags>', 'Regex flags (e.g., "i" for case-insensitive)')
+    .option('--namespace <prefix>', 'Search for pages by namespace prefix (e.g., "Convention" finds "Convention/*")')
     .addHelpText('after', `
 Examples:
   # Text search
   roam search "meeting notes"               # Find blocks containing text
   roam search api integration               # Multiple terms (AND logic)
 
+  # Namespace search (find pages by title prefix)
+  roam search --namespace Convention        # Find all Convention/* pages
+  roam search --namespace "Convention/"     # Same (trailing slash optional)
+
   # Stdin search
   echo "urgent project" | roam search       # Pipe terms
   roam get today | roam search TODO         # Search within output
@@ -89,7 +95,7 @@ Examples:
 
 Output format:
   Markdown: Flat results with UIDs and content (no hierarchy).
-  JSON:     [{ block_uid, content, page_title }]
+  JSON:     [{ block_uid, content, page_title }] or [{ page_uid, page_title }] for namespace
 
 Note: For hierarchical output with children, use 'roam get --tag/--text' instead.
 `)
@@ -121,6 +127,39 @@ Note: For hierarchical output with children, use 'roam get --tag/--text' instead
 
         const searchOps = new SearchOperations(graph);
 
+        // Namespace search mode (search page titles by prefix)
+        if (options.namespace) {
+          const result = await searchOps.searchByText({
+            text: options.namespace,
+            scope: 'page_titles'
+          });
+
+          if (!result.success) {
+            exitWithError(result.message || 'Namespace search failed');
+          }
+
+          let matches = result.matches.slice(0, limit);
+
+          if (options.json) {
+            // For JSON output, return page_uid and page_title
+            const jsonMatches = matches.map(m => ({
+              page_uid: m.block_uid,
+              page_title: m.page_title
+            }));
+            console.log(JSON.stringify(jsonMatches, null, 2));
+          } else {
+            if (matches.length === 0) {
+              console.log('No pages found.');
+            } else {
+              console.log(`Found ${result.matches.length} page(s)${result.matches.length > limit ? ` (showing first ${limit})` : ''}:\n`);
+              for (const match of matches) {
+                console.log(`- ${match.page_title} (${match.block_uid})`);
+              }
+            }
+          }
+          return;
+        }
+
         // Datalog query mode (bypasses other search options)
         if (options.query) {
           // Parse inputs if provided

src/cli/commands/search.ts

@@ -13,7 +13,12 @@ export class TextSearchHandler extends BaseSearchHandler {
   }
 
   async execute(): Promise<SearchResult> {
-    const { text, page_title_uid, case_sensitive = false, limit = -1, offset = 0 } = this.params;
+    const { text, page_title_uid, case_sensitive = false, limit = -1, offset = 0, scope = 'blocks' } = this.params;
+
+    // Handle page_titles scope (namespace search)
+    if (scope === 'page_titles') {
+      return this.executePageTitleSearch();
+    }
 
     // Get target page UID if provided for scoped search
     let targetPageUid: string | undefined;
@@ -104,4 +109,54 @@ export class TextSearchHandler extends BaseSearchHandler {
     formattedResults.total_count = totalCount;
     return formattedResults;
   }
+
+  /**
+   * Search for page titles matching a namespace prefix.
+   * Normalizes the search text to ensure trailing slash for prefix matching.
+   */
+  private async executePageTitleSearch(): Promise<SearchResult> {
+    const { text, limit = -1, offset = 0 } = this.params;
+
+    // Normalize namespace: ensure trailing slash for prefix matching
+    const namespace = text.endsWith('/') ? text : `${text}/`;
+
+    // Query for pages with titles starting with the namespace
+    const queryLimit = limit === -1 ? '' : `:limit ${limit}`;
+    const queryOffset = offset === 0 ? '' : `:offset ${offset}`;
+
+    const queryStr = `[:find ?title ?uid
+                      :in $ ${queryLimit} ${queryOffset}
+                      :where
+                      [?e :node/title ?title]
+                      [?e :block/uid ?uid]
+                      [(clojure.string/starts-with? ?title "${namespace}")]]`;
+
+    const rawResults = await q(this.graph, queryStr, []) as [string, string][];
+
+    // Get total count
+    const countQueryStr = `[:find (count ?e)
+                           :in $
+                           :where
+                           [?e :node/title ?title]
+                           [(clojure.string/starts-with? ?title "${namespace}")]]`;
+    const totalCountResults = await q(this.graph, countQueryStr, []) as number[][];
+    const totalCount = totalCountResults[0] ? totalCountResults[0][0] : 0;
+
+    // Format results: page UID as block_uid, title as content
+    const matches = rawResults.map(([title, uid]) => ({
+      block_uid: uid,
+      content: title,
+      page_title: title
+    }));
+
+    // Sort alphabetically by title
+    matches.sort((a, b) => a.content.localeCompare(b.content));
+
+    return {
+      success: true,
+      matches,
+      message: `Found ${matches.length} page(s) with namespace "${namespace}"`,
+      total_count: totalCount
+    };
+  }
 }

src/search/text-search.ts

@@ -39,6 +39,7 @@ export interface TextSearchParams {
   case_sensitive?: boolean;
   limit?: number;
   offset?: number;
+  scope?: 'blocks' | 'page_titles';
 }
 
 // Base class for all search handlers

src/search/types.ts

@@ -333,6 +333,7 @@ export class RoamServer {
             const params = cleanedArgs as {
               text: string;
               page_title_uid?: string;
+              scope?: 'blocks' | 'page_titles';
             };
             const result = await toolHandlers.searchByText(params);
             return {

src/server/roam-server.ts

@@ -36,6 +36,7 @@ export interface HierarchySearchParams extends BaseSearchParams {
 // Text search parameters
 export interface TextSearchParams extends BaseSearchParams {
   text: string;
+  scope?: 'blocks' | 'page_titles';
 }
 
 // Status search parameters

src/tools/operations/search/types.ts

@@ -361,21 +361,27 @@ export const toolSchemas = {
   },
   roam_search_by_text: {
     name: 'roam_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.',
+    description: 'Search for blocks containing specific text across all pages or within a specific page. Use `scope: "page_titles"` to search for pages by namespace prefix (e.g., "Convention/" finds all pages starting with that prefix). This tool supports pagination via the `limit` and `offset` parameters.',
     inputSchema: {
       type: 'object',
       properties: withMultiGraphParams({
         text: {
           type: 'string',
-          description: 'The text to search for'
+          description: 'The text to search for. When scope is "page_titles", this is the namespace prefix (trailing slash optional).'
+        },
+        scope: {
+          type: 'string',
+          enum: ['blocks', 'page_titles'],
+          default: 'blocks',
+          description: 'Search scope: "blocks" for block content (default), "page_titles" for page title namespace prefix matching.'
         },
         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.'
+          description: 'Optional: Title or UID of the page to search in (UID is preferred for accuracy). If not provided, searches across all pages. Only used when scope is "blocks".'
         },
         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.',
+          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. Only used when scope is "blocks".',
           default: false
         },
         limit: {

src/tools/schemas.ts

@@ -93,6 +93,7 @@ export class ToolHandlers {
   async searchByText(params: {
     text: string;
     page_title_uid?: string;
+    scope?: 'blocks' | 'page_titles';
   }) {
     return this.searchOps.searchByText(params);
   }