RushDB

Instructions

Implementation Reference

• tools/FindRecords.ts:17-45 (handler)

  The main handler function that executes the tool logic: constructs a search query from parameters and queries the database for records, handling aggregation and grouping specially.

  export async function FindRecords(params: {
    labels?: string[]
    where?: Record<string, any>
    limit?: number
    skip?: number
    orderBy?: Record<string, 'asc' | 'desc'>
    aggregate?: Record<string, { fn: string; field?: string; alias?: string; where?: any }>
    groupBy?: string[]
  }) {
    const { labels, where, limit = 10, skip = 0, orderBy, aggregate, groupBy } = params
  
    const searchQuery: any = {}
    if (labels && labels.length > 0) searchQuery.labels = labels
    if (where) searchQuery.where = where
    if (limit) searchQuery.limit = limit
    if (skip) searchQuery.skip = skip
    if (orderBy && Object.keys(orderBy).length > 0) searchQuery.orderBy = orderBy
    if (aggregate && Object.keys(aggregate).length > 0) searchQuery.aggregate = aggregate
    if (groupBy && groupBy.length > 0) searchQuery.groupBy = groupBy
  
    const result = await db.records.find(searchQuery)
  
    // If aggregation present, return raw response so caller gets aggregates.
    if (searchQuery.aggregate || searchQuery.groupBy) {
      return result
    }
  
    return result.data.map((record: any) => record.data)
  }

• tools.ts:116-158 (schema)

  Defines the input schema and description for the FindRecords tool, used for validation in the MCP server.

    name: 'FindRecords',
    description: 'Find records in the database using a search query',
    inputSchema: {
      type: 'object',
      properties: {
        labels: { type: 'array', items: { type: 'string' }, description: 'Filter by record labels' },
        where: { type: 'object', description: 'Search conditions for finding records' },
        limit: { type: 'number', description: 'Maximum number of records to return', default: 10 },
        skip: { type: 'number', description: 'Number of records to skip', default: 0 },
        orderBy: {
          type: 'object',
          description: 'Sorting configuration: key = field, value = asc|desc',
          additionalProperties: { type: 'string', enum: ['asc', 'desc'] }
        },
        aggregate: {
          type: 'object',
          description: 'Aggregation definitions (records only)',
          additionalProperties: {
            type: 'object',
            properties: {
              fn: {
                type: 'string',
                description: 'Aggregation function (count,sum,avg,min,max,timeBucket)'
              },
              field: { type: 'string', description: 'Field to aggregate' },
              alias: { type: 'string', description: 'Optional alias override' },
              granularity: {
                type: 'string',
                description: 'For timeBucket, the time granularity (e.g., day, week, month, quarter, year)'
              }
            },
            required: ['fn']
          }
        },
        groupBy: {
          type: 'array',
          items: { type: 'string' },
          description: 'Fields to group by (records only)'
        }
      },
      required: []
    }
  },

• index.ts:72-76 (registration)

  Registers the list of tools including FindRecords for the MCP ListTools request.

  server.setRequestHandler(ListToolsRequestSchema, async () => {
    return {
      tools
    }
  })

• index.ts:182-206 (registration)

  Dispatches the tool call to the FindRecords handler function in the MCP CallTool request handler.

  case 'FindRecords':
    const foundRecords = await FindRecords({
      labels: args.labels as string[] | undefined,
      where: args.where as Record<string, any> | undefined,
      limit: args.limit as number | undefined,
      skip: args.skip as number | undefined,
      orderBy: args.orderBy as Record<string, 'asc' | 'desc'> | undefined,
      aggregate: args.aggregate as
        | Record<string, { fn: string; field?: string; alias?: string; where?: any }>
        | undefined,
      groupBy: args.groupBy as string[] | undefined
    })
  
    const isAggregate = Boolean(args.aggregate) || Boolean(args.groupBy)
    return {
      content: [
        {
          type: 'text',
          text:
            Array.isArray(foundRecords) && foundRecords.length === 0 ?
              'No matching records found.'
            : JSON.stringify(foundRecords, null, 2)
        }
      ]
    }

• index.ts:30-30 (registration)

  Imports the FindRecords handler function for use in the main server.

  import { FindRecords } from './tools/FindRecords.js'