salesforce-metadata-mcp 2.12.0 → 3.0.0

package/CHANGELOG.md

@@ -1,5 +1,92 @@
 # 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

package/README.md

@@ -45,6 +45,72 @@ 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 — 228 total
@@ -210,6 +276,49 @@ 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.
 
 ---
 

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.
 
 ---