@bridge_gpt/mcp-server 0.1.6 → 0.1.8

package/README.md

@@ -2,30 +2,39 @@
 
 MCP server for [Bridge API](https://bridgegpt-api.com) — exposes Jira integration endpoints as MCP tools for AI coding agents. Works with Claude Code, VS Code/Copilot, Cursor, Windsurf, and OpenAI Codex.
 
-## Environment Variables
+## Getting Started
 
-| 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. Set automatically by --init. |
-| `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 |
-
-## Configuration
+### 1. Install the Package
 
-### Claude Code (CLI)
+From your **project root**, install the MCP server and scaffold slash commands:
 
 ```bash
-claude mcp add bridge-api -- npx -y @bridge_gpt/mcp-server \
-  --env BAPI_BASE_URL=https://bridgegpt-api.com \
-  --env BAPI_REPO_NAME=your-repo \
-  --env BAPI_API_KEY=your-api-key \
-  --env BAPI_DOCS_DIR=docs/tmp
+npm i @bridge_gpt/mcp-server
+npx @bridge_gpt/mcp-server --init
 ```
 
-### Claude Code (.mcp.json)
+`--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](https://bridgegpt-api.com) 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:
+
+<details>
+<summary><strong>Claude Code (.mcp.json)</strong></summary>
 
 ```json
 {
@@ -44,7 +53,19 @@ claude mcp add bridge-api -- npx -y @bridge_gpt/mcp-server \
 }
 ```
 
-### VS Code / Copilot (.vscode/mcp.json)
+Or via CLI:
+
+```bash
+claude mcp add bridge-api -- npx -y @bridge_gpt/mcp-server \
+  --env BAPI_BASE_URL=https://bridgegpt-api.com \
+  --env BAPI_REPO_NAME=your-repo \
+  --env BAPI_API_KEY=your-api-key \
+  --env BAPI_DOCS_DIR=docs/tmp
+```
+</details>
+
+<details>
+<summary><strong>VS Code / Copilot (.vscode/mcp.json)</strong></summary>
 
 ```json
 {
@@ -62,8 +83,10 @@ claude mcp add bridge-api -- npx -y @bridge_gpt/mcp-server \
   }
 }
 ```
+</details>
 
-### Cursor (.cursor/mcp.json — project-local)
+<details>
+<summary><strong>Cursor (.cursor/mcp.json)</strong></summary>
 
 ```json
 {
@@ -82,11 +105,13 @@ claude mcp add bridge-api -- npx -y @bridge_gpt/mcp-server \
 }
 ```
 
-> **Global fallback:** If project-local config is not supported in your Cursor version, use `~/.cursor/config/mcp.json` instead.
+> If project-local config is not supported in your Cursor version, use `~/.cursor/config/mcp.json` instead.
+</details>
 
-### Windsurf (~/.codeium/windsurf/mcp_config.json)
+<details>
+<summary><strong>Windsurf (~/.codeium/windsurf/mcp_config.json)</strong></summary>
 
-> **Note:** Windsurf only supports global MCP configuration. `--init` detects Windsurf projects and outputs a ready-to-paste config snippet to the console.
+Windsurf only supports global MCP configuration.
 
 ```json
 {
@@ -104,8 +129,10 @@ claude mcp add bridge-api -- npx -y @bridge_gpt/mcp-server \
   }
 }
 ```
+</details>
 
-### OpenAI Codex (~/.codex/config.toml)
+<details>
+<summary><strong>OpenAI Codex (~/.codex/config.toml)</strong></summary>
 
 ```toml
 [mcp_servers.bridge-api]
@@ -119,25 +146,27 @@ BAPI_API_KEY = "your-api-key"
 BAPI_DOCS_DIR = "docs/tmp"
 ```
 
-## Slash Commands
+> Codex users: set `BAPI_PROJECT_ROOT` manually in your config (see Environment Variables below).
+</details>
 
-Bridge API ships pre-built slash commands for Claude Code and Cursor. To scaffold them into your project:
+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.
 
-```bash
-npx @bridge_gpt/mcp-server --init
-```
+### 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.
 
-Run from your project root. `--init` performs the following:
+You only need to do this once per project — the learned standards persist for all team members.
 
-1. **IDE detection** — checks for `.vscode/`, `.cursor/`, `.windsurf/`, and `.windsurfrules` to determine which IDEs are in use.
-2. **MCP config files** — creates or updates `.mcp.json`, `.vscode/mcp.json`, and `.cursor/mcp.json` with sensible defaults and placeholder values (`YOUR_API_KEY`, `YOUR_REPO_NAME`). Only creates IDE-specific configs when that IDE is detected. Existing configs are preserved — only the `bridge-api` entry is added or updated.
-3. **Gitignore** — newly created config files are automatically added to `.gitignore` to prevent committing API key placeholders.
-4. **Slash commands** — writes command files to `.claude/commands/` (always) and `.cursor/commands/` (when Cursor is detected).
-5. **Windsurf** — since Windsurf only supports global config, outputs a ready-to-paste JSON snippet to the console.
+## Commands & Pipelines
 
-Re-run after upgrading the package to get updated commands. Replace placeholder values (`YOUR_API_KEY`, `YOUR_REPO_NAME`) with your actual credentials from the Bridge API setup UI.
+Slash commands are available after running `--init`. Invoke them from your AI assistant's chat.
 
-> **Codex users:** `--init` does not modify `~/.codex/config.toml`. Set `BAPI_PROJECT_ROOT` manually in your Codex MCP config.
+| Command | Description |
+|---|---|
+| `/explore-ticket` | Free-form codebase exploration — searches code, runs research, writes analysis with implementation options |
+| `/review-ticket PROJ-123` | Two-round ticket quality review with clarifying questions and critiques from multiple LLM providers |
+| `/implement-ticket PROJ-123` | End-to-end implementation — generates a plan, executes it, commits, opens a PR, monitors CI |
+| `/learn-repository` | Teaches Bridge API about your codebase by analyzing architecture, testing, and review patterns |
 
 ## Available Tools
 
@@ -183,34 +212,26 @@ Re-run after upgrading the package to get updated commands. Replace placeholder
 | `list_pipelines` | List available pipeline recipes |
 | `get_pipeline_recipe` | Retrieve a resolved pipeline recipe |
 
-### Pipeline Recipes
-
-The `list_pipelines` and `get_pipeline_recipe` tools provide access to declarative multi-step workflow recipes (e.g., `implement-ticket`, `review-ticket`, `learn-repository`). These are resolved locally from bundled definitions — no additional server calls are needed.
-
-Example pipeline JSON files are included in the published package under `pipelines/` for reference when authoring custom pipelines.
-
-### Custom Pipelines
+## Custom Pipelines
 
-You can create your own pipelines by placing JSON files in `.bridge/pipelines/` (or the directory specified by `BAPI_PIPELINES_DIR`). Custom pipelines are loaded at server startup and appear alongside bundled pipelines in `list_pipelines` with `source: "user"`.
-
-**Getting started:**
+You can create your own pipelines by placing JSON files in `.bridge/pipelines/` (or the directory specified by `BAPI_PIPELINES_DIR`). Custom pipelines are loaded at server startup and appear alongside bundled pipelines in `list_pipelines`.
 
 1. Run `npx @bridge_gpt/mcp-server --init` to scaffold the directory structure with a README and example pipeline.
 2. Add pipeline JSON files to `.bridge/pipelines/`.
 3. Optionally add instruction markdown files to `.bridge/instructions/` and reference them via `instruction_file` in your pipeline steps.
 
-**Pipeline JSON schema:**
-
-- `name` (string, required) — display name
-- `description` (string, optional) — shown in `list_pipelines`
-- `variables` (string[], optional) — variable names for `{variable_name}` substitution
-- `steps` (array, required) — ordered list of `mcp_call` or `agent_task` steps
-
-Each step supports `on_error` (`"halt"` or `"warn_and_continue"`) and `requires_approval` (boolean). See the generated `README.md` in `.bridge/pipelines/` for full documentation.
-
 If a custom pipeline has the same key as a bundled pipeline, it overrides the bundled one (a warning is logged at startup).
 
-> **Note:** The `instructions/` directory is always resolved as a sibling of the pipelines directory (i.e. one level up from `BAPI_PIPELINES_DIR`). With the default `.bridge/pipelines`, instructions are read from `.bridge/instructions/`.
+## 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 |
 
 ## Publishing
 
@@ -218,7 +239,7 @@ This package uses tag-based publishing. To release a new version:
 
 ```bash
 cd mcp_server
-npm version patch    # creates tag mcp-server/v0.1.1
+npm version patch    # creates tag mcp-server/v0.1.x
 git push --follow-tags
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bridge_gpt/mcp-server",
-  "version": "0.1.6",
+  "version": "0.1.8",
   "description": "Bridge API MCP server — exposes Jira endpoints as MCP tools for Claude Code agents",
   "license": "MIT",
   "type": "module",