fix(mcp): normalize select field choices to internal API format with id, choiceOrder, disableColors, and default handling

- Add id inside each choice value (required by internal API) when normalizing both array and object-form choices
- Generate choiceOrder array automatically from choice keys when not provided
- Set disableColors: false in typeOptions (required field)
- Extract default (string for singleSelect, array for multipleSelects) from typeOptions and place at payload root level
- Update

Author: ARHAEEM

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

@@ -454,18 +454,20 @@ Non-destructive field operations.
 | 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" }] }\` |
+| singleSelect | \`{ choices: [{ name: "Option A", color: "blue" }], default: "selXXX" }\` |
+| multipleSelects | \`{ choices: [{ name: "PC", color: "blue" }, { name: "Xbox", color: "cyan" }], default: ["selXXX"] }\` |
 | 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.
+Color names (confirmed from API): \`"blue"\`, \`"cyan"\`, \`"teal"\`, \`"green"\`, \`"yellow"\`, \`"orange"\`, \`"red"\`, \`"pink"\`, \`"purple"\`, \`"gray"\`.
+Set a default: \`"default": "selXXX"\` (string) for singleSelect, \`"default": ["selXXX"]\` (array) for multipleSelects.
 
 To **add choices without losing existing ones**, call \`get_table_schema\` first to get existing choice IDs, then pass the full merged list:
 \`\`\`json
 { "choices": [
     { "id": "selXXXXXXXXXXXXXX", "name": "Existing Choice" },
-    { "name": "New Choice", "color": "pinkLight2" }
+    { "name": "New Choice", "color": "pink" }
 ] }
 \`\`\`
 Choices **not** in the list are deleted. Omitting \`id\` creates a new choice.

packages/mcp-server/src/client.js

@@ -267,11 +267,19 @@ function generateChoiceId() {
  */
 function normalizeChoices(choices) {
   if (!choices) return choices;
-  if (!Array.isArray(choices)) return choices; // already object-keyed, pass through
+  if (!Array.isArray(choices)) {
+    // Already object-keyed — ensure each value includes its own id (required by internal API).
+    const result = {};
+    for (const [key, val] of Object.entries(choices)) {
+      result[key] = { id: key, ...val };
+    }
+    return result;
+  }
+  // Array form: generate IDs for new choices, preserve existing ids.
   const result = {};
   for (const { id, name, color, ...rest } of choices) {
     const key = id || generateChoiceId();
-    result[key] = { name, ...(color ? { color } : {}), ...rest };
+    result[key] = { id: key, name, ...(color ? { color } : {}), ...rest };
   }
   return result;
 }
@@ -312,12 +320,19 @@ function normalizeFieldType(type, typeOptions = {}) {
     };
   }
   // "multipleSelects" is the public/REST API name; internal API uses "multiSelect" (no "s").
-  // Also normalize choices from array form to the object form the internal API requires.
+  // Internal API requires: choices as keyed object with id inside each value, choiceOrder array,
+  // disableColors bool. default (array of IDs) lives OUTSIDE typeOptions at the payload root.
   if (type === 'multipleSelects' || type === 'multiSelect') {
-    return {
-      type: 'multiSelect',
-      typeOptions: { ...opts, ...(opts.choices ? { choices: normalizeChoices(opts.choices) } : {}) },
-    };
+    const { default: defaultVal, choices, choiceOrder: inputOrder, disableColors, ...restOpts } = opts;
+    const normalizedChoices = choices ? normalizeChoices(choices) : null;
+    const order = inputOrder || (normalizedChoices ? Object.keys(normalizedChoices) : null);
+    const typeOpts = { ...restOpts };
+    if (normalizedChoices) typeOpts.choices = normalizedChoices;
+    if (order) typeOpts.choiceOrder = order;
+    typeOpts.disableColors = disableColors !== undefined ? disableColors : false;
+    const result = { type: 'multiSelect', typeOptions: typeOpts };
+    if (defaultVal !== undefined) result.default = defaultVal;
+    return result;
   }
   // 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
@@ -335,12 +350,20 @@ function normalizeFieldType(type, typeOptions = {}) {
     }
     return { type, typeOptions: translated };
   }
-  // "singleSelect" is the public/REST API name; internal API uses "select" (mirrors multipleSelects → multiSelect).
+  // "singleSelect" is the public/REST API name; internal API uses "select".
+  // Internal API requires: choices as keyed object with id inside each value, choiceOrder array,
+  // disableColors bool. default (single ID string) lives OUTSIDE typeOptions at the payload root.
   if (type === 'singleSelect' || type === 'select') {
-    return {
-      type: 'select',
-      typeOptions: { ...opts, ...(opts.choices ? { choices: normalizeChoices(opts.choices) } : {}) },
-    };
+    const { default: defaultVal, choices, choiceOrder: inputOrder, disableColors, ...restOpts } = opts;
+    const normalizedChoices = choices ? normalizeChoices(choices) : null;
+    const order = inputOrder || (normalizedChoices ? Object.keys(normalizedChoices) : null);
+    const typeOpts = { ...restOpts };
+    if (normalizedChoices) typeOpts.choices = normalizedChoices;
+    if (order) typeOpts.choiceOrder = order;
+    typeOpts.disableColors = disableColors !== undefined ? disableColors : false;
+    const result = { type: 'select', typeOptions: typeOpts };
+    if (defaultVal !== undefined) result.default = defaultVal;
+    return result;
   }
   return { type, typeOptions: opts };
 }
@@ -611,6 +634,7 @@ export class AirtableClient {
     const normalized = normalizeFieldType(fieldConfig.type, fieldConfig.typeOptions);
 
     const config = { type: normalized.type };
+    if (normalized.default !== undefined) config.default = normalized.default;
     if (normalized.typeOptions && Object.keys(normalized.typeOptions).length > 0) {
       config.typeOptions = normalized.typeOptions;
     }
@@ -657,6 +681,7 @@ export class AirtableClient {
     // 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.default !== undefined) payload.default = normalized.default;
     if (normalized.typeOptions && Object.keys(normalized.typeOptions).length > 0) {
       payload.typeOptions = normalized.typeOptions;
     }

packages/mcp-server/src/index.js

@@ -135,10 +135,11 @@ const server = new Server(
     title: 'Airtable User MCP',
     version: PKG_VERSION,
     description:
-      'Manage Airtable bases with 35+ tools: schema inspection, table CRUD, ' +
-      'field CRUD (formula, rollup, lookup, count, url, dateTime, email, phone), ' +
-      'view configuration (filters, sorts, grouping, visibility), formula validation, ' +
-      'extension/block management, and tool profile control (read-only, safe-write, full, custom).',
+      'Manage Airtable base structure with 62 tools: schema inspection, table/field/view CRUD, ' +
+      'formula/rollup/lookup/count field management, view configuration (filters, sorts, groups, column layout), ' +
+      'select field choices with color support, formula validation and file-based bulk editing, ' +
+      'extension management, and granular tool profile control (read-only / safe-write / full / custom). ' +
+      'Record read/write/delete is handled by the official Airtable MCP — this server focuses on schema and structure.',
     websiteUrl: 'https://github.com/Automations-Project/VSCode-Airtable-Formula/tree/main/packages/mcp-server',
     icons: [{ src: ICON_DATA_URI, mimeType: 'image/png', sizes: ['128x109'] }],
   },
@@ -172,7 +173,7 @@ const TOOLS = [
   // ── Read Tools ──
   {
     name: 'get_base_schema',
-    description: 'Get the full schema of an Airtable base including all tables, fields, and views.',
+    description: 'Get the full schema of an Airtable base — all tables, fields (with typeOptions), and views in one call. Use this when you need fields or views; use `list_tables` when you only need table names/IDs (faster, lighter). Returns { tables: [...] }.',
     annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
     inputSchema: {
       type: 'object',
@@ -185,7 +186,7 @@ const TOOLS = [
   },
   {
     name: 'list_tables',
-    description: 'List all tables in an Airtable base with their IDs and names. Uses lightweight scaffolding data.',
+    description: 'List all tables in a base with their IDs and names — lightweight scaffolding call (no field data). Use this when you only need table IDs/names; use `get_base_schema` or `get_table_schema` when you also need fields or views. Returns [{ id, name }].',
     annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
     inputSchema: {
       type: 'object',
@@ -198,7 +199,7 @@ const TOOLS = [
   },
   {
     name: 'get_table_schema',
-    description: 'Get the full schema for a single table including all fields and views.',
+    description: 'Get the full schema for a single table — all fields (with typeOptions) and views. Use instead of `get_base_schema` when you only need one table (faster, less context). Use `list_fields` when you need fields only without view data. Returns { id, name, fields: [...], views: [...] }.',
     annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
     inputSchema: {
       type: 'object',
@@ -212,7 +213,7 @@ const TOOLS = [
   },
   {
     name: 'list_fields',
-    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.',
+    description: 'List fields in a table — returns id, name, type, and typeOptions per field. Use instead of `get_table_schema` when you need fields only (no view data). Use `fieldType` or `nameContains` filters on large tables to reduce context size. Returns [{ id, name, type, typeOptions }].',
     annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
     inputSchema: {
       type: 'object',
@@ -498,11 +499,16 @@ TYPE OPTIONS by fieldType:
   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" }] }
+  singleSelect:           { choices: [{ name: "Option A", color: "blue" }], default: "selXXX" }
+  multipleSelects:        { choices: [{ name: "PC", color: "blue" }, { name: "Xbox", color: "cyan" }], default: ["selXXX"] }
   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.`,
+SELECT CHOICES:
+  - Pass choices as an array [{ name, color? }] or as an object { selXXX: { name, color? } }.
+  - The client auto-adds id inside each choice value, generates choiceOrder, and sets disableColors: false.
+  - Color names (confirmed): "blue", "cyan", "teal", "green", "yellow", "orange", "red", "pink", "purple", "gray".
+  - "default" sets the pre-selected value: string ID for singleSelect, array of IDs for multipleSelects.
+  - To add/remove choices without losing existing ones, call get_table_schema first and include ALL choices in the update.`,
     annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
     inputSchema: {
       type: 'object',
@@ -530,7 +536,7 @@ SELECT CHOICES: pass an array of { name, color? } objects — the client auto-co
   },
   {
     name: 'create_formula_field',
-    description: 'Create a new formula field in a table. Shorthand for create_field with type "formula".',
+    description: 'Create a new formula field — shorthand for `create_field` with type "formula". Use `create_field` for all other field types (singleSelect, rollup, number, etc.). Returns { columnId }.',
     annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
     inputSchema: {
       type: 'object',
@@ -605,18 +611,21 @@ COMMON typeOptions by fieldType:
   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" }] }
+  singleSelect:    { choices: [{ name: "Option A", color: "blue" }], default: "selXXX" }
+  multipleSelects: { choices: [{ name: "PC", color: "blue" }, { name: "Xbox", color: "cyan" }], default: ["selXXX"] }
   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.
+SELECT CHOICES:
+  - Pass choices as array [{ name, color? }] or object { selXXX: { name, color? } }.
+  - Color names (confirmed): "blue", "cyan", "teal", "green", "yellow", "orange", "red", "pink", "purple", "gray".
+  - "default" = pre-selected value: string ID for singleSelect, array of IDs for multipleSelects.
 
 ADDING TO AN EXISTING SELECT FIELD (merge, not replace):
   Choices not in the list are DELETED. To add without losing existing choices:
   1. Call get_table_schema — each existing choice has { id, name, color }
   2. Pass the full list: existing entries WITH their id, new entries WITHOUT:
-     { choices: [{ id: "selXXXXXXXXXXXXXX", name: "Existing" }, { name: "New Choice", color: "pinkLight2" }] }
+     { choices: [{ id: "selXXXXXXXXXXXXXX", name: "Existing" }, { name: "New Choice", color: "pink" }] }
 
 REPLACING ALL CHOICES: just pass the new choices without any IDs.`,
     annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
@@ -637,7 +646,7 @@ REPLACING ALL CHOICES: just pass the new choices without any IDs.`,
   },
   {
     name: 'update_formula_field',
-    description: 'Update the formula text of an existing formula field. Shorthand for update_field_config with type "formula".',
+    description: 'Update the formula body of an existing formula field — shorthand for `update_field_config` with type "formula". Automatically preserves existing format/precision typeOptions (e.g. percentV2, precision). Use `update_field_config` to change the field type or other typeOptions.',
     annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
     inputSchema: {
       type: 'object',
@@ -671,7 +680,7 @@ REPLACING ALL CHOICES: just pass the new choices without any IDs.`,
   },
   {
     name: 'delete_field',
-    description: 'Delete a field from an Airtable table. Requires both fieldId AND the expected field name as a safety guard. First checks for downstream dependencies — if found, returns dependency info instead of deleting. Set force=true to delete even with dependencies.',
+    description: 'Delete a field from an Airtable table. Requires fieldId AND expectedName as a safety guard — deletion is refused if the name does not match. ⚠️ Irreversible: deleted field data is permanently lost and cannot be recovered. Always checks downstream dependencies first (formula fields, lookups, rollups referencing this field); returns dependency info without deleting unless force=true.',
     annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: false },
     inputSchema: {
       type: 'object',
@@ -933,7 +942,7 @@ EXAMPLES:
   },
   {
     name: 'show_or_hide_view_columns',
-    description: 'Show or hide specific fields (columns) in a view. Pass an array of column IDs and a single visibility flag — every ID in the array is set to that visibility. To toggle many fields at once, send the full set in one call (no separate "show all" / "hide all" tool exists today; that lives in 2.4.0+).',
+    description: 'Show or hide specific columns in a view without affecting others. Pass field IDs + a visibility flag — every listed ID is set to that state, all other columns are untouched. Use `set_view_columns` instead when you want to define the full visible set from scratch. Use `show_or_hide_all_columns` to bulk-toggle every column at once.',
     annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
     inputSchema: {
       type: 'object',
@@ -1115,7 +1124,7 @@ For section reorders, targetIndex is into the table's top-level mixed viewOrder;
   // ── View Columns (bulk visibility, ordering, freezing) ──
   {
     name: 'set_view_columns',
-    description: 'One-shot view-column setup. Hides every column in the view, then shows only `visibleColumnIds` in the order given (left-to-right), then optionally sets the frozen-column divider. Use this to turn a brand-new view from "all 168 fields visible" into a curated layout in a single tool call.',
+    description: 'One-shot view-column reset: hides every column then shows only `visibleColumnIds` in the given left-to-right order, with optional freeze. Use this for fresh view setup or full layout rewrites. Use `show_or_hide_view_columns` when you only want to toggle specific columns without touching the rest.',
     annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
     inputSchema: {
       type: 'object',
@@ -1131,7 +1140,7 @@ For section reorders, targetIndex is into the table's top-level mixed viewOrder;
   },
   {
     name: 'show_or_hide_all_columns',
-    description: 'Show or hide every column in a view in one call. Use `set_view_columns` for "hide all then show these specific ones" — this tool is the bulk all-or-nothing primitive.',
+    description: 'Show or hide every column in a view in one call. Use when you want a clean all-visible or all-hidden baseline. Use `set_view_columns` when you want to show a specific subset (it hides all then shows only the listed IDs). Use `show_or_hide_view_columns` for selective per-column toggles.',
     annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
     inputSchema: {
       type: 'object',
@@ -1146,7 +1155,7 @@ For section reorders, targetIndex is into the table's top-level mixed viewOrder;
   },
   {
     name: 'move_visible_columns',
-    description: 'Move one or more columns to a new position in the *visible-only* index. Index 0 is the leftmost visible column. Distinct from `reorder_view_fields` (which writes the full overall order — visible + hidden) and `move_overall_columns` (which also operates on overall index but accepts a partial array of columns to move).',
+    description: 'Move columns by visible-only index (index 0 = leftmost shown column, hidden columns not counted). Use when you want to position relative to what the user sees. Use `move_overall_columns` when you need to position relative to the full underlying column order including hidden fields. ⚠️ The API preserves existing relative order of supplied IDs — to place columns in a custom sequence, issue one call per column with incrementing targets.',
     annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
     inputSchema: {
       type: 'object',