@bridge_gpt/mcp-server

The Bridge MCP is an end-to-end accelerator for shipping code within SFCC, powered by Bridge API. Works with Claude Code, Github Copilot, Cursor, Windsurf, and OpenAI Codex.

Contents

• Getting Started
• Usage Documentation
  • Tier 1 — Regularly useful
  • Tier 2 — Occasionally useful
  • Tier 3 — Now and then
  • Operational commands
  • Extra Capabilities
• Salesforce B2C Commerce (SFCC) Tools
• CLI Subcommands
• Custom Pipelines
• Environment Variables
• Worktree credentials and the mcp-invoke shim
• Reference

For advanced epic/multi-agent orchestration, see CONDUCTOR.md.

Getting Started

Quick start

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 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. 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.

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:

npx -y @bridge_gpt/mcp-server@latest install-bridge --invite

That one-liner is deliberately secret-free: the CLI prompts for the bootstrap invite token with echo suppressed, and sends it only in the request body. It creates your project and mints your own admin API key in a single command.

To upgrade later, run:

npx -y @bridge_gpt/mcp-server upgrade

upgrade re-execs from @latest, refreshes all scaffolded artifacts (slash commands, agents, pipelines), rewrites the version pin, and reconnects — also available as the /upgrade-bridge slash command. (The legacy --upgrade flag still works as a fallback.)

What install-bridge does

install-bridge collapses the whole setup into a single command. It:

1. Scaffolds the project (the same artifacts --init writes: slash commands, agents, .bridge/pipelines/, and secret-free MCP config placeholders).
2. Writes the per-host MCP config (.mcp.json / .cursor/mcp.json / .vscode/mcp.json) with your real BAPI_REPO_NAME / BAPI_API_KEY / BAPI_BASE_URL / BAPI_DOCS_DIR, preserving any unrelated servers. The launcher it writes is pinned to the exact installed version so npx never silently reuses a stale local copy. (Windsurf and Codex are global configs it can't safely write — it prints copy-paste instructions for those.)
3. Verifies connectivity against the Bridge API before persisting anything.
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 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:

• 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); 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> 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:

npx -y @bridge_gpt/mcp-server@latest install-bridge --email [email protected]

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). It 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.

Bootstrap-invite onboarding (--invite)

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).
2. Generates your key_secret (32 CSPRNG bytes) and fsyncs it locally before contacting the server. If that write fails the run aborts and the invite is not spent.
3. Redeems the invite — POST /setup/bootstrap with the token, repo name, and key_secret in the body — which creates the project and mints your admin key. (This replaces the connectivity ping: there is no key to ping with yet.)
4. Verifies the newly-minted key, then writes the per-host MCP config.
5. Promotes the credential to bapi:<repo> and opens the agent session — the same Steps 3–5 as the normal flow.

Because the locally-saved key_secret is the only proof that can replay a redemption, a re-run after a network failure is safe: it re-sends the same secret and gets back the same project and key. If the repo name you chose is already taken (names are globally unique) the server rolls back — your invite is untouched — and the CLI asks for a different name and retries with the same token.

The delivered one-liner is secret-free, by design. "A copy/paste one-liner" and "the token never touches shell history" are contradictory, so the token is not in the command: the CLI asks for it, and it travels only in the request body. --invite <token>, --invite=<token>, and BAPI_INVITE still work for scripting only — and both forms expose the token to your shell history and to the process list. Prefer the prompt.

Useful flags:

• --dry-run — preview every step (scaffold targets, config files and keys with the key value redacted, the ping target, the credential store target, and the exact agent spawn command) without writing, pinging, or spawning anything. With --invite it also never calls the exchange endpoint and never generates or stores a secret.
• --force — overwrite an existing real BAPI_API_KEY in a host config, or in the 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 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 same thing.

Manual Setup (Alternative)

1. Install the Package

From your project root, install the MCP server and scaffold slash commands:

npm i @bridge_gpt/mcp-server
npx -y @bridge_gpt/mcp-server --init

--init must be run from the directory containing your package.json. It:

• Creates slash commands in .claude/commands/ and .cursor/commands/
• Detects existing MCP config files and sets BAPI_PROJECT_ROOT so local file output resolves correctly
• Scaffolds .bridge/pipelines/ for custom pipeline authoring

Re-run --init after upgrading the package to get updated commands.

2. Generate an API Key

1. Log in to Bridge API and navigate to your project's Security page
2. Click Create New Key
3. Enter your email, an optional label (e.g., "MCP Server"), and select the Admin role
4. Click Create Key
5. Copy the key immediately — it will not be shown again

3. Configure the MCP Server

Add the following to your editor's MCP configuration file, pasting in the API key from step 2:

The --init command (step 1) detects Claude Code and creates a .mcp.json at your project root with placeholder values. Open it and replace your-repo and your-api-key with your actual values from step 2:

{
  "mcpServers": {
    "bridge-api": {
      "command": "npx",
      "args": ["-y", "@bridge_gpt/mcp-server"],
      "env": {
        "BAPI_BASE_URL": "https://bridgegpt-api.com",
        "BAPI_REPO_NAME": "your-repo",
        "BAPI_API_KEY": "your-api-key",
        "BAPI_DOCS_DIR": "docs/tmp"
      }
    }
  }
}

{
  "servers": {
    "bridge-api": {
      "command": "npx",
      "args": ["-y", "@bridge_gpt/mcp-server"],
      "env": {
        "BAPI_BASE_URL": "https://bridgegpt-api.com",
        "BAPI_REPO_NAME": "your-repo",
        "BAPI_API_KEY": "your-api-key",
        "BAPI_DOCS_DIR": "docs/tmp"
      }
    }
  }
}

{
  "mcpServers": {
    "bridge-api": {
      "command": "npx",
      "args": ["-y", "@bridge_gpt/mcp-server"],
      "env": {
        "BAPI_BASE_URL": "https://bridgegpt-api.com",
        "BAPI_REPO_NAME": "your-repo",
        "BAPI_API_KEY": "your-api-key",
        "BAPI_DOCS_DIR": "docs/tmp"
      }
    }
  }
}

If project-local config is not supported in your Cursor version, use ~/.cursor/config/mcp.json instead.

Windsurf only supports global MCP configuration.

{
  "mcpServers": {
    "bridge-api": {
      "command": "npx",
      "args": ["-y", "@bridge_gpt/mcp-server"],
      "env": {
        "BAPI_BASE_URL": "https://bridgegpt-api.com",
        "BAPI_REPO_NAME": "your-repo",
        "BAPI_API_KEY": "your-api-key",
        "BAPI_DOCS_DIR": "docs/tmp"
      }
    }
  }
}

[mcp_servers.bridge-api]
command = "npx"
args = ["-y", "@bridge_gpt/mcp-server"]

[mcp_servers.bridge-api.env]
BAPI_BASE_URL = "https://bridgegpt-api.com"
BAPI_REPO_NAME = "your-repo"
BAPI_API_KEY = "your-api-key"
BAPI_DOCS_DIR = "docs/tmp"

Codex users: set BAPI_PROJECT_ROOT manually in your config (see Environment Variables below).

After saving the config, restart your editor or reload the MCP server connection. Verify connectivity by asking your AI assistant to call the ping tool.

4. First-Time Setup: Teach Bridge Your Codebase

If you're the first person to install Bridge API on your project, run the /learn-repository slash command after completing setup. This analyzes your codebase's architecture, testing patterns, code review standards, and documentation conventions, then uploads the findings to Bridge API. This gives Bridge the context it needs to generate implementation plans, ticket critiques, and code reviews that are consistent with your project's actual architecture and conventions.

You only need to do this once per project — the learned standards persist for all team members.

Upgrading (details)

The one-command npx -y @bridge_gpt/mcp-server upgrade (shown above) is the recommended path. The legacy flag npx -y @bridge_gpt/mcp-server --upgrade still works: it runs npm i @bridge_gpt/mcp-server@latest, prints a before/after version summary, then re-runs the full --init scaffolding flow to update your slash commands, agents, and pipeline definitions.

The MCP server also checks for updates automatically on startup. If a newer version is available, you'll see a notice in your editor's MCP output logs with the upgrade command to run. This check is cached for 24 hours and never blocks server startup.

Usage Documentation

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, and a full enumeration lives in Reference.

Working in a Salesforce B2C Commerce codebase? Bridge also ships read-only SFCC platform-introspection tools — see 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

These features are useful for most tickets.

1. Review Ticket

• What it does: Runs a full quality review of a ticket: clarifying questions + critique plus an automatic alternate-model second opinion, then evaluates findings and produces a decision page to accept/reject them. The backend executor now owns all review round orchestration (including the second-opinion round) server-side; pass --rounds=1 for a cheaper single-pass review, --rounds=2 to force the full second-opinion review, or omit --rounds to let the backend's difficulty-adaptive review policy decide.
• When it's useful: (Refinement) Right after a ticket is drafted, before anyone starts building — to surface gaps and tighten it.
• How to use it: /review-ticket BAPI-123 (command only — "review" as free text is easily mistaken for a freehand agent review).
• Flags: --auto auto-accept findings / skip the approval gates · --rounds=1 request a cheaper single-pass review (no second-opinion round) while preserving downstream evaluation and decision-capture work · --rounds=2 force the full second-opinion review · omit --rounds to let the backend's difficulty-adaptive review policy decide (it falls back to a full second-opinion review when adaptive routing is disabled or the ticket's difficulty cannot be resolved).
• Multi-ticket fan-out: /review-tickets BAPI-123 BAPI-456 opens one terminal tab per ticket for parallel review with no worktrees (terminal launcher only — no wt/git). All /review-ticket flags apply; --review KEY=auto,rounds=N sets per-ticket overrides. Packaged CLI: npx -y @bridge_gpt/mcp-server review-tickets KEY [KEY ...].

2. Start Tickets

• What it does: Creates one git worktree per ticket and spawns an agent session in each to implement them in parallel.
• When it's useful: (Implementation | Automation) When you're ready to start building one or more refined tickets concurrently.
• How to use it: /start-tickets BAPI-248 BAPI-250 (see CLI Subcommands for the full flag table and cross-platform behavior).
• Flags: --auto skip the approval gates · --base-branch <branch> branch off something other than the default · --workflow implement|review-and-implement selects which slash command each spawned worktree runs (default implement, byte-identical to today; review-and-implement runs /review-ticket then, after a per-ticket halt gate, /implement-ticket in the same session) · --rounds=1|2 review-only, forwarded to the review phase, valid only with --workflow review-and-implement.

2b. Review and Start

• What it does: Spawns one worktree per ticket, each running review then (after a per-ticket human proceed/halt gate) implementation — the chained review → gate → implement composition.
• When it's useful: (Refinement | Implementation | Automation) The recommended front door for "review these tickets, then implement the ones that pass," starting from existing ticket keys (unlike /full-automation, which only accepts an idea).
• How to use it: /review-and-start BAPI-248 BAPI-250 (single or multiple keys flow through the identical code path).
• Flags: --auto a single chain-level flag that auto-approves both the review and the implementation phase of every spawned session · --rounds=1|2 forwarded to the review phase · --agent, --base-branch, --max-parallel, --dry-run mirror /start-tickets.
• Under the hood, this is a thin shim over start-tickets --workflow review-and-implement <KEYS> — the lower-level launcher seam documented above; the halt-gate decision logic lives in the spawned /review-and-implement session, never in this command or the CLI.

3. Brainstorm

• What it does: Fans your problem out to two different LLMs and returns their approaches directly. Runs in one of three modes, selected via mode: technical (default — implementation/architecture approaches), design (UI/UX and visual direction), or discovery (stakeholder discovery questions for early/vague tasks, grouped into Technical Discovery Questions and Business / Stakeholder Discovery Questions and tagged [HUMAN]/[CODE]/[TICKET]). Discovery needs no extra configuration. The legacy boolean design=true still works and maps to mode: "design".
• When it's useful: (Architecture | Refinement) Early, when you want a spread of approaches — technical for how to build it, design for how it should look, discovery for what we still need to figure out before a real ticket exists.
• How to use it: ask your agent to brainstorm — "Brainstorm approaches for adding rate limiting to the LLM client; fan it out to multiple models." For a design pass: "Run a design brainstorm for the evidence-freshness dashboard UI." For early discovery: "Run a discovery brainstorm — request_brainstorm with mode: "discovery" — for this vague request so we can collect the questions stakeholders need to answer first."

4. Deep Research

• What it does: Runs multi-source, fact-checked web research on a technical topic and returns a cited report.
• When it's useful: (Architecture | Refinement) When a decision hinges on outside knowledge (libraries, best practices, standards) you don't already have.
• How to use it: /bridge-research <question>

5. Jira Ticket Writer

• What it does: An agent that drafts a well-structured Jira ticket from a plain description, applying your project's standards.
• When it's useful: (Refinement) When you have an idea in your head and want a properly-formatted ticket draft without writing it by hand.
• How to use it: /write-ticket <description> (or ask your agent) — "Use the jira ticket writer to turn our conversation into a ticket."
• Flags: --standards <path> apply a specific standards file when drafting.

6. Upload Ticket

• What it does: Pushes a drafted ticket up to Jira as a real issue (the create_ticket capability); handles markdown and child tickets under an Epic.
• When it's useful: (Refinement) The final step after drafting — to get the ticket into Jira so it can be tracked and worked.
• How to use it: Ask your agent to create the ticket, and it should confirm before creating the live Jira issue.
• Options: Describe the issue type (Bug / Story / Task / Epic) and, for a child under an Epic, the parent key.

Tier 2 — Occasionally useful

These features are good to know, but you probably won't use them every day.

1. Plan Ticket

• What it does: Generates a step-by-step implementation plan for a ticket, with references to real code files, and saves it locally.
• When it's useful: (Refinement | Implementation) Once a ticket is solid and you want a concrete build plan before (or instead of) auto-implementing.
• How to use it: /plan-ticket BAPI-123
• Flags: --provider <name> choose the model provider · --second-opinion <provider> cross-check the plan with a second provider.

2. Clarify Ticket

• What it does: Generates clarifying questions for a ticket (or debugging guidance for bugs) and saves them locally.
• When it's useful: (Refinement) When a ticket feels under-specified and you want the open questions made explicit.
• How to use it: /clarify-ticket BAPI-123 — "Generate clarifying questions for BAPI-123"
• Flags: --provider <name> choose the model provider · --second-opinion <provider> cross-check with a second provider.

3. Critique Ticket

• What it does: Critiques a ticket's quality against your project standards and lists deviations + improvements.
• When it's useful: (Refinement) When you want a quality gate on a ticket before it's worked.
• How to use it: /critique-ticket BAPI-123 — "Critique BAPI-123 against our project standards and list what's missing or deviating."
• Flags: --provider <name> choose the model provider · --second-opinion <provider> cross-check with a second provider.

4. Create Doc

• What it does: Generates a design document for a ticket — a TDD (technical design, engineer audience), an FSD (functional spec, for product/design/QA), or a PRD (product requirements: problem, goals, success metrics) — and saves it locally.
• When it's useful: (Architecture | Refinement) When a ticket needs a fuller design write-up before planning or implementation, in the shape that fits your audience.
• How to use it: /create-doc BAPI-123 --doc-type tdd (or fsd / prd)
• Flags: --doc-type tdd|fsd|prd which document to generate (required) · --provider <name> choose the model provider · --second-opinion <provider> cross-check with a second provider.

5. Explore Ticket

• What it does: Explores the codebase for a task and recommends implementation options or surfaces clarifying questions, with optional research.
• When it's useful: (Architecture | Refinement) Before writing a ticket or plan, when you're unsure how a change would fit the existing code.
• How to use it: /explore-ticket <task> — "Explore the codebase for how we'd add a Mistral LLM provider and recommend 2–3 implementation options."

6. Second Opinion

• What it does: Gets an immediate critique of any text from a different model family — no artifact saved, just the reply.
• When it's useful: (Architecture | Refinement | Implementation) Any time you want a quick sanity check on a plan, draft, or decision from a fresh perspective.
• How to use it: ask your agent — "Get a second opinion from Gemini on whether the BAPI-123 plan's migration step is safe to run against prod."
• Options: pick the provider (anthropic / openai / gemini) and the tier (cheap / basic / premium).

7. Generate Image

• What it does: Generates an image from a text prompt using a provider image model (OpenAI gpt-image-2 by default, or Google Imagen) and returns the image directly. Spends provider credits on every call.
• When it's useful: (Architecture | Refinement) When you want a quick visual — a UI mockup, diagram, or illustration — to anchor a design discussion or attach to a ticket.
• How to use it: ask your agent — "Generate an image of a dashboard showing SOC2 evidence freshness as a traffic-light grid."
• Options: provider openai (gpt-image-2) / gemini (Imagen — adds an invisible SynthID watermark) · quality low (default, cheapest) / medium / high · size 1024x1024 / 1024x1536 / 1536x1024. The image is always saved to BAPI_DOCS_DIR/images/ and also returned inline.

8. Implement Ticket

• What it does: Full build for one ticket: generate a plan, write the code, commit, open a PR, and monitor CI.
• When it's useful: (Implementation) When a ticket is ready and you want it taken from plan to open PR in one go.
• How to use it: /implement-ticket BAPI-123 (command only — "implement X" as free text almost always triggers a freehand build instead of the Bridge plan→code→PR→CI pipeline).
• Flags: --auto skip the approval gates (e.g. auto-commit/push).

9. Full Automation

• What it does: Drives the whole chain end-to-end: idea → ticket(s) → review each → spawn worktrees to implement.
• When it's useful: (Automation) When you want to go from a raw idea to in-progress implementation with minimal hands-on steps.
• How to use it: /full-automation <idea> (command only — creates tickets, spawns worktrees, and carries scheduling/--max-children flags that free text can't).
• Flags: --require-approval toggle the approval gates, full automation runs end to end by default.

10. Idea to Ticket

• What it does: Turns a one-line idea into a Jira Task/Spike (or an Epic plus child tickets), with research, duplicate detection, and a critique pass built in.
• When it's useful: (Refinement | Automation) When you have a rough idea and want a fully-formed, uploaded ticket without the manual draft-and-refine loop.
• How to use it: /idea-to-ticket <idea>

Tier 3 — Now and then

These features are useful once in a while, but you probably won't need them everyday.

1. Reimplement Ticket

• What it does: Pulls in new context/attachments since the last pass and implements small follow-up changes on an already-built ticket.
• When it's useful: (Implementation) After review feedback or new screenshots, when you need a targeted second pass rather than a fresh build.
• How to use it: /reimplement-ticket BAPI-123

2. Run Tests

• What it does: Runs the unit and E2E suites and autonomously triages/fixes failures (via the test-correction agent).
• When it's useful: (Implementation) After making changes, to confirm everything passes and auto-fix straightforward breakages.
• How to use it: /run-tests (--unit-only, --skip-e2e)

3. Plan Epic

• What it does: Decomposes a large epic into sub-tasks with a structured exploration doc for each.
• When it's useful: (Architecture | Refinement) When a feature is too big for one ticket and you need it broken down and scoped.
• How to use it: /plan-epic <epic> — "Decompose the epic 'migrate PayPal token storage off Custom Objects' into sub-tasks with an exploration doc for each."

4. Update Ticket

• What it does: Synthesizes a ticket's clarifying answers and critique into a rewritten description and pushes it to Jira.
• When it's useful: (Refinement) After review, to fold the resolved questions and fixes back into the ticket itself.
• How to use it: /update-ticket BAPI-123 (command only — does a full overwrite of the live Jira description; "update" as free text is both vague and hard to reverse).

5. Get Ticket

• What it does: Retrieves the full details of a Jira ticket (summary, status, description, etc.).
• When it's useful: (Refinement | Implementation) Any time you want the agent to read a ticket before acting on it.
• How to use it: ask your agent — "Pull up BAPI-123 and show me its description, status, and acceptance criteria."

6. Write Comment

• What it does: Posts a comment on a Jira ticket (markdown; long ones can attach as a file).
• When it's useful: (Refinement | Implementation) To leave context, status, or a decision trail on the ticket.
• How to use it: ask your agent — "Post a comment on BAPI-123: blocked on the expired Atlassian token — will retry after it's rotated."

7. Download / Upload Attachment

• What it does: Pulls files off a Jira ticket to disk, or attaches a local file to a ticket.
• When it's useful: (Refinement | Implementation) When a ticket has design files/logs you need locally, or you want to attach output back to it.
• How to use it: ask your agent — "Download the design mockups attached to BAPI-123 into my docs folder." / "Attach build-log.txt to BAPI-123."

8. Learn Repository

• What it does: Researches and documents the repo's architecture, testing, review, and correctness standards, then saves them to Bridge for future agents.
• When it's useful: (Setup/Learning) When onboarding a new repo, or after big changes, so Bridge's agents follow your conventions.
• How to use it: /learn-repository

9. Teach Bridge

• What it does: Takes a plain-English instruction, figures out which standards field it belongs to, and merges it in (admin only).
• When it's useful: (Setup/Learning) When you notice the agents missing a convention and want to correct it in one sentence.
• How to use it: /teach-bridge <teaching> — "Teach Bridge: always use data-testid selectors in E2E tests."

Operational commands

Workflow commands you'll reach for during implementation and CI, beyond the tiers above:

| Command | What it does | |---|---| | /code-ticket PROJ-123 | Download the implementation plan and questions, then execute the plan inline | | /commit-ticket PROJ-123 | Stage, commit, and push changes; transition Jira status; post a smoke-test comment | | /create-pr PROJ-123 | Commit staged changes and open a pull request | | /check-ci [PROJ-123] | Monitor CI checks for the current branch, triage failures, apply fixes, and report results | | /parse-repository | Queue a background job to index the repository for Bridge AI agents | | /check-parse-status | Check whether a background repository parse job is still running | | /scan-tickets | Sync recently-updated Jira tickets and backfill workflow timestamps |

Commands are designed for Claude Code. Other editors may support slash commands differently — check your editor's documentation for how to invoke prompt files.

Extra Capabilities

Behind-the-scenes capabilities an agent gains from the MCP tools — mostly invoked automatically by the commands above, rarely requested by name:

• Ship a PR end-to-end: commit & push, open a pull request, transition the Jira status, and discover/poll CI checks (powers commit-ticket, create-pr, check-ci, implement-ticket).
• Architecture plan for a ticket (design-level guidance, separate from the implementation plan).
• Index the codebase so Bridge's agents can reason about it: queue/parse the repo, check parse status, regenerate the directory map.
• Read & tune project config/standards: list/read/update config fields, fetch project standards, and the per-topic learn-* commands that populate them.
• Ticket lifecycle bookkeeping: track tickets and backfill workflow-state timestamps (scan-tickets), search across tickets, read comments, list attachments.
• Pipeline machinery: list/inspect pipeline recipes and run/resume/list/delete pipeline runs (the engine under the orchestration commands).
• Decision page generation for capturing human review decisions as structured data.
• Connectivity & identity checks: ping Bridge, check your role, resolve the local docs directory.
• 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.

For a step-by-step OCAPI client setup guide (including the Business Manager permissions grant), see docs/install/sfcc-integration.md.

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).

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:

{
  "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:

"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.

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, 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)

• 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_attributes_get — fetch attribute definitions for a known custom object type. OCAPI cannot enumerate custom object types, so object_type must already be known.
• custom_object_definition_attribute_search — search attribute definitions within a known custom object type. Read-only — creating a custom object type isn't possible via OCAPI; that's a future v2 metadata-import capability.
• custom_object_definition_attribute_create — write (sandbox only): create an attribute definition on a known custom object type via PUT /custom_object_definitions/{type}/attribute_definitions/{id}. TYPE creation is never attempted (the type must pre-exist). Echoes paste-ready OCAPI grant JSON on 403.
• custom_object_definition_attribute_update — write (sandbox only): update an attribute definition via an ETag-conditional PATCH …/attribute_definitions/{id}; surfaces 409/412 conflicts and echoes grant JSON on 403.

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.
• 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 for when to use start-tickets; this section is the full CLI reference.

start-tickets

Spawns one Worktrunk worktree + selected-agent session per Jira ticket and backs the /start-tickets slash command. The agent defaults to Claude Code (claude) and is configurable via --agent. For existing ticket keys, /review-and-start (see Usage Documentation → Review and Start) is the recommended enriched front door over this CLI's --workflow review-and-implement seam; using the CLI directly (below) remains the advanced/lower-level path.

npx -y @bridge_gpt/mcp-server start-tickets [flags] KEY [KEY ...]

| Flag | Default | Meaning | |---|---|---| | --agent claude\|cursor-agent | claude | Agent command to launch in each worktree | | --workflow implement\|review-and-implement | implement | Slash command each spawned worktree runs. implement is byte-identical to today's /implement-ticket <KEY> [--auto]. review-and-implement spawns /review-and-implement <KEY> [--auto] [--rounds=<n>], which runs /review-ticket then, after a per-ticket halt gate, /implement-ticket in the same session. --auto applies to the selected workflow as a whole. | | --rounds 1\|2 | unset | Review round count forwarded to the review phase. Review-only — valid only with --workflow review-and-implement. | | --terminal terminal\|iterm | auto-detect via $TERM_PROGRAM | Override the macOS terminal app (honored on macOS only) | | --dry-run | off | Print intended actions; create no worktrees, open no tabs (any OS) | | --branch KEY=BRANCH | feature/<KEY> | Use a custom branch for that ticket (repeatable) | | --base-branch <BRANCH> | main | Cut new worktrees from <BRANCH> and refresh origin/<BRANCH> instead of main | | --no-refresh-main | off (the configured base branch is refreshed) | Skip refresh of the configured base branch (default main). Historical flag name preserved for backward compatibility — despite the name, it now skips refresh of whatever --base-branch resolves to. | | --max-parallel N | 3 | Max worktrees created concurrently | | --conductor | off | Opt into the Conductor system (per-worker BAPI_CONDUCTOR_* env + Claude hook injection, a supervisor peer tab, and the check_messages message-relay prompt). Default off — a plain run spawns cd <worktree> && <agent> '/implement-ticket <KEY>'. | | -h, --help | — | Show usage |

Each KEY must match [A-Z]+-[0-9]+ (e.g., BAPI-248). The CLI creates/switches each worktree up front (throttled by --max-parallel), then opens one tab/session per successful worktree running the selected agent's '/implement-ticket <KEY>' — claude '/implement-ticket <KEY>' by default, or cursor-agent '/implement-ticket <KEY>' with --agent cursor-agent. The /implement-ticket <KEY> prompt is unchanged for both agents. To launch Cursor Agent instead of Claude Code:

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 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.

• macOS — opens a Terminal.app or iTerm tab via osascript.
• Windows — creates worktrees with git-wt (Worktrunk's winget alias) and opens a tab via Windows Terminal (wt.exe new-tab), falling back to Start-Process powershell.exe when Windows Terminal is absent. Requires Git for Windows / Git Bash (Worktrunk runs its pre-start / post-start hooks via Git Bash). The Worktrunk binary (git-wt) and the tab launcher (wt.exe) are resolved independently and never conflated.
• Linux — creates one detached tmux session per ticket (pane kept open after the agent exits); attach with tmux attach -t <session>. A missing tmux produces a clear, actionable error.

Per-OS prerequisites: macOS wt, git, osascript; Windows git-wt, Git for Windows / Git Bash, Windows Terminal or PowerShell; Linux wt, git, tmux. Set BAPI_WORKTRUNK_BIN to override the Worktrunk executable name/path for nonstandard installs (doctor honors it too). The read-only doctor subcommand (below) additionally surfaces a missing uv — Worktrunk's pre-start hook runs uv, but live preflight does not check it — and the selected agent's command; run doctor --agent cursor-agent to also check cursor-agent (it prints cursor-agent login as an informational auth reminder).

doctor

The package also ships a strictly read-only doctor subcommand that diagnoses the start-tickets prerequisites for the current OS without changing anything:

npx -y @bridge_gpt/mcp-server doctor [--agent <name>]

It is read-only: it never installs anything, modifies your system, adds an npm postinstall, spawns a terminal, or starts the MCP server, and there is no --fix. For each prerequisite it prints found/missing and, when missing, the exact per-OS install command as a manual instruction you run yourself. The checked set is the start-tickets preflight prerequisites plus uv plus the selected agent's command (claude by default, or cursor-agent with --agent cursor-agent). The Worktrunk binary is probed via the resolved name (honoring BAPI_WORKTRUNK_BIN), not a hard-coded one. Exit code: 0 when all required prerequisites are present, non-zero when any is missing or the platform is unsupported. A failing start-tickets preflight now hints you to run doctor for an actionable diagnostics report.

setup-epic

Bootstraps an Epic Conductor v2 run in one command — creates the epic run, stores the plan DAG, and approves it:

npx -y @bridge_gpt/mcp-server setup-epic --epic-key <KEY> --plan-file <path-to-epic-plan.dag.json>

The plan sidecar is produced by the decompose-epic pipeline step. setup-epic validates it locally (unique ticket keys, resolvable dependency references, acyclicity) before sending anything, so a malformed plan fails legibly instead of as a bare HTTP 400. It is idempotent: re-running it on an epic that already has a live run reuses that run rather than minting a second one. --dry-run validates and previews the calls without mutating anything; --json emits a single machine-readable result object.

Once the plan is approved, the server-side reconciler picks the run up within ~30s. To execute claimed jobs on your machine, run executor:

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.

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.

Custom Pipelines

You can create your own pipelines by adding JSON files to .bridge/pipelines/. Running --init scaffolds this directory with a README.md and an example pipeline to get you started.

The easiest way to write a custom pipeline is to describe what you want to automate to your AI coding agent and have it draft the JSON for you. The schema is straightforward, and agents like Claude Code understand it well — just describe the steps you want, and the agent will produce a working pipeline file.

What you can build:

• Any sequence of Bridge MCP tool calls and free-form agent tasks
• Parameterized workflows using variables (e.g., {ticket_key})
• Approval gates that pause for user confirmation before sensitive steps
• Per-step error handling — halt immediately or warn and continue

Ideas for custom pipelines:

• A standup pipeline that fetches your open tickets and summarizes their status
• A ticket triage pipeline that runs critiques on a batch of new tickets
• A pre-merge checklist that runs tests, checks linting, and posts a summary comment

Step types:

| Type | What it does | |---|---| | mcp_call | Calls an MCP tool with the given params | | agent_task | Gives the AI a free-form instruction (inline or from a file in .bridge/instructions/) |

Variables are declared in the variables array and referenced as {variable_name} in params and instructions. Each step supports on_error: "halt" (default) or "warn_and_continue", and requires_approval: true to pause before execution.

System variables:

Two variables are automatically available in every pipeline without declaring them:

| Variable | What it does | |---|---| | {provider} | Routes AI generation to a specific LLM provider (openai, anthropic, or gemini). Pass it through to any request_* tool param to control which provider handles that step. Omit it (or leave it empty) to use the project default. | | {second_opinion} | Runs AI generation through a different provider than the default, acting as a cross-check. Set to "auto" to let Bridge pick the second provider automatically. When set, it takes precedence over {provider}. Use this when you want two independent AI perspectives on the same task — for example, running clarifying questions and a critique twice (once with each provider) produces better results than a single pass. |

See .bridge/pipelines/README.md for the full schema reference.

If a custom pipeline has the same key as a built-in pipeline, the custom version takes precedence (a warning is logged at startup).

Environment Variables

| Variable | Required | Default | Description | |---|---|---|---| | BAPI_BASE_URL | Yes | https://bridgegpt-api.com | Bridge API base URL | | BAPI_REPO_NAME | Yes | (none) | Jira project/repository identifier configured in Bridge API | | BAPI_API_KEY | Yes | (none) | API key obtained from the Bridge API setup UI | | BAPI_PROJECT_ROOT | No | (auto-set by --init) | Absolute path to project root. Anchors BAPI_DOCS_DIR and BAPI_PIPELINES_DIR resolution | | BAPI_DOCS_DIR | No | docs/tmp | Local directory for saving plans, critiques, and research reports | | BAPI_PIPELINES_DIR | No | .bridge/pipelines | Directory for user-defined custom pipeline JSON files | | 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 | | CURSOR_API_KEY | No | (none) | API key used to authenticate cursor-agent when launching start-tickets/scheduled runs with --agent cursor-agent. Not needed for the default Claude Code agent | | 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; 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

When start-tickets creates a git worktree, it provisions a Bridge API MCP registration into that worktree so Claude Code (.mcp.json) and Cursor (.cursor/mcp.json) can reach the server immediately. These registrations are secret-free: they contain no env block and no API key. Instead they point at an internal subcommand of the published single CLI bin, mcp-invoke:

npx -y @bridge_gpt/mcp-server@<VERSION> mcp-invoke --target bapi --project-root <ABS_WORKTREE_PATH>

mcp-invoke is not a separate binary — it is a positional subcommand of bridge-api-mcp-server. It resolves the repo identity from the absolute --project-root (the committed .bridge/config manifest, falling back to the git common dir), resolves credentials from the home-directory credential store, and then spawns the real MCP server with that environment.

Credential store

Credentials live outside the repository, keyed by bapi:<repo_name>:

{
  "bapi:<repo_name>": {
    "BAPI_API_KEY": "..."
  }
}

Resolution order:

1. BAPI_API_KEY in the parent environment (overrides the file entirely).
2. $XDG_CONFIG_HOME/bridge/credentials.json, else ~/.config/bridge/credentials.json.
3. ~/.bridge/credentials.json (only when the primary path is absent).

On POSIX systems, lock the file down so only you can read it:

chmod 600 ~/.config/bridge/credentials.json

mcp-invoke warns (but continues) if the file is group/world-readable, and it never creates or initializes the credential file for you.

Populating the credential store

The same store also backs the shell-spawned start-tickets CLI (its difficulty→model routing runs in a Bash process that cannot see an env block in .mcp.json / .cursor/mcp.json), so the store must hold the key for routing to work. Two supported paths write it for you:

• Install-time upsert. /install-bridge's final stage persists the validated routing credential into ~/.config/bridge/credentials.json (target bapi:<repo>) via the persist_routing_credential MCP tool — the tool resolves the key inside the MCP process and writes the store, so no secret crosses the wire.

• One-shot migration. If a key currently lives only in .mcp.json / .cursor/mcp.json, migrate it into the user-scoped store with the consent-gated command (a compatibility aid, not a live fallback):

  npx -y @bridge_gpt/mcp-server credentials migrate-agent-config [--write-credentials]

  Run it without --write-credentials to preview; add the flag to write the store.

Reference

The full surface, for when you need the complete enumeration. Day-to-day, use Usage Documentation instead — you don't call MCP tools directly; you ask your AI assistant to perform a task, or compose tools into a pipeline.

MCP tools

The server exposes 59 documented tools (enumerated below). What's actually registered in a session depends on BRIDGE_MCP_PROFILE: the default core profile loads a trimmed subset, and the conductor/pipeline-authoring/SFCC tools are added only under their respective profiles (see Environment Variables). 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 — 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, visual_diff (deterministic pixel diff of a rendered URL vs a design comp)
• 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, config_field (operations: get, update, list)

Bundled pipelines

Pipelines are declarative, multi-step workflows your AI agent executes step-by-step — each a JSON recipe chaining MCP tool calls and free-form agent tasks, with variable substitution, per-step error handling, and optional approval gates. You can also write your own (see Custom Pipelines).

| Pipeline | Description | Invoke with | |---|---|---| | implement-ticket | Generate a plan, execute the implementation, commit, open a PR, and monitor CI | /implement-ticket PROJ-123 | | review-ticket | Full ticket quality review: clarifying questions + critique plus an automatic second-opinion pass, then evaluation and decision capture. The backend owns round orchestration; pass --rounds=1 for a single-pass review or --rounds=2 to force the full second-opinion review, or omit --rounds to let the backend decide adaptively. | /review-ticket PROJ-123 | | idea-to-ticket | Turn an idea into a Jira Task/Spike (or Epic + children) with research, dedup, and critique | /idea-to-ticket "<idea>" | | plan-epic | Decompose an epic into sub-tasks with a structured exploration doc for each | /plan-epic "<epic>" | | full-automation | Chain: idea → ticket(s) → review each → spawn worktrees to implement | /full-automation "<idea>" | | pr-ticket | Commit changes and open a pull request | /create-pr PROJ-123 | | check-ci-ticket | Commit, open a PR, then monitor CI checks until they pass or fail | /check-ci PROJ-123 | | learn-repository | Analyze codebase architecture, testing, review, and documentation standards, then upload to Bridge | /learn-repository |

Pipeline response envelope

run_pipeline, resume_pipeline, and list_pipeline_runs share a unified envelope keyed on status:

• completed — terminal success; results holds per-step output.
• needs_agent_task — the orchestrator paused. Read instruction, perform the task, then call resume_pipeline with pipeline_run_id and a string agent_result.
• failed — terminal failure. error_code is one of VALIDATION, NOT_FOUND, EXPIRED, REPO_MISMATCH, TOOL_ERROR.

Paused runs auto-expire after an idle TTL (default 24 hours; override with ttl_seconds). The TTL is reset on every state transition. List output is metadata-only — it never includes resolved recipes, params, instructions, results, or agent outputs.