Roam Research MCP Server

Instructions

Implementation Reference

• src/search/datomic-search.ts:14-82 (handler)

  The core handler implementation for executing custom Datomic queries on the Roam graph, including optional client-side regex filtering on results.

  export class DatomicSearchHandler extends BaseSearchHandler {
    constructor(
      graph: Graph,
      private params: DatomicSearchParams
    ) {
      super(graph);
    }
  
    async execute(): Promise<SearchResult> {
      try {
        // Execute the datomic query using the Roam API
        let results = await q(this.graph, this.params.query, this.params.inputs || []) as unknown[];
  
        if (this.params.regexFilter) {
          let regex: RegExp;
          try {
            regex = new RegExp(this.params.regexFilter, this.params.regexFlags);
          } catch (e) {
            return {
              success: false,
              matches: [],
              message: `Invalid regex filter provided: ${e instanceof Error ? e.message : String(e)}`
            };
          }
  
          results = results.filter(result => {
            if (this.params.regexTargetField && this.params.regexTargetField.length > 0) {
              for (const field of this.params.regexTargetField) {
                // Access nested fields if path is provided (e.g., "prop.nested")
                const fieldPath = field.split('.');
                let value: any = result;
                for (const part of fieldPath) {
                  if (typeof value === 'object' && value !== null && part in value) {
                    value = value[part];
                  } else {
                    value = undefined; // Field not found
                    break;
                  }
                }
                if (typeof value === 'string' && regex.test(value)) {
                  return true;
                }
              }
              return false;
            } else {
              // Default to stringifying the whole result if no target field is specified
              return regex.test(JSON.stringify(result));
            }
          });
        }
  
        return {
          success: true,
          matches: results.map(result => ({
            content: JSON.stringify(result),
            block_uid: '', // Datomic queries may not always return block UIDs
            page_title: '' // Datomic queries may not always return page titles
          })),
          message: `Query executed successfully. Found ${results.length} results.`
        };
      } catch (error) {
        return {
          success: false,
          matches: [],
          message: `Failed to execute query: ${error instanceof Error ? error.message : String(error)}`
        };
      }
    }
  }

• src/tools/schemas.ts:454-489 (schema)

  The tool schema defining the name, description, and input validation for roam_datomic_query.

  [toolName(BASE_TOOL_NAMES.DATOMIC_QUERY)]: {
    name: toolName(BASE_TOOL_NAMES.DATOMIC_QUERY),
    description: 'Execute a custom Datomic query on the Roam graph for advanced data retrieval beyond the available search tools. This provides direct access to Roam\'s query engine. Note: Roam graph is case-sensitive.\n\n__Optimal Use Cases for `roam_datomic_query`:__\n- __Advanced Filtering (including Regex):__ Use for scenarios requiring complex filtering, including regex matching on results post-query, which Datalog does not natively support for all data types. It can fetch broader results for client-side post-processing.\n- __Highly Complex Boolean Logic:__ Ideal for intricate combinations of "AND", "OR", and "NOT" conditions across multiple terms or attributes.\n- __Arbitrary Sorting Criteria:__ The go-to for highly customized sorting needs beyond default options.\n- __Proximity Search:__ For advanced search capabilities involving proximity, which are difficult to implement efficiently with simpler tools.\n\nList of some of Roam\'s data model Namespaces and Attributes: ancestor (descendants), attrs (lookup), block (children, heading, open, order, page, parents, props, refs, string, text-align, uid), children (view-type), create (email, time), descendant (ancestors), edit (email, seen-by, time), entity (attrs), log (id), node (title), page (uid, title), refs (text).\nPredicates (clojure.string/includes?, clojure.string/starts-with?, clojure.string/ends-with?, <, >, <=, >=, =, not=, !=).\nAggregates (distinct, count, sum, max, min, avg, limit).\nTips: Use :block/parents for all ancestor levels, :block/children for direct descendants only; combine clojure.string for complex matching, use distinct to deduplicate, leverage Pull patterns for hierarchies, handle case-sensitivity carefully, and chain ancestry rules for multi-level queries.',
    inputSchema: {
      type: 'object',
      properties: {
        query: {
          type: 'string',
          description: 'The Datomic query to execute (in Datalog syntax). Example: `[:find ?block-string :where [?block :block/string ?block-string] (or [(clojure.string/includes? ?block-string "hypnosis")] [(clojure.string/includes? ?block-string "trance")] [(clojure.string/includes? ?block-string "suggestion")]) :limit 25]`'
        },
        inputs: {
          type: 'array',
          description: 'Optional array of input parameters for the query',
          items: {
            type: 'string'
          }
        },
        regexFilter: {
          type: 'string',
          description: 'Optional: A regex pattern to filter the results client-side after the Datomic query. Applied to JSON.stringify(result) or specific fields if regexTargetField is provided.'
        },
        regexFlags: {
          type: 'string',
          description: 'Optional: Flags for the regex filter (e.g., "i" for case-insensitive, "g" for global).',
        },
        regexTargetField: {
          type: 'array',
          items: {
            type: 'string'
          },
          description: 'Optional: An array of field paths (e.g., ["block_string", "page_title"]) within each Datomic result object to apply the regex filter to. If not provided, the regex is applied to the stringified full result.'
        }
      },
      required: ['query']
    }
  },

• src/server/roam-server.ts:319-328 (registration)

  Registration and dispatch logic in the MCP server\'s tool call handler that routes calls to roam_datomic_query to the appropriate handler method.

  case BASE_TOOL_NAMES.DATOMIC_QUERY: {
    const { query, inputs } = request.params.arguments as {
      query: string;
      inputs?: unknown[];
    };
    const result = await this.toolHandlers.executeDatomicQuery({ query, inputs });
    return {
      content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
    };
  }

• src/tools/tool-handlers.ts:103-107 (handler)

  Intermediate handler method in ToolHandlers class that instantiates and calls the DatomicSearchHandlerImpl.

  // Datomic query
  async executeDatomicQuery(params: { query: string; inputs?: unknown[] }) {
    const handler = new DatomicSearchHandlerImpl(this.graph, params);
    return handler.execute();
  }

• src/tools/schemas.ts:24-24 (registration)

  Definition of the base tool name constant used for handler routing and registration.

  DATOMIC_QUERY: 'roam_datomic_query',