@j0hanz/code-review-analyst-mcp 1.1.0 → 1.2.0

package/README.md

@@ -6,23 +6,22 @@
 
 [![Install in VS Code](https://img.shields.io/badge/VS_Code-Install_Server-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect/mcp/install?name=Code+Review+Analyst&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40j0hanz%2Fcode-review-analyst-mcp%40latest%22%5D%7D) [![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install_Server-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect/mcp/install?name=Code+Review+Analyst&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40j0hanz%2Fcode-review-analyst-mcp%40latest%22%5D%7D&quality=insiders) [![Install in Visual Studio](https://img.shields.io/badge/Visual_Studio-Install_Server-C16FDE?logo=visualstudio&logoColor=white)](https://vs-open.link/mcp-install?%7B%22name%22%3A%22code-review-analyst%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40j0hanz%2Fcode-review-analyst-mcp%40latest%22%5D%7D)
 
-[![Install in Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en/install-mcp?name=Code+Review+Analyst&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBqMGhhbnovY29kZS1yZXZpZXctYW5hbHlzdC1tY3BAbGF0ZXN0Il19) [![Install in Goose](https://block.github.io/goose/img/extension-install-dark.svg)](https://block.github.io/goose/extension?cmd=npx&arg=-y%20%40j0hanz%2Fcode-review-analyst-mcp%40latest&id=code-review-analyst&name=Code%20Review%20Analyst&description=Gemini-powered%20MCP%20server%20for%20code%20review%20analysis.)
+[![Install in Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en/install-mcp?name=code-review-analyst&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBqMGhhbnovY29kZS1yZXZpZXctYW5hbHlzdC1tY3BAbGF0ZXN0Il19)
 
 Gemini-powered MCP server for pull request analysis with structured outputs for findings, release risk, and focused patch suggestions.
 
 ## Overview
 
-This server runs over **stdio transport** and exposes three review-focused tools: `review_diff`, `risk_score`, and `suggest_patch`. It also publishes an `internal://instructions` resource and a `get-help` prompt for in-client guidance.
+This server accepts unified diffs and returns structured JSON results — findings with severity, impact categories, merge risk, test plans, and verbatim search/replace fixes. It uses Gemini Thinking models (Flash for fast tools, Pro for deep analysis) and runs over **stdio transport**.
 
 ## Key Features
 
-- Structured review analysis with strict JSON output envelopes (`ok`, `result`, `error`).
-- Three complementary workflows: full review, release risk scoring, and targeted patch generation.
-- Runtime diff-size budget guard (`MAX_DIFF_CHARS`, default `120000`).
-- Optional task execution support (`execution.taskSupport: "optional"`) with in-memory task store.
-- Progress notifications when clients provide `_meta.progressToken`.
-- Shared Gemini adapter with timeout, retries, safety thresholds, and structured observability logs to `stderr`.
-- Docker image available via GitHub Container Registry.
+- **Impact Analysis** — Objective severity scoring, breaking change detection, and rollback complexity assessment.
+- **Review Summary** — Concise PR digest with merge recommendation and change statistics.
+- **Deep Code Inspection** — Pro model with 16K thinking budget for context-aware analysis using full file contents.
+- **Search & Replace Fixes** — Verbatim, copy-paste-ready code fixes tied to specific findings.
+- **Test Plan Generation** — Systematic test case generation with priority ranking and pseudocode.
+- **Async Task Support** — All tools support MCP task lifecycle with progress notifications.
 
 ## Requirements
 
@@ -32,8 +31,6 @@ This server runs over **stdio transport** and exposes three review-focused tools
 
 ## Quick Start
 
-Standard config for most MCP clients:
-
 ```json
 {
   "mcpServers": {
@@ -48,18 +45,14 @@ Standard config for most MCP clients:
 }
 ```
 
-> [!TIP]
-> For local development, build and run directly via `node dist/index.js` after `npm run build`.
-
 ## Client Configuration
 
 <details>
-<summary><b>Install in VS Code</b></summary>
+<summary><b>VS Code / VS Code Insiders</b></summary>
 
-[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install_Server-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect/mcp/install?name=Code+Review+Analyst&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40j0hanz%2Fcode-review-analyst-mcp%40latest%22%5D%7D)
-[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install_Server-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect/mcp/install?name=Code+Review+Analyst&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40j0hanz%2Fcode-review-analyst-mcp%40latest%22%5D%7D&quality=insiders)
+[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install_Server-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect/mcp/install?name=Code+Review+Analyst&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40j0hanz%2Fcode-review-analyst-mcp%40latest%22%5D%7D) [![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install_Server-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect/mcp/install?name=Code+Review+Analyst&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40j0hanz%2Fcode-review-analyst-mcp%40latest%22%5D%7D&quality=insiders)
 
-`.vscode/mcp.json`
+Add to `.vscode/mcp.json`:
 
 ```json
 {
@@ -75,22 +68,20 @@ Standard config for most MCP clients:
 }
 ```
 
-CLI install:
+Or via CLI:
 
 ```bash
 code --add-mcp '{"name":"code-review-analyst","command":"npx","args":["-y","@j0hanz/code-review-analyst-mcp@latest"]}'
 ```
 
-For more info, see [VS Code MCP docs](https://code.visualstudio.com/docs/copilot/customization/mcp-servers).
-
 </details>
 
 <details>
-<summary><b>Install in Cursor</b></summary>
+<summary><b>Cursor</b></summary>
 
-[![Install in Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en/install-mcp?name=Code+Review+Analyst&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBqMGhhbnovY29kZS1yZXZpZXctYW5hbHlzdC1tY3BAbGF0ZXN0Il19)
+[![Install in Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en/install-mcp?name=code-review-analyst&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBqMGhhbnovY29kZS1yZXZpZXctYW5hbHlzdC1tY3BAbGF0ZXN0Il19)
 
-`~/.cursor/mcp.json`
+Add to `~/.cursor/mcp.json`:
 
 ```json
 {
@@ -106,14 +97,21 @@ For more info, see [VS Code MCP docs](https://code.visualstudio.com/docs/copilot
 }
 ```
 
-For more info, see [Cursor MCP docs](https://cursor.com/docs/context/mcp).
+</details>
+
+<details>
+<summary><b>Visual Studio</b></summary>
+
+[![Install in Visual Studio](https://img.shields.io/badge/Visual_Studio-Install_Server-C16FDE?logo=visualstudio&logoColor=white)](https://vs-open.link/mcp-install?%7B%22name%22%3A%22code-review-analyst%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40j0hanz%2Fcode-review-analyst-mcp%40latest%22%5D%7D)
+
+For more info, see [Visual Studio MCP docs](https://learn.microsoft.com/en-us/visualstudio/ide/mcp-servers).
 
 </details>
 
 <details>
-<summary><b>Install in Claude Desktop</b></summary>
+<summary><b>Claude Desktop</b></summary>
 
-`claude_desktop_config.json`
+Add to `claude_desktop_config.json`:
 
 ```json
 {
@@ -129,25 +127,25 @@ For more info, see [Cursor MCP docs](https://cursor.com/docs/context/mcp).
 }
 ```
 
-For more info, see [Claude Desktop MCP docs](https://modelcontextprotocol.io/docs/develop/connect-local-servers).
+For more info, see [Claude Desktop MCP docs](https://modelcontextprotocol.io/quickstart/user).
 
 </details>
 
 <details>
-<summary><b>Install in Claude Code</b></summary>
+<summary><b>Claude Code</b></summary>
 
 ```bash
 claude mcp add code-review-analyst -- npx -y @j0hanz/code-review-analyst-mcp@latest
 ```
 
-For more info, see [Claude Code MCP docs](https://docs.anthropic.com/en/docs/claude-code/mcp).
+For more info, see [Claude Code MCP docs](https://docs.anthropic.com/en/docs/agents-and-tools/claude-code/tutorials#set-up-model-context-protocol-mcp).
 
 </details>
 
 <details>
-<summary><b>Install in Windsurf</b></summary>
+<summary><b>Windsurf</b></summary>
 
-MCP config:
+Add to MCP config:
 
 ```json
 {
@@ -163,25 +161,25 @@ MCP config:
 }
 ```
 
-For more info, see [Windsurf MCP docs](https://docs.windsurf.com/windsurf/cascade/mcp).
+For more info, see [Windsurf MCP docs](https://docs.windsurf.com/windsurf/mcp).
 
 </details>
 
 <details>
-<summary><b>Install in Amp</b></summary>
+<summary><b>Amp</b></summary>
 
 ```bash
 amp mcp add code-review-analyst -- npx -y @j0hanz/code-review-analyst-mcp@latest
 ```
 
-For more info, see [Amp MCP docs](https://ampcode.com/manual).
+For more info, see [Amp MCP docs](https://docs.amp.dev/mcp).
 
 </details>
 
 <details>
-<summary><b>Install in Cline</b></summary>
+<summary><b>Cline</b></summary>
 
-`cline_mcp_settings.json`
+Add to `cline_mcp_settings.json`:
 
 ```json
 {
@@ -197,32 +195,61 @@ For more info, see [Amp MCP docs](https://ampcode.com/manual).
 }
 ```
 
-For more info, see [Cline MCP docs](https://docs.cline.bot/mcp/adding-and-configuring-servers).
+For more info, see [Cline MCP docs](https://docs.cline.bot/mcp-servers/configuring-mcp-servers).
 
 </details>
 
 <details>
-<summary><b>Install in Zed</b></summary>
+<summary><b>Zed</b></summary>
 
-`settings.json`
+Add to Zed `settings.json`:
 
 ```json
 {
   "context_servers": {
     "code-review-analyst": {
-      "command": "npx",
-      "args": ["-y", "@j0hanz/code-review-analyst-mcp@latest"]
+      "command": {
+        "path": "npx",
+        "args": ["-y", "@j0hanz/code-review-analyst-mcp@latest"],
+        "env": {
+          "GEMINI_API_KEY": "YOUR_API_KEY"
+        }
+      }
     }
   }
 }
 ```
 
-For more info, see [Zed MCP docs](https://zed.dev/docs/ai/mcp).
+For more info, see [Zed MCP docs](https://zed.dev/docs/assistant/model-context-protocol).
 
 </details>
 
 <details>
-<summary><b>Install with Docker</b></summary>
+<summary><b>Augment</b></summary>
+
+Add to `settings.json`:
+
+```json
+{
+  "augment.advanced": {
+    "mcpServers": [
+      {
+        "name": "code-review-analyst",
+        "command": "npx",
+        "args": ["-y", "@j0hanz/code-review-analyst-mcp@latest"],
+        "env": {
+          "GEMINI_API_KEY": "YOUR_API_KEY"
+        }
+      }
+    ]
+  }
+}
+```
+
+</details>
+
+<details>
+<summary><b>Docker</b></summary>
 
 ```json
 {
@@ -234,7 +261,7 @@ For more info, see [Zed MCP docs](https://zed.dev/docs/ai/mcp).
         "-i",
         "--rm",
         "-e",
-        "GEMINI_API_KEY",
+        "GEMINI_API_KEY=YOUR_API_KEY",
         "ghcr.io/j0hanz/code-review-analyst-mcp:latest"
       ]
     }
@@ -242,212 +269,195 @@ For more info, see [Zed MCP docs](https://zed.dev/docs/ai/mcp).
 }
 ```
 
-> [!NOTE]
-> Set `GEMINI_API_KEY` in your shell environment before running. Docker passes it through via `-e GEMINI_API_KEY`.
+Or build locally:
+
+```bash
+docker build -t code-review-analyst-mcp .
+```
 
 </details>
 
-## MCP Surface
+## Tools
 
-### Tools
+### `analyze_pr_impact`
 
-#### `review_diff`
+Assess the impact and risk of a pull request diff using the Flash model.
 
-Analyze a unified diff and return structured findings, overall merge risk, and test recommendations.
+| Parameter    | Type     | Required | Description                              |
+| ------------ | -------- | -------- | ---------------------------------------- |
+| `diff`       | `string` | Yes      | Unified diff text.                       |
+| `repository` | `string` | Yes      | Repository identifier (e.g. `org/repo`). |
+| `language`   | `string` | No       | Primary language hint.                   |
 
-| Name          | Type       | Required | Default                                           | Description                                          |
-| ------------- | ---------- | -------- | ------------------------------------------------- | ---------------------------------------------------- |
-| `diff`        | `string`   | Yes      | —                                                 | Unified diff text (`10..400000` chars schema limit). |
-| `repository`  | `string`   | Yes      | —                                                 | Repository identifier (example: `org/repo`).         |
-| `language`    | `string`   | No       | `not specified`                                   | Primary language hint for analysis.                  |
-| `focusAreas`  | `string[]` | No       | `security, correctness, regressions, performance` | Optional review priorities (`1..12` items).          |
-| `maxFindings` | `integer`  | No       | `10`                                              | Max findings returned (`1..25`).                     |
+**Returns:** `severity` (low/medium/high/critical), `categories[]`, `breakingChanges[]`, `affectedAreas[]`, `rollbackComplexity`, `summary`.
 
-Returns (inside `result`):
+### `generate_review_summary`
 
-- `summary`, `overallRisk` (`low|medium|high`), `findings[]`, `testsNeeded[]`
+Summarize a pull request diff and assess high-level risk using the Flash model.
 
-Example:
+| Parameter    | Type     | Required | Description                              |
+| ------------ | -------- | -------- | ---------------------------------------- |
+| `diff`       | `string` | Yes      | Unified diff text.                       |
+| `repository` | `string` | Yes      | Repository identifier (e.g. `org/repo`). |
+| `language`   | `string` | No       | Primary language hint.                   |
 
-```json
-{
-  "ok": true,
-  "result": {
-    "summary": "One high-risk auth-path change without null guards.",
-    "overallRisk": "high",
-    "findings": [
-      {
-        "severity": "high",
-        "file": "src/auth.ts",
-        "line": 42,
-        "title": "Missing null check",
-        "explanation": "Null response can throw and break login.",
-        "recommendation": "Guard for null before property access."
-      }
-    ],
-    "testsNeeded": ["Add auth null-path regression test"]
-  }
-}
-```
-
-#### `risk_score`
+**Returns:** `summary`, `overallRisk` (low/medium/high), `keyChanges[]`, `recommendation`, `stats` (filesChanged, linesAdded, linesRemoved).
 
-Score deployment risk for a diff and explain the score drivers.
+### `inspect_code_quality`
 
-| Name                    | Type                          | Required | Default  | Description                                          |
-| ----------------------- | ----------------------------- | -------- | -------- | ---------------------------------------------------- |
-| `diff`                  | `string`                      | Yes      | —        | Unified diff text (`10..400000` chars schema limit). |
-| `deploymentCriticality` | `"low" \| "medium" \| "high"` | No       | `medium` | Sensitivity of target deployment.                    |
+Deep-dive code review with optional file context using the Pro model with thinking (16K token budget).
 
-Returns (inside `result`):
+| Parameter     | Type       | Required | Description                                         |
+| ------------- | ---------- | -------- | --------------------------------------------------- |
+| `diff`        | `string`   | Yes      | Unified diff text.                                  |
+| `repository`  | `string`   | Yes      | Repository identifier (e.g. `org/repo`).            |
+| `language`    | `string`   | No       | Primary language hint.                              |
+| `focusAreas`  | `string[]` | No       | Areas to inspect: security, correctness, etc.       |
+| `maxFindings` | `number`   | No       | Maximum findings to return (1-25).                  |
+| `files`       | `object[]` | No       | Full file contents (`path`, `content`) for context. |
 
-- `score` (`0..100`), `bucket` (`low|medium|high|critical`), `rationale[]`
+**Returns:** `summary`, `overallRisk` (low/medium/high/critical), `findings[]` (severity, file, line, title, explanation, recommendation), `testsNeeded[]`, `contextualInsights[]`.
 
-#### `suggest_patch`
+> [!NOTE]
+> Enforces `MAX_CONTEXT_CHARS` (default 500,000) on combined diff + files size. Expect 60-120s latency due to deep thinking.
 
-Generate a focused unified-diff patch for one selected finding.
+### `suggest_search_replace`
 
-| Name             | Type                                     | Required | Default    | Description                                      |
-| ---------------- | ---------------------------------------- | -------- | ---------- | ------------------------------------------------ |
-| `diff`           | `string`                                 | Yes      | —          | Unified diff text containing the issue context.  |
-| `findingTitle`   | `string`                                 | Yes      | —          | Short finding title (`3..160` chars).            |
-| `findingDetails` | `string`                                 | Yes      | —          | Detailed finding explanation (`10..3000` chars). |
-| `patchStyle`     | `"minimal" \| "balanced" \| "defensive"` | No       | `balanced` | Desired patch breadth.                           |
+Generate verbatim search-and-replace blocks to fix a specific finding using the Pro model with thinking.
 
-Returns (inside `result`):
+| Parameter        | Type     | Required | Description                              |
+| ---------------- | -------- | -------- | ---------------------------------------- |
+| `diff`           | `string` | Yes      | Unified diff that contains the issue.    |
+| `findingTitle`   | `string` | Yes      | Short title of the finding to fix.       |
+| `findingDetails` | `string` | Yes      | Detailed explanation of the bug or risk. |
 
-- `summary`, `patch` (unified diff text), `validationChecklist[]`
+**Returns:** `summary`, `blocks[]` (file, search, replace, explanation), `validationChecklist[]`.
 
-### Resources
+### `generate_test_plan`
 
-| URI                       | Name                  | MIME Type       | Description                                  |
-| ------------------------- | --------------------- | --------------- | -------------------------------------------- |
-| `internal://instructions` | `server-instructions` | `text/markdown` | In-repo usage guide for tools and workflows. |
+Create a test plan covering the changes in the diff using the Flash model with thinking (8K token budget).
 
-### Prompts
+| Parameter       | Type     | Required | Description                                 |
+| --------------- | -------- | -------- | ------------------------------------------- |
+| `diff`          | `string` | Yes      | Unified diff to generate tests for.         |
+| `repository`    | `string` | Yes      | Repository identifier (e.g. `org/repo`).    |
+| `language`      | `string` | No       | Primary language hint.                      |
+| `testFramework` | `string` | No       | Test framework (e.g. jest, vitest, pytest). |
+| `maxTestCases`  | `number` | No       | Maximum test cases to return (1-30).        |
 
-| Name       | Description                        | Arguments |
-| ---------- | ---------------------------------- | --------- |
-| `get-help` | Returns server usage instructions. | None      |
+**Returns:** `summary`, `testCases[]` (name, type, file, description, pseudoCode, priority), `coverageSummary`.
 
-### Tasks & Progress
+## Resources
 
-- Server declares `capabilities.tasks` with tool-call task support.
-- Each tool is registered with `execution.taskSupport: "optional"`.
-- Progress updates are emitted via `notifications/progress` when `_meta.progressToken` is provided.
-- Task storage uses in-memory task store (`InMemoryTaskStore`).
+| URI                       | Type            | Description                |
+| ------------------------- | --------------- | -------------------------- |
+| `internal://instructions` | `text/markdown` | Server usage instructions. |
 
-## Configuration
+## Prompts
 
-### Runtime Mode
+| Name           | Arguments           | Description                                         |
+| -------------- | ------------------- | --------------------------------------------------- |
+| `get-help`     | —                   | Return the server usage instructions.               |
+| `review-guide` | `tool`, `focusArea` | Guided workflow for a specific tool and focus area. |
 
-| Mode                     | Supported | Notes                               |
-| ------------------------ | --------- | ----------------------------------- |
-| `stdio`                  | Yes       | Active transport in `src/index.ts`. |
-| HTTP/SSE/Streamable HTTP | No        | Not implemented.                    |
+## Configuration
 
 ### CLI Arguments
 
-The server binary accepts optional command-line flags:
-
-| Option             | Short | Description                              | Env Override     |
-| ------------------ | ----- | ---------------------------------------- | ---------------- |
-| `--model`          | `-m`  | Override the Gemini model id at startup. | `GEMINI_MODEL`   |
-| `--max-diff-chars` | —     | Override the runtime diff-size budget.   | `MAX_DIFF_CHARS` |
-
-Example:
-
-```bash
-npx @j0hanz/code-review-analyst-mcp@latest --model gemini-2.5-pro --max-diff-chars 200000
-```
+| Option             | Description            | Env Var Equivalent |
+| ------------------ | ---------------------- | ------------------ |
+| `--model`, `-m`    | Override default model | `GEMINI_MODEL`     |
+| `--max-diff-chars` | Override max diff size | `MAX_DIFF_CHARS`   |
 
 ### Environment Variables
 
-| Variable                      | Description                                                                                         | Default            | Required                                    |
-| ----------------------------- | --------------------------------------------------------------------------------------------------- | ------------------ | ------------------------------------------- |
-| `GEMINI_API_KEY`              | Gemini API key (preferred).                                                                         | —                  | One of `GEMINI_API_KEY` or `GOOGLE_API_KEY` |
-| `GOOGLE_API_KEY`              | Alternate Gemini API key env.                                                                       | —                  | One of `GEMINI_API_KEY` or `GOOGLE_API_KEY` |
-| `GEMINI_MODEL`                | Gemini model id.                                                                                    | `gemini-2.5-flash` | No                                          |
-| `GEMINI_HARM_BLOCK_THRESHOLD` | Safety threshold (`BLOCK_NONE`, `BLOCK_ONLY_HIGH`, `BLOCK_MEDIUM_AND_ABOVE`, `BLOCK_LOW_AND_ABOVE`) | `BLOCK_NONE`       | No                                          |
-| `MAX_DIFF_CHARS`              | Runtime diff-size budget (chars).                                                                   | `120000`           | No                                          |
+| Variable                       | Description                                          | Default      | Required |
+| ------------------------------ | ---------------------------------------------------- | ------------ | -------- |
+| `GEMINI_API_KEY`               | Gemini API key                                       | —            | Yes      |
+| `GOOGLE_API_KEY`               | Alternative API key (if `GEMINI_API_KEY` not set)    | —            | No       |
+| `GEMINI_MODEL`                 | Override default model selection                     | —            | No       |
+| `GEMINI_HARM_BLOCK_THRESHOLD`  | Safety threshold (BLOCK_NONE, BLOCK_ONLY_HIGH, etc.) | `BLOCK_NONE` | No       |
+| `MAX_DIFF_CHARS`               | Max chars for diff input                             | `120000`     | No       |
+| `MAX_CONTEXT_CHARS`            | Max combined context for inspection                  | `500000`     | No       |
+| `MAX_CONCURRENT_CALLS`         | Max concurrent Gemini requests                       | `10`         | No       |
+| `MAX_CONCURRENT_CALLS_WAIT_MS` | Max wait time for a free Gemini slot                 | `2000`       | No       |
+| `MAX_CONCURRENT_CALLS_POLL_MS` | Poll interval while waiting for a free slot          | `25`         | No       |
 
-## Security
+### Models
 
-- Stdio transport avoids HTTP exposure in the current runtime path.
-- Runtime logs and warnings are written to `stderr`; no non-protocol output is written to `stdout`.
-- Input and output contracts use strict Zod schemas (`z.strictObject`) with explicit bounds.
-- Oversized diffs are rejected early with `E_INPUT_TOO_LARGE`.
-- Tool metadata marks calls as `readOnlyHint: true` and `openWorldHint: true` (external model call, no local state mutation).
+| Tool                      | Model              | Thinking Budget |
+| ------------------------- | ------------------ | --------------- |
+| `analyze_pr_impact`       | `gemini-2.5-flash` | —               |
+| `generate_review_summary` | `gemini-2.5-flash` | —               |
+| `inspect_code_quality`    | `gemini-2.5-pro`   | 16,384 tokens   |
+| `suggest_search_replace`  | `gemini-2.5-pro`   | 16,384 tokens   |
+| `generate_test_plan`      | `gemini-2.5-flash` | 8,192 tokens    |
 
-## Development
+## Workflows
 
-Install and run locally:
+### Quick PR Triage
 
-```bash
-npm install
-npm run build
-npm start
-```
+1. Call `analyze_pr_impact` to get severity and category breakdown.
+2. If low/medium — call `generate_review_summary` for a quick digest.
+3. If high/critical — proceed to deep inspection.
 
-Useful scripts:
+### Deep Code Inspection
 
-| Script       | Command                              | Purpose                                                                 |
-| ------------ | ------------------------------------ | ----------------------------------------------------------------------- |
-| `build`      | `node scripts/tasks.mjs build`       | Clean, compile, validate instructions, copy assets, set executable bit. |
-| `dev`        | `tsc --watch --preserveWatchOutput`  | TypeScript watch mode.                                                  |
-| `dev:run`    | `node --env-file=.env --watch dist/` | Run built server with watch and `.env`.                                 |
-| `test`       | `node scripts/tasks.mjs test`        | Full build + Node test runner.                                          |
-| `test:fast`  | `node --test --import tsx/esm ...`   | Fast test path on TS sources (no build step).                           |
-| `type-check` | `node scripts/tasks.mjs type-check`  | TypeScript no-emit checks.                                              |
-| `lint`       | `eslint .`                           | ESLint checks.                                                          |
-| `lint:fix`   | `eslint . --fix`                     | ESLint auto-fix.                                                        |
-| `format`     | `prettier --write .`                 | Prettier formatting.                                                    |
-| `inspector`  | `npm run build && npx ... inspector` | MCP Inspector for the stdio server.                                     |
+1. Call `inspect_code_quality` with the diff and critical files in `files[]`.
+2. Use `focusAreas` to target specific concerns (security, performance).
+3. Review `findings` and `contextualInsights`.
 
-> [!TIP]
-> Set `TASK_TIMEOUT_MS` (env var) to enforce a timeout on build/test script tasks in `scripts/tasks.mjs`.
-
-Debugging with MCP Inspector:
-
-```bash
-npx @modelcontextprotocol/inspector node dist/index.js
-```
+### Remediation & Testing
 
-### Docker
+1. For each finding, call `suggest_search_replace` with `findingTitle` and `findingDetails`.
+2. Call `generate_test_plan` to create a verification strategy.
+3. Apply fixes and implement tests.
 
-Build and run locally with Docker:
+## Development
 
 ```bash
-docker build -t code-review-analyst-mcp .
-docker run -i --rm -e GEMINI_API_KEY code-review-analyst-mcp
+npm ci            # Install dependencies
+npm run dev       # TypeScript watch mode
+npm run dev:run   # Run built server with .env and --watch
 ```
 
-Or use Docker Compose:
+| Script               | Command                             | Purpose                        |
+| -------------------- | ----------------------------------- | ------------------------------ |
+| `npm run build`      | `node scripts/tasks.mjs build`      | Clean, compile, validate, copy |
+| `npm test`           | `node scripts/tasks.mjs test`       | Build + run all tests          |
+| `npm run test:fast`  | `node --test --import tsx/esm ...`  | Run tests without build        |
+| `npm run lint`       | `eslint .`                          | Lint all files                 |
+| `npm run lint:fix`   | `eslint . --fix`                    | Lint and auto-fix              |
+| `npm run format`     | `prettier --write .`                | Format all files               |
+| `npm run type-check` | `node scripts/tasks.mjs type-check` | Type-check without emitting    |
+| `npm run inspector`  | Build + launch MCP Inspector        | Debug with MCP Inspector       |
+
+### Debugging with MCP Inspector
 
 ```bash
-docker compose up --build
+npx @modelcontextprotocol/inspector node dist/index.js
 ```
 
 ## Build & Release
 
-Releases are managed via the `Release` GitHub Actions workflow (manual dispatch):
+Releases are triggered via GitHub Actions `workflow_dispatch` with version bump selection (patch/minor/major/custom).
+
+The pipeline runs lint, type-check, test, and build, then publishes to three targets in parallel:
 
-1. **Version bump** — increments `package.json` and `server.json`, commits and tags.
-2. **npm publish** — publishes `@j0hanz/code-review-analyst-mcp` with OIDC provenance.
-3. **MCP Registry** — publishes `io.github.j0hanz/code-review-analyst` to the [MCP Registry](https://registry.modelcontextprotocol.io).
-4. **Docker image** — builds and pushes multi-arch (`linux/amd64`, `linux/arm64`) to `ghcr.io/j0hanz/code-review-analyst-mcp`.
+- **npm** — `@j0hanz/code-review-analyst-mcp` with OIDC trusted publishing and provenance
+- **Docker** — `ghcr.io/j0hanz/code-review-analyst-mcp` (linux/amd64, linux/arm64)
+- **MCP Registry** — `io.github.j0hanz/code-review-analyst`
 
 ## Troubleshooting
 
-- **`E_INPUT_TOO_LARGE`**: Split diff into smaller chunks or increase `MAX_DIFF_CHARS`.
-- **`E_REVIEW_DIFF` / `E_RISK_SCORE` / `E_SUGGEST_PATCH`**: Verify API key env vars and retry with narrower input.
-- **`Gemini request timed out after ...ms.`**: Reduce diff/prompt size or increase timeout in caller.
-- **`Gemini returned an empty response body.`**: Retry and check upstream model health.
-- **Malformed model JSON response**: Retry with same schema and inspect `stderr` logs.
-- **Inspector not connecting**: Ensure the server is built (`npm run build`) before running the inspector.
-- **Claude Desktop logs**: Check `~/Library/Logs/Claude/mcp*.log` (macOS) for server communication issues.
+| Issue                                      | Solution                                                                             |
+| ------------------------------------------ | ------------------------------------------------------------------------------------ |
+| `Missing GEMINI_API_KEY or GOOGLE_API_KEY` | Set one of the API key env vars in your MCP client config.                           |
+| `E_INPUT_TOO_LARGE`                        | Diff or combined context exceeds budget. Split into smaller diffs or reduce files.   |
+| `Gemini request timed out`                 | Pro model tasks may take 60-120s. Increase your client timeout.                      |
+| `Too many concurrent Gemini calls`         | Reduce parallel tool calls or increase `MAX_CONCURRENT_CALLS`.                       |
+| No tool output visible                     | Ensure your MCP client is not swallowing `stderr` — the server uses stdio transport. |
 
-## Contributing & License
+## License
 
-- Contributions are welcome. Please open an issue or pull request on [GitHub](https://github.com/j0hanz/code-review-analyst-mcp).
-- License: **MIT** (see `package.json`).
+MIT