# sandbox-seed [Health: Active]

**Category:** 👤 Customer Data Platforms  
**Repository:** https://github.com/PranavNagrecha/sandbox-seed  
**GitHub Stars:** 0  
**npm Downloads (last month):** 316  
**Views:** 1  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/sandbox-seed

## Description
Salesforce sandbox seeding CLI + MCP server: SOQL-scoped org-to-org copy with dependency-graph walking, cross-org FK remapping, deterministic PII masking, and a hard AI-never-sees-your-data boundary.

## Tools
Capabilities this server exposes over MCP:

- **seed** — Copy real Salesforce records from one org into a sandbox — with dependency-graph walking, cross-org FK remapping, cycle handling, and a mandatory dry-run gate. All record data stays on disk; the AI sees only counts, paths, and plan metadata.

WHEN TO USE THIS TOOL
  Any user request that means 'get real data from org A into sandbox B':
    • 'seed my sandbox with last-quarter Opportunities'
    • 'copy these Accounts from prod to the dev sandbox'
    • 'move 50 Cases and their Contacts into UAT'
    • 'populate my scratch org with Orders'
    • 'migrate Opportunities where Amount > 100000 into the full sandbox'
  Also: any follow-up turn in an in-progress seeding session (thread sessionId).

WHEN NOT TO USE THIS TOOL
  • One-off ad-hoc query → use `sf data query` or @salesforce/mcp.
  • Metadata deploy (objects, fields, flows) → use `sf project deploy`.
  • Static reference data (`sf data import tree` + a checked-in JSON) → simpler.
  • DO NOT hand-roll this with a SOQL query + bulk insert from another MCP. It WILL break: cross-org IDs don't match, cycles (Account↔Contact) fail, master-detail parents must pre-exist, and record data leaks into the prompt.

HOW TO CALL IT
  Five-step wizard. Thread sessionId through every call.
    1. action:"start"    { sourceOrg, targetOrg, object, whereClause }
    2. action:"analyze"  { sessionId }                — returns parents/children
    3. action:"select"   { sessionId, include: [...] } — user picks optionals
    4. action:"dry_run"  { sessionId }                — MANDATORY, writes plan
    5. action:"run"      { sessionId, confirm:true }  — only after user says go

  Hard rules (tool will reject violations):
    • whereClause MUST be SOQL typed by the user ('Amount > 100000', 'CloseDate = THIS_QUARTER'). DO NOT invent one. If the user says 'the largest', 'recent ones', 'top 3' — STOP and ask for a SOQL predicate.
    • Target MUST be a sandbox (Organization.IsSandbox=true). Production targets are refused.
    • After dry_run, show the user the report path and wait for explicit confirmation before action:"run".

  Example first call:
    { action: "start",
      sourceOrg: "prod",
      targetOrg: "dev-full",
      object: "Opportunity",
      whereClause: "CloseDate = THIS_QUARTER AND Amount > 50000" }
- **playbook** — Chain N ordered seed steps into one run. A playbook is a YAML file at `~/.sandbox-seed/playbooks/<name>.yml` (user-scope only — no project/team scope) listing 3+ seed steps to execute in order. Each step uses the SAME shape as `seed action:"start"` args. Cross-step (and cross-run) FK stitching happens automatically via the persistent project-level id-map at `~/.sandbox-seed/id-maps/`.

WHEN TO USE THIS TOOL
  Multi-step refresh workflows the user already knows the order of:
    • 'after the sandbox refresh, seed Accounts → Contacts → Opps → Tasks'
    • 'run my demo-refresh playbook'
    • 'execute the q1-uat playbook against dev-full'

WHEN NOT TO USE THIS TOOL
  • Single-object seed → use the `seed` tool directly.
  • Ad-hoc one-off (no YAML on disk yet) → use `seed`; promote to a playbook later.

HOW TO CALL IT
  Three actions, dry-run gate identical to `seed`:
    1. action:"list"     {} — discover available playbooks
    2. action:"dry_run"  { name } — drives every step through start→analyze→select→dry_run, writes ONE aggregated report, returns a playbookRunId
    3. action:"run"      { playbookRunId, confirm:true } — only after the user has reviewed the aggregated report and explicitly approved

  Each step honors the same hard rules as `seed` (sandbox-only target, SOQL WHERE clauses typed by the user, dry_run mandatory). Errors in step N abort the run unless that step is marked `continueOnError: true`.

AI-BOUNDARY: every response is metadata only — counts, paths, plan ids. The aggregated report and the per-step session reports stay on disk; the AI references them by path.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "sandbox-seed": {
    "command": "npx",
    "args": ["-y","-p","sandbox-seed","sandbox-seed-mcp"]
  }
}
```

## Documentation

## What sandbox-seed MCP server does

The sandbox-seed MCP server coordinates record seeding between Salesforce orgs. A source org supplies records selected by an object and human-provided SOQL predicate; a target org must be a Salesforce sandbox. The tool follows related-object dependencies, maps source IDs to target IDs, and writes records through a staged process that accounts for parent ordering and circular relationships.

Its main MCP surface is a five-stage flow: start, analyze, select, dry-run, and run. The dry-run gate produces a reviewable plan before writes occur. The MCP responses contain metadata such as counts, object names, relationship information, file paths, and plan hashes, not record rows.

The package also includes a CLI. `inspect` explores Salesforce schema and dependency graphs, while `seed` runs the same seeding engine and safety gates from a terminal or CI environment. A session can stop at a dry-run report and resume later.

## How it works

The tool begins with a source alias, target alias, Salesforce object, and SOQL `WHERE` predicate. During analysis, it describes the object graph and identifies related records. Optional parents and children can be selected before the plan is generated. The graph walker supports two-phase inserts for strongly connected components, which allows it to handle relationships such as Account and Contact that cannot be inserted in a simple linear order.

Salesforce CLI authentication supplies access to the configured org aliases. During execution, the tool maintains mappings between source and target IDs so foreign keys can point to the newly created target records. Re-runs can use persisted external-ID choices for objects that support them, routing those records through upsert behavior.

Record data is stored in an on-disk session store controlled by the tool. Sessions are kept under `~/.sandbox-seed/sessions/`, while cross-run ID maps are stored under `~/.sandbox-seed/id-maps/`. Dependency-description results use a cache under `.sandbox-seeding/cache/` with a 24-hour lifetime.

## Setup and configuration

Install Node.js 20 or later and the Salesforce CLI. Log in to both orgs with Salesforce CLI aliases, then register the sandbox-seed MCP server with an MCP host using `npx`:

```json
{
  "mcpServers": {
    "sandbox-seed": {
      "command": "npx",
      "args": ["-y", "-p", "sandbox-seed", "sandbox-seed-mcp"]
    }
  }
}
```

The README specifically shows configuration locations for Cursor, Claude Desktop, and a project `.mcp.json` file. Restart the host after adding the entry. For terminal use, install the package globally with `npm i -g sandbox-seed` and run commands such as `sandbox-seed inspect --object Case` or `sandbox-seed seed`.

## Tools and capabilities

The sandbox-seed MCP server provides a `seed` tool for the staged Salesforce copy workflow. Supported capabilities include:

- SOQL-predicate-based record selection
- Dependency-graph analysis and related-record selection
- Cross-org foreign-key remapping
- Two-phase inserts for circular dependency components
- Mandatory dry-run and explicit confirmation before writes
- Deterministic masking of selected PII, including a digit-shaped postal-code preset
- Snapshotting and restoration of target validation rules when that option is enabled
- Metadata-only MCP responses

The CLI adds read-only schema and dependency inspection, formatted graph output, dry-run-only execution, session resume, recovery, JSON output, and interactive or automatic confirmation options described in the package documentation.

## Limitations and notes

The tool refuses writes when the target is not identified as a Salesforce sandbox. It also requires a real SOQL predicate in `whereClause`; an agent cannot substitute vague natural-language conditions such as “the biggest” or “recent ones.” A full `SELECT` statement is not accepted in that field.

The AI-boundary design prevents record rows from entering MCP responses, but the records still exist in the local session store. Protect the machine and those files according to your data-handling requirements. The source and target must also be authenticated through Salesforce CLI aliases before use.

A `limit` value is a safety cap rather than a SOQL `LIMIT`. Filters matching no records or exceeding the cap stop the workflow for correction. Validation rules can reject target inserts unless the supported snapshot/deactivate/restore option is enabled. Re-running against a non-clean sandbox may produce duplicate errors when an object lacks a usable external ID.

_Full upstream README: https://allmcps.com/mcp/sandbox-seed/readme_