fix(mcp): add rollup/lookup key translation + omit empty typeOptions to prevent 422 errors

- Add normalizeFieldType() translation for rollup/lookup: public API keys (fieldIdInLinkedTable, recordLinkFieldId) → internal keys (foreignTableRollupColumnId, relationColumnId)
- Omit typeOptions entirely when empty in create_field/update_field_config — passing {} causes 422 for text/multilineText/checkbox/rating
- Add defensive fallback chain for formula text extraction: typeOptions.formulaText → typeOptions.formula

Author: ARHAEEM

packages/extension/src/skills/templates/skillTemplates.ts

@@ -451,12 +451,12 @@ Non-destructive field operations.
 | Field Type | typeOptions |
 |------------|-------------|
 | formula | \`{ formulaText: "IF({A},1,0)" }\` |
-| rollup | \`{ fieldIdInLinkedTable, recordLinkFieldId, resultType, referencedFieldIds }\` |
-| lookup | \`{ recordLinkFieldId, fieldIdInLinkedTable }\` |
+| rollup | \`{ relationColumnId: "fldLINK", foreignTableRollupColumnId: "fldTARGET", formulaText: "SUM(values)" }\` — **formulaText required**. Old keys \`fieldIdInLinkedTable\`/\`recordLinkFieldId\` are auto-translated. |
+| lookup | \`{ relationColumnId: "fldLINK", foreignTableRollupColumnId: "fldTARGET" }\` — old keys auto-translated. |
 | count | \`{ recordLinkFieldId }\` |
 | singleSelect | \`{ choices: [{ name: "Option A", color: "blueLight2" }] }\` |
 | multipleSelects | \`{ choices: [{ name: "PC" }, { name: "Xbox", color: "greenLight2" }] }\` |
-| text, number, checkbox | \`{}\` (no typeOptions needed) |
+| text, multilineText, number, checkbox | omit typeOptions entirely (passing \`{}\` causes 422) |
 
 #### Working with Select Choices
 Pass choices as an array of \`{ name, color? }\` objects — IDs are auto-generated for new choices.

packages/mcp-server/package.json

@@ -14,6 +14,7 @@
   "files": [
     "src/**/*.js",
     "src/**/*.mjs",
+    "src/**/*.json",
     "README.md",
     "LICENSE"
   ],

packages/mcp-server/src/client.js

@@ -319,6 +319,22 @@ function normalizeFieldType(type, typeOptions = {}) {
       typeOptions: { ...opts, ...(opts.choices ? { choices: normalizeChoices(opts.choices) } : {}) },
     };
   }
+  // Rollup and lookup use different key names in the internal API vs the public REST API.
+  // Translate the public names (fieldIdInLinkedTable, recordLinkFieldId) to the internal
+  // names (foreignTableRollupColumnId, relationColumnId) so callers can use either vocabulary.
+  // formulaText is required for rollup; relationColumnId + foreignTableRollupColumnId for lookup.
+  if (type === 'rollup' || type === 'lookup') {
+    const translated = { ...opts };
+    if (opts.recordLinkFieldId !== undefined && opts.relationColumnId === undefined) {
+      translated.relationColumnId = opts.recordLinkFieldId;
+      delete translated.recordLinkFieldId;
+    }
+    if (opts.fieldIdInLinkedTable !== undefined && opts.foreignTableRollupColumnId === undefined) {
+      translated.foreignTableRollupColumnId = opts.fieldIdInLinkedTable;
+      delete translated.fieldIdInLinkedTable;
+    }
+    return { type, typeOptions: translated };
+  }
   // "singleSelect" is the public/REST API name; internal API uses "select" (mirrors multipleSelects → multiSelect).
   if (type === 'singleSelect' || type === 'select') {
     return {
@@ -592,13 +608,15 @@ export class AirtableClient {
 
     const normalized = normalizeFieldType(fieldConfig.type, fieldConfig.typeOptions);
 
+    const config = { type: normalized.type };
+    if (normalized.typeOptions && Object.keys(normalized.typeOptions).length > 0) {
+      config.typeOptions = normalized.typeOptions;
+    }
+
     const payload = {
       tableId,
       name: fieldConfig.name,
-      config: {
-        type: normalized.type,
-        typeOptions: normalized.typeOptions,
-      },
+      config,
     };
 
     if (fieldConfig.description) {
@@ -634,11 +652,12 @@ export class AirtableClient {
 
     const normalized = normalizeFieldType(config.type, config.typeOptions);
 
-    // Flat payload — matches real Airtable requests
-    const payload = {
-      type: normalized.type,
-      typeOptions: normalized.typeOptions,
-    };
+    // Flat payload — matches real Airtable requests. Omit typeOptions when empty;
+    // the internal API rejects typeOptions: {} for field types that have no options.
+    const payload = { type: normalized.type };
+    if (normalized.typeOptions && Object.keys(normalized.typeOptions).length > 0) {
+      payload.typeOptions = normalized.typeOptions;
+    }
 
     const res = await this.auth.postForm(url, this._mutationParams(payload, appId), appId);
 

packages/mcp-server/src/index.js

@@ -488,15 +488,19 @@ FIELD TYPES (fieldType parameter):
 
 TYPE OPTIONS by fieldType:
   formula:                { formulaText: "..." }
-  rollup:                 { fieldIdInLinkedTable, recordLinkFieldId, resultType, referencedFieldIds }
-  lookup:                 { recordLinkFieldId, fieldIdInLinkedTable }
+  rollup:                 { relationColumnId: "fldLINK", foreignTableRollupColumnId: "fldTARGET", formulaText: "SUM(values)" }
+                          (formulaText is REQUIRED — e.g. "SUM(values)", "COUNTA(values)", "IF(OR(values='X'),1,0)"))
+                          (old keys fieldIdInLinkedTable/recordLinkFieldId are auto-translated for backward compat)
+  lookup:                 { relationColumnId: "fldLINK", foreignTableRollupColumnId: "fldTARGET" }
+                          (old keys fieldIdInLinkedTable/recordLinkFieldId are auto-translated for backward compat)
   count:                  { recordLinkFieldId }
   number (integer):       { format: "integer", negative: false }
   number (currency):      { format: "currency", symbol: "$", precision: 2, negative: false }
   number (percent):       { format: "percentV2", precision: 2, negative: false }
   date / dateTime:        { dateFormat: "Local"|"us"|"european"|"iso"|"friendly", timeFormat: "12hour"|"24hour", timeZone: "UTC"|"client"|<IANA-tz>, shouldDisplayTimeZone: true|false, isDateTime: true (auto for dateTime) }
   singleSelect:           { choices: [{ name: "Option A", color: "blueLight2" }] }
   multipleSelects:        { choices: [{ name: "PC" }, { name: "Xbox", color: "greenLight2" }] }
+  text / multilineText / checkbox / rating: omit typeOptions entirely — passing {} causes a 422
 
 SELECT CHOICES: pass an array of { name, color? } objects — the client auto-converts to the object format the internal API requires and generates valid choice IDs.`,
     annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
@@ -596,12 +600,15 @@ Works for formula, rollup, lookup, count, singleSelect, multipleSelects, number,
 COMMON typeOptions by fieldType:
 
   formula:         { formulaText: "IF({Field}, 1, 0)" }
-  rollup:          { relationColumnId: "fldXXX", formulaText: "SUM(values)" }
-  lookup:          { relationColumnId: "fldXXX", foreignTableRollupColumnId: "fldYYY" }
+  rollup:          { relationColumnId: "fldLINK", foreignTableRollupColumnId: "fldTARGET", formulaText: "SUM(values)" }
+                   (formulaText is REQUIRED; old keys fieldIdInLinkedTable/recordLinkFieldId auto-translated)
+  lookup:          { relationColumnId: "fldLINK", foreignTableRollupColumnId: "fldTARGET" }
+                   (old keys fieldIdInLinkedTable/recordLinkFieldId auto-translated)
   count:           { recordLinkFieldId: "fldXXX" }
   singleSelect:    { choices: [{ name: "Option A", color: "blueLight2" }] }
   multipleSelects: { choices: [{ name: "PC" }, { name: "Xbox", color: "greenLight2" }] }
   number:          { format: "integer"|"decimal"|"currency"|"percentV2", precision: 2, symbol: "$", negative: false }
+  text / multilineText / checkbox: omit typeOptions entirely — passing {} causes a 422
 
 SELECT CHOICES — pass an array of { name, color? } objects; the client handles the internal format.
 
@@ -1771,7 +1778,12 @@ const handlers = {
     if (foundField.type !== 'formula') {
       return { content: [{ type: 'text', text: JSON.stringify({ error: `Field ${fieldId} is type "${foundField.type}", not formula` }) }], isError: true };
     }
-    const formulaText = foundField.typeOptions?.formulaText ?? '';
+    // Airtable's internal API has stored formula text at typeOptions.formulaText historically.
+    // Defensive fallback chain handles potential key renames in future API responses.
+    const formulaText = foundField.typeOptions?.formulaText
+      || foundField.typeOptions?.formula
+      || foundField.formula
+      || '';
     const fieldName = foundField.name ?? fieldId;
     const description = foundField.description ?? '';
     const resultType = foundField.typeOptions?.resultType ?? '';
@@ -1805,7 +1817,10 @@ const handlers = {
       await mkdir(tableDir, { recursive: true });
 
       for (const field of formulaFields) {
-        const formulaText = field.typeOptions?.formulaText ?? '';
+        const formulaText = field.typeOptions?.formulaText
+          || field.typeOptions?.formula
+          || field.formula
+          || '';
         const fieldName = field.name ?? field.id;
         const description = field.description ?? '';
         const resultType = field.typeOptions?.resultType ?? '';