query

Instructions

Implementation Reference

• src/tools/query.ts:52-83 (handler)

  The asynchronous handler function for the 'query' tool. It uses the NocoDBClient to list records with provided filters, sorting, fields, limit, and offset, then returns the records, page info, count, and query parameters.

  handler: async (
    client: NocoDBClient,
    args: {
      base_id: string;
      table_name: string;
      where?: string;
      sort?: string[];
      fields?: string[];
      limit?: number;
      offset?: number;
    },
  ) => {
    const result = await client.listRecords(args.base_id, args.table_name, {
      where: args.where,
      sort: args.sort,
      fields: args.fields,
      limit: args.limit || 25,
      offset: args.offset || 0,
    });
    return {
      records: result.list,
      pageInfo: result.pageInfo,
      count: result.list.length,
      query: {
        where: args.where,
        sort: args.sort,
        fields: args.fields,
        limit: args.limit,
        offset: args.offset,
      },
    };
  },

• src/tools/query.ts:9-51 (schema)

  JSON schema defining the input parameters for the 'query' tool, including base_id, table_name, optional where, sort, fields, limit, and offset.

  inputSchema: {
    type: "object",
    properties: {
      base_id: {
        type: "string",
        description: "The ID of the base/project",
      },
      table_name: {
        type: "string",
        description: "The name of the table",
      },
      where: {
        type: "string",
        description:
          'Filter condition using NocoDB syntax (e.g., "(status,eq,active)~and(priority,gt,5)")',
      },
      sort: {
        type: "array",
        description: "Array of sort fields (prefix with - for descending)",
        items: {
          type: "string",
        },
      },
      fields: {
        type: "array",
        description: "Array of fields to return",
        items: {
          type: "string",
        },
      },
      limit: {
        type: "number",
        description: "Number of records to return",
        default: 25,
      },
      offset: {
        type: "number",
        description: "Number of records to skip",
        default: 0,
      },
    },
    required: ["base_id", "table_name"],
  },

• src/index.ts:55-62 (registration)

  Registration of the 'query' tool by including queryTools in the allTools array, which is used to list and call tools in the MCP server handlers.

  const allTools = [
    ...databaseTools,
    ...tableTools,
    ...recordTools,
    ...viewTools,
    ...queryTools,
    ...attachmentTools,
  ];

• src/index.ts:16-16 (registration)

  Import of queryTools from src/tools/query.ts for registration in the main server.

  import { queryTools } from "./tools/query.js";

• src/tools/query.ts:4-84 (registration)

  Definition and export of queryTools array containing the 'query' tool object.

  export const queryTools: Tool[] = [
    {
      name: "query",
      description:
        "Execute an advanced query with filtering, sorting, and field selection",
      inputSchema: {
        type: "object",
        properties: {
          base_id: {
            type: "string",
            description: "The ID of the base/project",
          },
          table_name: {
            type: "string",
            description: "The name of the table",
          },
          where: {
            type: "string",
            description:
              'Filter condition using NocoDB syntax (e.g., "(status,eq,active)~and(priority,gt,5)")',
          },
          sort: {
            type: "array",
            description: "Array of sort fields (prefix with - for descending)",
            items: {
              type: "string",
            },
          },
          fields: {
            type: "array",
            description: "Array of fields to return",
            items: {
              type: "string",
            },
          },
          limit: {
            type: "number",
            description: "Number of records to return",
            default: 25,
          },
          offset: {
            type: "number",
            description: "Number of records to skip",
            default: 0,
          },
        },
        required: ["base_id", "table_name"],
      },
      handler: async (
        client: NocoDBClient,
        args: {
          base_id: string;
          table_name: string;
          where?: string;
          sort?: string[];
          fields?: string[];
          limit?: number;
          offset?: number;
        },
      ) => {
        const result = await client.listRecords(args.base_id, args.table_name, {
          where: args.where,
          sort: args.sort,
          fields: args.fields,
          limit: args.limit || 25,
          offset: args.offset || 0,
        });
        return {
          records: result.list,
          pageInfo: result.pageInfo,
          count: result.list.length,
          query: {
            where: args.where,
            sort: args.sort,
            fields: args.fields,
            limit: args.limit,
            offset: args.offset,
          },
        };
      },
    },