@bridge_gpt/mcp-server 0.2.9 → 0.2.12

package/README.md

@@ -6,7 +6,58 @@ MCP server for [Bridge API](https://bridgegpt-api.com) — exposes Jira integrat
 
 ## Getting Started
 
-### 1. Install the Package
+### Quick start (one command)
+
+From your **project root**, run:
+
+```bash
+npx -y @bridge_gpt/mcp-server@latest install-bridge
+```
+
+`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 the
+   remaining config fields from your codebase) and then `/learn-repository`.
+
+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. 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.
+
+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.
+- `--force` — overwrite an existing real `BAPI_API_KEY` in a host config without
+  prompting (re-running is otherwise non-destructive).
+- `--agent claude|cursor-agent` — which agent to launch for the agentic remainder
+  (default `claude`).
+
+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:
 
@@ -23,7 +74,7 @@ npx -y @bridge_gpt/mcp-server --init
 
 Re-run `--init` after upgrading the package to get updated commands.
 
-### 2. Generate an API Key
+#### 2. Generate an API Key
 
 1. Log in to [Bridge API](https://bridgegpt-api.com) and navigate to your project's **Security** page
 2. Click **Create New Key**
@@ -31,7 +82,7 @@ Re-run `--init` after upgrading the package to get updated commands.
 4. Click **Create Key**
 5. **Copy the key immediately** — it will not be shown again
 
-### 3. Configure the MCP Server
+#### 3. Configure the MCP Server
 
 Add the following to your editor's MCP configuration file, pasting in the API key from step 2:
 
@@ -145,7 +196,7 @@ BAPI_DOCS_DIR = "docs/tmp"
 
 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
+#### 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.
 
@@ -540,6 +591,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. |
 
 ## Worktree credentials and the `mcp-invoke` shim
 
@@ -614,18 +666,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