AITable MCP Server

Instructions

Implementation Reference

• src/index.ts:146-179 (handler)

  The handler function that implements the core logic for the 'list_records' tool. It validates the node_id, builds the query string for pagination, sorting, etc., fetches records from the AITable API, and returns formatted success or error responses.

  async ({ node_id, sort, pageNum, pageSize, fields, viewId }) => {
    try {
      if (!node_id) {
        throw new Error("datasheet ID is required.");
      }
  
      const queryStr = aitableService.buildQueryString({
        sort, pageNum, pageSize, fields, viewId,
        cellFormat: "string",
        fieldKey: "name",
      });
      const endpoint = `/v1/datasheets/${node_id}/records${queryStr}`;
  
      const result: ResponseVO<GetRecordsResponeDataVO> = await aitableService.fetchFromAPI(endpoint, {
        method: "GET",
      });
  
      if (!result.success) {
        throw new Error(result.message || "Failed to list records");
      }
  
      return formatToolResponse({
        success: true,
        data: result.data
      });
    }
    catch (error) {
      console.error("Error in get_records:", error);
      return formatToolResponse({
        success: false,
        message: error instanceof Error ? error.message : "Unknown error occurred"
      }, true);
    }
  }

• src/index.ts:134-145 (schema)

  Zod schema defining the input parameters for the list_records tool, including required datasheet ID, optional sorting, pagination, field filtering, view ID, and formula-based filtering.

  {
    node_id: z.string().describe('The ID of the datasheet to fetch records from.'),
    sort: z.array(z.object({
      field: z.string().describe("field name"),
      order: z.enum(["asc", "desc"]).describe("Sorting order, must be 'asc' or 'desc'"),
    })).optional().describe("Sort the returned records."),
    pageNum: z.number().default(1).optional().describe("Specifies the page number of the page, which is used in conjunction with the pageSize parameter."),
    pageSize: z.number().min(1).max(1000).default(20).optional().describe("How many records are returned per page."),
    fields: z.string().optional().describe("The returned record results are limited to the specified fields by name. Multiple fields should be separated by commas without spaces (e.g. 'field1,field2,field3')."),
    viewId: z.string().optional().describe("When the viewId is explicitly specified, all records in the specified view will be returned in turn according to the sorting in the specified view."),
    filterByFormula: z.string().optional().describe("Filter the records by a formula. The formula should be in the format accepted by AITable, this is useful for filtering records based on specific criteria. e.g. '{field1}=\"value1\"' or 'AND({field1}=\"value1\", {field2}=\"value2\")'."),
  },

• src/index.ts:132-180 (registration)

  The server.tool call that registers the 'list_records' tool with the MCP server, including its name, description, input schema, and handler function.

  server.tool("list_records",
    "Read the records from a specified datasheet with support for pagination, field filtering, and sorting options.",
    {
      node_id: z.string().describe('The ID of the datasheet to fetch records from.'),
      sort: z.array(z.object({
        field: z.string().describe("field name"),
        order: z.enum(["asc", "desc"]).describe("Sorting order, must be 'asc' or 'desc'"),
      })).optional().describe("Sort the returned records."),
      pageNum: z.number().default(1).optional().describe("Specifies the page number of the page, which is used in conjunction with the pageSize parameter."),
      pageSize: z.number().min(1).max(1000).default(20).optional().describe("How many records are returned per page."),
      fields: z.string().optional().describe("The returned record results are limited to the specified fields by name. Multiple fields should be separated by commas without spaces (e.g. 'field1,field2,field3')."),
      viewId: z.string().optional().describe("When the viewId is explicitly specified, all records in the specified view will be returned in turn according to the sorting in the specified view."),
      filterByFormula: z.string().optional().describe("Filter the records by a formula. The formula should be in the format accepted by AITable, this is useful for filtering records based on specific criteria. e.g. '{field1}=\"value1\"' or 'AND({field1}=\"value1\", {field2}=\"value2\")'."),
    },
    async ({ node_id, sort, pageNum, pageSize, fields, viewId }) => {
      try {
        if (!node_id) {
          throw new Error("datasheet ID is required.");
        }
  
        const queryStr = aitableService.buildQueryString({
          sort, pageNum, pageSize, fields, viewId,
          cellFormat: "string",
          fieldKey: "name",
        });
        const endpoint = `/v1/datasheets/${node_id}/records${queryStr}`;
  
        const result: ResponseVO<GetRecordsResponeDataVO> = await aitableService.fetchFromAPI(endpoint, {
          method: "GET",
        });
  
        if (!result.success) {
          throw new Error(result.message || "Failed to list records");
        }
  
        return formatToolResponse({
          success: true,
          data: result.data
        });
      }
      catch (error) {
        console.error("Error in get_records:", error);
        return formatToolResponse({
          success: false,
          message: error instanceof Error ? error.message : "Unknown error occurred"
        }, true);
      }
    }
  );

• src/types.ts:47-52 (schema)

  TypeScript type definition for the response data structure returned by the list_records tool, including pagination info and array of records.

  export type GetRecordsResponeDataVO = {
    total: number,
    pageSize: number,
    pageNum: number,
    records: RecordVO[],
  }