@j0hanz/code-review-analyst-mcp 0.1.0

package/README.md

@@ -0,0 +1,297 @@
+# Code Review Analyst MCP Server
+
+<!-- mcp-name: io.github.j0hanz/code-review-analyst -->
+
+[![Node.js](https://img.shields.io/badge/Node.js-%3E%3D24-339933?style=flat-square&logo=nodedotjs&logoColor=white)](package.json) [![TypeScript](https://img.shields.io/badge/TypeScript-5.9%2B-3178C6?style=flat-square&logo=typescript&logoColor=white)](package.json) [![MCP SDK](https://img.shields.io/badge/MCP_SDK-1.26.0-6f42c1?style=flat-square)](package.json) [![License](https://img.shields.io/badge/License-MIT-blue?style=flat-square)](package.json)
+
+[![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%20Review%20Analyst&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22code-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%20Review%20Analyst&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22code-review-analyst-mcp%40latest%22%5D%7D&quality=insiders)
+
+[![Install in Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en/install-mcp?name=Code%20Review%20Analyst&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsImNvZGUtcmV2aWV3LWFuYWx5c3QtbWNwQGxhdGVzdCJdfQ==)
+
+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.
+
+## 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`.
+
+## Requirements
+
+- Node.js `>=24`
+- One API key: `GEMINI_API_KEY` or `GOOGLE_API_KEY`
+- MCP client that supports stdio servers and tool calls
+
+## Quick Start
+
+Standard config for most MCP clients:
+
+```json
+{
+  "mcpServers": {
+    "code-review-analyst": {
+      "command": "npx",
+      "args": ["-y", "code-review-analyst-mcp@latest"],
+      "env": {
+        "GEMINI_API_KEY": "YOUR_API_KEY"
+      }
+    }
+  }
+}
+```
+
+> [!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>
+
+[![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%20Review%20Analyst&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22code-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%20Review%20Analyst&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22code-review-analyst-mcp%40latest%22%5D%7D&quality=insiders)
+
+`.vscode/mcp.json`
+
+```json
+{
+  "servers": {
+    "code-review-analyst": {
+      "command": "npx",
+      "args": ["-y", "code-review-analyst-mcp@latest"],
+      "env": {
+        "GEMINI_API_KEY": "YOUR_API_KEY"
+      }
+    }
+  }
+}
+```
+
+CLI install:
+
+```bash
+code --add-mcp '{"name":"code-review-analyst","command":"npx","args":["-y","code-review-analyst-mcp@latest"]}'
+```
+
+</details>
+
+<details>
+<summary><b>Install in Cursor</b></summary>
+
+[![Install in Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en/install-mcp?name=Code%20Review%20Analyst&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsImNvZGUtcmV2aWV3LWFuYWx5c3QtbWNwQGxhdGVzdCJdfQ==)
+
+`~/.cursor/mcp.json`
+
+```json
+{
+  "mcpServers": {
+    "code-review-analyst": {
+      "command": "npx",
+      "args": ["-y", "code-review-analyst-mcp@latest"],
+      "env": {
+        "GEMINI_API_KEY": "YOUR_API_KEY"
+      }
+    }
+  }
+}
+```
+
+</details>
+
+<details>
+<summary><b>Install in Claude Desktop</b></summary>
+
+`claude_desktop_config.json`
+
+```json
+{
+  "mcpServers": {
+    "code-review-analyst": {
+      "command": "npx",
+      "args": ["-y", "code-review-analyst-mcp@latest"],
+      "env": {
+        "GEMINI_API_KEY": "YOUR_API_KEY"
+      }
+    }
+  }
+}
+```
+
+</details>
+
+<details>
+<summary><b>Install in Claude Code</b></summary>
+
+```bash
+claude mcp add code-review-analyst -- npx -y code-review-analyst-mcp@latest
+```
+
+</details>
+
+## MCP Surface
+
+### Tools
+
+#### `review_diff`
+
+Analyze a unified diff and return structured findings, overall merge risk, and test recommendations.
+
+| 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 (inside `result`):
+
+- `summary`, `overallRisk` (`low|medium|high`), `findings[]`, `testsNeeded[]`
+
+Example:
+
+```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`
+
+Score deployment risk for a diff and explain the score drivers.
+
+| 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.                    |
+
+Returns (inside `result`):
+
+- `score` (`0..100`), `bucket` (`low|medium|high|critical`), `rationale[]`
+
+#### `suggest_patch`
+
+Generate a focused unified-diff patch for one selected finding.
+
+| 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.                           |
+
+Returns (inside `result`):
+
+- `summary`, `patch` (unified diff text), `validationChecklist[]`
+
+### Resources
+
+| URI                       | Name                  | MIME Type       | Description                                  |
+| ------------------------- | --------------------- | --------------- | -------------------------------------------- |
+| `internal://instructions` | `server-instructions` | `text/markdown` | In-repo usage guide for tools and workflows. |
+
+### Prompts
+
+| Name       | Description                        | Arguments |
+| ---------- | ---------------------------------- | --------- |
+| `get-help` | Returns server usage instructions. | None      |
+
+### Tasks & Progress
+
+- 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`).
+
+## Configuration
+
+### Runtime Mode
+
+| Mode                     | Supported | Notes                                  |
+| ------------------------ | --------- | -------------------------------------- |
+| `stdio`                  | Yes       | Active transport in `src/index.ts`.    |
+| HTTP/SSE/Streamable HTTP | No        | Not implemented in current entrypoint. |
+
+### 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                                                                            | `120000`           | No                                          |
+| `TASK_TIMEOUT_MS`             | Task-runner timeout for build/test scripts                                                          | unset              | No                                          |
+
+## Security
+
+- Stdio transport avoids HTTP exposure in the current runtime path.
+- Runtime logs and warnings are written to `stderr`; avoid writing non-protocol output to `stdout` in stdio mode.
+- 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).
+
+## Development
+
+Install and run locally:
+
+```bash
+npm install
+npm run build
+npm start
+```
+
+Useful scripts:
+
+| 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/index.js`                                                    | 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.                                           |
+| `type-check` | `node scripts/tasks.mjs type-check`                                                             | TypeScript no-emit checks.                                              |
+| `lint`       | `eslint .`                                                                                      | ESLint checks.                                                          |
+| `format`     | `prettier --write .`                                                                            | Prettier formatting.                                                    |
+| `inspector`  | `npm run build && npx -y @modelcontextprotocol/inspector node dist/index.js ${workspaceFolder}` | MCP Inspector for stdio server.                                         |
+
+Inspector examples:
+
+```bash
+# stdio
+npx @modelcontextprotocol/inspector node dist/index.js
+```
+
+## Troubleshooting
+
+- **`E_INPUT_TOO_LARGE`**: split diff into smaller chunks, then rerun.
+- **`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.
+
+## Contributing & License
+
+- License: **MIT** (from `package.json`).

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,54 @@
+#!/usr/bin/env node
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { parseArgs } from 'node:util';
+import { getErrorMessage } from './lib/errors.js';
+import { createServer } from './server.js';
+const SHUTDOWN_SIGNALS = ['SIGINT', 'SIGTERM'];
+function parseCommandLineArgs() {
+    const { values } = parseArgs({
+        args: process.argv.slice(2),
+        options: {
+            model: {
+                type: 'string',
+                short: 'm',
+            },
+            'max-diff-chars': {
+                type: 'string',
+            },
+        },
+        strict: false,
+    });
+    if (typeof values.model === 'string') {
+        process.env.GEMINI_MODEL = values.model;
+    }
+    if (typeof values['max-diff-chars'] === 'string') {
+        process.env.MAX_DIFF_CHARS = values['max-diff-chars'];
+    }
+}
+let shuttingDown = false;
+async function shutdown(server) {
+    if (shuttingDown) {
+        return;
+    }
+    shuttingDown = true;
+    await server.close();
+    process.exit(0);
+}
+function registerShutdownHandlers(server) {
+    for (const signal of SHUTDOWN_SIGNALS) {
+        process.on(signal, () => {
+            void shutdown(server);
+        });
+    }
+}
+async function main() {
+    parseCommandLineArgs();
+    const server = createServer();
+    const transport = new StdioServerTransport();
+    registerShutdownHandlers(server);
+    await server.connect(transport);
+}
+main().catch((error) => {
+    console.error(`[fatal] ${getErrorMessage(error)}`);
+    process.exit(1);
+});

package/dist/instructions.md

@@ -0,0 +1,126 @@
+# CODE REVIEW ANALYST MCP INSTRUCTIONS
+
+These instructions are available as a resource (internal://instructions) or prompt (get-help). Load them when unsure about tool usage.
+
+---
+
+## CORE CAPABILITY
+
+- Domain: Analyze pull request diffs with Gemini and return structured review findings, risk scores, and focused patch suggestions for automation clients.
+- Primary Resources: Unified diff text, structured JSON review results, release-risk assessments, and unified-diff patch suggestions.
+- Tools: READ: `review_diff`, `risk_score`, `suggest_patch`. WRITE: none.
+
+---
+
+## PROMPTS
+
+- `get-help`: Returns these instructions for quick recall.
+
+---
+
+## RESOURCES & RESOURCE LINKS
+
+- `internal://instructions`: This document.
+
+---
+
+## PROGRESS & TASKS
+
+- Include `_meta.progressToken` in requests to receive `notifications/progress` updates during Gemini processing.
+- Task-augmented tool calls are supported for `review_diff`, `risk_score`, and `suggest_patch`:
+  - These tools declare `execution.taskSupport: "optional"` — invoke normally or as a task.
+  - Send `tools/call` with `task` to get a task id.
+  - Poll `tasks/get` and fetch results via `tasks/result`.
+  - Use `tasks/cancel` to abort.
+  - Task data is stored in memory and cleared on restart.
+
+---
+
+## THE "GOLDEN PATH" WORKFLOWS (CRITICAL)
+
+### WORKFLOW A: FULL PR REVIEW
+
+1. Call `review_diff` with `diff` and `repository` to get structured findings and merge risk.
+2. Use `focusAreas` to bias analysis toward the highest-priority concerns.
+3. Use `maxFindings` to cap result volume when context windows are tight.
+   NOTE: Never pass oversized diffs. Pre-check against your own limits and handle `E_INPUT_TOO_LARGE`.
+
+### WORKFLOW B: RELEASE GATE RISK CHECK
+
+1. Call `risk_score` with `diff` to get a 0–100 score, bucket, and rationale.
+2. Set `deploymentCriticality` when evaluating sensitive systems.
+3. Use score and rationale to decide whether to block or require additional validation.
+   NOTE: Call `review_diff` first if you need file-level defect evidence.
+
+### WORKFLOW C: PATCH FROM A SELECTED FINDING
+
+1. Call `review_diff` to identify one concrete finding to fix.
+2. Call `suggest_patch` with the same `diff`, plus `findingTitle` and `findingDetails` from that finding.
+3. Use `patchStyle` (`minimal`, `balanced`, `defensive`) to control change breadth.
+   NOTE: Keep inputs scoped to one finding at a time to avoid mixed patch intent.
+
+---
+
+## TOOL NUANCES & GOTCHAS
+
+`review_diff`
+
+- Purpose: Generate structured review findings, overall risk, and test recommendations from a unified diff.
+- Input: `maxFindings` defaults to 10; `focusAreas` defaults to security/correctness/regressions/performance when omitted.
+- Output: `ok/result/error` envelope; successful payload follows `ReviewDiffResultSchema` and includes `summary`, `overallRisk`, `findings`, and `testsNeeded`.
+- Gotcha: Schema allows `diff` up to 400,000 chars, but runtime rejects payloads above `MAX_DIFF_CHARS` (default 120,000) with `E_INPUT_TOO_LARGE`.
+- Side effects: Calls external Gemini API (`openWorldHint: true`); does not mutate local state (`readOnlyHint: true`).
+
+`risk_score`
+
+- Purpose: Produce deployment risk score and rationale for release decisions.
+- Input: `deploymentCriticality` defaults to `medium` when omitted.
+- Output: `ok/result/error` envelope; successful payload includes `score`, `bucket`, and `rationale`.
+- Gotcha: Uses the same runtime diff budget guard as other tools; oversized inputs fail before model execution.
+- Side effects: External Gemini call only.
+
+`suggest_patch`
+
+- Purpose: Generate a focused unified diff patch for one selected review finding.
+- Input: `patchStyle` defaults to `balanced`; requires both `findingTitle` and `findingDetails`.
+- Output: `ok/result/error` envelope; successful payload includes `summary`, `patch`, and `validationChecklist`.
+- Gotcha: Output is model-generated text and must be validated before application.
+- Side effects: External Gemini call only.
+
+---
+
+## CROSS-FEATURE RELATIONSHIPS
+
+- Use `review_diff` first to generate concrete finding metadata for `suggest_patch` inputs.
+- Use `risk_score` after `review_diff` when you need both defect-level detail and a release gate score.
+- All tools share the same Gemini adapter, retry policy, timeout policy, and diff-size guard.
+- All tool responses include both `structuredContent` and JSON-string `content` for client compatibility.
+
+---
+
+## CONSTRAINTS & LIMITATIONS
+
+- Transport: stdio only in current server entrypoint.
+- API credentials: Require `GEMINI_API_KEY` or `GOOGLE_API_KEY`.
+- Model selection: Uses `GEMINI_MODEL` if set; defaults to `gemini-2.5-flash`.
+- Diff size: Runtime limit defaults to 120,000 chars (`MAX_DIFF_CHARS` env override). Input schema max is 400,000 chars.
+- Timeout/retries: Per-call timeout defaults to 15,000 ms; retry count defaults to 1 with exponential backoff.
+- Output tokens: `maxOutputTokens` defaults to 16,384 to prevent unbounded responses.
+- Safety config: Gemini safety thresholds default to `BLOCK_NONE` for configured harm categories and can be overridden with `GEMINI_HARM_BLOCK_THRESHOLD` (`BLOCK_NONE`, `BLOCK_ONLY_HIGH`, `BLOCK_MEDIUM_AND_ABOVE`, `BLOCK_LOW_AND_ABOVE`).
+- Resource scope: Only `internal://instructions` is registered as a resource; no dynamic resource templates are exposed.
+- Prompt scope: Only `get-help` is registered.
+
+---
+
+## ERROR HANDLING STRATEGY
+
+- `E_INPUT_TOO_LARGE`: Diff exceeded runtime budget. → Split the diff into smaller chunks or raise `MAX_DIFF_CHARS` safely.
+- `E_REVIEW_DIFF`: Review generation failed. → Check API key env vars, reduce diff size, and retry; inspect stderr Gemini logs.
+- `E_RISK_SCORE`: Risk scoring failed. → Check connectivity/model availability and retry with same diff.
+- `E_SUGGEST_PATCH`: Patch generation failed. → Verify finding inputs are specific and retry with narrower details.
+- Missing `GEMINI_API_KEY`/`GOOGLE_API_KEY` (wrapped by tool error codes): Credentials not configured. → Set one API key env var and rerun.
+- Gemini timeout message (`Gemini request timed out after ...ms.`): Request exceeded timeout budget. → Reduce prompt/diff size or increase `timeoutMs` in caller.
+- Empty model body (`Gemini returned an empty response body.`): Provider returned no text payload. → Retry and inspect model/service status.
+- JSON parse failure from model output (wrapped by tool error codes): Output was not valid JSON. → Retry with same schema; inspect logs for malformed response text.
+
+---

package/dist/lib/diff-budget.d.ts

@@ -0,0 +1,4 @@
+import { createErrorToolResponse } from './tool-response.js';
+export declare function exceedsDiffBudget(diff: string): boolean;
+export declare function getDiffBudgetError(diffLength: number): string;
+export declare function validateDiffBudget(diff: string): ReturnType<typeof createErrorToolResponse> | undefined;

package/dist/lib/diff-budget.js

@@ -0,0 +1,27 @@
+import { createErrorToolResponse } from './tool-response.js';
+const DEFAULT_MAX_DIFF_CHARS = 120_000;
+const MAX_DIFF_CHARS_ENV_VAR = 'MAX_DIFF_CHARS';
+const numberFormatter = new Intl.NumberFormat('en-US');
+function formatNumber(value) {
+    return numberFormatter.format(value);
+}
+function getPositiveIntEnv(name) {
+    const parsed = Number.parseInt(process.env[name] ?? '', 10);
+    return Number.isFinite(parsed) && parsed > 0 ? parsed : undefined;
+}
+function getMaxDiffChars() {
+    return getPositiveIntEnv(MAX_DIFF_CHARS_ENV_VAR) ?? DEFAULT_MAX_DIFF_CHARS;
+}
+export function exceedsDiffBudget(diff) {
+    return diff.length > getMaxDiffChars();
+}
+export function getDiffBudgetError(diffLength) {
+    const maxDiffChars = getMaxDiffChars();
+    return `diff exceeds max allowed size (${formatNumber(diffLength)} chars > ${formatNumber(maxDiffChars)} chars)`;
+}
+export function validateDiffBudget(diff) {
+    if (!exceedsDiffBudget(diff)) {
+        return undefined;
+    }
+    return createErrorToolResponse('E_INPUT_TOO_LARGE', getDiffBudgetError(diff.length));
+}

package/dist/lib/errors.d.ts

@@ -0,0 +1 @@
+export declare function getErrorMessage(error: unknown): string;

package/dist/lib/errors.js

@@ -0,0 +1,16 @@
+import { inspect } from 'node:util';
+function isErrorWithMessage(error) {
+    return (typeof error === 'object' &&
+        error !== null &&
+        'message' in error &&
+        typeof error.message === 'string');
+}
+export function getErrorMessage(error) {
+    if (isErrorWithMessage(error)) {
+        return error.message;
+    }
+    if (typeof error === 'string') {
+        return error;
+    }
+    return inspect(error, { depth: 3, breakLength: 120 });
+}

package/dist/lib/gemini-schema.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Recursively strips value-range constraints (`min*`, `max*`, `multipleOf`)
+ * from a JSON Schema object and converts `"type": "integer"` to
+ * `"type": "number"`.
+ *
+ * Use this to derive a relaxed schema for Gemini structured output from the
+ * same Zod schema that validates tool results. The tool-level result schema
+ * enforces strict bounds *after* Gemini returns its response.
+ */
+export declare function stripJsonSchemaConstraints(schema: Record<string, unknown>): Record<string, unknown>;

package/dist/lib/gemini-schema.js

@@ -0,0 +1,51 @@
+/**
+ * JSON Schema property keys that represent value-range or count constraints.
+ * These are stripped when generating relaxed schemas for Gemini structured
+ * output so the model is not over-constrained by bounds that the
+ * application-level result schema enforces after parsing.
+ */
+const CONSTRAINT_KEYS = new Set([
+    'minLength',
+    'maxLength',
+    'minimum',
+    'maximum',
+    'exclusiveMinimum',
+    'exclusiveMaximum',
+    'minItems',
+    'maxItems',
+    'multipleOf',
+]);
+/**
+ * Recursively strips value-range constraints (`min*`, `max*`, `multipleOf`)
+ * from a JSON Schema object and converts `"type": "integer"` to
+ * `"type": "number"`.
+ *
+ * Use this to derive a relaxed schema for Gemini structured output from the
+ * same Zod schema that validates tool results. The tool-level result schema
+ * enforces strict bounds *after* Gemini returns its response.
+ */
+export function stripJsonSchemaConstraints(schema) {
+    const result = {};
+    for (const [key, value] of Object.entries(schema)) {
+        if (CONSTRAINT_KEYS.has(key))
+            continue;
+        // Relax integer → number so Gemini is not forced into integer-only
+        // output; the stricter result schema still validates integrality.
+        if (key === 'type' && value === 'integer') {
+            result[key] = 'number';
+            continue;
+        }
+        if (Array.isArray(value)) {
+            result[key] = value.map((item) => typeof item === 'object' && item !== null && !Array.isArray(item)
+                ? stripJsonSchemaConstraints(item)
+                : item);
+        }
+        else if (typeof value === 'object' && value !== null) {
+            result[key] = stripJsonSchemaConstraints(value);
+        }
+        else {
+            result[key] = value;
+        }
+    }
+    return result;
+}

package/dist/lib/gemini.d.ts

@@ -0,0 +1,6 @@
+import { EventEmitter } from 'node:events';
+import { GoogleGenAI } from '@google/genai';
+import type { GeminiStructuredRequest } from './types.js';
+export declare const geminiEvents: EventEmitter<[never]>;
+export declare function setClientForTesting(client: GoogleGenAI): void;
+export declare function generateStructuredJson(request: GeminiStructuredRequest): Promise<unknown>;