AITable MCP Server

Instructions

Implementation Reference

• src/index.ts:182-213 (registration)

  Registration of the 'get_fields_schema' MCP tool, including description, input schema, and inline handler function that delegates to AitableService helpers.

  server.tool("get_fields_schema",
    "Returns the JSON schema of all fields within the specified database, This schema will be sent to LLM to help the AI understand the expected structure of the data.",
    {
      node_id: z.string().describe('The ID of the database to fetch records from.'),
    },
    async ({ node_id }) => {
      try {
        if (!node_id) {
          throw new Error("The datasheet ID (node_id) is required.");
        }
        const result = await aitableService.getDatasheetFieldsSchema(node_id);
  
        if (!result.success) {
          throw new Error(result.message || "Failed to fetch datasheet fields schema");
        }
  
        const fieldsSchema: FieldFormatJSONSchema = aitableService.getFieldsJSONSchema(result.data.fields);
  
        return formatToolResponse({
          success: true,
          data: fieldsSchema
        });
      }
      catch (error) {
        console.error("Error in list_database_fields:", error);
        return formatToolResponse({
          success: false,
          message: error instanceof Error ? error.message : "Unknown error occurred"
        }, true);
      }
    }
  );

• src/index.ts:187-212 (handler)

  Core handler logic for executing the tool: validates input, fetches raw fields schema from API via service, formats into LLM-compatible JSON schema, and returns standardized tool response.

  async ({ node_id }) => {
    try {
      if (!node_id) {
        throw new Error("The datasheet ID (node_id) is required.");
      }
      const result = await aitableService.getDatasheetFieldsSchema(node_id);
  
      if (!result.success) {
        throw new Error(result.message || "Failed to fetch datasheet fields schema");
      }
  
      const fieldsSchema: FieldFormatJSONSchema = aitableService.getFieldsJSONSchema(result.data.fields);
  
      return formatToolResponse({
        success: true,
        data: fieldsSchema
      });
    }
    catch (error) {
      console.error("Error in list_database_fields:", error);
      return formatToolResponse({
        success: false,
        message: error instanceof Error ? error.message : "Unknown error occurred"
      }, true);
    }
  }

• src/index.ts:184-186 (schema)

  Input validation schema using Zod, requiring a single 'node_id' string parameter.

  {
    node_id: z.string().describe('The ID of the database to fetch records from.'),
  },

• src/aitableService.ts:367-379 (helper)

  Helper method in AitableService that performs the API call to retrieve the raw fields schema from the AITable '/v1/datasheets/{node_id}/fields' endpoint.

  public async getDatasheetFieldsSchema(
    node_id: string
  ): Promise<ResponseVO<{fields: FieldSchemaVO[]}>> {
    if (!node_id) {
      throw new Error("The datasheet ID (node_id) is required.");
    }
  
    const endpoint = `/v1/datasheets/${node_id}/fields`;
  
    return this.fetchFromAPI(endpoint, {
      method: "GET",
    });
  }

• src/aitableService.ts:281-312 (helper)

  Helper method that transforms raw FieldSchemaVO[] into a structured JSON schema (FieldFormatJSONSchema) suitable for LLM structured outputs, mapping field types to appropriate Zod/JSON schema keywords.

  public getFieldsJSONSchema(fields: FieldSchemaVO[]): FieldFormatJSONSchema {
    const schema: {
      type: string;
      properties: Record<string, unknown>;
      additionalProperties: boolean;
      required: string[];
    } = {
      type: "object",
      properties: {},
      additionalProperties: false,
      required: [],
    };
  
    fields.forEach((field) => {
      const keywordsForField = this._getKeywordByFieldType(field);
  
      // If the field type is not supported, we skip it
      if (keywordsForField) {
        schema.properties[field.name] = keywordsForField;
        schema.required.push(field.name);
      }
    });
  
    return {
      type: "json_schema",
      json_schema: {
        name: "fields_in_datasheet",
        schema,
        strict: true,
      },
    };
  }