salesforce-metadata-mcp 2.11.2 → 3.0.0

package/CHANGELOG.md

@@ -1,5 +1,195 @@
 # Changelog
 
+## [Unreleased]
+
+### Production write guard
+
+This server hands an LLM a Salesforce credential and lets the LLM decide what to do with it. Any
+text the model reads along the way — a case comment, a field description, a retrieved `.flow` file,
+an email body — can carry an instruction, and nothing downstream can distinguish it from one the
+user typed. Salesforce's own hosted MCP servers ship a blunt version of the same defence: they
+create and update records but refuse to delete, with deletes behind a separate opt-in server.
+
+Nine tools are now refused against a **production** org: `sf_delete_metadata`, `sf_delete_record`,
+`sf_bulk_delete_records`, `sf_execute_anonymous_apex`, `sf_uninstall_package`, `sf_create_user`,
+`sf_update_user`, `sf_reset_user_password`, `sf_freeze_user`. Set `SF_PRODUCTION_GUARD=strict` to
+refuse every write instead, or `=off` to disable the guard.
+
+**Metadata creation is deliberately untouched.** All 137 `sf_create_*` tools, `sf_deploy_metadata`
+and `sf_retrieve_metadata` still work against production. `sf_deploy_metadata` was reviewed and
+left open because it has no `destructiveChanges` path — it builds a package.xml from the components
+passed to it and can only add or upsert. A guard that taxed metadata authoring would be turned off
+on day one, which is worse than no guard because it would then be off for everything too.
+
+Apex authoring (`sf_create_apex_class`, `sf_create_apex_trigger`) is also left open, even though a
+trigger is arbitrary code running on every DML. The line drawn is auditability: created Apex is
+metadata with a name, an author and a deploy record, and can be found and removed afterwards.
+`sf_execute_anonymous_apex` leaves no artifact at all, which is why it is the Apex path that is
+blocked. This is a real residual risk and is documented rather than papered over.
+
+An org counts as production only when it is not a sandbox, not a Developer Edition org, and has no
+trial expiry. **`IsSandbox = false` alone is not sufficient** — Developer Edition and scratch orgs
+both report `false`, and gating those would have made the feature unusable for everyone developing
+against a dev org. Org identity is resolved once per process and cached; if it cannot be determined,
+the org is treated as production (fail closed).
+
+The guard is a hard refusal rather than a confirmation prompt, because a prompt the calling agent
+can satisfy by itself is not a control — and this server is routinely run under clients with
+permissions bypassed. Only an environment variable set outside the conversation lifts it.
+
+Implemented in `src/services/guard.ts` and wired through the single `ToolsetRegistry.capture()`
+proxy, so every current and future tool passes through it without the 33 tool modules changing.
+Covered by `qa-guard.mjs` (26 checks), including assertions that each metadata-creation tool stays
+allowed and that Developer Edition / scratch / sandbox orgs are never treated as production.
+
+### Security: sf_deploy_metadata could be turned into a metadata deletion primitive
+
+Found by attacking the guard above rather than in review, and it was live in every published version
+that shipped `sf_deploy_metadata` with the `componentsXml` parameter.
+
+`inferMetadataPath`'s `default` branch (unrecognised metadata types) returned `` `${lower}s/${name}` ``
+with no extension appended, so the caller-supplied `name` controlled the tail of the zip path
+outright. A component of `{ type: "X", name: "../destructiveChanges.xml" }` produced the zip path
+`xs/../destructiveChanges.xml`, which JSZip normalises to a **root-level `destructiveChanges.xml`** —
+the manifest the Metadata API uses to *delete* every component listed in it. Confirmed by reading the
+generated archive's entry list, not by inspection.
+
+Impact: `sf_deploy_metadata` was documented and treated as additive-only (it is not in the production
+guard's blocked set for exactly that reason), while in fact being able to delete arbitrary metadata
+from any org the server could reach — bypassing the block on `sf_delete_metadata` completely.
+
+Fixed by validating component names before they reach the zip: path separators and `..` are rejected,
+as are the reserved manifest names `package.xml`, `destructiveChanges.xml`,
+`destructiveChangesPre.xml` and `destructiveChangesPost.xml` (case-insensitively). The assembled path
+is re-checked afterwards so a future branch that builds a path some other way cannot reintroduce this.
+Salesforce component names cannot contain path separators in any metadata type, so nothing legitimate
+is rejected. `sf_deploy_metadata` therefore stays available against production, as intended.
+
+### Security: production guard evaluated the wrong org for tools taking an org override
+
+`uninstallPackage()` ignores its `auth` argument entirely and shells out to
+`sf package uninstall --target-org <params.targetOrg>`. The guard resolved production-ness from
+`getAuth()` — a different org — so pointing `SF_INSTANCE_URL` at a dev org and passing
+`targetOrg: "<prod-alias>"` walked a gated tool straight past a guard that believed it was protecting
+production.
+
+Gated tools called with an explicit `targetOrg`, `targetAlias`, `targetOrgAlias` or `orgAlias` are now
+refused outright, since the named org cannot be verified from here without a second CLI round-trip.
+Fail closed rather than guess.
+
+### Security: package.xml manifest injection
+
+`buildPackageXml` interpolated component names and types into XML unescaped, so a name containing `<`
+closed the element early and appended attacker-chosen manifest entries. Lower severity than the two
+above (a manifest cannot express deletion, and listed components must also be present in the zip), but
+fixed with proper escaping. The `*` wildcard is unaffected.
+
+Attack coverage for all three lives in `qa-guard.mjs` (43 checks) so they cannot regress silently.
+
+
+## [2.12.0] - 2026-08-11
+
+### Five new tools (223 → 228), and a dangerous pair of functions removed
+
+#### `sf_list_objects` — find objects without knowing their API name
+
+`sf_describe_object` requires an exact API name, which is useless when the user does not yet know it
+("what objects handle cases here?"). This lists objects by partial name or label, filterable to
+custom/standard/queryable, ranked exact match → prefix → substring so a search for `Account` returns
+`Account` before `AccountBrandShare`.
+
+#### `sf_get_metadata_dependencies` — impact analysis before you change anything
+
+Read-only. Answers "what breaks if I change this?" for custom fields, objects, Apex classes and
+triggers, flows, validation rules, layouts, permission sets, LWC/Aura bundles and static resources,
+via the Tooling API's `MetadataComponentDependency`. For custom fields it additionally reports how
+many records currently hold a value, which is usually the deciding factor in whether a change is safe.
+
+Every response — **including empty ones** — carries a `blindSpots` list. `MetadataComponentDependency`
+cannot see dynamic SOQL, field names built by string concatenation in Apex, managed-package internals,
+label-based references, or anything outside the org (integrations, ETL, API clients). An unqualified
+"0 dependencies found" reads as "safe to change", and for those categories that inference is wrong. A
+tool that stays silent about its blind spots is more dangerous than one that says nothing at all,
+because it manufactures false confidence.
+
+#### `sf_update_custom_object` / `sf_update_custom_field` — risk-classified, with a confirmation gate
+
+Every change is classified before anything is written:
+
+| Tier | Examples | Behaviour |
+|---|---|---|
+| SAFE | label, description, help text, `trackHistory`, feature toggles, adding picklist values | applied immediately |
+| GUARDED | `required`→true, `unique`→true, `externalId`, `defaultValue`, length/precision **increase**, `sharingModel`, `deploymentStatus` | impact report first |
+| DESTRUCTIVE | length/precision/scale **reduction**, removing picklist values, restricting a picklist, repointing a lookup | impact report first |
+| REFUSED | field `type` change, API-name rename | rejected outright |
+
+GUARDED and DESTRUCTIVE changes do **not** apply on the first call. They return the dependency list,
+the count of records holding data, and Salesforce's own `checkOnly` validate-only verdict; applying
+requires a second call with `confirmImpact: true`. The REFUSED tier is policy, not limitation:
+Salesforce's own UI performs type conversion through a multi-step wizard with data-loss warnings, and
+renaming a field breaks every string-literal reference no dependency API can see. Neither belongs
+behind a single chat message.
+
+#### Removed: the previous `updateCustomObject` / `updateCustomField`
+
+Both existed in `services/salesforce.ts` but were never wired to a tool. On inspection that was
+fortunate. They did `readMetadata` → regex edits → `upsertMetadata`, and:
+
+1. **`upsertMetadata` is a full component replace, and a `readMetadata` of a CustomObject carries
+   every field, validation rule, list view and record type.** A one-word label change therefore
+   round-tripped every child component through Salesforce's serializer and wrote it back — anything
+   rendered imperfectly was silently damaged or dropped.
+2. Their regexes could not match self-closing tags, so `<description/>` fell through to the append
+   branch and emitted a **duplicate** element.
+3. Replacements were written unprefixed while appends were `met:`-prefixed, inside a `met:` wrapper.
+
+The replacements in `services/impact.ts` write through a **scoped `deploy()`** instead. Deploy
+*merges*: child components absent from the payload are left alone. A field write names exactly one
+`<fields>` entry; an object write carries object-level properties only and structurally cannot contain
+a field. The same deploy path is used for `checkOnly` validation as for the real write, so the thing
+that was validated is the thing that gets applied.
+
+**Live-org finding that shaped this:** the Tooling API exposes no `Metadata` for `CustomObject` —
+absent from `/tooling/sobjects/CustomObject/<id>` and `SELECT Metadata FROM CustomObject` fails with
+"No such column". Object reads therefore use `readMetadata`, but every child collection is stripped
+from the XML before any scalar is parsed and the write payload is built from a whitelist, so the
+failure mode above cannot recur. Tooling `CustomField` *does* expose `Metadata` and is used directly.
+
+#### `sf_disable_debug_logs`
+
+Deletes active `TraceFlag` records, completing enable/disable/read. Defaults to still-active flags
+only (expired ones are already inert). The `DebugLevel` is deliberately left in place — they are
+shared and reusable, and deleting one another flag still points at fails for no benefit.
+
+### Improved
+
+- **`sf_get_apex_class` / `sf_get_apex_trigger` accept glob patterns.** `namePattern` supports `*` and
+  `?` (`Account*Controller`, `*Test`); triggers also accept `objectName` to answer "what triggers run
+  on Case?". Pattern results omit bodies — a broad match over a real org would otherwise return tens
+  of thousands of lines — so callers narrow down, then re-call with the exact name. Literal `%` and
+  `_` in the input are escaped before glob translation, so `Account_Helper` cannot act as a wildcard.
+- **Two more auth strategies:** OAuth 2.0 client-credentials (`SF_CLIENT_ID` + `SF_CLIENT_SECRET`) and
+  username/password (`+ SF_USERNAME` + `SF_PASSWORD` + optional `SF_SECURITY_TOKEN`). Both are ordered
+  *after* every existing strategy, and client-credentials is gated on `SF_REFRESH_TOKEN` being absent,
+  so no existing configuration changes which user the server acts as.
+- **`SF_API_VERSION`** overrides the API version (default `66.0`), with format validation — a newer org
+  may expose objects the default cannot see, and an org on a slower release track can reject a version
+  it does not yet serve. An unparseable value silently 404s every endpoint, so it falls back loudly
+  rather than being trusted.
+
+### Verified
+
+`test-new-tools-v212.mjs` 32/32, `test-dataprobe-v212.mjs` 4/4, `qa-flow-comprehensive.mjs` 144/144,
+`test-suite.mjs` 209/212 (the 2 failures probe a nonexistent scratch org and a dummy package ID on
+purpose). Both transports driven: stdio lists 228 tools, HTTP serves `/health` and `initialize` over
+`/mcp`, 404s unknown paths, and still binds `127.0.0.1`.
+
+The gate is asserted against a live org rather than reasoned about: a DESTRUCTIVE change is withheld,
+`type` changes and renames are refused, GUARDED applies only after `confirmImpact`, and — the
+regression that motivated the rewrite — a bystander field survives both a field-level and an
+object-level update. **Field survival is checked via the Tooling API, not REST describe**: describe's
+schema cache lags minutes on a dev org and reports fields as missing when they demonstrably exist.
+
 ## [2.11.2] - 2026-08-06
 
 ### Security — resolved all 5 production-dependency advisories (2 high, 3 moderate)

package/README.md

@@ -5,7 +5,7 @@
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 [![MCP Compatible](https://img.shields.io/badge/MCP-Compatible-green.svg)](https://modelcontextprotocol.io)
 
-**The only Salesforce MCP server that builds Agentforce agents, OmniStudio components, and DevOps Center pipelines** — alongside a complete daily developer loop (schema describe, Apex read, debug logs) and 223 tools total for building, configuring, and automating Salesforce orgs directly from Claude or any MCP client.
+**The only Salesforce MCP server that builds Agentforce agents, OmniStudio components, and DevOps Center pipelines** — alongside a complete daily developer loop (schema describe, Apex read, debug logs) and 228 tools total for building, configuring, and automating Salesforce orgs directly from Claude or any MCP client.
 
 ---
 
@@ -45,9 +45,75 @@ Add to your MCP configuration (`claude_desktop_config.json` or `.claude/settings
 
 See [SETUP.md](SETUP.md) for all authentication methods and detailed setup instructions.
 
+### One-click install (Claude Desktop)
+
+Download `salesforce-metadata-mcp-<version>.mcpb` from the [latest release](https://github.com/semwalajay83-sem/salesforce-metadata-mcp/releases/latest), then drag it into **Claude Desktop → Settings → Extensions**. It prompts for your org URL and credentials — no JSON editing.
+
+The bundle resolves the server from npm at launch rather than embedding a copy, so it always runs the current published version and never needs re-downloading after an upgrade.
+
+### Docker
+
+```bash
+docker build -t salesforce-metadata-mcp .
+docker run -i --rm \
+  -e SF_INSTANCE_URL="https://your-org.my.salesforce.com" \
+  -e SF_ACCESS_TOKEN="your_access_token" \
+  salesforce-metadata-mcp
+```
+
+The image builds from source, runs as a non-root user, and ships production dependencies only. Because this server speaks MCP over stdio, `-i` is required — the container is driven by its client, not run as a background service. `SF_ALIAS` will not work in a container: the Salesforce CLI's login flow needs a browser, so use token, JWT, refresh-token, or client-credentials variables instead.
+
+---
+
+## Toolsets — loading 228 tools without burning your context
+
+All 228 tools are always available. Most are not loaded into the model's context until something asks for them.
+
+Listing every tool up front costs roughly **98,000 tokens** — about half a 200k context window, spent
+before you type anything, whether or not the session ever touches OmniStudio or DevOps Center. A
+228-candidate tool list also makes the model measurably worse at picking the right tool. So the server
+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 |
+
+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:
+
+- **`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.
+
+In practice you don't manage this by hand: ask for what you want, and the model loads what it needs.
+
+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:
+
+```json
+{ "env": { "SF_TOOLSETS": "metadata,objects,automation,security" } }
+```
+
+Available toolsets: `core`, `metadata`, `objects`, `data`, `flows`, `automation`, `security`, `apex`,
+`lwc`, `ui`, `pages`, `actions`, `agentforce`, `omnistudio`, `omnichannel`, `devops`, `deployment`,
+`integrations`, `identity`, `reports`, `experience`, `admin`, `monitoring`, `audit`, `einstein`,
+`knowledge`, `cpq`, `sandbox`, `streaming`, `visualforce`, `aura`, `comms`, `mcp`, `i18n`.
+
+Flow tools live in their own `flows` toolset because `sf_create_flow` carries the full Flow element
+schema — 15,266 bytes (~4,126 tokens) on its own, the largest tool definition in the server. Keeping
+it out of the default means sessions that never build a Flow never pay for it, while sessions that do
+still get the complete validated schema.
+
 ---
 
-## Tools — 223 total
+## Tools — 228 total
 
 Highlights below; see [TOOLS.md](TOOLS.md) for the complete reference with parameters and example prompts.
 
@@ -69,6 +135,10 @@ Highlights below; see [TOOLS.md](TOOLS.md) for the complete reference with param
 | `sf_create_sharing_rule` | Create criteria or ownership sharing rules |
 | `sf_create_field_dependency` | Create controlling/dependent picklist dependency |
 | `sf_describe_object` | Read an object's full schema — fields, types, picklist values, child relationships, record types |
+| `sf_list_objects` | **Find objects by partial name or label** — the discovery step before `sf_describe_object` |
+| `sf_get_metadata_dependencies` | **Impact analysis: what references this component, and does the field hold data?** Read-only |
+| `sf_update_custom_object` | Update object-level properties, risk-classified with a confirmation gate |
+| `sf_update_custom_field` | Update a field's definition, risk-classified — destructive changes report impact before applying |
 
 ### Automation
 | Tool | Description |
@@ -120,6 +190,7 @@ Highlights below; see [TOOLS.md](TOOLS.md) for the complete reference with param
 | `sf_get_apex_class` | Read the source of an existing Apex class |
 | `sf_get_apex_trigger` | Read the source of an existing Apex trigger |
 | `sf_enable_debug_logs` | Turn on Apex debug logging for a user (TraceFlag) |
+| `sf_disable_debug_logs` | Turn Apex debug logging back off (deletes active TraceFlags) |
 | `sf_get_debug_logs` | List recent Apex debug logs |
 | `sf_get_debug_log_body` | Read the full content of a debug log |
 | `sf_scan_apex_antipatterns` | Lightweight heuristic scan for SOQL/DML-in-loop, hardcoded IDs, debug statements |
@@ -205,13 +276,56 @@ Highlights below; see [TOOLS.md](TOOLS.md) for the complete reference with param
 | `SF_ACCESS_TOKEN` | Static access token (expires ~1hr) | For static |
 | `PORT` | HTTP server port (default: 3000) | For HTTP mode |
 | `TRANSPORT` | `stdio` or `http` (default: stdio) | Optional |
+| `SF_TOOLSETS` | Toolsets to load at startup: `all`, `none`, or a comma-separated list (default: `core,metadata`) | Optional |
+| `SF_TOOLSETS_VERBOSE` | Set to `1` to print the full toolset list to stderr on startup | Optional |
+| `SF_PRODUCTION_GUARD` | `destructive` (default), `strict`, or `off` — see below | Optional |
+
+---
+
+## Production write guard
+
+This server hands an LLM a Salesforce credential, and the LLM decides what to do with it. Any text
+the model reads on the way — a case comment, a field description, a retrieved `.flow` file, an
+email body — can carry an instruction, and nothing downstream can tell it apart from one you typed.
+
+So against a **production org**, nine tools are refused by default:
+
+| Blocked on production | Why |
+|---|---|
+| `sf_delete_metadata` | Destroys metadata and every record in it |
+| `sf_delete_record`, `sf_bulk_delete_records` | Destroy data |
+| `sf_execute_anonymous_apex` | Arbitrary code that leaves no artifact behind |
+| `sf_uninstall_package` | Removes a managed package and its data |
+| `sf_create_user`, `sf_update_user` | Privilege escalation |
+| `sf_reset_user_password`, `sf_freeze_user` | Account takeover / lockout |
+
+**Metadata creation is not affected.** All 137 `sf_create_*` tools, `sf_deploy_metadata` and
+`sf_retrieve_metadata` work against production exactly as before — authoring metadata by natural
+language is the point of this package, and a guard that taxed it would just get switched off.
+
+Apex authoring (`sf_create_apex_class`, `sf_create_apex_trigger`) is also **not** blocked, even
+though a trigger runs on every DML. The line drawn is auditability: created Apex is metadata — it
+has a name, an author and a deploy record, and can be found and removed. `sf_execute_anonymous_apex`
+leaves nothing to find, which is why that one is blocked.
+
+An org counts as production only when it is **not** a sandbox, **not** a Developer Edition org, and
+**not** on a trial/scratch expiry. Sandboxes, dev orgs and scratch orgs are never gated.
+
+```jsonc
+{ "env": { "SF_PRODUCTION_GUARD": "strict" } }   // refuse ALL writes on production
+{ "env": { "SF_PRODUCTION_GUARD": "off" } }      // no guard at all
+```
+
+The guard is a hard refusal, not a confirmation prompt: a prompt the calling agent can approve by
+itself is not a control, and this server is often run with client permissions bypassed. Only the
+environment variable lifts it.
 
 ---
 
 ## Documentation
 
 - [SETUP.md](SETUP.md) — Prerequisites, authentication, Claude configuration
-- [TOOLS.md](TOOLS.md) — All 223 tools with full parameter documentation
+- [TOOLS.md](TOOLS.md) — All 228 tools with full parameter documentation
 - [AGENTFORCE.md](AGENTFORCE.md) — Agentforce agent creation guide
 - [APEX_LWC.md](APEX_LWC.md) — Apex and LWC development guide
 - [CHANGELOG.md](CHANGELOG.md) — Version history

package/SECURITY.md

@@ -68,11 +68,31 @@ All tool inputs are validated by Zod schemas before being used:
 
 ## Supported Versions
 
-| Version | Supported |
-|---------|-----------|
-| 2.1.x   | ✅ Current |
-| 2.0.x   | ⚠️ Upgrade recommended |
-| 1.x     | ❌ No longer supported |
+| Version | Status |
+|---------|--------|
+| 2.12.x | ✅ Supported — current npm `latest` |
+| 2.11.2 | ✅ Contains all security fixes |
+| 2.11.1 | ⚠️ Has the code fixes, but ships 5 production-dependency advisories resolved in 2.11.2 — upgrade |
+| **≤ 2.8.7** | ❌ **Deprecated on npm (2026-08-26) — command injection (RCE), SOQL injection, credential leak** |
+| 1.x | ❌ No longer supported |
+
+### Deprecated versions — 2026-08-26
+
+Every version **2.0.0 through 2.8.7** was deprecated on npm and now emits a warning on install.
+
+The security audit in **v2.8.8** fixed a confirmed command injection (RCE), a SOQL injection, a
+credential leak and a generated-code injection. **v2.8.8, v2.8.9, v2.9.0, v2.10.0 and v2.11.0 were
+never published to npm**, so the first npm release carrying those fixes is **v2.11.1**. Anyone on
+`2.8.7` or below — including the version that was npm `latest` at the time — is running unfixed code.
+
+If you are pinned to any version at or below 2.8.7, upgrade:
+
+```
+npm install salesforce-metadata-mcp@latest
+```
+
+Note that pinning to an exact old version bypasses `latest` entirely; check your lockfile, Dockerfile
+or MCP client config for a hardcoded version string.
 
 ---