Standardize MCP project and instance resolution

.changeset/steady-mcp-context.md

@@ -0,0 +1,8 @@
+---
+'@salesforce/b2c-dx-mcp': minor
+'@salesforce/b2c-dx-docs': patch
+'@salesforce/b2c-agent-plugins': patch
+'@salesforce/b2c-tooling-sdk': patch
+---
+
+Added per-call named-instance selection and consistent resolution provenance to project-aware MCP tools, including persisted context for debugger sessions and log watches. Removed the retired Storefront Next MCP toolset in favor of the current Storefront Next agent skills.

docs/.vitepress/config.mts

@@ -212,18 +212,6 @@ const referenceSidebar = [
         collapsed: true,
         items: [{text: 'Documentation Tools', link: '/mcp/tools/docs'}],
       },
-      {
-        text: 'Storefront Next (deprecated)',
-        collapsed: true,
-        items: [
-          {text: 'sfnext_get_guidelines', link: '/mcp/tools/sfnext-get-guidelines'},
-          {text: 'sfnext_start_figma_workflow', link: '/mcp/tools/sfnext-start-figma-workflow'},
-          {text: 'sfnext_analyze_component', link: '/mcp/tools/sfnext-analyze-component'},
-          {text: 'sfnext_match_tokens_to_theme', link: '/mcp/tools/sfnext-match-tokens-to-theme'},
-          {text: 'sfnext_add_page_designer_decorator', link: '/mcp/tools/sfnext-add-page-designer-decorator'},
-          {text: 'sfnext_configure_theme', link: '/mcp/tools/sfnext-configure-theme'},
-        ],
-      },
     ],
   },
 ];

docs/mcp/configuration.md

@@ -84,12 +84,13 @@ If both `dw.json` and `~/.mobify` contain an API key, `dw.json` takes precedence
 
 ## Per-call Project Context {#project-directory}
 
-Tools that resolve project files or B2C/MRT configuration expose two common per-call arguments:
+Tools expose only the context they consume. Local project tools accept `projectDirectory`. Tools that resolve B2C/MRT configuration use the same three flat, optional arguments:
 
-- `projectDirectory` selects the project root used for `.env`, `dw.json`, `package.json`, and relative project files.
-- `configPath` explicitly selects a configuration file in `dw.json` format. Relative paths resolve from the effective `projectDirectory`.
+- `projectDirectory` is an absolute project root for the call. It overrides the server-level project directory; the tool schema shows the exact server-level or `cwd` fallback it will use when omitted.
+- `configPath` selects the primary configuration file in `dw.json` format. Relative paths resolve from `projectDirectory`. The shared default `dw.json` remains available for fallback and named-instance lookup.
+- `instanceName` selects a named instance from the primary and shared default files without changing either file. The primary file is searched first. When omitted, the active/default instance is used.
 
-Configuration-dependent tools receive these fields automatically. Pure documentation tools and follow-up calls that operate only on existing server-side state do not expose them.
+Specialized roots such as `cartridgeDirectory`, `buildDirectory`, and `outputDirectory` remain separate and resolve from `projectDirectory` when relative. Pure documentation tools and follow-up calls that operate only on existing server-side state do not expose project or configuration fields.
 
 The server resolves the project directory in this order:
 
@@ -99,7 +100,7 @@ The server resolves the project directory in this order:
 
 For reliable behavior, either set `--project-directory "${workspaceFolder}"` (or your client's project-path variable) in `mcp.json`, or let the agent pass `projectDirectory` per call. A per-call override controls both project-local configuration discovery (`.env`, `SFCC_CONFIG`, and `dw.json`) and relative filesystem paths. Use `configPath` when the desired `dw.json`-format file is not the project default. JSON-returning filesystem tools echo the resolved directory back in their output so you can confirm which path was used.
 
-Each project-aware call selects its primary configuration path in this order, then adds the global `dw.json` to the available instances:
+Each configuration-aware call selects its primary configuration path in this order, then adds the global `dw.json` to the available instances:
 
 1. Per-call `configPath`
 2. Server startup `--config` / `SFCC_CONFIG`
@@ -112,13 +113,15 @@ This list selects the primary `dw.json`-format file. Individual configuration va
 
 The global `dw.json` is shared with the CLI and B2C DX VS Code extension. It is useful when an MCP client starts the server outside your project or when you want its instances available alongside project instances.
 
-The primary and global `dw.json` files form one instance catalog. An instance named by `--instance` / `SFCC_INSTANCE` is searched in the primary file first and then the global file; same-name primary entries shadow global entries. The selected instance's fields are not merged across files.
+The primary and global `dw.json` files form one instance catalog. An instance named by the MCP `instanceName` argument, CLI `--instance`, or `SFCC_INSTANCE` is searched in the primary file first and then the global file; same-name primary entries shadow global entries. The selected instance's fields are not merged across files.
+
+Configuration- and project-aware tools return a compact `resolution` block showing the effective project directory, selected configuration file, instance name, target hostname, and any specialized directories, together with the source of each choice. Session and watch start tools capture this block; their corresponding list tools return it so callers do not need to repeat context on follow-up calls.
 
 ::: tip Diagnosing configuration
-Run the `config_inspect` tool (ask your agent to "inspect the B2C MCP configuration") to see the resolved configuration — instance, auth, SCAPI/MRT settings, and which source provided each value — along with the effective project directory and how it was resolved. Secrets are redacted by default.
+Run the `config_inspect` tool (ask your agent to "inspect the B2C MCP configuration") to see the resolved configuration — instance, auth, SCAPI/MRT settings, the complete source graph, and the same compact `resolution` block returned by ordinary tools. Secrets are redacted by default.
 :::
 
-`config_inspect` uses the same SDK `loadConfig` resolver and globally registered CLI plugin configuration sources as `b2c setup inspect`. Given the same installed plugins, environment, `projectDirectory`, and `configPath`, its resolved values and source provenance follow the same pipeline; MCP adds the effective project-directory context to its response.
+`config_inspect` uses the same SDK `loadConfig` resolver and globally registered CLI plugin configuration sources as `b2c setup inspect`. Given the same installed plugins, environment, `projectDirectory`, `configPath`, and `instanceName`, its resolved values and source provenance follow the same pipeline; MCP adds compact call-resolution context to its response.
 
 This is the [Agent Plugins](https://agent-plugins.org/plugin-authors/mcp-servers) `cwd` model: when a plugin declares an MCP server without an explicit `cwd`, the working directory defaults to the plugin root rather than your open project — which is exactly why the explicit outlets above matter.
 
@@ -155,8 +158,6 @@ Override auto-discovery with `--toolsets` or `SFCC_TOOLSETS`:
 
 **Available toolsets:** `CARTRIDGES`, `MRT`, `PWAV3`, `SCAPI`, `STOREFRONTNEXT`, `all`
 
-**Deprecated toolset:** `STOREFRONTNEXT_DEPRECATED` holds the legacy `sfnext_*` tools, which are not compatible with the Storefront Next 1.0 GA release and are superseded by the [`storefront-next`/`storefront-next-figma` agent-skills plugins](../guide/agent-skills). It is **never auto-enabled** and **not included in `all`** — request it explicitly with `--toolsets STOREFRONTNEXT_DEPRECATED --allow-non-ga-tools`. See [Toolsets](./toolsets#storefrontnext-deprecated).
-
 With auto-discovery, the `SCAPI` toolset is always included. When using `--toolsets` or `--tools`, only the specified toolsets/tools are enabled.
 
 ### Individual Tool Selection

docs/mcp/index.md

@@ -30,10 +30,6 @@ The **SCAPI** and **DIAGNOSTICS** toolsets are always enabled. On top of those,
 
 Every configuration also includes the always-on base toolsets (**SCAPI** + **DIAGNOSTICS**). Hybrid projects (e.g. cartridges + PWA Kit) get the union of the matching rows. You can also [manually select toolsets](./configuration#toolset-selection).
 
-::: warning Storefront Next `sfnext_*` tools are deprecated
-The legacy Storefront Next MCP tools (`sfnext_*`) are **not compatible with the Storefront Next 1.0 GA release** and have been superseded by the [`storefront-next` and `storefront-next-figma` agent-skills plugins](../guide/agent-skills). They no longer auto-enable for Storefront Next projects and have moved to the opt-in [`STOREFRONTNEXT_DEPRECATED`](./toolsets#storefrontnext-deprecated) toolset. Install the skills plugins instead — see the [Agent Skills guide](../guide/agent-skills).
-:::
-
 ## Plugins
 
 The MCP server uses the B2C CLI under the hood, so CLI plugins automatically extend MCP functionality. See the [CLI Plugin documentation](../guide/extending) for details.

docs/mcp/installation.md

@@ -12,8 +12,6 @@ This guide covers installing and configuring the B2C DX MCP Server for various M
 - A B2C Commerce project (for project-specific toolsets)
 - MCP client (Claude Code, Cursor, GitHub Copilot, or compatible client)
 
-> **Note:** For Figma-to-component tools, you also need an external Figma MCP server enabled. See [Figma-to-Component Tools Setup](./figma-tools-setup) for details.
-
 The MCP server is installed via `npx`, which downloads and runs the latest version on demand. For project type detection details, see [MCP Server Overview](./#project-type-detection).
 
 ## Claude Code

docs/mcp/tools/cartridge-deploy.md

@@ -25,14 +25,16 @@ See [Configuration](../configuration) for complete credential setup details incl
 
 ### Parameters
 
-| Parameter          | Type     | Required | Default                                                         | Description                                                                                                                                                                                                                                     |
-| ------------------ | -------- | -------- | --------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `projectDirectory` | string   | No       | Configured project directory                                    | Project root used for configuration discovery and relative path resolution. Overrides the MCP process working directory.                                                                                                                        |
-| `configPath`       | string   | No       | Resolved from project context                                   | Explicit `dw.json`-format configuration file. Relative paths resolve from `projectDirectory`.                                                                                                                                                   |
-| `directory`        | string   | No       | Project directory (from `--project-directory` or auto-detected) | Path to directory to search for cartridges. The tool recursively searches for `.project` files to identify cartridges.                                                                                                                          |
-| `cartridges`       | string[] | No       | All found cartridges                                            | Array of cartridge names to include in the deployment. Use this to selectively deploy specific cartridges when you have multiple cartridges but only want to update some. If not specified, all cartridges found in the directory are deployed. |
-| `exclude`          | string[] | No       | None                                                            | Array of cartridge names to exclude from the deployment. Use this to skip deploying certain cartridges, such as third-party or unchanged cartridges. Applied after the include filter.                                                          |
-| `reload`           | boolean  | No       | `false`                                                         | Whether to reload the code version after deployment. When `true`, the tool triggers a code version reload on the instance.                                                                                                                      |
+| Parameter            | Type     | Required | Default                       | Description                                                                                                                                                                                                                                     |
+| -------------------- | -------- | -------- | ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `projectDirectory`   | string   | No       | Server project directory/cwd  | Absolute project root used for configuration discovery and relative path resolution. The tool schema shows the exact fallback.                                                                                                                  |
+| `configPath`         | string   | No       | Resolved from project context | Primary `dw.json`-format configuration file. Relative paths resolve from `projectDirectory`; the shared default remains available for instance lookup.                                                                                          |
+| `instanceName`       | string   | No       | Active/default instance       | Named instance selected from the primary file first, then the shared default `dw.json`.                                                                                                                                                         |
+| `cartridgeDirectory` | string   | No       | `projectDirectory`            | Cartridge discovery root. Relative paths resolve from `projectDirectory`.                                                                                                                                                                       |
+| `directory`          | string   | No       | —                             | Deprecated alias for `cartridgeDirectory`.                                                                                                                                                                                                      |
+| `cartridges`         | string[] | No       | All found cartridges          | Array of cartridge names to include in the deployment. Use this to selectively deploy specific cartridges when you have multiple cartridges but only want to update some. If not specified, all cartridges found in the directory are deployed. |
+| `exclude`            | string[] | No       | None                          | Array of cartridge names to exclude from the deployment. Use this to skip deploying certain cartridges, such as third-party or unchanged cartridges. Applied after the include filter.                                                          |
+| `reload`             | boolean  | No       | `false`                       | Whether to reload the code version after deployment. When `true`, the tool triggers a code version reload on the instance.                                                                                                                      |
 
 ### Usage
 
@@ -48,7 +50,7 @@ Deploy specific cartridges and reload the code version:
 Deploy app_storefront_base and reload the code version.
 ```
 
-**Returns:** `{cartridges, codeVersion, reloaded, projectDirectory, resolvedDirectory}` — deployed cartridge mappings, code version, reload status, and the effective paths used.
+**Returns:** deployed cartridge mappings, code version, reload status, and a `resolution` block identifying the selected project, configuration, instance, hostname, and cartridge directory.
 
 ## See Also