AITable MCP Server

Instructions

Implementation Reference

• src/index.ts:230-284 (handler)

  MCP tool handler for 'create_record': validates inputs, fetches datasheet fields schema, converts fields to cell format, handles attachments, creates record via service, returns formatted response or error.

  async ({ node_id, fields, attachments_fields }) => {
    try {
      if (!node_id) {
        throw new Error("The datasheet ID (node_id) is required.");
      }
  
      if (!fields && !attachments_fields) {
        throw new Error("At least one of 'fields' or 'attachments_fields' must be provided.");
      }
  
  
      const getFieldsResult = await aitableService.getDatasheetFieldsSchema(node_id);
  
      if (!getFieldsResult.success) {
        throw new Error(getFieldsResult.message || "Failed to fetch datasheet fields schema");
      }
  
      const fieldsSchema = getFieldsResult.data.fields;
      let cells: Record<string, any> = {};
      if (fields !== undefined) {
        cells = aitableService.convertFieldValuesToCellFormat(fieldsSchema, fields);
      }
  
      if (attachments_fields) {
        console.error("attachments_fields", attachments_fields);
        console.error("fieldsSchema", fieldsSchema);
        fieldsSchema.forEach((fieldschema) => {
          const fieldValue = attachments_fields[fieldschema.name];
          if (fieldValue !== undefined) {
            cells[fieldschema.name] = fieldValue;
          }
        });
      }
  
      const createRecordResult = await aitableService.createDatasheetRecord(node_id, cells);
  
      if (!createRecordResult.success) {
        throw new Error(createRecordResult.message || "Failed to create record");
      }
  
      return formatToolResponse({
        success: true,
        data: {
          records: createRecordResult.data.records,
        },
      });
    }
    catch (error) {
      console.error("Error in create_record:", error);
      return formatToolResponse({
        success: false,
        message: error instanceof Error ? error.message : "Unknown error occurred"
      }, true);
    }
  }

• src/index.ts:217-229 (schema)

  Zod input schema for create_record tool parameters: node_id (string), fields (record of any), attachments_fields (optional record of attachment arrays).

  {
    node_id: z.string().describe('The ID of the datasheet where the new record will be created.'),
    fields: z.record(z.any()).describe('A JSON object containing non-Attachment type field data. Keys represent field names and values represent field values. Omit unspecified fields in the API request. The structure of field values must conform to the Fields JSON Schema provided by the "get_fields_schema" tool.'),
    attachments_fields: z.record(z.array(z.object({
      token: z.string(),
      name: z.string(),
      size: z.number(),
      mimeType: z.string(),
      height: z.number().optional(),
      width: z.number().optional(),
      url: z.string(),
    }))).optional().describe('A JSON object containing Attachment type field data. Keys represent field names and values are arrays of attachment objects. The structure of attachment objects must conform to the Fields JSON Schema provided by the "get_fields_schema" tool. You need to use the "upload_file_via_url" tool to obtain the attachment objects.'),
  },

• src/index.ts:215-285 (registration)

  Registration of the create_record tool on the MCP server, specifying name, description, input schema, and handler function.

  server.tool("create_record",
    "Create a new record in the datasheet. Extract key information from user-provided text based on a predefined Fields JSON Schema and create a new record in the datasheet as a JSON object.",
    {
      node_id: z.string().describe('The ID of the datasheet where the new record will be created.'),
      fields: z.record(z.any()).describe('A JSON object containing non-Attachment type field data. Keys represent field names and values represent field values. Omit unspecified fields in the API request. The structure of field values must conform to the Fields JSON Schema provided by the "get_fields_schema" tool.'),
      attachments_fields: z.record(z.array(z.object({
        token: z.string(),
        name: z.string(),
        size: z.number(),
        mimeType: z.string(),
        height: z.number().optional(),
        width: z.number().optional(),
        url: z.string(),
      }))).optional().describe('A JSON object containing Attachment type field data. Keys represent field names and values are arrays of attachment objects. The structure of attachment objects must conform to the Fields JSON Schema provided by the "get_fields_schema" tool. You need to use the "upload_file_via_url" tool to obtain the attachment objects.'),
    },
    async ({ node_id, fields, attachments_fields }) => {
      try {
        if (!node_id) {
          throw new Error("The datasheet ID (node_id) is required.");
        }
  
        if (!fields && !attachments_fields) {
          throw new Error("At least one of 'fields' or 'attachments_fields' must be provided.");
        }
  
  
        const getFieldsResult = await aitableService.getDatasheetFieldsSchema(node_id);
  
        if (!getFieldsResult.success) {
          throw new Error(getFieldsResult.message || "Failed to fetch datasheet fields schema");
        }
  
        const fieldsSchema = getFieldsResult.data.fields;
        let cells: Record<string, any> = {};
        if (fields !== undefined) {
          cells = aitableService.convertFieldValuesToCellFormat(fieldsSchema, fields);
        }
  
        if (attachments_fields) {
          console.error("attachments_fields", attachments_fields);
          console.error("fieldsSchema", fieldsSchema);
          fieldsSchema.forEach((fieldschema) => {
            const fieldValue = attachments_fields[fieldschema.name];
            if (fieldValue !== undefined) {
              cells[fieldschema.name] = fieldValue;
            }
          });
        }
  
        const createRecordResult = await aitableService.createDatasheetRecord(node_id, cells);
  
        if (!createRecordResult.success) {
          throw new Error(createRecordResult.message || "Failed to create record");
        }
  
        return formatToolResponse({
          success: true,
          data: {
            records: createRecordResult.data.records,
          },
        });
      }
      catch (error) {
        console.error("Error in create_record:", error);
        return formatToolResponse({
          success: false,
          message: error instanceof Error ? error.message : "Unknown error occurred"
        }, true);
      }
    }
  );

• src/aitableService.ts:381-400 (helper)

  AitableService helper method that sends POST request to AITable API to create a datasheet record using provided cells.

  public async createDatasheetRecord(
    node_id: string,
    cells: Record<string, unknown>
  ): Promise<ResponseVO<{records: RecordVO[]}>> {
  
    const endpoint = `/v1/datasheets/${node_id}/records`;
  
    console.error('Creating record with cells:', cells);
  
    return this.fetchFromAPI(endpoint, {
      method: "POST",
      body: JSON.stringify({
        records:[
          {
            fields: cells,
          }
        ]
      }),
    });
  }

• src/aitableService.ts:253-275 (helper)

  Helper method to convert user field values to API-compatible cell format, applying type-specific conversions using field schema.

  public convertFieldValuesToCellFormat(
    fieldsSchema: FieldSchemaVO[],
    fieldValues: Record<string, unknown>
  ): Record<string, unknown> {
    const cells: Record<string, unknown> = {};
  
    fieldsSchema.forEach((fieldschema) => {
      const fieldValue = fieldValues[fieldschema.name];
      if (fieldValue !== undefined) {
        const cellValue = this._getCellValueByFieldType(
          fieldschema,
          fieldValue
        );
  
        // Only add the cell if the value is not null
        if (cellValue !== null) {
          cells[fieldschema.name] = cellValue;
        }
      }
    });
  
    return cells;
  }