@bridge_gpt/mcp-server 0.2.38 → 0.2.41

package/build/credential-store.js

@@ -6,10 +6,16 @@
  *   2. `$XDG_CONFIG_HOME/bridge/credentials.json` (or `~/.config/bridge/credentials.json`).
  *   3. `~/.bridge/credentials.json` (only when the primary path is absent).
  *
- * The file is keyed by a logical target `bapi:<repoName>`. The resolver NEVER
- * creates or initializes credential files. The mutation primitives — the
- * best-effort {@link upsertBapiCredential} and the fail-closed bootstrap-invite
- * pending-state operations ({@link prepareBootstrapPendingCredential},
+ * The file is keyed by logical targets, of which the only one this module still
+ * resolves or writes is the repo-scoped `bapi:<repoName>`. It previously also
+ * owned a host-scoped `anthropic:oauth` target (BAPI-778, the operator's
+ * subscription token) — that responsibility, its resolvers, and its writer were
+ * REMOVED by BAPI-791. A pre-existing `anthropic:oauth` entry in an operator's
+ * store is left in place as opaque, unread JSON; this module never interprets,
+ * migrates, or deletes it. The resolver NEVER creates or initializes credential
+ * files. The mutation primitives — the best-effort {@link upsertBapiCredential}
+ * and the fail-closed bootstrap-invite pending-state operations
+ * ({@link prepareBootstrapPendingCredential},
  * {@link repointBootstrapPendingCredential}, {@link promoteBootstrapPendingCredential},
  * {@link discardBootstrapPendingCredential})
  * — are the ONLY writers: they mutate the user-scoped primary store from explicit

package/build/credentials-cli.js

@@ -1,23 +1,34 @@
 /**
  * credentials-cli — the `credentials` subcommand, which hosts the consent-gated
- * migration of a `BAPI_API_KEY` from an agent MCP config (`.mcp.json` /
- * `.cursor/mcp.json`) into the user-scoped credential store.
+ * WRITE path for the user-scoped credential store:
  *
  *   npx -y @bridge_gpt/mcp-server credentials migrate-agent-config \
  *     [--write-credentials|--no-write-credentials] \
  *     [--source=.mcp.json|--source=.cursor/mcp.json]
  *
+ * It migrates a `BAPI_API_KEY` out of an agent MCP config (`.mcp.json` /
+ * `.cursor/mcp.json`) into the user-scoped credential store.
+ *
+ * `setup-anthropic-oauth` (BAPI-778) — onboarding for a stored Anthropic
+ * subscription OAuth token — was REMOVED by BAPI-791, along with the credential
+ * store's OAuth writer/resolvers it called. A worker now authenticates through
+ * the executor host's interactive `claude login`, or, headlessly, through an
+ * operator-exported `CLAUDE_CODE_OAUTH_TOKEN` that Bridge only forwards and
+ * never stores — there is nothing left for this CLI to onboard.
+ * `migrate-agent-config` is the only supported subcommand.
+ *
  * This subcommand owns the WRITE path so the `doctor` subcommand can remain
- * strictly read-only. Without `--write-credentials` it is a dry preview that
- * writes nothing. The migrated key value is NEVER printed anywhere — diagnostics
- * and prompts reference only candidate `filePath`/`serverName`.
+ * strictly read-only. Secret values are NEVER printed anywhere: the migration
+ * references only candidate `filePath`/`serverName`.
  */
-import { readFile, mkdir, writeFile, rename, chmod, unlink } from "fs/promises";
+import { readFile, mkdir, writeFile, rename, chmod, unlink, open } from "fs/promises";
 import os from "os";
 import readline from "readline";
 import { migrateAgentConfigCredentialToStore, } from "./agent-config-credential-migration.js";
 /** The only agent-config sources the migration knows how to scan. */
 const ALLOWED_SOURCES = [".mcp.json", ".cursor/mcp.json"];
+/** Every subcommand this CLI accepts, in help order. */
+const SUBCOMMANDS = ["migrate-agent-config"];
 /** User-facing usage text for the `credentials` subcommand. */
 export function getCredentialsUsage() {
     return [
@@ -26,13 +37,14 @@ export function getCredentialsUsage() {
         "    [--write-credentials|--no-write-credentials] \\",
         "    [--source=.mcp.json|--source=.cursor/mcp.json]",
         "",
-        "Migrates a BAPI_API_KEY found in .mcp.json / .cursor/mcp.json into the",
-        "user-scoped credential store (~/.config/bridge/credentials.json), so that a",
-        "Bash-spawned CLI (e.g. start-tickets) can resolve it. The key value is never",
-        "printed.",
+        "migrate-agent-config",
+        "  Migrates a BAPI_API_KEY found in .mcp.json / .cursor/mcp.json into the",
+        "  user-scoped credential store (~/.config/bridge/credentials.json), so that a",
+        "  Bash-spawned CLI (e.g. start-tickets) can resolve it. The key value is never",
+        "  printed.",
         "",
-        "Without --write-credentials this is a dry preview: it scans and reports what",
-        "it WOULD migrate but writes nothing.",
+        "  Without --write-credentials this is a dry preview: it scans and reports what",
+        "  it WOULD migrate but writes nothing.",
         "",
         "Flags:",
         "  --write-credentials        Consent to write the discovered key into the store",
@@ -83,7 +95,7 @@ export function parseCredentialsArgs(argv) {
     if (positionals.length === 0) {
         return {
             status: "error",
-            message: "Missing subcommand. Expected: migrate-agent-config.",
+            message: `Missing subcommand. Expected one of: ${SUBCOMMANDS.join(", ")}.`,
         };
     }
     if (positionals.length > 1) {
@@ -95,7 +107,7 @@ export function parseCredentialsArgs(argv) {
     if (positionals[0] !== "migrate-agent-config") {
         return {
             status: "error",
-            message: `Unknown subcommand: '${positionals[0]}'. Expected: migrate-agent-config.`,
+            message: `Unknown subcommand: '${positionals[0]}'. Expected one of: ${SUBCOMMANDS.join(", ")}.`,
         };
     }
     return {
@@ -137,9 +149,11 @@ function promptChoiceViaReadline(candidates) {
  * Build default CLI deps from the live process: env, cwd, platform, homedir, and
  * `fs/promises` I/O primitives. `promptChoice` is only wired when stdin is a TTY
  * (otherwise undefined, so a conflict refuses non-interactively). `log` and
- * `errorLog` go to stdout/stderr respectively.
+ * `errorLog` go to stdout/stderr respectively. `open` is needed for the
+ * fsync-backed durable write the credential-store lock uses.
  */
 export function createDefaultCredentialsDeps(writeCredentials) {
+    const interactive = Boolean(process.stdin.isTTY);
     return {
         env: process.env,
         cwd: process.cwd(),
@@ -151,21 +165,22 @@ export function createDefaultCredentialsDeps(writeCredentials) {
         rename: (a, b) => rename(a, b),
         chmod: (p, m) => chmod(p, m),
         unlink: (p) => unlink(p),
+        open: (p, flags, mode) => open(p, flags, mode),
         writeCredentials,
-        promptChoice: process.stdin.isTTY ? promptChoiceViaReadline : undefined,
+        promptChoice: interactive ? promptChoiceViaReadline : undefined,
         log: (m) => console.log(m),
         errorLog: (m) => console.error(m),
     };
 }
 /**
  * CLI entry for the `credentials` subcommand. Returns a process exit code. Help
- * returns 0; parser errors return 1. For `migrate-agent-config` it runs the
- * consent-gated migration:
+ * returns 0; parser errors return 1. For `migrate-agent-config`, the only
+ * supported subcommand, it runs the consent-gated migration:
  *   - success → confirmation (secret-free), return 0.
  *   - `consent-required` → a successful no-op preview: print the exact re-run
  *     command WITH `--write-credentials` plus candidate sources, return 0.
  *   - any other failure → errorLog the secret-free message, return 1.
- * The migrated key value is never printed anywhere.
+ * No secret value is ever printed anywhere.
  */
 export async function runCredentialsCli(argv, overrides) {
     const parse = overrides?.parse ?? parseCredentialsArgs;

package/build/docs.generated.js

@@ -2,5 +2,5 @@
 // This file is produced by scripts/bundle-docs.js
 export const DOCS = {
     "docs/mcp-tool-integrations.md": "# MCP tool integrations — the human \"why\" behind the capability report\n\nThis catalog is **explanatory prose only**. It exists so the `/install-bridge`\ncapability report can cite a human-readable \"why\" for each gate. It is **not** a\nsource of truth for gating: the server computes every `locked_tools` /\n`unlocked_tools` membership decision itself and the agent must never recompute a\ntool's dependencies from this document.\n\n**Authoritative source of gating.** The enforced rules — which tools are blocked,\nwhich are degraded, and what each requires — live in\n`api/library/vcs/vcs_route_operations.py`:\n\n- `VCS_ROUTE_REQUIREMENTS` — routes that **BLOCK** (are unavailable) without a\n  VCS connection.\n- `VCS_ROUTE_WARNINGS` — routes that **DEGRADE** (stay usable, but without\n  codebase context) without a VCS connection.\n- `NEVER_GATED_ROUTE_KEYS` — routes that are never gated on any integration.\n- `INDEX_REQUIRED_ROUTE_KEYS`, `INDEX_REQUIRED_BRAINSTORM_MODES`,\n  `CREATE_DOC_CODEBASE_CONTEXT_DOC_TYPES`, `CREATE_DOC_WARN_DOC_TYPES` — the\n  conditional \"requires a successful code index\" dimension.\n- The resolver helpers `get_required_vcs_operation()`, `get_warn_vcs_operation()`,\n  and `requires_successful_index()` are the authoritative functions that decide a\n  case. The capability report is derived from these; this catalog explains them.\n\n## Reading the capability report\n\nEach tool entry the server returns has the exact shape\n`{tool, effect, missing, semantics}`:\n\n- **`effect`**\n  - **`BLOCK`** — the tool is **unavailable** until every listed dependency is\n    met. It will refuse to run without them.\n  - **`DEGRADE`** — the tool is **usable right now**, but **without codebase\n    context** (it cannot ground its output in your repository). Connecting the\n    listed dependency upgrades it from \"works blind\" to \"works with full context\".\n    A `DEGRADE` tool is never \"failed\".\n- **`missing`** — the server-computed dependency identifiers still needed:\n  integration ids such as `github_app` / `vcs_access_token`, and the synthetic\n  `code_index` (a successful repository index).\n- **`semantics`**\n  - **`all_of`** — every id in `missing` is required.\n  - **`any_of`** — the VCS-provider candidates in `missing` are alternatives:\n    **either** `github_app` **or** `vcs_access_token` satisfies the VCS\n    requirement (this is the \"provider unknown\" case). When `code_index` also\n    appears, it remains separately required — `semantics` describes only the VCS\n    provider candidates, and a code index is always mandatory in addition.\n\nThe three readiness dimensions `configured` / `learned` / `indexed` are reported\nindependently. `indexed` may be `true`, `false`, or `null` — a `null` means the\nindex status could not be confirmed and must **not** be read as \"indexed\".\n\n## The integrations\n\n| Integration id | What it is | What it unlocks |\n| --- | --- | --- |\n| `jira` | Jira API access | Ticket reads/writes, estimation and review automations, status transitions. |\n| `github_app` | GitHub App installation | Pull requests, code review, and private-repo parsing on GitHub projects. |\n| `vcs_access_token` | VCS access token | Pull requests, code review, and private-repo parsing on Bitbucket projects. |\n| `vcs_webhook` | VCS webhook secret | Merge webhooks and CI follow-up triggers. |\n| `code_index` | A successful repository index | Codebase-grounded planning, architecture, reimplementation, and technical/discovery brainstorms. Produced by `/parse-repository`. |\n\nA project's `github_app` **or** `vcs_access_token` provides the VCS connection;\nwhich one applies depends on the project's version-control system. When the\nproject's provider is unknown, either credential satisfies the requirement — the\nreport expresses that as `semantics: any_of`.\n\n## The gates, by capability\n\n### Pull requests and CI (BLOCK on VCS)\n\nTools like `create_pull_request`, `resolve_ci_checks`, `poll_ci_checks`, and\n`materialize_fresh_base` are **unavailable** (`BLOCK`) until a VCS connection is\nconfigured. They act directly on the version-control host, so without a\nconnection there is nothing for them to talk to.\n\n### Repository indexing and maps (BLOCK on VCS)\n\n`parse_repository` and `regenerate_directory_map` need a VCS connection to read\nthe repository. They **BLOCK** until VCS is connected.\n\n### Codebase-grounded generation (BLOCK on VCS **and** a code index)\n\nPlanning and architecture tools — `generate_plan_direct`,\n`generate_architecture_direct`, `request_reimplement_context`,\n`code_writer_generate_plan`, `code_writer_generate_architecture`, and\n`create_doc` for **TDD** / **architecture** documents — ground their output in\nyour indexed codebase. They **BLOCK** until BOTH a VCS connection AND a\nsuccessful code index exist (`all_of`, with `code_index` in `missing`).\n\n### Council (BLOCK on a code index, mode-dependent)\n\n`request_council` in **technical** or **discovery** mode searches your indexed\ncodebase, so it **BLOCK**s on `code_index`. **Design**-mode brainstorming never\nqueries the index and is never gated.\n\n### Document generation that DEGRADEs (usable without codebase context)\n\nTools like `generate_prd_direct`, `generate_fsd_direct`,\n`code_writer_generate_fsd`, `generate_clarifying_questions_direct`,\n`generate_ticket_critique_direct`, `generate_ticket_review_direct`, and\n`create_doc` for **PRD** / **FSD** documents **DEGRADE** rather than block: they\nrun today from the ticket alone, and connecting VCS simply lets them ground their\noutput in your codebase. They always appear under \"Tools you can use now\", with a\nreduced-context caveat when the VCS connection is missing.\n\n### Never gated\n\nSetup and bootstrap tools (`ping`, `config_field`, `get_install_manifest`,\n`apply_install_manifest`, `get_my_role`, `persist_routing_credential`,\n`get_docs_dir`, and the bootstrap-invite exchange) are always available — they\nare how you configure everything else.\n",
-    "docs/install/sfcc-integration.md": "# Installing the SFCC Integration (OCAPI)\n\nBridge's Salesforce B2C Commerce (SFCC) tools give an AI coding agent read access to\na sandbox's object model, custom object definitions, and site preferences — plus a\nsmall set of sandbox-only writes — through the **OCAPI Data API**. This guide covers\nsetting up the OCAPI client that those tools authenticate against.\n\n> **Sandbox / local development only.** This integration is intended for a **developer\n> sandbox**. The tools reject non-sandbox instances, and the permissions grant below is\n> deliberately broad (all methods, all resources) — appropriate for a throwaway dev\n> sandbox, **never** for staging or production. Do not configure this grant on any\n> instance that holds real data. Credentials stay local (in `dw.json` or `SFCC_*` env\n> vars) and are never sent to Bridge.\n\nFor the full per-tool list and what each SFCC tool depends on, see\n[MCP Tool Integration Dependencies](./mcp-tool-integrations.md). For the tool reference\nand the `BRIDGE_MCP_PROFILE` gating, see the SFCC section of the\n[package README](../../README.md).\n\n## Prerequisites\n\n- A running SFCC **developer sandbox** and its hostname\n  (e.g. `zzzz-001.sandbox.us01.dx.commercecloud.salesforce.com`).\n- An **Account Manager API client** — a `client-id` and `client-secret`. This is the\n  OCAPI client the tools use to obtain an OAuth token. Create one in Account Manager\n  (**API Client** → *Add API Client*) if you don't already have it, and note its\n  `client_id`.\n- Business Manager access to the sandbox with permission to edit **Open Commerce API\n  Settings**.\n\n## 1. Grant the OCAPI client access in Business Manager\n\nIn Business Manager for the sandbox:\n\n**Administration → Site Development → Open Commerce API Settings → Data API** tab.\n\nAdd the following client entry to the `clients` array of the Data API settings, then\n**Save**. This grants the client full read/write access to every Data API resource —\nacceptable only on a developer sandbox:\n\n```json\n{\n  \"client_id\": \"<your-client-id-here>\",\n  \"resources\": [\n    {\n      \"methods\": [\"get\", \"post\", \"put\", \"patch\", \"delete\"],\n      \"read_attributes\": \"(**)\",\n      \"write_attributes\": \"(**)\",\n      \"resource_id\": \"/**\"\n    }\n  ]\n}\n```\n\nNotes:\n\n- The `client_id` **must match** the Account Manager API client whose credentials you\n  put in `dw.json` / `SFCC_*` below. Replace the value above with your own client id if\n  it differs.\n- If the Data API settings are empty, wrap the entry in the standard settings envelope:\n\n  ```json\n  {\n    \"_v\": \"23.2\",\n    \"clients\": [\n      {\n        \"client_id\": \"<your-client-id-here>\",\n        \"resources\": [\n          {\n            \"methods\": [\"get\", \"post\", \"put\", \"patch\", \"delete\"],\n            \"read_attributes\": \"(**)\",\n            \"write_attributes\": \"(**)\",\n            \"resource_id\": \"/**\"\n          }\n        ]\n      }\n    ]\n  }\n  ```\n\n- `check_permissions` (below) prints a ready-to-paste grant JSON on a 401/403, so you can\n  also let the tool tell you exactly what to add.\n\n## 2. Provide credentials locally\n\nCreate a `dw.json` in your project root (auto-added to git exclude — never commit it):\n\n```json\n{\n  \"hostname\": \"zzzz-001.sandbox.us01.dx.commercecloud.salesforce.com\",\n  \"client-id\": \"<your-client-id-here>\",\n  \"client-secret\": \"<account-manager-client-secret>\"\n}\n```\n\nAccepted key spellings: `hostname`/`host`, `client-id`/`clientId`/`client_id`,\n`client-secret`/`clientSecret`/`client_secret`. Prefer a single config — a multi-entry\n`configs[]` array forces an explicit `instance` on every call. Alternatively, export\n`SFCC_HOSTNAME` / `SFCC_CLIENT_ID` / `SFCC_CLIENT_SECRET` in the MCP server environment.\n\n## 3. Set the repo `version` config field\n\nSet the repo's `version` config to your SFCC project type — one of\n`sfra | pwakit | sitegenesis | storefrontnext | hybrid`. The call-time gate reads this;\na non-SFCC value blocks every SFCC tool except `sfcc_setup_status`. Set it via your\nnormal config path, the `config_field` MCP tool (operation `update`, field `version`),\nor the `/teach-bridge` skill.\n\n## 4. Enable the SFCC tools\n\nThe two diagnostic tools (`sfcc_setup_status`, `check_permissions`) are always\nregistered. The read tools, write tools, and `sfcc_log_query` are gated behind the\n`sfcc` profile. Add `sfcc` to `BRIDGE_MCP_PROFILE` in the MCP server `env` block (it is\ncomma-separated; `full` also works), then **restart the MCP client**:\n\n```json\n\"env\": { \"BRIDGE_MCP_PROFILE\": \"sfcc\" }\n```\n\n## 5. Verify\n\nAsk your agent to run:\n\n1. `sfcc_setup_status` — expect all prerequisite checks ✓ (Bridge API key, repo name,\n   `version` config, `dw.json` presence/uniqueness, AM/OCAPI token acquisition).\n2. `check_permissions` — probes OCAPI via `GET /system_object_definitions`. A 200 (with\n   the OCAPI version) confirms the grant. On 401/403 it prints the exact grant JSON to\n   paste back in step 1.\n\nRestart the MCP client after any credential, grant, or env change — a running session\ndoes not pick them up.\n\n## Notes\n\n- **WebDAV logs are separate.** `sfcc_log_query` authenticates with a Business Manager\n  username + a 40-character **WebDAV access key** over HTTP Basic auth — *not* the OCAPI\n  OAuth token configured here. `sfcc_setup_status` reports OCAPI (step 5) and WebDAV\n  (step 6) independently; one can be green while the other is not.\n- **Writes are sandbox-only.** The write tools (attribute/preference create/update) target\n  a developer sandbox and echo a paste-ready grant JSON on a 403.\n"
+    "docs/install/sfcc-integration.md": "# Installing the SFCC Integration (OCAPI)\n\nBridge's Salesforce B2C Commerce (SFCC) tools give an AI coding agent read access to\na sandbox's object model, custom object definitions, and site preferences — plus a\nsmall set of sandbox-only writes — through the **OCAPI Data API**. This guide covers\nsetting up the OCAPI client that those tools authenticate against.\n\n> **Sandbox / local development only.** This integration is intended for a **developer\n> sandbox**, and that restriction is **enforced in code**: before any SFCC tool runs,\n> Bridge validates the hostname your credentials actually resolve to — from `dw.json`\n> or `SFCC_*` — against the sandbox forms listed below. An unrecognized host is refused\n> with a `403` (`error.code: \"TARGET_NOT_SANDBOX\"`) before any request leaves your\n> machine. The check reads the resolved hostname, never the `instance` tool argument,\n> so omitting `instance` or passing `\"sandbox\"` cannot bypass it.\n>\n> Accepted sandbox hostname forms:\n>\n> - `<realm>-<nnn>.sandbox.<region>.dx.commercecloud.salesforce.com`\n> - `<realm>-<nnn>.sandbox.dx.commercecloud.salesforce.com`\n> - `<realm>-<nnn>.dx.commercecloud.salesforce.com`\n>\n> Anything else — a `production-`/`staging-`/`development-` prefixed host, or any\n> `*.demandware.net` host — is rejected.\n>\n> Still do not configure the grants below on an instance that holds real data.\n> Credentials stay local (in `dw.json` or `SFCC_*` env vars) and are never sent to\n> Bridge.\n\nFor the full per-tool list and what each SFCC tool depends on, see\n[MCP Tool Integration Dependencies](./mcp-tool-integrations.md). For the tool reference\nand the `BRIDGE_MCP_PROFILE` gating, see the SFCC section of the\n[package README](../../README.md).\n\n## Prerequisites\n\n- A running SFCC **developer sandbox** and its hostname\n  (e.g. `zzzz-001.sandbox.us01.dx.commercecloud.salesforce.com`).\n- An **Account Manager API client** — a `client-id` and `client-secret`. This is the\n  OCAPI client the tools use to obtain an OAuth token. Create one in Account Manager\n  (**API Client** → *Add API Client*) if you don't already have it, and note its\n  `client_id`.\n- Business Manager access to the sandbox with permission to edit **Open Commerce API\n  Settings**.\n\n## 1. Grant the OCAPI client access in Business Manager\n\nIn Business Manager for the sandbox:\n\n**Administration → Site Development → Open Commerce API Settings → Data API** tab.\n\nAdd the client entry below to the `clients` array of the Data API settings, then\n**Save**. It grants only the resource families and HTTP methods Bridge's SFCC tools\nactually call — not a global `/**` grant. `check_permissions` prints the same JSON on\na 401/403, split into the two blocks.\n\n**READ/SEARCH TOOL GRANTS** — required by the `sfcc` read tools. (`post` is OCAPI's\nconvention for its `*_search` endpoints, not a mutation.)\n\n```json\n{\n  \"client_id\": \"<your-client-id-here>\",\n  \"resources\": [\n    { \"resource_id\": \"/system_object_definitions\",    \"methods\": [\"get\"],         \"read_attributes\": \"(**)\", \"write_attributes\": \"(**)\" },\n    { \"resource_id\": \"/system_object_definitions/**\", \"methods\": [\"get\", \"post\"], \"read_attributes\": \"(**)\", \"write_attributes\": \"(**)\" },\n    { \"resource_id\": \"/site_preferences/**\",          \"methods\": [\"get\", \"post\"], \"read_attributes\": \"(**)\", \"write_attributes\": \"(**)\" },\n    { \"resource_id\": \"/custom_object_definitions/**\", \"methods\": [\"get\", \"post\"], \"read_attributes\": \"(**)\", \"write_attributes\": \"(**)\" }\n  ]\n}\n```\n\n**MUTATION GRANTS** — required **only if you enable `BRIDGE_MCP_PROFILE=sfcc-write`**,\nwhich registers the nine destructive write tools. These are shipped capabilities, not\nfuture work. No `delete` is granted, because no shipped write tool performs one; the\n`get` entries are needed for the If-Match ETag round trip that precedes each `PATCH`.\n\n```json\n{\n  \"client_id\": \"<your-client-id-here>\",\n  \"resources\": [\n    { \"resource_id\": \"/system_object_definitions\",    \"methods\": [\"get\"],                  \"read_attributes\": \"(**)\", \"write_attributes\": \"(**)\" },\n    { \"resource_id\": \"/system_object_definitions/**\", \"methods\": [\"get\", \"put\", \"patch\"],  \"read_attributes\": \"(**)\", \"write_attributes\": \"(**)\" },\n    { \"resource_id\": \"/custom_object_definitions/**\", \"methods\": [\"get\", \"put\", \"patch\"],  \"read_attributes\": \"(**)\", \"write_attributes\": \"(**)\" },\n    { \"resource_id\": \"/site_preferences/**\",          \"methods\": [\"get\", \"patch\"],         \"read_attributes\": \"(**)\", \"write_attributes\": \"(**)\" }\n  ]\n}\n```\n\nNotes:\n\n- The `client_id` **must match** the Account Manager API client whose credentials you\n  put in `dw.json` / `SFCC_*` below. Replace the value above with your own client id if\n  it differs.\n- If the Data API settings are empty, wrap the entries in the standard settings\n  envelope. Merge the resource lists from the block(s) above into one `resources`\n  array — do not substitute a global `\"resource_id\": \"/**\"` grant:\n\n  ```json\n  {\n    \"_v\": \"23.2\",\n    \"clients\": [\n      {\n        \"client_id\": \"<your-client-id-here>\",\n        \"resources\": [\n          { \"resource_id\": \"/system_object_definitions\",    \"methods\": [\"get\"],         \"read_attributes\": \"(**)\", \"write_attributes\": \"(**)\" },\n          { \"resource_id\": \"/system_object_definitions/**\", \"methods\": [\"get\", \"post\"], \"read_attributes\": \"(**)\", \"write_attributes\": \"(**)\" },\n          { \"resource_id\": \"/site_preferences/**\",          \"methods\": [\"get\", \"post\"], \"read_attributes\": \"(**)\", \"write_attributes\": \"(**)\" },\n          { \"resource_id\": \"/custom_object_definitions/**\", \"methods\": [\"get\", \"post\"], \"read_attributes\": \"(**)\", \"write_attributes\": \"(**)\" }\n        ]\n      }\n    ]\n  }\n  ```\n\n- `check_permissions` (below) prints a ready-to-paste grant JSON on a 401/403, so you can\n  also let the tool tell you exactly what to add.\n\n## 2. Provide credentials locally\n\nCreate a `dw.json` in your project root (auto-added to git exclude — never commit it):\n\n```json\n{\n  \"hostname\": \"zzzz-001.sandbox.us01.dx.commercecloud.salesforce.com\",\n  \"client-id\": \"<your-client-id-here>\",\n  \"client-secret\": \"<account-manager-client-secret>\"\n}\n```\n\nAccepted key spellings: `hostname`/`host`, `client-id`/`clientId`/`client_id`,\n`client-secret`/`clientSecret`/`client_secret`. Prefer a single config — a multi-entry\n`configs[]` array forces an explicit `instance` on every call. Alternatively, export\n`SFCC_HOSTNAME` / `SFCC_CLIENT_ID` / `SFCC_CLIENT_SECRET` in the MCP server environment.\n\n## 3. Set the repo `version` config field\n\nSet the repo's `version` config to your SFCC project type — one of\n`sfra | pwakit | sitegenesis | storefrontnext | hybrid`. The call-time gate reads this;\na non-SFCC value blocks every SFCC tool except `sfcc_setup_status`. Set it via your\nnormal config path, the `config_field` MCP tool (operation `update`, field `version`),\nor the `/teach-bridge` skill.\n\n## 4. Enable the SFCC tools\n\nThe two diagnostic tools (`sfcc_setup_status`, `check_permissions`) are always\nregistered. Everything else is gated, behind **two independent profile groups**:\n\n| Group | Registers |\n|---|---|\n| `sfcc` | the 8 OCAPI read tools + `sfcc_log_query` — read-only |\n| `sfcc-write` | the 9 destructive write tools |\n\nNeither implies the other. Add what you need to `BRIDGE_MCP_PROFILE` in the MCP server\n`env` block (it is comma-separated), then **restart the MCP client**:\n\n```json\n\"env\": { \"BRIDGE_MCP_PROFILE\": \"sfcc\" }\n```\n\nFor reads plus writes, use `\"sfcc,sfcc-write\"`. `full` expands to every group and is\ntherefore write-capable.\n\n> **Migration.** `sfcc` used to register the nine write tools too. It no longer does.\n> If you were relying on SFCC writes through `BRIDGE_MCP_PROFILE=sfcc`, change it to\n> `BRIDGE_MCP_PROFILE=sfcc,sfcc-write`. `full` users keep write access and need no\n> change.\n\n## 5. Verify\n\nAsk your agent to run:\n\n1. `sfcc_setup_status` — expect all prerequisite checks ✓ (Bridge API key, repo name,\n   `version` config, `dw.json` presence/uniqueness, AM/OCAPI token acquisition).\n2. `check_permissions` — probes OCAPI via `GET /system_object_definitions`. A 200 (with\n   the OCAPI version) confirms the grant. On 401/403 it prints the exact grant JSON to\n   paste back in step 1.\n\nRestart the MCP client after any credential, grant, or env change — a running session\ndoes not pick them up.\n\n## Notes\n\n- **WebDAV logs are separate.** `sfcc_log_query` authenticates with a Business Manager\n  username + a 40-character **WebDAV access key** over HTTP Basic auth — *not* the OCAPI\n  OAuth token configured here. `sfcc_setup_status` reports OCAPI (step 5) and WebDAV\n  (step 6) independently; one can be green while the other is not.\n- **Writes are sandbox-only.** The write tools (attribute/preference create/update) target\n  a developer sandbox and echo a paste-ready grant JSON on a 403.\n"
 };