@bridge_gpt/mcp-server 0.2.10 → 0.2.13

package/README.md

@@ -218,6 +218,8 @@ The MCP server also checks for updates automatically on startup. If a newer vers
 
 This is the Bridge API tooling worth knowing about as a software engineer — the things you'd ask an agent to do — grouped by how often you would use them. Each entry covers **what it does**, **when it's useful** and **how to use it**. The behind-the-scenes plumbing is summarized at the end under [Extra Capabilities](#extra-capabilities), and a full enumeration lives in [Reference](#reference).
 
+Working in a Salesforce B2C Commerce codebase? Bridge also ships read-only SFCC platform-introspection tools — see [Salesforce B2C Commerce (SFCC) Tools](#salesforce-b2c-commerce-sfcc-tools).
+
 For invocation, prefer the slash command — it's deterministic. A free-text example is shown only where natural-language phrasing reliably maps to the right automation; high-consequence or easily-misread automations show only the slash command on purpose.
 
 ### Tier 1 — Regularly useful
@@ -401,6 +403,66 @@ Behind-the-scenes capabilities an agent gains from the MCP tools — mostly invo
 - **Retrieve any generated artifact** (`get_*` for plans, critiques, questions, brainstorms, research, architecture) without regenerating it.
 - **Tiered-section execution telemetry** recording (internal measurement).
 
+## Salesforce B2C Commerce (SFCC) Tools
+
+Salesforce's official MCP server, `@salesforce/b2c-dx-mcp`, covers developer-experience tasks — cartridge deploy, step debugging, docs search, logs/MRT, and SCAPI Custom API scaffolding. As of its current toolset it has no way to *read* the platform's object model, custom objects, or site configuration — exactly the context an AI coding agent needs to write correct Commerce code and to inspect a sandbox before touching it. Bridge's SFCC tools install side-by-side with `b2c-dx-mcp` (they don't duplicate its surface) and close that gap with **read-only OCAPI Data API introspection** of system objects, custom object definitions, and site preferences.
+
+**v1 is read-only and developer-sandbox-only** — no writes, and non-sandbox instances are rejected. Credentials stay local (in `dw.json` or `SFCC_*` env vars) and are never sent to Bridge.
+
+<details>
+<summary><strong>Setup</strong></summary>
+
+The two diagnostic tools (`sfcc_setup_status`, `check_permissions`) are always available. The seven read tools must be enabled with a profile (step 3).
+
+**Prerequisites:** a running SFCC **sandbox** and its hostname, plus an Account Manager API client (`client-id` + `client-secret`).
+
+**1. Set the repo `version` config field** to your SFCC project type — one of `sfra | pwakit | sitegenesis | storefrontnext | hybrid`. The call-time gate reads this; a non-SFCC value blocks every SFCC tool except `sfcc_setup_status`. Set it via your normal config path, the `config_field` MCP tool (operation `update`, field `version`), or the `/teach-bridge` skill.
+
+**2. Provide SFCC credentials.** Create a `dw.json` in your project root:
+
+```json
+{
+  "hostname": "zzzz-001.sandbox.us01.dx.commercecloud.salesforce.com",
+  "client-id": "<account-manager-client-id>",
+  "client-secret": "<account-manager-client-secret>"
+}
+```
+
+Accepted key spellings: `hostname`/`host`, `client-id`/`clientId`/`client_id`, `client-secret`/`clientSecret`/`client_secret`. Prefer a single config — a multi-entry `configs[]` array forces you to pass an explicit `instance` on every call. `dw.json` is auto-added to git exclude and must never be committed. Alternatively, export `SFCC_HOSTNAME` / `SFCC_CLIENT_ID` / `SFCC_CLIENT_SECRET` in the MCP server environment.
+
+**3. Enable the read tools.** Add `sfcc` to `BRIDGE_MCP_PROFILE` in the MCP server `env` block (it is comma-separated; `full` also works), then **restart the MCP client**:
+
+```json
+"env": { "BRIDGE_MCP_PROFILE": "sfcc" }
+```
+
+Without this, only the diagnostic tools are registered.
+
+**4. Verify and grant OCAPI access.** Ask your agent to run `sfcc_setup_status` (expect all checks ✓), then `check_permissions`. If it reports HTTP 401/403, it prints the exact OCAPI Settings JSON to paste in Business Manager (**Administration → Site Development → Open Commerce API Settings → Data API** tab); save it there and re-run. Restart the MCP client after any credential or env change — a running session does not pick them up.
+
+</details>
+
+### Tools
+
+All SFCC tools are read-only and target a developer sandbox. Oversized responses are automatically saved to `BAPI_DOCS_DIR/sfcc/` and previewed inline.
+
+**Diagnostics** (always available, no profile needed)
+- `sfcc_setup_status` — report on every prerequisite: Bridge API key, repo name, `version` config, `dw.json` presence/uniqueness, and AM token acquisition.
+- `check_permissions` — probe OCAPI access via `GET /system_object_definitions`; on 401/403, print the exact OCAPI Settings JSON to paste in Business Manager (split read-only vs. write/import grants).
+
+**System object model** (needs the `sfcc` profile)
+- `system_object_list` — list system object types (Product, Order, Customer, …).
+- `system_object_get` — fetch one type's definition, optionally with its full attribute definitions (`expand_attribute_definitions`).
+- `system_object_attribute_search` — search a type's attribute definitions; prefer this over a full dump when hunting a specific `c_` custom attribute.
+
+**Custom object definitions** (needs the `sfcc` profile)
+- `custom_object_definition_list` — list custom object type definitions.
+- `custom_object_definition_get` — fetch an existing custom type with its key definition and attribute definitions/groups. Read-only — creating a custom object *type* isn't possible via OCAPI; that's a future v2 metadata-import capability.
+
+**Site preferences** (needs the `sfcc` profile; sandbox only)
+- `site_preference_get` — read a preference group's effective preferences.
+- `site_preference_search` — search/filter preferences within a group.
+
 ## CLI Subcommands
 
 Beyond `--init` / `--upgrade`, the package ships operational subcommands of the **single `bridge-api-mcp-server` bin** (not separate binaries) — so they travel with the package to every consumer. See [Usage Documentation → Start Tickets](#tier-1--regularly-useful) for *when* to use `start-tickets`; this section is the full CLI reference.
@@ -591,7 +653,7 @@ Reports are written to `<BAPI_DOCS_DIR>/smoke-test/REPORT-<host>-<timestamp>.md`
 | `BAPI_WORKTRUNK_BIN` | No | `wt` (`git-wt` on Windows) | Override the Worktrunk executable name/path used by `start-tickets` for nonstandard installs |
 | `BAPI_TMUX_SESSION` | No | `bridge-start-tickets` | Override the tmux session-name prefix used by `start-tickets` on Linux |
 | `BAPI_MCP_UPGRADE_ADVICE_ENABLED` | No | _(enabled)_ | MCP-local opt-out for proactively surfacing upgrade advice in pipeline recipe preambles. Set to `false`/`0`/`no`/`off`/`disabled` to suppress. Disabling it does **not** change the `/jira/ping` response or server-side upgrade computation — it only gates the recipe-preamble convention |
-| `BRIDGE_MCP_PROFILE` | No | `core` | Startup-time tool registration profile. Controls which tool groups are registered when the server starts. Valid values: `core` (default — normal coding tools only), `conductor` (core + 8 conductor/event/supervisor tools), `pipeline-authoring` (core + 5 pipeline run/admin tools — `get_pipeline_recipe` is NOT gated; it stays in `core` because the recipe-driven slash commands depend on it), `full` (all tools, equivalent to the legacy unconditional registration). Unknown, blank, or malformed values fail safe to `core`. Dynamic mid-session switching via `tools/list_changed` is unsupported — the profile is resolved once at process startup. **Phase 2b note:** epic/conductor sessions launched via `start-tickets` will automatically inject `BRIDGE_MCP_PROFILE=conductor`; that injection is handled at the spawn boundary and is out of scope for this phase. |
+| `BRIDGE_MCP_PROFILE` | No | `core` | Startup-time tool registration profile — a **comma-separated** list of groups controlling which tool groups are registered when the server starts. `core` is always implicitly included. Valid groups: `core` (default — normal coding tools only), `conductor` (+ 8 conductor/event/supervisor tools), `pipeline-authoring` (+ 5 pipeline run/admin tools — `get_pipeline_recipe` is NOT gated; it stays in `core` because the recipe-driven slash commands depend on it), `sfcc` (+ the 7 heavy SFCC read tools — see [Salesforce B2C Commerce (SFCC) Tools](#salesforce-b2c-commerce-sfcc-tools); the `sfcc_setup_status`/`check_permissions` diagnostics are always registered regardless), and `full` (shortcut that expands to every group). Example: `sfcc,conductor`. Unknown, blank, or malformed tokens are dropped (falling back to `core`). Dynamic mid-session switching via `tools/list_changed` is unsupported — groups are resolved once at process startup. Conductor/epic sessions launched via `start-tickets --conductor` automatically inject `BRIDGE_MCP_PROFILE=conductor` at the spawn boundary; a normal `start-tickets` run stays on `core`. |
 
 ## Worktree credentials and the `mcp-invoke` shim
 
@@ -666,18 +728,18 @@ The full surface, for when you need the complete enumeration. Day-to-day, use [U
 
 ### MCP tools
 
-The server registers **62 tools**. Async AI tools follow a request/get pattern: call the `request_*` tool to kick off generation, then the matching `get_*` tool to retrieve the result (or pass `wait_for_result: true` to poll automatically).
+The server registers **58 tools**. Async AI tools follow a request/get pattern: call the `request_*` tool to kick off generation, then the matching `get_*` tool to retrieve the result (or pass `wait_for_result: true` to poll automatically).
 
 - **Connectivity & identity** — `ping`, `get_my_role`, `get_docs_dir`
 - **Jira tickets** — `get_tickets`, `get_ticket`, `create_ticket`, `update_ticket_description`, `add_comment`, `get_comments`
-- **Attachments** — `list_attachments`, `upload_attachment`, `download_attachment`
+- **Attachments** — `attachment` (operations: `upload`, `download`, `list`)
 - **AI generation (request/get)** — `request_plan_generation`/`get_plan`, `request_architecture`/`get_architecture`, `create_doc`/`get_doc` (design docs by `doc_type`: tdd/fsd/prd), `request_prd`/`get_prd`, `request_clarifying_questions`/`get_clarifying_questions`, `request_ticket_critique`/`get_ticket_critique`, `request_ticket_review`, `request_reimplement_context`/`get_reimplement_context`, `request_brainstorm`/`get_brainstorm`, `request_deep_research`/`get_deep_research`
 - **Other AI** — `second_opinion`, `generate_image`, `generate_decision_page`
 - **Ticket lifecycle** — `track_ticket`, `update_ticket_state`, `get_ticket_state`
 - **Jira status** — `get_jira_transitions`, `update_jira_status`, `resolve_target_status`
 - **Repository & CI** — `parse_repository`, `get_parse_status`, `regenerate_directory_map`, `create_pull_request`, `resolve_ci_checks`, `poll_ci_checks`
 - **Pipelines & automation** — `list_pipelines`, `get_pipeline_recipe`, `run_pipeline`, `resume_pipeline`, `list_pipeline_runs`, `delete_pipeline_run`, `run_full_automation`, `resume_full_automation`
-- **Config** — `get_project_standards`, `list_config_fields`, `get_config_field`, `update_config_field`
+- **Config** — `get_project_standards`, `config_field` (operations: `get`, `update`, `list`)
 
 ### Bundled pipelines