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[], }