@bridge_gpt/mcp-server 0.2.23 → 0.2.25

package/README.md

@@ -18,7 +18,7 @@ The Bridge MCP is an end-to-end accelerator for shipping code within SFCC, power
 - [Worktree credentials and the `mcp-invoke` shim](#worktree-credentials-and-the-mcp-invoke-shim)
 - [Reference](#reference)
 
-For advanced epic/multi-agent orchestration, see [CONDUCTOR.md](./CONDUCTOR.md).
+For advanced epic/multi-agent orchestration, see [CONDUCTOR.md](./docs/CONDUCTOR.md).
 
 ## Getting Started
 
@@ -30,12 +30,29 @@ From your **project root**, install and connect in one command:
 npx -y @bridge_gpt/mcp-server@latest install-bridge
 ```
 
-`install-bridge` scaffolds the project, writes your editor's MCP config with real
-values, verifies connectivity, persists your API key to the user-scoped credential
-store, and opens a fresh agent session to finish setup (`/install-bridge` then
-`/learn-repository`). The only inputs are an **API key** (generate one on the Bridge
-API web UI **Security** page) and a **repo name** — everything else is derived. Add
-`--dry-run` to preview every step without writing, pinging, or spawning anything.
+Run bare like that in a terminal and it starts by asking
+**`Do you have a Bridge API key? [Y/n]`**:
+
+- **Yes** (or just press Enter) — the existing-key flow. It asks for your **API key**
+  (generate one on the Bridge API web UI **Security** page) and a **repo name**
+  matching your server-side registration; everything else is derived.
+- **No** — the **self-serve** flow. It asks for an **email**, then a name for your new
+  Bridge project, and creates the workspace and your own admin API key for you. No
+  account, no key, and no invite needed beforehand. Same as passing
+  `--email you@example.com` (see below).
+
+That question is asked only for a *bare interactive* run. Passing any flag, setting
+`BAPI_API_KEY`, or running without an interactive terminal skips it and keeps the
+existing deterministic behavior.
+
+From there `install-bridge` scaffolds the project, writes your editor's MCP config
+with real values, verifies connectivity, persists your API key to the user-scoped
+credential store, and opens a fresh agent session that runs `/install-bridge` to
+derive and apply the remaining config, presents a **capability report** (what you can
+use now and what you'll unlock), and closes by asking whether to index the
+repository. It does **not** automatically run `/learn-repository` or index without
+your consent — both remain available as separate steps. Add `--dry-run` to preview
+every step without writing, pinging, or spawning anything.
 
 **Were you sent a bootstrap invite?** Then you don't need an API key or the web UI
 at all — run the command your operator gave you:
@@ -78,25 +95,66 @@ works as a fallback.)
 4. **Persists your key** to the user-scoped credential store
    (`~/.config/bridge/credentials.json`, target `bapi:<repo>`) so shell-spawned
    tooling (e.g. `start-tickets`) can resolve it.
-5. **Opens a fresh agent session** that runs `/install-bridge` (to derive the
-   remaining config fields from your codebase) and then `/learn-repository`.
+5. **Opens a fresh agent session** that runs `/install-bridge` to derive and apply
+   the remaining config fields from your codebase, presents the capability report
+   (Connected / Not yet connected / Tools you can use now / Tools you'll unlock /
+   Recommended next step), and closes with one optional `[Y/n] Index repository
+   now?` question. It does not chain `/learn-repository` and never indexes without
+   consent; run `/learn-repository` and `/parse-repository` yourself when you want
+   them.
 
-The only inputs are an **API key** and a **repo name** (everything else is
-derived). Resolution order:
+In this **existing-key** flow the only inputs are an **API key** and a **repo name**
+(everything else is derived). Resolution order:
 
 - **API key:** `--api-key <key>` → `BAPI_API_KEY` env → an interactive (no-echo)
   prompt. Generate one first on the Bridge API web UI **Security** page (see
-  [Generate an API Key](#2-generate-an-api-key)); the command consumes a key, it
-  never mints one — **`--invite` is the one exception** (below). The key is
-  **never printed or logged**.
-- **Repo name:** `--repo <name>` → `BAPI_REPO_NAME` env → an inferred default you
-  confirm interactively. It MUST match the server-side repository registration.
+  [Generate an API Key](#2-generate-an-api-key)); in this flow the command consumes
+  a key, it never mints one — **`--email` and `--invite` are the two exceptions**
+  (below), and each mints your first key. The key is **never printed or logged**.
+- **Repo name:** `--repo <name>` and `BAPI_REPO_NAME` remain the deterministic
+  short-circuits and compatibility fallbacks — when either is set it is used
+  directly, with no network round-trip. When **neither** is set, a compatible
+  server resolves the unique repository from your existing API key automatically
+  (a read-only lookup), so you don't have to supply it. If the server is older,
+  the key can't be uniquely resolved, or the lookup fails, `install-bridge` falls
+  back to an inferred default you confirm interactively (and requires `--repo`
+  when stdin is non-interactive). Whatever name is used MUST match the
+  server-side repository registration.
+
+#### Self-serve email onboarding (`--email`) — no account, no key, no invite
+
+The primary path for a **first-time user with nothing yet** — no Bridge account,
+no API key, and no pre-issued invite. Run:
+
+```bash
+npx -y @bridge_gpt/mcp-server@latest install-bridge --email you@example.com
+```
+
+`install-bridge` requests a brand-new Bridge workspace for that email, receives an
+invite token, and then feeds it into the **exact same** persist-before-exchange
+bootstrap protocol as `--invite` below — so the project is created and your first
+admin key is minted in one command. The minted token is used internally and **never
+shown**.
+
+The email may instead come from the `BAPI_SIGNUP_EMAIL` environment variable or a
+**visible** interactive prompt (email is not a secret, so it is echoed as you type —
+unlike the API key and the invite token, which use a hidden prompt). That prompt is
+what answering **no** to `Do you have a Bridge API key? [Y/n]` on a bare run reaches,
+so `install-bridge --email you@example.com` and a bare `install-bridge` + "no" land
+in the same place. The email is still **never written to a log line**. No email
+verification is performed and no message is sent to the address — it only labels your
+new workspace. `--email` is mutually exclusive with `--api-key` and `--invite`.
+
+Because this flow *creates* the project, it asks you to **name a new project**
+(`Name your new Bridge project [<inferred>]: `) rather than to match an existing
+server-side registration. The name must be globally unique; if it's taken, you're
+asked for another one and the invite is not consumed. The same applies to `--invite`.
 
 #### Bootstrap-invite onboarding (`--invite`)
 
-With a **bootstrap invite** there is no pre-existing key and no web UI: this is the
-one mode where `install-bridge` **creates** the project and its first admin key
-instead of consuming one. Run `install-bridge --invite` and it:
+With a **bootstrap invite** you were already given, there is no pre-existing key and
+no web UI: like `--email` above, this mode **creates** the project and its first
+admin key instead of consuming one. Run `install-bridge --invite` and it:
 
 1. **Prompts for the bootstrap invite token** with echo suppressed (the default —
    see below).
@@ -134,8 +192,12 @@ Useful flags:
   credential store, without prompting (re-running is otherwise non-destructive).
 - `--agent claude|cursor-agent` — which agent to launch for the agentic remainder
   (default `claude`).
+- `--email <addr>` — self-serve signup: create a new workspace from just an email
+  (mutually exclusive with `--api-key` and `--invite`). Falls back to
+  `BAPI_SIGNUP_EMAIL`, then a visible prompt. Visible input, not a secret; still
+  never logged.
 - `--invite [token]` — redeem a bootstrap invite (mutually exclusive with
-  `--api-key`). Omit the value to get the hidden prompt.
+  `--api-key` and `--email`). Omit the value to get the hidden prompt.
 
 That's it — once `install-bridge` finishes you're connected. If you prefer to do
 it by hand (or just want to understand each step), the manual flow below does the
@@ -502,10 +564,12 @@ Salesforce's official MCP server, `@salesforce/b2c-dx-mcp`, covers developer-exp
 
 **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.
 
+For a step-by-step OCAPI client setup guide (including the Business Manager permissions grant), see [docs/install/sfcc-integration.md](./docs/install/sfcc-integration.md).
+
 <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).
+The two diagnostic tools (`sfcc_setup_status`, `check_permissions`) are always available. The read tools, the write tools, and `sfcc_log_query` must be enabled with a profile (step 3). Changing `BRIDGE_MCP_PROFILE` requires an MCP client restart.
 
 **Prerequisites:** a running SFCC **sandbox** and its hostname, plus an Account Manager API client (`client-id` + `client-secret`).
 
@@ -540,7 +604,7 @@ Without this, only the diagnostic tools are registered.
 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.
+- `sfcc_setup_status` — report on every prerequisite: Bridge API key, repo name, `version` config, `dw.json` presence/uniqueness, AM (OCAPI) token acquisition, and the independent **SFCC Log Query (WebDAV)** capability that gates `sfcc_log_query`.
 - `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)
@@ -559,6 +623,14 @@ All SFCC tools are read-only and target a developer sandbox. Oversized responses
 - `site_preference_search` — search/filter preferences within a group.
 - `site_preference_values_set` — **write** (sandbox only): set custom preference values via `PATCH /site_preferences/preference_groups/{group}/sandbox` with a flat map of `c_`-prefixed ids to string/number/boolean/string[] values. A bad group returns 404 `CustomPreferenceGroupNotFoundException`; echoes grant JSON on 403.
 
+**On-demand log query** (needs the `sfcc` profile)
+- `sfcc_log_query` — query redacted, filtered SFCC logs on demand. `environment` and `time_range` (`start`/`end`) are **required** — production, "all environments", and an open-ended period are never inferred. The tool calls a Bridge backend endpoint that runs the pull → redaction → filter pipeline server-side and returns scoped, redacted findings; **WebDAV credentials, retrieval, redaction, and filtering all stay server-side and single-sourced.** It holds no credentials of its own.
+  - **Guardrails.** Selection is bounded by log-file `prefixes` (max 5), the time range, a scanned-entry cap (`max_entries`, ≤ 2000), a finding cap, and a per-snippet length cap. High-volume prefix classes (`info`, `jobs`, `debug`, `customdebug`) impose a **stricter 6-hour** max range (vs. 24h for the error class) because `info-*` runs ~1 MB/day versus `error-*` at ~13 KB median — a wide window over a high-volume prefix is **rejected**, never silently narrowed.
+  - **Response order.** Resolved scope (`environment`, `time_range`, `applied_prefixes`) and cap `status` first, redacted `findings` second, retrieval/truncation `metadata` last.
+  - **Statuses & errors.** `ready`, `no_matching_findings`, `results_truncated`; plus `VALIDATION_ERROR` (bad/oversized scope, caught before any network call), `NOT_CONFIGURED` (503 — the log capability isn't set up; run `sfcc_setup_status`, whose step 6 reports it), and `BAD_GATEWAY`/`SERVICE_UNAVAILABLE` on a retrieval/backend failure.
+  - **Auth is separate from OCAPI.** Log retrieval uses **HTTP Basic auth** — a Business Manager username + a **40-character WebDAV access key** — *not* the OCAPI Account Manager OAuth token the other SFCC tools use. A valid AM bearer token 401s on `/Logs`. `sfcc_setup_status` step 5 (AM/OCAPI token) and step 6 (WebDAV log access) are independent: one can be green while the other is not.
+  - **Local / air-gapped fallback.** The primary path above is the only path this tool takes. For air-gapped development, the documented fallback is Salesforce's own **`@salesforce/b2c-dx-mcp`** (`logs_list_files`, configured from `dw.json`) — it is vendor-maintained and reads log files over WebDAV, so it is strictly less work than shelling the B2C CLI (`b2c logs get --since <window> --search <q> --json`). It is **not** the primary path because its credentials live client-side and its output has **not** passed Bridge's redaction/filter. If you use it, its output must be treated as raw: route it back through the same server-side Python `LogSource` composition and `RedactionPort`/T3 filter workflow — never paste or relay unredacted `b2c-dx-mcp` or CLI output to an LLM.
+
 ## 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.
@@ -593,7 +665,7 @@ npx -y @bridge_gpt/mcp-server start-tickets --agent cursor-agent BAPI-248
 
 **Difficulty-based model routing.** Before launching each agent, the CLI selects an implementation **model tier** from the ticket's `difficulty` (1-2 → cheap, 3-5 → basic, 6+ → premium) and injects it as a `--model` flag at the spawn boundary. The Python backend returns only the coarse tier (`GET /jira/tickets/{KEY}/model-tier`, computing + caching difficulty on demand); this CLI alone maps a tier to the agent-specific alias (`claude`: `haiku`/`sonnet`/`opus`; `cursor-agent`: version-suffixed strings validated against `cursor-agent --list-models`). It is gated per repo by `difficulty_model_routing_enabled` (default **ON**) with an optional `difficulty_model_tier_overrides` JSON map (tier → alias). Routing is **fail-open**: missing credentials, an evaluation failure/timeout, a backend `fallback`, an invalid/unavailable alias, an unadvertised Cursor model, or an agent without `--model` support all omit `--model` (the agent uses its default) and surface a per-ticket warning rather than failing the spawn. `--dry-run` does **not** fetch tiers or inject `--model`.
 
-**Conductor observability (opt-in via `--conductor`, BAPI-394).** Conductor is **off by default**. With `--conductor`, a run mints a conductor `run_id`, emits events into the local ledger (`~/.config/bridge/events.db`), opens a supervisor peer tab, and (for Claude Code) injects a secret-free lifecycle hook into each worktree; it also sets `BRIDGE_MCP_PROFILE=conductor` so workers get the conductor MCP tools. Observability is best-effort — a conductor failure never blocks a spawn, and `--dry-run` performs no conductor side effects. (Epic-tick dispatch always enables conductor internally.) See **[CONDUCTOR.md](./CONDUCTOR.md)** for the full observability, git-hook, done-gate, and auto-merge reference.
+**Conductor observability (opt-in via `--conductor`, BAPI-394).** Conductor is **off by default**. With `--conductor`, a run mints a conductor `run_id`, emits events into the local ledger (`~/.config/bridge/events.db`), opens a supervisor peer tab, and (for Claude Code) injects a secret-free lifecycle hook into each worktree; it also sets `BRIDGE_MCP_PROFILE=conductor` so workers get the conductor MCP tools. Observability is best-effort — a conductor failure never blocks a spawn, and `--dry-run` performs no conductor side effects. (Epic-tick dispatch always enables conductor internally.) See **[CONDUCTOR.md](./docs/CONDUCTOR.md)** for the full observability, git-hook, done-gate, and auto-merge reference.
 
 **Cross-platform spawning.** The CLI routes spawning per platform; `--dry-run` previews the platform-correct command form on any OS. An unsupported `process.platform` (not `darwin`/`win32`/`linux`) fails fast with a clear "unsupported platform" message.
 
@@ -631,7 +703,7 @@ npx -y @bridge_gpt/mcp-server executor --repo <name>
 
 ### Conductor (epic & multi-agent orchestration)
 
-Conductor is an **opt-in, off-by-default** layer for epic supervision, inter-agent messaging, done-gate evaluation, local git-hook event producers, and conditional auto-merge. Its full reference — the v2 architecture (server-side reconciler + local executor), `setup-epic`, `conductor install-git-hooks`, the supervisor `done_gate_config` / `auto_merge_enabled` settings, and the observability stream — lives in **[CONDUCTOR.md](./CONDUCTOR.md)**.
+Conductor is an **opt-in, off-by-default** layer for epic supervision, inter-agent messaging, done-gate evaluation, local git-hook event producers, and conditional auto-merge. Its full reference — the v2 architecture (server-side reconciler + local executor), `setup-epic`, `conductor install-git-hooks`, the supervisor `done_gate_config` / `auto_merge_enabled` settings, and the observability stream — lives in **[CONDUCTOR.md](./docs/CONDUCTOR.md)**.
 
 > The v1 `conductor epic-tick` command is **frozen** — it throws on every invocation. There is nothing to schedule locally, and `conductor doctor` flags any epic-tick schedule left over from an earlier release so you can cancel it.