salesforce-metadata-mcp 3.0.0 → 3.2.0

package/CHANGELOG.md

@@ -1,6 +1,172 @@
 # Changelog
 
-## [Unreleased]
+## [3.2.0] - 2026-09-23
+
+A full-surface QA release. Every one of the 233 tools was called individually over real MCP traffic
+(`tools/call` → schema → service → org) against a Developer Edition org and a scratch org with
+Communities, Service Cloud, Knowledge and Omni-Channel enabled, and each result was checked in the
+org with the sf CLI — never by the server under test. **3.1.0 and 3.1.1 were never published to npm,
+so this release also carries them** (lazy-toolset fallback, `sf_query_records` limit, `sf_find_tool`
+search — see below).
+
+Result on the scratch org: **170 PASS / 41 feature-unavailable / 4 org-limit / 17 open**, up from a
+baseline of 100 PASS / 114 failing on the first sweep. None of the 17 open items is a tool sending a
+wrong payload for a feature the org has: they are cascades (OmniStudio not installed, an org cap
+reached earlier in the run), unlicensed features (Agentforce, Einstein, Digital Engagement) and
+fixture gaps. **No tool claims success without doing the work.**
+
+### Fixed: tools that silently replaced a whole component
+`upsertMetadata` replaces what it names. Eight tools sent only the part they were changing, so they
+either failed or would have wiped the rest: compact layouts / list views / search layouts, queue
+routing config, connected-app OAuth policy, the five Workflow children (a `Workflow` upsert replaces
+an object's entire workflow — the old 500s were the only reason nothing was lost), business hours,
+holidays, LWC Jest tests, and forecasting settings. Each now addresses its component directly or
+reads, modifies and writes it back.
+
+### Fixed: tools that could not succeed at all
+Around 50 tools, including: custom tabs, custom notification types, roles (access-level enum and
+forecast-manager default), FlexiPages, SAML SSO, change data capture, quick/global actions, auth
+providers with custom endpoints, sharing rules, dashboards, path assistants, scheduled flows,
+duplicate rules (a bare Allow is rejected — Allow now carries Report), data category groups
+(`KnowledgeArticleVersion`), service territories (operating hours), Experience sites (now created
+through the Connect API from a real template), and package versions (`--installation-key-bypass`).
+The full create → version → install → uninstall packaging chain is verified end to end.
+
+### Fixed: errors nobody could act on
+Bare 404s and 500s now name the cause: sandboxes and change sets on editions without them, DevOps
+Center not installed, a connected app on an org that only allows External Client Apps, an Experience
+page (Salesforce has no REST endpoint for creating one — the tool now says so), scheduled-job compile
+errors, and upserts whose external-ID field is invisible to the running user.
+
+### Changed
+- `sf_create_forecast_hierarchy`: `forecastingType` is now a string checked against the org (the old
+  enum offered names that do not exist). Unknown names return the org's list.
+- `sf_create_experience_site` returns the site URL, Builder link and the Site API names Salesforce
+  chose (it derives them from the label).
+
+### Added
+- `qa-full-sweep.mjs` and friends: the full-surface sweep, with a four-way verdict
+  (PASS / UNAVAIL / LIMIT / BUG). `QA_DEVHUB=<alias>` enables the real packaging chain.
+- `qa-workflow-children.mjs`, `qa-translation-merge.mjs`, `qa-scratch-fixes.mjs`: pins for the
+  fixes above.
+
+## [3.1.1] - 2026-09-09
+
+Three bugs reported against a Claude Desktop session. **None were introduced by 3.1.0.** Two date to
+the first public release (`f808b50`, v2.6.5) and one to the lazy-toolsets change in 3.0.0
+(`479a40d`) — traced with `git log -S`/`-L`, not assumed.
+
+### Fixed: `sf_query_records` ignored its own `limit` (since v2.6.5)
+
+`limit` was only interpolated into the SOQL `queryRecords` *builds* from `objectApiName`/`fields`.
+Every call through `sf_query_records` passes a `query` string, which takes the other branch, so the
+parameter — and its documented default of 200 — did nothing. A caller setting `limit: 100` to stay
+small got 1,323 rows and no warning; the failure was silent and failed open.
+
+The cap is now applied by rewriting the outgoing SOQL, so it reduces what Salesforce sends rather
+than only what the tool returns. **Precedence is `min(parameter, LIMIT in the query)`**: the
+parameter is a guardrail, so a `LIMIT` in the query string may tighten it but never raise it, while
+a caller who explicitly wrote `LIMIT 5` still gets 5.
+
+A cap that is applied but not reported would just be a silent truncation — the same bug wearing a
+different hat — so the response now carries `appliedLimit`, `limitSource` and `truncated`, and the
+message says when rows were cut off. `truncated` is a fact, not a guess: one row beyond the cap is
+fetched to distinguish "exactly N matched" from "more than N matched", then discarded. Aggregate
+(`COUNT()`), `OFFSET` and `FOR UPDATE` queries are handled without being rewritten into invalid SOQL.
+
+### Fixed: `sf_find_tool` returned nothing for multi-word queries (since v3.0.0)
+
+The search required *every* token to appear in a tool name, so any natural-language phrase returned
+`matches: []` — including two of the tool's own documented examples. That is the worst moment to
+return an empty list: this tool is reached precisely when someone cannot find a capability and is
+describing it in words, and an empty result reads as "no such tool exists" rather than "rephrase".
+
+Matching is now scored rather than filtered — any token can match, ranked by how many hit, with an
+exact tool name always first. Tool **titles and descriptions are searched too**, at a lower weight
+than names, because a phrase like *"run some apex code in the org"* cannot be resolved from names
+alone (`sf_run_apex_tests` wins on tokens while the caller means `sf_execute_anonymous_apex`).
+Common filler words are dropped.
+
+Two guards came with it, since a looser match could otherwise undo the point of lazy toolsets:
+results are capped at the 25 best matches, and a single search auto-loads at most 3 toolsets — those
+from the top-scoring band only. Lower-ranked matches are named in the response instead of loaded.
+
+### Fixed: Salesforce error messages truncated mid-sentence (since v2.6.5)
+
+API error bodies were cut with a flat `slice(0, 300)`, and Salesforce puts the actionable part at
+the end — *"…be sure to append the '__c' after the entity name. Please refer to…"* arrived as
+*"…Please ref"*. A cap is still wanted, since an error body can be a whole HTML page, so oversized
+errors now keep a generous head **and** the tail, with a count of what was dropped.
+
+### Notes
+
+- `sf_find_tool` now attaches input schemas to the top 3 **ranked** matches rather than only when
+  the whole result set was ≤3. Broader matching pushed even exact-name queries past that threshold,
+  which cost them the schema `sf_call_tool` needs.
+- **Inlined schemas are now bounded by size, not just count** — found by measuring the release
+  rather than from a report. A count is not a bound: `sf_create_flow` serialises to ~28KB, so
+  `sf_find_tool("create flow")` was returning ~8,500 tokens, most of what a whole default startup
+  costs. v3.0.0 had moved that tool out of the default toolset for exactly this reason, and inlining
+  it on search quietly put it back. Oversized schemas are now named with a pointer to
+  `sf_tool_schema` instead of being sent. Measured after: 8,532 → 1,721 tokens for the same call,
+  and every `sf_find_tool` response now lands between ~1.4k and ~2.5k tokens.
+- New `qa-query-limit.mjs` (17 checks) covers the cap, its precedence, truncation reporting, the
+  aggregate/OFFSET edge cases and the error-text length. `qa-toolsets.mjs` gains natural-language
+  search coverage and the auto-load bounds (26 → 38 checks).
+- Verified against `demo-org` before and after: `limit: 3` returned 1,764 rows before the fix and 3
+  after.
+
+## [3.1.0] - 2026-09-09
+
+### Fixed: loaded toolsets could be unreachable on clients that ignore `list_changed`
+
+Reported against Claude Desktop: `sf_load_toolset(["apex","data"])` returned `success: true` with
+`residentTools` moving 18 → 47, `sf_find_tool` confirmed the tools existed in a loaded toolset, and
+not one of them was ever callable. The entire write surface of the server — anonymous Apex, record
+creation, bulk insert — was unreachable for a whole session while every status payload reported
+healthy. Reads kept working, because the initially-resident set was never affected.
+
+The server was not violating the protocol. It declares `tools.listChanged`, emits exactly one
+`notifications/tools/list_changed` per load, and `tools/list` genuinely changes — all now asserted
+end-to-end in `qa-client-refetch.mjs`. The client never re-fetched.
+
+Being protocol-correct was not enough. Lazy toolsets put 210 of 228 tools behind an *optional*
+client behaviour with no fallback when it is absent, so v3.1.0 adds one that needs no re-fetch:
+
+- **`sf_call_tool({ tool, arguments })`** — invokes any tool by name whether or not its toolset is
+  loaded and whether or not it appears in the client's tool list. Arguments are validated against
+  the same zod schema, and the handler it calls is the guard-wrapped one, so the production guard
+  applies exactly as on a direct call. It cannot invoke itself or the other meta-tools.
+- **`sf_tool_schema({ tool })`** — returns any tool's input schema, loaded or not, so a model can
+  construct that call for a tool it cannot see.
+- **`sf_find_tool`** now returns input schemas inline when a query matches three tools or fewer,
+  collapsing find → call into a single round trip. Wider searches still return names only, so this
+  does not reintroduce the context cost lazy toolsets exist to avoid.
+- **`sf_load_toolset`** now checks whether the client re-fetched `tools/list` after the notification
+  and reports `clientDidNotRefresh: true` with instructions to use `sf_call_tool`, rather than
+  claiming an unqualified success for tools that have silently become unreachable.
+
+With this, the full 228-tool surface is reachable from the handshake tool list alone, even under
+`SF_TOOLSETS=none`.
+
+The regression this adds is deliberately end-to-end. Every internal signal — `loadedToolsets`,
+`residentTools`, `sf_find_tool` matches — was correct throughout the reported session, so asserting
+on any of them would have passed cleanly while the server was unusable. `qa-client-refetch.mjs`
+instead drives two simulated clients, one that honours `list_changed` and one that never re-fetches,
+and asserts what the model can actually call.
+
+Also fixed along the way: `sf_call_tool`'s first implementation assumed `inputSchema` was always a
+`ZodRawShape`, but the shared schemas in `src/schemas` are built `ZodObject`s. Both forms are now
+normalised, matching what the SDK itself does.
+
+### Notes
+
+- Meta-tool count goes from 3 to 5, so the default startup listing is 20 tools rather than 18 and
+  `SF_TOOLSETS=all` lists 233 rather than 231. No Salesforce tool was added, removed or renamed.
+- `zod-to-json-schema` is now a direct dependency. It was already present transitively — the MCP SDK
+  uses it to serialise Zod v3 schemas — and this server now uses it for the same purpose.
+
+## [3.0.0] - 2026-09-02
 
 ### Production write guard
 

package/README.md

@@ -76,26 +76,46 @@ starts with a small core loaded and pulls in the rest on demand:
 
 | Startup | Tools listed | Approx. tokens |
 |---------|-------------:|---------------:|
-| Default (`core,metadata`) | 18 | **~9,400** |
-| After loading two more toolsets | 41 | ~20,300 |
-| `SF_TOOLSETS=all` | 231 | ~98,600 |
+| Default (`core,metadata`) | 20 | **~9,900** |
+| After loading two more toolsets | 43 | ~20,800 |
+| `SF_TOOLSETS=all` | 233 | ~99,100 |
 
 The default covers what nearly every session needs: describe/list objects, SOQL query,
 deploy/retrieve/delete metadata, deploy status, and core schema creation (objects, fields, formula
 fields, picklist values, validation rules, approval processes).
 
-Three tools are always present and make everything else reachable:
+Five tools are always present and make everything else reachable:
 
 - **`sf_find_tool`** — search all 228 tools by name and load whatever contains the matches, in one
   call. Ask for *"create an omniscript"* and it finds the tools, loads `omnistudio`, and they are
   callable immediately. This is usually all you or the model needs.
 - **`sf_load_toolset`** — load named toolsets explicitly.
 - **`sf_list_toolsets`** — browse all toolsets, their tool counts, and what is loaded.
+- **`sf_call_tool`** — invoke any tool by name, loaded or not, without it having to appear in the
+  tool list first. Arguments are validated and the production guard applies exactly as on a direct
+  call.
+- **`sf_tool_schema`** — return any tool's input schema, so `sf_call_tool` can be constructed for a
+  tool the client cannot see.
 
 In practice you don't manage this by hand: ask for what you want, and the model loads what it needs.
 
+### If loaded tools don't show up
+
+Loading a toolset enables it on the server and emits `notifications/tools/list_changed`. A client is
+supposed to re-fetch `tools/list` when it sees that. Some clients don't — and when that happens, the
+load reports success, the tools really are enabled, and the model still cannot call any of them
+because they never entered its tool list.
+
+Two things handle this, so no client can lose access to a tool:
+
+- `sf_load_toolset` checks whether the client re-fetched and says so in its response, instead of
+  reporting an unqualified success for tools that have become unreachable.
+- `sf_call_tool` reaches every tool without needing a re-fetch at all. Combined with `sf_tool_schema`,
+  the full 228-tool surface is usable from the handshake tool list alone — even under
+  `SF_TOOLSETS=none`.
+
 To restore the previous behaviour of loading everything at startup, set `SF_TOOLSETS=all`. To start
-with only the three meta-tools, set `SF_TOOLSETS=none`. To pick your own core, pass a list:
+with only the five meta-tools, set `SF_TOOLSETS=none`. To pick your own core, pass a list:
 
 ```json
 { "env": { "SF_TOOLSETS": "metadata,objects,automation,security" } }