refactor(tools): move download_* to a new local-write category

download_formula_field and download_base_formulas READ from Airtable but
WRITE .formula files to a caller-chosen path, so they did not belong in the
`read` category -- the read-only profile is advertised as "Schema inspection,
formula validation, and record reading only". Correcting the readOnlyHint
annotation (previous commit) restored the MCP client's consent prompt, but the
profile itself still claimed a file-writing tool was read-only.

New `local-write` category, included in safe-write and full, so those tool
sets are unchanged (54 / 72). Only read-only changes: 12 -> 10.

Deliberately NOT added to LEGACY_CATEGORIES_DEFAULT_ON, per the invariant
documented there -- a pre-existing on-disk `custom` profile must not silently
widen to include a category it never opted into.

Propagated through every mirror the sync guard checks: tool-config.js,
tool-profile.ts, shared types, extension package.json (new
mcp.categories.localWrite setting + enumDescriptions), webview store +
Settings toggle + store test, CLAUDE.md, all three READMEs, skill templates
and the three banner SVGs.

Verified: check:tool-sync green at 10/54/72 with 17 labels, 1451 mcp-server
+ 421 extension + 88 webview tests pass, pnpm build clean.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: ARHAEEM

CLAUDE.md

@@ -51,7 +51,7 @@ Typed message protocol between extension host and webview. Exports `ExtensionMes
 React 19 + Vite 6 + Tailwind CSS v4 + Zustand 5 dashboard. Three tabs: Overview, Setup, Settings. Builds directly into `packages/extension/dist/webview/`. Communicates with the extension host via `acquireVsCodeApi().postMessage()` — messages are typed through the shared package.
 
 ### packages/mcp-server
-The Airtable MCP server itself — ES modules Node app, **published to npm as `airtable-user-mcp`**. Provides **72 tools** across 16 categories (read, record-read, table-write, table-destructive, field-write, field-destructive, view-write, view-destructive, view-section, view-section-destructive, form-write, extension, record-write, record-destructive, sync, daemon) via `@modelcontextprotocol/sdk`. Includes `upload_attachment` (record-write) which writes attachment cells by URL — the general `update_records` tool cannot set attachment cells. The `daemon` category holds exactly one tool, `manage_daemon` (`src/daemon/manage.js`) — the only way the model can see its own runtime: `action=status` reports daemon liveness/holder/transport/uptime/tunnel plus the live session state (`sessionDead`, the last breaker trip including Airtable's captured response body, the browser busy queue), which is what distinguishes *daemon gone* from *session dead* from *browser busy*. `start`/`restart`/`stop`/`tunnel_*`/`token_rotate` administer the process; `stop`/`restart` answer first and exit from a `res.on('finish')` hook in `daemon/server.js` (exiting from the handler deadlocks the SDK's `enableJsonResponse` promise), `stop` writes a `daemon.stopped` sentinel so the extension does not silently respawn, and `token_rotate`/`tunnel_*` are refused for tunnel-origin callers. `daemon` is **`full`-profile only** and defaults off for pre-existing `custom` profiles. Uses `patchright` (Chromium stealth fork) with a persistent profile for browser-based authentication against Airtable's internal API. **Transport:** API calls run through a direct node HTTP transport (`src/http-transport.js`; `fetch` default, `impit` Chrome-TLS-impersonation via `AIRTABLE_HTTP_CLIENT=impit`) — NOT through the browser page; the browser mints/refreshes the session cookie only. Proxy env (`HTTP_PROXY`/`HTTPS_PROXY`/`NO_PROXY`) is honored by the `fetch` client via undici's `EnvHttpProxyAgent` (`src/proxy.js`; `undici` is an optionalDependency — absent → direct, one warning); the `impit` client is NOT proxy-aware, and TLS-inspecting proxies additionally need `NODE_EXTRA_CA_CERTS` (Node ignores the OS trust store). Auth is cookie-only (no bearer/API key). `AIRTABLE_AUTH_MODE`: `browser` (default) | `byo` (cookie-only, no browser — `AIRTABLE_COOKIE` or `~/.airtable-user-mcp/credentials.json`, csrf auto-scraped; `src/byo-credentials.js`) | `direct-login` (browser-free login via impit + otpauth TOTP replaying the HTTP login flow; `src/direct-login.js`).
+The Airtable MCP server itself — ES modules Node app, **published to npm as `airtable-user-mcp`**. Provides **72 tools** across 17 categories (read, record-read, table-write, table-destructive, field-write, field-destructive, view-write, view-destructive, view-section, view-section-destructive, form-write, extension, record-write, record-destructive, sync, daemon, local-write) via `@modelcontextprotocol/sdk`. Includes `upload_attachment` (record-write) which writes attachment cells by URL — the general `update_records` tool cannot set attachment cells. The `daemon` category holds exactly one tool, `manage_daemon` (`src/daemon/manage.js`) — the only way the model can see its own runtime: `action=status` reports daemon liveness/holder/transport/uptime/tunnel plus the live session state (`sessionDead`, the last breaker trip including Airtable's captured response body, the browser busy queue), which is what distinguishes *daemon gone* from *session dead* from *browser busy*. `start`/`restart`/`stop`/`tunnel_*`/`token_rotate` administer the process; `stop`/`restart` answer first and exit from a `res.on('finish')` hook in `daemon/server.js` (exiting from the handler deadlocks the SDK's `enableJsonResponse` promise), `stop` writes a `daemon.stopped` sentinel so the extension does not silently respawn, and `token_rotate`/`tunnel_*` are refused for tunnel-origin callers. `daemon` is **`full`-profile only** and defaults off for pre-existing `custom` profiles. Uses `patchright` (Chromium stealth fork) with a persistent profile for browser-based authentication against Airtable's internal API. **Transport:** API calls run through a direct node HTTP transport (`src/http-transport.js`; `fetch` default, `impit` Chrome-TLS-impersonation via `AIRTABLE_HTTP_CLIENT=impit`) — NOT through the browser page; the browser mints/refreshes the session cookie only. Proxy env (`HTTP_PROXY`/`HTTPS_PROXY`/`NO_PROXY`) is honored by the `fetch` client via undici's `EnvHttpProxyAgent` (`src/proxy.js`; `undici` is an optionalDependency — absent → direct, one warning); the `impit` client is NOT proxy-aware, and TLS-inspecting proxies additionally need `NODE_EXTRA_CA_CERTS` (Node ignores the OS trust store). Auth is cookie-only (no bearer/API key). `AIRTABLE_AUTH_MODE`: `browser` (default) | `byo` (cookie-only, no browser — `AIRTABLE_COOKIE` or `~/.airtable-user-mcp/credentials.json`, csrf auto-scraped; `src/byo-credentials.js`) | `direct-login` (browser-free login via impit + otpauth TOTP replaying the HTTP login flow; `src/direct-login.js`).
 
 Standalone users install via `npx airtable-user-mcp` or `npm i -g airtable-user-mcp`. The CLI exposes subcommands: `login`, `logout`, `status`, `doctor`, `install-browser`, `daemon start/stop/status`. Config and session data live in `~/.airtable-user-mcp/`.
 
@@ -267,8 +267,8 @@ Located at `packages/mcp-server/dev-tools/` (gitignored):
 
 All under `airtableFormula.*`:
 - `mcp.autoConfigureOnInstall` — auto-write MCP config to detected IDEs on first launch
-- `mcp.toolProfile` — `read-only` (12 tools) / `safe-write` (54 tools) / `full` (72 tools) / `custom`
-- `mcp.categories.{read,recordRead,recordWrite,recordDestructive,tableWrite,tableDestructive,fieldWrite,fieldDestructive,viewWrite,viewDestructive,viewSection,viewSectionDestructive,formWrite,extension,sync,daemon}` — per-category toggles when profile is `custom`. `sync`, `recordDestructive` and `daemon` default to **off**; the other 13 default to on.
+- `mcp.toolProfile` — `read-only` (10 tools) / `safe-write` (54 tools) / `full` (72 tools) / `custom`
+- `mcp.categories.{read,recordRead,recordWrite,recordDestructive,tableWrite,tableDestructive,fieldWrite,fieldDestructive,viewWrite,viewDestructive,viewSection,viewSectionDestructive,formWrite,extension,sync,daemon,localWrite}` — per-category toggles when profile is `custom`. `sync`, `recordDestructive` and `daemon` default to **off**; the other 13 default to on.
 - `mcp.daemonPort` — fixed TCP port for the shared MCP daemon HTTP server (default 8723, kept stable across restarts; 0 = automatic/ephemeral; falls back to an automatic port if the chosen port is busy; takes effect on next daemon restart)
 - `mcp.authMode` — `browser` (default; headless Chrome mints the cookie, calls go direct-HTTP) / `byo` (cookie-only, no browser; cookie from `~/.airtable-user-mcp/credentials.json` or `AIRTABLE_COOKIE`) / `direct-login` (browser-free email+password+TOTP; `login.json` or `AIRTABLE_EMAIL/PASSWORD/TOTP_SECRET`). Injected as `AIRTABLE_AUTH_MODE` into the spawned server via `buildDaemonEnv`/`registration.ts` (non-default only). Takes effect on next daemon/server restart.
 - `mcp.httpClient` — `fetch` (default) / `impit` (Chrome-TLS impersonation fallback). Injected as `AIRTABLE_HTTP_CLIENT`. `impit` must be available to the server (optionalDependency; add to the vendored deps for the bundled path).

README.md

@@ -70,7 +70,7 @@
 | **IDE Auto-Setup** | One-click MCP config for Cursor, Windsurf, Claude Desktop, Cline, Amp | — |
 | **AI Skills** | Pre-built Airtable-specific rules and workflows for AI coding assistants | — |
 | **Daemon + Tunnel** | Persistent background server; optional Cloudflare or ngrok remote access | — |
-| **Tool Profiles** | `read-only` (12 tools) / `safe-write` (54 tools) / `full` (72 tools) / `custom` permission scopes | — |
+| **Tool Profiles** | `read-only` (10 tools) / `safe-write` (54 tools) / `full` (72 tools) / `custom` permission scopes | — |
 | **OS Keychain Auth** | Browser-based Airtable login with SSO/2FA — credentials in your OS keychain | — |
 
 ---
@@ -127,7 +127,7 @@ This is a coverage map, not a "pick one" decision — the two servers are comple
 | **Extension / block management (install, enable, rename, duplicate, remove)** | ❌ | ✅ |
 | **Create dashboard pages** | ❌ | ✅ |
 | **Daemon self-diagnosis (session dead? browser busy? daemon gone?)** | ❌ | ✅ `manage_daemon` `action=status`, plus start / restart / stop / tunnel / token rotation |
-| **Tool profiles & per-tool toggles** | ❌ | ✅ read-only (12) / safe-write (54) / full (72) / custom |
+| **Tool profiles & per-tool toggles** | ❌ | ✅ read-only (10) / safe-write (54) / full (72) / custom |
 | **Destructive-action safety guards** | Relies on token scopes | ✅ `expectedName` match, dependency summary, `force` flag |
 | **Batch record create limit** | 10 / request | Uses the same Airtable limit; no added restriction |
 | **VS Code / Cursor / Windsurf / Cline / Amp one-click install** | Manual JSON edit per IDE | ✅ One click via the companion extension |

packages/extension/package.json

@@ -531,7 +531,7 @@
             "custom"
           ],
           "enumDescriptions": [
-            "Schema inspection, formula validation, and record reading only (12 tools)",
+            "Schema inspection, formula validation, and record reading only (10 tools)",
             "Read + record read/write + create/update tables, fields, views, sidebar sections, and record templates, no deletes, no form metadata (54 tools)",
             "All tools enabled including destructive ops, form metadata, extensions, and daemon control (72 tools)",
             "User-defined per-tool selection"
@@ -618,6 +618,11 @@
           "default": false,
           "description": "Daemon Control tool: manage_daemon (inspect and administer the MCP daemon itself — not Airtable). action=status is read-only and reports daemon liveness, transport, uptime, tunnel URL and the live session/browser state; start, restart, stop, tunnel_enable, tunnel_disable and token_rotate control the running process. Off by default: this lets an AI agent stop or restart the server it is talking through."
         },
+        "airtableFormula.mcp.categories.localWrite": {
+          "type": "boolean",
+          "default": true,
+          "description": "Local File Write tools: download_formula_field, download_base_formulas. These READ from Airtable but WRITE .formula files to a path the caller chooses, so they are not part of the read-only profile. Included in safe-write and full."
+        },
         "airtableFormula.mcp.tools": {
           "type": "object",
           "default": {},

packages/extension/src/mcp/tool-profile.ts

@@ -29,7 +29,7 @@ type ExtraCategoryKey =
   | 'view-section' | 'view-section-destructive'
   | 'form-write'
   | 'record-read' | 'record-write' | 'record-destructive'
-  | 'sync' | 'daemon';
+  | 'sync' | 'daemon' | 'local-write';
 export const TOOL_CATEGORIES: Record<string, keyof ToolCategories | ExtraCategoryKey> = {
   // Read-only / inspection
   get_base_schema:           'read',
@@ -41,8 +41,8 @@ export const TOOL_CATEGORIES: Record<string, keyof ToolCategories | ExtraCategor
   validate_formula:          'read',
   list_view_sections:        'read',
   list_record_templates:     'read',
-  download_formula_field:    'read',
-  download_base_formulas:    'read',
+  download_formula_field:    'local-write',
+  download_base_formulas:    'local-write',
   // Record read (snapshot read via readQueries)
   query_records:             'record-read',
   // Table mutations (non-destructive)
@@ -138,6 +138,7 @@ export const CATEGORY_LABELS: Record<string, string> = {
   'record-destructive':       'Record Destructive',
   'sync':                     'Sync',
   'daemon':                   'Daemon Control',
+  'local-write':              'Local File Write',
 };
 
 interface ProfileDef {
@@ -149,15 +150,15 @@ interface ProfileDef {
 export const BUILTIN_PROFILES: Record<'read-only' | 'safe-write' | 'full', ProfileDef> = {
   'read-only': { description: 'Schema inspection, formula validation, and record reading only', categories: ['read', 'record-read'] },
   'safe-write':{ description: 'Read + record read/write + create/update tables, fields, views, sidebar sections, and record templates (no deletes, no form metadata)',
-                 categories: ['read', 'record-read', 'record-write', 'table-write', 'field-write', 'view-write', 'view-section'] },
+                 categories: ['read', 'record-read', 'record-write', 'table-write', 'field-write', 'view-write', 'view-section', 'local-write'] },
   full:        { description: 'All tools enabled including destructive ops, form metadata, extensions, and daemon control',
                  categories: [
                    'read', 'record-read', 'record-write', 'record-destructive',
                    'table-write', 'table-destructive',
                    'field-write', 'field-destructive',
                    'view-write', 'view-destructive',
                    'view-section', 'view-section-destructive',
-                   'form-write', 'extension', 'sync', 'daemon',
+                   'form-write', 'extension', 'sync', 'daemon', 'local-write',
                  ] },
 };
 
@@ -183,6 +184,7 @@ export const SETTINGS_TO_CATEGORY: Record<keyof ToolCategories, string> = {
   recordWrite:             'record-write',
   sync:                    'sync',
   daemon:                  'daemon',
+  localWrite:              'local-write',
 };
 
 // Inverse: file-format category key → settings key suffix
@@ -288,6 +290,7 @@ export class ToolProfileManager implements vscode.Disposable {
       recordWrite:            cfg.get('mcp.categories.recordWrite',            true),
       sync:                   cfg.get('mcp.categories.sync',                   false),
       daemon:                 cfg.get('mcp.categories.daemon',                 false),
+      localWrite:             cfg.get('mcp.categories.localWrite',             true),
     };
     return {
       profile,
@@ -345,6 +348,7 @@ export class ToolProfileManager implements vscode.Disposable {
       'record-write', 'record-destructive',
       'sync',
       'daemon',
+      'local-write',
     ];
     for (const cat of categoryOrder) {
       const label = CATEGORY_LABELS[cat] ?? cat;

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

@@ -304,7 +304,7 @@ When user wants to convert an Excel formula to Airtable.
 export const MCP_TOOLS_GUIDE = `# Airtable MCP — Tools Guide
 
 > **Server**: airtable-user-mcp v2.4.x  |  **Protocol**: MCP (JSON-RPC 2.0)
-> **Tools**: 72 tools across 16 categories + \`manage_tools\`
+> **Tools**: 72 tools across 17 categories + \`manage_tools\`
 
 ---
 
@@ -771,7 +771,7 @@ and use airtable-user-mcp \`query_records\` to read/search data (especially when
 
 - **Name**: airtable-user-mcp  |  **Version**: 2.4.x
 - **Protocol**: Model Context Protocol (JSON-RPC 2.0)
-- **Tools**: 72 tools across 16 categories + \`manage_tools\`
+- **Tools**: 72 tools across 17 categories + \`manage_tools\`
 - **Auth**: browser session (or PAT via Official MCP panel in the VS Code extension)
 
 ## Mandatory Workflows

packages/mcp-server/CHANGELOG.md

@@ -2,6 +2,18 @@
 
 ## [Unreleased]
 
+### Changed (2026-08-01 — new `local-write` category; read-only is 12 → 10 tools)
+
+- **`download_formula_field` and `download_base_formulas` moved out of `read` into a new
+  `local-write` category.** They READ from Airtable but WRITE .formula files to a path the caller
+  chooses, so a profile advertised as "Schema inspection, formula validation, and record reading
+  only" had no business containing them — the annotation fix in the previous entry restored the
+  client's consent prompt, but the profile itself was still mislabelled. `local-write` is included
+  in **safe-write** and **full**, so those tool sets are UNCHANGED (54 / 72); only **read-only**
+  changes, 12 → 10. Deliberately NOT added to `LEGACY_CATEGORIES_DEFAULT_ON`, so a pre-existing
+  `custom` profile does not silently widen to include it. New setting:
+  `airtableFormula.mcp.categories.localWrite` (default true).
+
 ### Fixed (2026-07-31 — sync prune could delete data it had not replaced)
 
 - **`pruneRecords` had only a RUN-wide failure gate.** The "don't prune after a failed run" check

packages/mcp-server/README.md

@@ -111,7 +111,7 @@ The official Airtable MCP is a thin wrapper over the public Web API. That API 
 | Form metadata (description, redirect, attribution, branding) | ❌ | ✅ |
 | Extension & dashboard page management | ❌ | ✅ install, enable, rename, duplicate, remove |
 | Daemon self-diagnosis (is the session dead, the browser busy, or the daemon gone?) | ❌ | ✅ `manage_daemon` `action=status` — plus start / restart / stop / tunnel / token rotation |
-| Tool profiles & per-tool toggles | ❌ | ✅ `read-only` (12 tools) / `safe-write` (54 tools) / `full` (72 tools) / `custom` |
+| Tool profiles & per-tool toggles | ❌ | ✅ `read-only` (10 tools) / `safe-write` (54 tools) / `full` (72 tools) / `custom` |
 | Install effort | Manual PAT + JSON edit per client | Single `claude mcp add` or JSON snippet |
 | Price | Free | Free, MIT |