fix(mcp): address 4 open bugs from bulk-delete report

Bug 6 (HIGH): Silent success masked as timeout
- Wrap both destroyMultipleColumns calls in try/catch in deleteFields()
- On network/timeout error, call _verifyFieldsDeletion() which invalidates
  cache, re-fetches schema, and checks which fields are actually gone
- Fields missing from fresh schema → succeeded (timedOut:true); still
  present → failed with honest error message

Bug 7 (MEDIUM): Name-verification timeout on 300+ field tables
- Thread evalTimeoutMs through auth._rawApiCall / _apiCall / get()
- getApplicationData() now passes evalTimeoutMs:60_000 (was hardcoded 15s)
- Add getApplicationDataForTable(appId, tableId) using includeDataForTableIds
  for targeted single-table fetches — avoids downloading the full base schema
  when the caller already knows the tableId
- resolveTable() uses targeted fetch when tableIdOrName starts with 'tbl',
  falling back to full fetch for name-based lookups
- getApplicationDataForTable() detects if server ignored the filter (returned
  all tables) and stores the result in the full cache to avoid redundant fetches

Bug 5 (Partial→Fixed): Checkpoint not written on timeout
- Flows from Bug 6 fix: post-timeout verification now correctly populates
  succeeded[] so the checkpoint handler has accurate data to write

Bug 3 (MEDIUM): list_fields returns full 2.7MB schema
- Add optional fieldType param: filter fields by type ("formula", "text", …)
- Add optional nameContains param: case-insensitive substring match on name
- Update tool description to mention filtering on large tables

Bug 4 (Airtable cursor behavior — not actionable)

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: ARHAEEM

packages/mcp-server/src/auth.js

@@ -368,7 +368,7 @@ export class AirtableAuth {
 
   // ─── Raw API Call (no queue, no recovery) ─────────────────────
 
-  async _rawApiCall(method, urlPath, body = null, appId = null, contentType = 'form') {
+  async _rawApiCall(method, urlPath, body = null, appId = null, contentType = 'form', evalTimeoutMs = 15_000) {
     const url = urlPath.startsWith('http') ? urlPath : `https://airtable.com${urlPath}`;
     const timeZone = Intl.DateTimeFormat().resolvedOptions().timeZone;
     const csrfToken = this.csrfToken;
@@ -379,13 +379,14 @@ export class AirtableAuth {
 
     // H3 — per-evaluate timeout. Playwright has no built-in timeout on
     // page.evaluate; a CDP-dead Chromium can hang forever. We race against
-    // a 15s timer and let _apiCall's catch trigger _recoverSession.
-    const EVAL_TIMEOUT_MS = 15_000;
+    // a configurable timer (default 15s) and let _apiCall's catch trigger
+    // _recoverSession. Callers handling large responses (e.g. getApplicationData)
+    // should pass a higher evalTimeoutMs to avoid spurious recovery cycles.
     const withTimeout = (promise) => Promise.race([
       promise,
       new Promise((_, reject) => setTimeout(
-        () => reject(new Error(`page.evaluate exceeded ${EVAL_TIMEOUT_MS / 1000}s; browser may be unresponsive`)),
-        EVAL_TIMEOUT_MS,
+        () => reject(new Error(`page.evaluate exceeded ${evalTimeoutMs / 1000}s; browser may be unresponsive`)),
+        evalTimeoutMs,
       )),
     ]);
 
@@ -448,7 +449,7 @@ export class AirtableAuth {
 
   // ─── Queued API Call (with session recovery & rate-limit backoff) ──────────────────
 
-  async _apiCall(method, urlPath, body = null, appId = null, contentType = 'form') {
+  async _apiCall(method, urlPath, body = null, appId = null, contentType = 'form', evalTimeoutMs = 15_000) {
     return this._enqueue(async () => {
       await this.ensureLoggedIn();
 
@@ -464,7 +465,7 @@ export class AirtableAuth {
         }
         let result;
         try {
-          result = await this._rawApiCall(method, urlPath, body, appId, contentType);
+          result = await this._rawApiCall(method, urlPath, body, appId, contentType, evalTimeoutMs);
         } catch (evalError) {
           // page.evaluate itself failed (browser crashed, context destroyed)
           if (!this._recovering && attempt < MAX_RETRIES) {
@@ -527,11 +528,11 @@ export class AirtableAuth {
     }
   }
 
-  async get(url, appId) {
+  async get(url, appId, { evalTimeoutMs = 15_000 } = {}) {
     const pattern = url.replace(/.*v0\.3\//, '').replace(/(app|tbl|viw|fld|rec|usr|wsp|sel|flt|blk|ext|col)[A-Za-z0-9]{10,}/g, '$1*');
     trace('http', 'http:request', { method: 'GET', endpoint_pattern: pattern, has_payload: false });
     const start = Date.now();
-    const result = await this._apiCall('GET', url, null, appId);
+    const result = await this._apiCall('GET', url, null, appId, 'form', evalTimeoutMs);
     trace('http', 'http:response', { endpoint_pattern: pattern, status: result.status, duration_ms: Date.now() - start });
     return this._wrapResponse(result);
   }

packages/mcp-server/src/cache.js

@@ -19,6 +19,8 @@ export class SchemaCache {
     // we use for simple LRU-ish eviction (evict oldest when size exceeds cap).
     this._scaffolding = new Map();
     this._full = new Map();
+    // Map<`${appId}:${tableId}`, { data, timestamp }> — single-table targeted fetches
+    this._table = new Map();
   }
 
   // ─── Scaffolding Cache ────────────────────────────────────────
@@ -41,20 +43,34 @@ export class SchemaCache {
     this._setEntry(this._full, appId, data);
   }
 
+  // ─── Per-Table Cache ──────────────────────────────────────────
+
+  getTable(appId, tableId) {
+    return this._getEntry(this._table, `${appId}:${tableId}`);
+  }
+
+  setTable(appId, tableId, data) {
+    this._setEntry(this._table, `${appId}:${tableId}`, data);
+  }
+
   // ─── Invalidation ─────────────────────────────────────────────
 
   /**
    * Invalidate caches for an app after a mutation.
-   * Clears both full and scaffolding since field changes affect both.
+   * Clears full, scaffolding, and all per-table entries for this app.
    */
   invalidate(appId) {
     this._full.delete(appId);
     this._scaffolding.delete(appId);
+    for (const key of this._table.keys()) {
+      if (key.startsWith(`${appId}:`)) this._table.delete(key);
+    }
   }
 
   invalidateAll() {
     this._full.clear();
     this._scaffolding.clear();
+    this._table.clear();
   }
 
   // ─── Internals ────────────────────────────────────────────────

packages/mcp-server/src/client.js

@@ -424,7 +424,8 @@ export class AirtableClient {
       requestId: this._genRequestId(),
     });
     const url = `https://airtable.com/v0.3/application/${appId}/read?${params}`;
-    const res = await this.auth.get(url, appId);
+    // Use a generous timeout — full-base responses can exceed 1MB on large bases.
+    const res = await this.auth.get(url, appId, { evalTimeoutMs: 60_000 });
     if (!res.ok) {
       const text = await res.text();
       throw new Error(`getApplicationData failed (${res.status}): ${text}`);
@@ -434,6 +435,49 @@ export class AirtableClient {
     return data;
   }
 
+  /**
+   * Fetch schema data for a single table using includeDataForTableIds.
+   * Dramatically reduces response size on large bases (avoids downloading all tables).
+   * Falls back to caching full data if the endpoint returns all tables anyway.
+   */
+  async getApplicationDataForTable(appId, tableId) {
+    assertAirtableId(appId, 'appId');
+    assertAirtableId(tableId, 'tableId');
+
+    const cachedTable = this.cache.getTable(appId, tableId);
+    if (cachedTable) return cachedTable;
+
+    // Also accept a warm full-cache hit — no extra fetch needed.
+    const cachedFull = this.cache.getFull(appId);
+    if (cachedFull) return cachedFull;
+
+    const params = new URLSearchParams({
+      stringifiedObjectParams: JSON.stringify({
+        includeDataForTableIds: [tableId],
+        includeDataForViewIds: null,
+        shouldIncludeSchemaChecksum: false,
+      }),
+      requestId: this._genRequestId(),
+    });
+    const url = `https://airtable.com/v0.3/application/${appId}/read?${params}`;
+    const res = await this.auth.get(url, appId, { evalTimeoutMs: 60_000 });
+    if (!res.ok) {
+      const text = await res.text();
+      throw new Error(`getApplicationDataForTable failed (${res.status}): ${text}`);
+    }
+    const data = await res.json();
+    const tables = data?.data?.tableSchemas || data?.data?.tables || [];
+
+    if (tables.length === 1 && tables[0].id === tableId) {
+      // Targeted response — cache per-table only (don't pollute the full cache).
+      this.cache.setTable(appId, tableId, data);
+    } else {
+      // Endpoint returned the full base (no server-side filtering) — cache as full.
+      this.cache.setFull(appId, data);
+    }
+    return data;
+  }
+
   async getScaffoldingData(appId) {
     assertAirtableId(appId, 'appId');
     const cached = this.cache.getScaffolding(appId);
@@ -462,7 +506,11 @@ export class AirtableClient {
   // ─── Schema Resolution Helpers ────────────────────────────────
 
   async resolveTable(appId, tableIdOrName) {
-    const data = await this.getApplicationData(appId);
+    // When caller passes a table ID we can do a targeted single-table fetch,
+    // avoiding a full-base download on large bases.
+    const data = tableIdOrName.startsWith('tbl')
+      ? await this.getApplicationDataForTable(appId, tableIdOrName)
+      : await this.getApplicationData(appId);
     const tables = data?.data?.tableSchemas || data?.data?.tables || [];
 
     // Exact ID match is always unambiguous.
@@ -691,6 +739,31 @@ export class AirtableClient {
     return { deleted: true, fieldId, name: expectedName, forced: true, ...data };
   }
 
+  /**
+   * After a destroyMultipleColumns network error, verify which fields are actually
+   * gone from a fresh schema fetch. This handles the case where the request timed
+   * out at the MCP layer but Airtable had already deleted the fields (Bug 6).
+   */
+  async _verifyFieldsDeletion(appId, tableFields) {
+    this.cache.invalidate(appId);
+    const freshData = await this.getApplicationData(appId);
+    const tables = freshData?.data?.tableSchemas || freshData?.data?.tables || [];
+    const stillExist = new Set();
+    for (const t of tables) {
+      for (const f of (t.columns || t.fields || [])) stillExist.add(f.id);
+    }
+    const succeeded = [];
+    const failed = [];
+    for (const { fieldId, expectedName } of tableFields) {
+      if (!stillExist.has(fieldId)) {
+        succeeded.push({ fieldId, name: expectedName, deleted: true, forced: false, timedOut: true });
+      } else {
+        failed.push({ fieldId, name: expectedName, error: 'destroyMultipleColumns timed out; field still exists' });
+      }
+    }
+    return { succeeded, failed };
+  }
+
   /**
    * Delete multiple fields using the native batch endpoint (destroyMultipleColumns).
    * Fields are grouped by tableId and each table's fields are deleted in 1-2 API
@@ -730,11 +803,24 @@ export class AirtableClient {
     for (const [tableId, tableFields] of byTable) {
       const columnIds = tableFields.map(f => f.fieldId);
 
-      const checkRes = await this.auth.postForm(
-        `https://airtable.com/v0.3/table/${tableId}/destroyMultipleColumns`,
-        this._mutationParams({ columnIds, checkSchemaDependencies: true }, appId),
-        appId,
-      );
+      let checkRes;
+      try {
+        checkRes = await this.auth.postForm(
+          `https://airtable.com/v0.3/table/${tableId}/destroyMultipleColumns`,
+          this._mutationParams({ columnIds, checkSchemaDependencies: true }, appId),
+          appId,
+        );
+      } catch (err) {
+        // Network/timeout — Airtable may have already deleted the fields.
+        // Verify by re-fetching the schema (Bug 6: silent success masking).
+        const verified = await this._verifyFieldsDeletion(appId, tableFields).catch(ve => ({
+          succeeded: [],
+          failed: tableFields.map(f => ({ fieldId: f.fieldId, name: f.expectedName, error: `destroyMultipleColumns network error: ${err.message}; verification also failed: ${ve.message}` })),
+        }));
+        succeeded.push(...verified.succeeded);
+        failed.push(...verified.failed);
+        continue;
+      }
 
       if (checkRes.ok) {
         this.cache.invalidate(appId);
@@ -758,11 +844,22 @@ export class AirtableClient {
       }
 
       // Deps exist and force=true: second call without checkSchemaDependencies
-      const forceRes = await this.auth.postForm(
-        `https://airtable.com/v0.3/table/${tableId}/destroyMultipleColumns`,
-        this._mutationParams({ columnIds }, appId),
-        appId,
-      );
+      let forceRes;
+      try {
+        forceRes = await this.auth.postForm(
+          `https://airtable.com/v0.3/table/${tableId}/destroyMultipleColumns`,
+          this._mutationParams({ columnIds }, appId),
+          appId,
+        );
+      } catch (err) {
+        const verified = await this._verifyFieldsDeletion(appId, tableFields).catch(ve => ({
+          succeeded: [],
+          failed: tableFields.map(f => ({ fieldId: f.fieldId, name: f.expectedName, error: `destroyMultipleColumns force network error: ${err.message}; verification also failed: ${ve.message}` })),
+        }));
+        succeeded.push(...verified.succeeded);
+        failed.push(...verified.failed);
+        continue;
+      }
 
       if (!forceRes.ok) {
         const errText = await forceRes.text().catch(() => '');

packages/mcp-server/src/index.js

@@ -212,13 +212,15 @@ const TOOLS = [
   },
   {
     name: 'list_fields',
-    description: 'List all fields (columns) in a specific table of an Airtable base.',
+    description: 'List fields (columns) in a table. Returns id, name, type, and typeOptions for each field. On large tables (100+ fields) use fieldType or nameContains to filter the response and reduce context size.',
     annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
     inputSchema: {
       type: 'object',
       properties: {
         appId: { type: 'string', description: 'The Airtable base/application ID' },
-        tableIdOrName: { type: 'string', description: 'The table ID or name to list fields for' },
+        tableIdOrName: { type: 'string', description: 'The table ID (tblXXX) or exact name' },
+        fieldType: { type: 'string', description: 'Return only fields of this type, e.g. "formula", "text", "number", "checkbox"' },
+        nameContains: { type: 'string', description: 'Return only fields whose name contains this substring (case-insensitive)' },
         debug: debugProp,
       },
       required: ['appId', 'tableIdOrName'],
@@ -1545,14 +1547,19 @@ const handlers = {
     return ok(summary, table, debug);
   },
 
-  async list_fields({ appId, tableIdOrName, debug }) {
+  async list_fields({ appId, tableIdOrName, fieldType, nameContains, debug }) {
     const table = await client.resolveTable(appId, tableIdOrName);
-    const fields = (table.columns || table.fields || []).map(f => ({
+    let fields = (table.columns || table.fields || []).map(f => ({
       id: f.id,
       name: f.name,
       type: f.type,
       typeOptions: f.typeOptions,
     }));
+    if (fieldType) fields = fields.filter(f => f.type === fieldType);
+    if (nameContains) {
+      const needle = nameContains.toLowerCase();
+      fields = fields.filter(f => f.name.toLowerCase().includes(needle));
+    }
     return ok(fields, table, debug);
   },