claude-mcp-bridge 0.2.0 → 0.3.1

package/README.md

@@ -1,18 +1,20 @@
 # claude-mcp-bridge
 
 [![npm version](https://img.shields.io/npm/v/claude-mcp-bridge)](https://www.npmjs.com/package/claude-mcp-bridge)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-[![Node.js](https://img.shields.io/badge/node-%3E%3D18-brightgreen)](https://nodejs.org/)
-[![TypeScript](https://img.shields.io/badge/TypeScript-5.7-blue)](https://www.typescriptlang.org/)
-[![MCP SDK](https://img.shields.io/badge/MCP%20SDK-1.12-purple)](https://modelcontextprotocol.io/)
+[![npm downloads](https://img.shields.io/npm/dm/claude-mcp-bridge)](https://www.npmjs.com/package/claude-mcp-bridge)
+[![CI](https://github.com/hampsterx/claude-mcp-bridge/actions/workflows/ci.yml/badge.svg)](https://github.com/hampsterx/claude-mcp-bridge/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+[![Node.js](https://img.shields.io/node/v/claude-mcp-bridge)](https://nodejs.org/)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.x-3178C6?logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
+[![MCP](https://img.shields.io/badge/MCP-compatible-8A2BE2)](https://modelcontextprotocol.io/)
 
-MCP server that wraps [Claude Code CLI](https://github.com/anthropics/claude-code) as a subprocess, exposing code execution, agentic review, web search, and structured output as MCP tools.
+MCP server that wraps [Claude Code CLI](https://github.com/anthropics/claude-code) as a subprocess, exposing its capabilities as [Model Context Protocol](https://modelcontextprotocol.io/) tools.
 
-Works with any MCP client: Codex CLI, Gemini CLI, Cursor, Windsurf, VS Code, or any tool that speaks [Model Context Protocol](https://modelcontextprotocol.io/).
+Works with any MCP client: Codex CLI, Gemini CLI, Cursor, Windsurf, VS Code, or any tool that speaks MCP.
 
 ## Do you need this?
 
-If you're in a terminal agent (Codex CLI, Gemini CLI) with shell access, you can call Claude Code CLI directly:
+If you're in a terminal agent (Codex CLI, Gemini CLI) with shell access, call Claude Code CLI directly:
 
 ```bash
 # Quick review of current diff
@@ -38,290 +40,203 @@ claude -p --bare --max-budget-usd 0.50 "Is this retry logic sound?"
 - You need concurrency management and security hardening
 - You want cost metadata surfaced in MCP responses
 
-## Installation
+## Quick Start
+
+```bash
+npx claude-mcp-bridge
+```
 
 ### Prerequisites
 
-- Node.js >= 18
 - [Claude Code CLI](https://github.com/anthropics/claude-code) installed and on PATH
 - Authentication (one of):
   - **Subscription**: `claude login` (uses your Pro/Max plan, no API credits needed)
   - **API key**: set `ANTHROPIC_API_KEY` (billed per use via console.anthropic.com)
 
-### From source
-
-```bash
-git clone https://github.com/hampsterx/claude-mcp-bridge.git
-cd claude-mcp-bridge
-npm install
-npm run build
-```
-
-### MCP client configuration
-
-Add to your MCP client config (e.g. `~/.claude/settings.json`, Cursor settings, etc.):
+### Codex CLI
 
+Add to `~/.codex/config.json`:
 ```json
 {
   "mcpServers": {
-    "claude-mcp-bridge": {
-      "command": "node",
-      "args": ["/path/to/claude-mcp-bridge/dist/index.js"],
-      "env": {
-        "ANTHROPIC_API_KEY": "sk-ant-..."
-      }
+    "claude-bridge": {
+      "command": "npx",
+      "args": ["-y", "claude-mcp-bridge"]
     }
   }
 }
 ```
 
-Or if installed globally:
+### Gemini CLI
 
+Add to `~/.gemini/settings.json`:
 ```json
 {
   "mcpServers": {
-    "claude-mcp-bridge": {
-      "command": "claude-mcp-bridge"
+    "claude-bridge": {
+      "command": "npx",
+      "args": ["-y", "claude-mcp-bridge"]
     }
   }
 }
 ```
 
-## Tools
-
-### `query`
-
-Execute a prompt via Claude Code CLI with optional file context and session resume.
+### Cursor / Windsurf / VS Code
 
+Add to your MCP settings:
 ```json
 {
-  "prompt": "Explain the error handling in this file",
-  "files": ["src/utils/errors.ts"],
-  "model": "sonnet",
-  "workingDirectory": "/path/to/repo",
-  "timeout": 60000,
-  "maxBudgetUsd": 0.50
+  "claude-bridge": {
+    "command": "npx",
+    "args": ["-y", "claude-mcp-bridge"],
+    "env": {
+      "ANTHROPIC_API_KEY": "sk-ant-..."
+    }
+  }
 }
 ```
 
-| Parameter | Type | Default | Description |
-|-----------|------|---------|-------------|
-| `prompt` | string | (required) | The prompt to send to Claude |
-| `files` | string[] | | File paths relative to workingDirectory (text or images) |
-| `model` | string | `sonnet` | Model alias or full Claude model name |
-| `sessionId` | string | | Session ID to resume a multi-turn conversation |
-| `noSessionPersistence` | boolean | | Disable session persistence for one-off calls |
-| `workingDirectory` | string | `cwd` | Working directory for file resolution and CLI execution |
-| `timeout` | number | 60000 | Timeout in ms (120000 for image queries) |
-| `maxResponseLength` | number | | Soft limit on response length in words |
-| `maxBudgetUsd` | number | | Cost cap in USD |
-| `effort` | string | | `low`, `medium`, `high`, or `max` |
-
-Supports images (.png, .jpg, .jpeg, .gif, .webp, .bmp) up to 5MB each. Text files are inlined into the prompt; image paths are passed to Claude's Read tool.
-
-### `structured`
-
-Generate JSON that conforms to a provided JSON Schema using Claude CLI's native `--json-schema` validation.
+## Tools
 
-```json
-{
-  "prompt": "Extract all function signatures from this file",
-  "schema": "{\"type\":\"object\",\"properties\":{\"functions\":{\"type\":\"array\",\"items\":{\"type\":\"object\",\"properties\":{\"name\":{\"type\":\"string\"},\"params\":{\"type\":\"array\",\"items\":{\"type\":\"string\"}}},\"required\":[\"name\"]}}},\"required\":[\"functions\"]}",
-  "files": ["src/index.ts"],
-  "workingDirectory": "/path/to/repo"
-}
-```
+| Tool | Description |
+|------|-------------|
+| **query** | Execute prompts with file context, session resume, effort control, and budget caps. Supports text and images. |
+| **review** | Agentic code review. Claude explores the repo with Read, Grep, Glob, and git commands. Quick diff-only mode available. |
+| **search** | Web search via Claude CLI's WebSearch and WebFetch tools. Returns synthesized answers with sources. |
+| **structured** | JSON Schema validated output via Claude CLI's native `--json-schema`. |
+| **ping** | Health check with CLI version, auth method, capabilities, and model config. |
+| **listSessions** | List active sessions with cumulative cost, turn count, and timestamps. |
 
-| Parameter | Type | Default | Description |
-|-----------|------|---------|-------------|
-| `prompt` | string | (required) | What to generate or extract |
-| `schema` | string | (required) | JSON Schema as a JSON string (max 20KB) |
-| `files` | string[] | | Text file paths to include as context (no images) |
-| `model` | string | `sonnet` | Model alias or full model name |
-| `sessionId` | string | | Session ID to resume |
-| `noSessionPersistence` | boolean | | Disable session persistence |
-| `workingDirectory` | string | `cwd` | Working directory for file resolution |
-| `timeout` | number | 60000 | Timeout in ms |
-| `maxBudgetUsd` | number | | Cost cap in USD |
+### query
 
-Returns clean JSON in the first content block. Metadata (model, session, cost) in a separate content block so JSON parsing isn't broken.
+Execute a prompt with optional file context. Supports session resume via `sessionId`, effort control (`low`/`medium`/`high`/`max`), and budget caps (`maxBudgetUsd`). Images (.png, .jpg, .gif, .webp, .bmp) up to 5MB each are passed to Claude's Read tool.
 
-### `review`
+Key parameters: `prompt` (required), `files`, `model` (default `sonnet`), `sessionId`, `effort`, `maxBudgetUsd`, `workingDirectory`, `timeout` (default 60s).
 
-Repo-aware code review with two modes:
+### review
 
-**Agentic mode** (default): Claude explores the repo using Read, Grep, Glob, and git commands. It follows imports, checks tests, and reads surrounding context. Slower but thorough.
+Two modes:
+- **Agentic** (default): Claude runs inside the repo with Read, Grep, Glob, and git commands. It diffs, reads files, follows imports, and checks tests. Timeout auto-scales from diff size.
+- **Quick** (`quick: true`): Diff-only review, no repo exploration. Faster and cheaper.
 
-**Quick mode** (`quick: true`): Reviews a pre-computed diff only. No tool calls, no file exploration. Faster, cheaper, good for small changes.
+Key parameters: `uncommitted` (default true), `base`, `focus`, `quick`, `model` (default `opus`), `effort` (default `high`), `maxBudgetUsd`, `workingDirectory`, `timeout`.
 
-```json
-{
-  "base": "main",
-  "focus": "security and error handling",
-  "workingDirectory": "/path/to/repo",
-  "maxBudgetUsd": 1.00
-}
-```
+### search
 
-| Parameter | Type | Default | Description |
-|-----------|------|---------|-------------|
-| `uncommitted` | boolean | `true` | Review uncommitted changes (staged + unstaged) |
-| `base` | string | | Base branch/ref to diff against (overrides uncommitted) |
-| `focus` | string | | Review focus area (e.g. "security", "error handling") |
-| `quick` | boolean | `false` | Use quick (diff-only) mode instead of agentic |
-| `model` | string | `opus` | Model alias or full model name |
-| `sessionId` | string | | Session ID to resume |
-| `noSessionPersistence` | boolean | | Disable session persistence |
-| `workingDirectory` | string | `cwd` | Repository root |
-| `timeout` | number | 300000 / 120000 | 5min (agentic) or 2min (quick) |
-| `maxResponseLength` | number | | Soft limit on response length in words |
-| `maxBudgetUsd` | number | | Cost cap in USD |
-| `effort` | string | `high` | `low`, `medium`, `high`, or `max` |
+Web search via Claude CLI's WebSearch and WebFetch tools. Returns synthesized answers with source URLs.
 
-Agentic mode allowed tools: `Read`, `Grep`, `Glob`, `Bash(git diff:*)`, `Bash(git log:*)`, `Bash(git show:*)`, `Bash(git status:*)`.
+Key parameters: `query` (required), `model` (default `sonnet`), `maxResponseLength`, `maxBudgetUsd`, `timeout` (default 120s).
 
-### `search`
+### structured
 
-Web search via Claude Code CLI using WebSearch and WebFetch tools.
+Generate JSON conforming to a provided schema using Claude CLI's native `--json-schema` flag. Returns clean JSON in the first content block, metadata in a separate block so JSON parsing isn't broken.
 
-```json
-{
-  "query": "What changed in MCP SDK v1.12?",
-  "maxResponseLength": 500
-}
-```
+Key parameters: `prompt` (required), `schema` (required, JSON string, max 20KB), `files`, `model` (default `sonnet`), `sessionId`, `maxBudgetUsd`, `timeout` (default 60s).
 
-| Parameter | Type | Default | Description |
-|-----------|------|---------|-------------|
-| `query` | string | (required) | Search query or question |
-| `model` | string | `sonnet` | Model alias or full model name |
-| `sessionId` | string | | Session ID to resume |
-| `noSessionPersistence` | boolean | | Disable session persistence |
-| `workingDirectory` | string | `cwd` | Working directory for the CLI |
-| `timeout` | number | 120000 | Timeout in ms |
-| `maxResponseLength` | number | | Soft limit on response length in words |
-| `maxBudgetUsd` | number | | Cost cap in USD |
-| `effort` | string | `medium` | `low`, `medium`, `high`, or `max` |
+### ping
 
-### `ping`
+No parameters. Returns CLI version, auth method (subscription/api-key/none), configured models, capabilities, and server version.
 
-Health check. No parameters. Returns CLI availability, auth status, configured models, server version, and capability flags.
+### listSessions
 
-```
-cliFound: true
-version: 2.1.92 (Claude Code)
-authMethod: subscription
-subscriptionType: max
-defaultModel: sonnet
-fallbackModel: haiku
-serverVersion: 0.1.0
-nodeVersion: v22.22.0
-maxConcurrent: 3
-capabilities: bareMode=true, jsonOutput=true, jsonSchema=true, sessionResume=true
-```
+No parameters. Returns active sessions with metadata: `sessionId`, `model`, `createdAt`, `lastUsedAt`, `turnCount`, `totalCostUsd`.
 
-`authMethod` is one of: `api-key` (ANTHROPIC_API_KEY set), `subscription` (logged in via `claude login`), or `none`.
+All tools attach execution metadata (`_meta`) with `durationMs`, `model`, `sessionId`, `totalCostUsd`, and token breakdowns. See [DESIGN.md](DESIGN.md) for details.
 
 ## Configuration
 
-All configuration is through environment variables. None are required if Claude CLI is on PATH and you're authenticated (via `claude login` or `ANTHROPIC_API_KEY`).
-
-### Authentication
-
-The bridge supports two auth methods, matching Claude Code CLI:
-
-| Method | Setup | Billing |
-|--------|-------|---------|
-| **Subscription** | `claude login` (OAuth) | Pro/Max plan (included) |
-| **API key** | Set `ANTHROPIC_API_KEY` | Pay-per-use (console.anthropic.com) |
-
-If `ANTHROPIC_API_KEY` is set, it takes priority over subscription auth. To use your subscription instead, unset the API key.
-
 ### Models
 
 | Variable | Default | Description |
 |----------|---------|-------------|
 | `CLAUDE_DEFAULT_MODEL` | | Shared default for all tools |
-| `CLAUDE_QUERY_MODEL` | `sonnet` | Default model for query |
-| `CLAUDE_STRUCTURED_MODEL` | `sonnet` | Default model for structured |
-| `CLAUDE_SEARCH_MODEL` | `sonnet` | Default model for search |
-| `CLAUDE_REVIEW_MODEL` | `opus` | Default model for review |
-| `CLAUDE_FALLBACK_MODEL` | `haiku` | Fallback on quota exhaustion (set to `none` to disable) |
+| `CLAUDE_QUERY_MODEL` | `sonnet` | Default for query |
+| `CLAUDE_STRUCTURED_MODEL` | `sonnet` | Default for structured |
+| `CLAUDE_SEARCH_MODEL` | `sonnet` | Default for search |
+| `CLAUDE_REVIEW_MODEL` | `opus` | Default for review |
+| `CLAUDE_FALLBACK_MODEL` | `haiku` | Fallback on quota exhaustion (`none` to disable) |
 
-Model resolution order: explicit parameter > tool-specific env var > `CLAUDE_DEFAULT_MODEL` > built-in default.
+Model resolution: explicit parameter > tool-specific env var > `CLAUDE_DEFAULT_MODEL` > built-in default.
 
-### Effort and budget
+### Runtime
 
 | Variable | Default | Description |
 |----------|---------|-------------|
-| `CLAUDE_REVIEW_EFFORT` | `high` | Default effort for review tool |
-| `CLAUDE_SEARCH_EFFORT` | `medium` | Default effort for search tool |
-| `CLAUDE_QUERY_EFFORT` | | Default effort for query tool |
+| `CLAUDE_MAX_CONCURRENT` | `3` | Max concurrent subprocess spawns |
+| `CLAUDE_CLI_PATH` | `claude` | Path to CLI binary |
 | `CLAUDE_MAX_BUDGET_USD` | | Global cost cap in USD (per call) |
+| `ANTHROPIC_API_KEY` | | API key for bare mode auth |
 
-### Runtime
+### Effort
 
 | Variable | Default | Description |
 |----------|---------|-------------|
-| `CLAUDE_MAX_CONCURRENT` | `3` | Max simultaneous Claude CLI processes |
-| `CLAUDE_CLI_PATH` | `claude` | Custom path to Claude CLI binary |
-| `ANTHROPIC_API_KEY` | | API key for bare mode auth |
-
-## Security
-
-### Subprocess environment isolation
-
-Only a strict allowlist of environment variables is passed to Claude CLI subprocesses: `ANTHROPIC_API_KEY`, `CLAUDE_CONFIG_DIR`, `CLAUDE_CODE_USE_BEDROCK`, `CLAUDE_CODE_USE_VERTEX`, `AWS_REGION`, `AWS_DEFAULT_REGION`, `HOME`, `PATH`, `USER`, `SHELL`, `LANG`, `TERM`, `XDG_CONFIG_HOME`. Everything else is stripped.
-
-### Path sandboxing
-
-All file paths are resolved to absolute paths via `realpath()` and verified to stay within the working directory. Symlink traversal and `..` path components that escape the sandbox are rejected.
-
-### Git argument injection prevention
-
-The `base` parameter in the review tool is validated against `/^[\w./-]+$/` before being passed to git commands, preventing argument injection (e.g. a malicious ref like `--output=/tmp/pwned`).
-
-### Output redaction
-
-CLI output is scanned for sensitive patterns before being returned: Anthropic API keys (`sk-ant-*`), Bearer tokens, token assignments, and base64-encoded strings that look like secrets are replaced with `[REDACTED]`.
-
-### Limits
-
-| Limit | Value |
-|-------|-------|
-| Max file size (text) | 1 MB |
-| Max file size (image) | 5 MB |
-| Max files per request | 20 |
-| Max JSON Schema size | 20 KB |
-| Hard timeout cap | 10 minutes |
-| Concurrency queue timeout | 30 seconds |
-
-## Concurrency
-
-Requests are queued with a FIFO scheduler. Default: 3 concurrent Claude CLI processes. If all slots are busy, new requests wait up to 30 seconds before being rejected. Timed-out processes are killed with SIGTERM, then SIGKILL after 5 seconds. On Unix, the entire process group is killed to clean up child processes.
+| `CLAUDE_REVIEW_EFFORT` | `high` | Default effort for review |
+| `CLAUDE_SEARCH_EFFORT` | `medium` | Default effort for search |
+| `CLAUDE_QUERY_EFFORT` | | Default effort for query |
+
+## Choosing a Claude Code MCP server
+
+| You need... | Consider |
+|-------------|----------|
+| Structured output, effort/budget control, session resume, cost metadata | This bridge |
+| Multi-tool orchestration (read, grep, edit, bash as separate MCP tools) | [mcp-claude-code](https://github.com/SDGLBL/mcp-claude-code) |
+| Session continuity with async execution | [claude-mcp](https://github.com/zhendalf/claude-mcp) |
+| Maintained lightweight wrapper | [@kunihiros/claude-code-mcp](https://github.com/KunihiroS/claude-code-mcp) |
+| Native Claude Code MCP (built-in, no wrapper) | `claude mcp serve` ([docs](https://github.com/anthropics/claude-code)) |
+
+## Performance
+
+Claude Code CLI has minimal startup overhead. Wall time is dominated by model inference and any agentic exploration.
+
+| Scenario | Typical time |
+|----------|-------------|
+| Trivial prompt (sonnet) | 5-10s |
+| Quick review, small diff | 15-30s |
+| Agentic review (explores repo) | 30s to 10 min |
+| Web search + synthesis | 15-30s |
+
+Cost metadata (`totalCostUsd`, token breakdowns) is returned in `_meta` on every response.
+
+## Bridge family
+
+Three MCP servers, same architecture, different underlying CLIs. Each wraps a terminal agent as a subprocess and exposes it as MCP tools. Pick the one that matches your model provider, or run multiple for cross-model workflows.
+
+| | [claude-mcp-bridge](https://github.com/hampsterx/claude-mcp-bridge) | [gemini-mcp-bridge](https://github.com/hampsterx/gemini-mcp-bridge) | [codex-mcp-bridge](https://github.com/hampsterx/codex-mcp-bridge) |
+|---|---|---|---|
+| **CLI** | Claude Code | Gemini CLI | Codex CLI |
+| **Provider** | Anthropic | Google | OpenAI |
+| **Tools** | query, review, search, structured, ping, listSessions | query, review, search, structured, ping | codex, review, search, query, structured, ping, listSessions |
+| **Agentic review** | Claude explores repo with Read/Grep/Glob/git | Gemini explores repo with file reads and git | Codex explores repo in full-auto mode |
+| **Structured output** | Native `--json-schema` (no Ajv) | Ajv validation | Ajv validation |
+| **Session resume** | Native `--resume` | Not supported | Session IDs with multi-turn |
+| **Budget caps** | Native `--max-budget-usd` | Not supported | Not supported |
+| **Effort control** | `--effort low/medium/high/max` | Not supported | Not supported |
+| **Cold start** | ~1-2s | ~16s | <100ms (inference dominates) |
+| **Auth** | `claude login` (subscription) or `ANTHROPIC_API_KEY` | `gemini auth login` | `OPENAI_API_KEY` |
+| **Cost** | Subscription (included) or API credits | Free tier available | Pay-per-token |
+| **Concurrency** | 3 (configurable) | 3 (configurable) | 3 (configurable) |
+| **Model fallback** | Auto-retry with fallback model | Not supported | Auto-retry with fallback model |
+
+All three share: subprocess env isolation, path sandboxing, output redaction, FIFO concurrency queue, MCP tool annotations, `_meta` response metadata, progress heartbeats.
 
 ## Development
 
 ```bash
-npm run build          # Compile TypeScript
-npm run dev            # Watch mode
-npm test               # Run unit tests (vitest)
-npm run lint           # ESLint
-npm run typecheck      # Type check without emitting
-npm run smoke          # Smoke test against live Claude CLI
+npm install
+npm run build        # Compile TypeScript
+npm run dev          # Watch mode
+npm test             # Run tests (vitest)
+npm run lint         # ESLint
+npm run typecheck    # tsc --noEmit
+npm run smoke        # Smoke test against live CLI
 ```
 
-### Smoke tests
-
-```bash
-node scripts/smoke-test.mjs query ~/my-repo
-node scripts/smoke-test.mjs structured ~/my-repo
-node scripts/smoke-test.mjs review ~/my-repo
-node scripts/smoke-test.mjs search
-node scripts/smoke-test.mjs ping
-```
+## Further reading
 
-Requires Claude CLI installed and `ANTHROPIC_API_KEY` set.
+- [DESIGN.md](DESIGN.md) - Architecture, sessions, cost tracking, response metadata, progress notifications
+- [SECURITY.md](SECURITY.md) - Environment isolation, path sandboxing, output redaction, tool sandboxing
+- [CHANGELOG.md](CHANGELOG.md) - Release history
 
 ## License
 

package/dist/annotations.d.ts

@@ -0,0 +1,24 @@
+import type { ToolAnnotations } from "@modelcontextprotocol/sdk/types.js";
+/**
+ * MCP tool annotations for all claude-mcp-bridge tools.
+ *
+ * Annotations are hints that help MCP clients understand tool behavior
+ * for permission prompts, safety checks, and orchestration decisions.
+ *
+ * readOnly: query/review/search/structured are false because they can persist
+ * Claude CLI session state to disk (~/.claude/) when sessionId is used.
+ * ping is true (purely local, no side effects).
+ *
+ * review: destructive=false because the default --allowed-tools list is read-only
+ * (Read, Grep, Glob, git). Callers that pass custom tools including write access
+ * should treat it as potentially destructive.
+ *
+ * Titles are set on the registerTool config in index.ts, not here (avoid duplication).
+ */
+export declare const queryAnnotations: ToolAnnotations;
+export declare const reviewAnnotations: ToolAnnotations;
+export declare const searchAnnotations: ToolAnnotations;
+export declare const structuredAnnotations: ToolAnnotations;
+export declare const listSessionsAnnotations: ToolAnnotations;
+export declare const pingAnnotations: ToolAnnotations;
+//# sourceMappingURL=annotations.d.ts.map

package/dist/annotations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"annotations.d.ts","sourceRoot":"","sources":["../src/annotations.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,oCAAoC,CAAC;AAE1E;;;;;;;;;;;;;;;GAeG;AAEH,eAAO,MAAM,gBAAgB,EAAE,eAK9B,CAAC;AAEF,eAAO,MAAM,iBAAiB,EAAE,eAK/B,CAAC;AAEF,eAAO,MAAM,iBAAiB,EAAE,eAK/B,CAAC;AAEF,eAAO,MAAM,qBAAqB,EAAE,eAKnC,CAAC;AAEF,eAAO,MAAM,uBAAuB,EAAE,eAKrC,CAAC;AAEF,eAAO,MAAM,eAAe,EAAE,eAK7B,CAAC"}

package/dist/annotations.js

@@ -0,0 +1,53 @@
+/**
+ * MCP tool annotations for all claude-mcp-bridge tools.
+ *
+ * Annotations are hints that help MCP clients understand tool behavior
+ * for permission prompts, safety checks, and orchestration decisions.
+ *
+ * readOnly: query/review/search/structured are false because they can persist
+ * Claude CLI session state to disk (~/.claude/) when sessionId is used.
+ * ping is true (purely local, no side effects).
+ *
+ * review: destructive=false because the default --allowed-tools list is read-only
+ * (Read, Grep, Glob, git). Callers that pass custom tools including write access
+ * should treat it as potentially destructive.
+ *
+ * Titles are set on the registerTool config in index.ts, not here (avoid duplication).
+ */
+export const queryAnnotations = {
+    readOnlyHint: false,
+    destructiveHint: false,
+    idempotentHint: false,
+    openWorldHint: true,
+};
+export const reviewAnnotations = {
+    readOnlyHint: false,
+    destructiveHint: false,
+    idempotentHint: false,
+    openWorldHint: true,
+};
+export const searchAnnotations = {
+    readOnlyHint: false,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: true,
+};
+export const structuredAnnotations = {
+    readOnlyHint: false,
+    destructiveHint: false,
+    idempotentHint: false,
+    openWorldHint: true,
+};
+export const listSessionsAnnotations = {
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: false,
+};
+export const pingAnnotations = {
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: false,
+};
+//# sourceMappingURL=annotations.js.map

package/dist/annotations.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"annotations.js","sourceRoot":"","sources":["../src/annotations.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;GAeG;AAEH,MAAM,CAAC,MAAM,gBAAgB,GAAoB;IAC/C,YAAY,EAAE,KAAK;IACnB,eAAe,EAAE,KAAK;IACtB,cAAc,EAAE,KAAK;IACrB,aAAa,EAAE,IAAI;CACpB,CAAC;AAEF,MAAM,CAAC,MAAM,iBAAiB,GAAoB;IAChD,YAAY,EAAE,KAAK;IACnB,eAAe,EAAE,KAAK;IACtB,cAAc,EAAE,KAAK;IACrB,aAAa,EAAE,IAAI;CACpB,CAAC;AAEF,MAAM,CAAC,MAAM,iBAAiB,GAAoB;IAChD,YAAY,EAAE,KAAK;IACnB,eAAe,EAAE,KAAK;IACtB,cAAc,EAAE,IAAI;IACpB,aAAa,EAAE,IAAI;CACpB,CAAC;AAEF,MAAM,CAAC,MAAM,qBAAqB,GAAoB;IACpD,YAAY,EAAE,KAAK;IACnB,eAAe,EAAE,KAAK;IACtB,cAAc,EAAE,KAAK;IACrB,aAAa,EAAE,IAAI;CACpB,CAAC;AAEF,MAAM,CAAC,MAAM,uBAAuB,GAAoB;IACtD,YAAY,EAAE,IAAI;IAClB,eAAe,EAAE,KAAK;IACtB,cAAc,EAAE,IAAI;IACpB,aAAa,EAAE,KAAK;CACrB,CAAC;AAEF,MAAM,CAAC,MAAM,eAAe,GAAoB;IAC9C,YAAY,EAAE,IAAI;IAClB,eAAe,EAAE,KAAK;IACtB,cAAc,EAAE,IAAI;IACpB,aAAa,EAAE,KAAK;CACrB,CAAC"}

package/dist/descriptions.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Rich tool descriptions for MCP clients.
+ *
+ * Descriptions include capability summaries, cost guidance, and prompt tips
+ * so calling LLMs can make informed tool selection and parameterization decisions.
+ *
+ * Keep each description at or under 2048 bytes to avoid bloating tool listings.
+ */
+export declare const queryDescription = "Execute a prompt via Claude Code CLI with optional file context and session resume. Claude is an AI coding agent that can generate, analyze, refactor, and explain code.\n\nCapabilities: code generation and refactoring, code analysis and explanation, file understanding (text and images), multi-turn conversations via sessionId.\n\nCost: Default model is Sonnet (~$0.01-0.10/call). Use effort=\"low\" for simple tasks, effort=\"high\" + model=\"opus\" for complex analysis. Set maxBudgetUsd to cap per-call cost (recommended for effort=\"max\" or model=\"opus\").\n\nTips:\n- Set workingDirectory to the target repo for project-aware responses.\n- Break complex tasks into focused prompts rather than one large request.\n- Resume multi-turn conversations with sessionId from a previous response's metadata.\n- Include relevant files via the files parameter for targeted context (text files inlined in prompt, images trigger allowed-tools mode).\n- Use noSessionPersistence=true for stateless one-shot calls.";
+export declare const reviewDescription = "Repo-aware code review powered by Claude Code CLI. Returns structured feedback on code changes with two modes:\n\n- Agentic (default): Claude explores the repo with Read, Grep, Glob, and git tools. Reads changed files, follows imports, and examines related code before reviewing. Best for thorough reviews. Default timeout: auto-scaled from diff size (3-10 minutes).\n- Quick (quick: true): Receives only the diff text. Fast single-pass review without repo exploration. Default timeout: 2 minutes.\n\nCost: Both modes default to Opus (~$0.05-0.15 quick, ~$0.25-0.50 agentic). Override with model parameter. Use maxBudgetUsd to cap cost on large diffs.\n\nTips:\n- Use the focus parameter to direct attention: \"security\", \"performance\", \"error handling\", \"test coverage\".\n- Set workingDirectory to the repo being reviewed (auto-resolves to git root).\n- Default reviews uncommitted changes (staged + unstaged). Use base to review a branch diff (e.g. base: \"main\").\n- Prefer agentic mode for important reviews, quick mode for rapid feedback during development.";
+export declare const searchDescription = "Web search via Claude Code CLI using WebSearch and WebFetch tools. Searches the web and synthesizes a comprehensive answer with source URLs.\n\nUse for: current information, documentation lookups, API references, comparing libraries, and research questions.\n\nCost: Typically ~$0.02-0.05/search with Sonnet.\n\nTips:\n- Ask specific, focused questions for best results.\n- Results include source URLs for verification.\n- Use maxResponseLength to control response verbosity.\n- Increase timeout for complex research queries that may require multiple web fetches.";
+export declare const structuredDescription = "Generate JSON conforming to a provided JSON Schema. Uses Claude CLI's native --json-schema flag for validated output (not client-side validation).\n\nUse for: data extraction from text/files, classification, entity parsing, or any task needing machine-parseable output.\n\nCost: Similar to query (~$0.01-0.10/call). Schema complexity doesn't significantly affect cost.\n\nTips:\n- Pass the JSON Schema as a JSON string in the schema parameter.\n- Schema max size: 20KB. Keep schemas focused for reliable output.\n- For extraction tasks, include source text via the files parameter or inline in the prompt.";
+export declare const listSessionsDescription = "List active Claude CLI sessions tracked by this server. Returns session metadata (IDs, models, timing, turn counts, cumulative cost) for orchestration. Use to check available sessions before resuming with sessionId. No cost (local lookup only).";
+export declare const pingDescription = "Health check: verifies Claude CLI is installed and authenticated, reports versions, capabilities, and configuration. No cost (local check only).";
+//# sourceMappingURL=descriptions.d.ts.map

package/dist/descriptions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"descriptions.d.ts","sourceRoot":"","sources":["../src/descriptions.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,eAAO,MAAM,gBAAgB,m/BAWiC,CAAC;AAE/D,eAAO,MAAM,iBAAiB,mjCAWiE,CAAC;AAEhG,eAAO,MAAM,iBAAiB,wjBAUyD,CAAC;AAExF,eAAO,MAAM,qBAAqB,kmBAS2D,CAAC;AAE9F,eAAO,MAAM,uBAAuB,yPAAyP,CAAC;AAE9R,eAAO,MAAM,eAAe,qJAAqJ,CAAC"}

package/dist/descriptions.js

@@ -0,0 +1,56 @@
+/**
+ * Rich tool descriptions for MCP clients.
+ *
+ * Descriptions include capability summaries, cost guidance, and prompt tips
+ * so calling LLMs can make informed tool selection and parameterization decisions.
+ *
+ * Keep each description at or under 2048 bytes to avoid bloating tool listings.
+ */
+export const queryDescription = `Execute a prompt via Claude Code CLI with optional file context and session resume. Claude is an AI coding agent that can generate, analyze, refactor, and explain code.
+
+Capabilities: code generation and refactoring, code analysis and explanation, file understanding (text and images), multi-turn conversations via sessionId.
+
+Cost: Default model is Sonnet (~$0.01-0.10/call). Use effort="low" for simple tasks, effort="high" + model="opus" for complex analysis. Set maxBudgetUsd to cap per-call cost (recommended for effort="max" or model="opus").
+
+Tips:
+- Set workingDirectory to the target repo for project-aware responses.
+- Break complex tasks into focused prompts rather than one large request.
+- Resume multi-turn conversations with sessionId from a previous response's metadata.
+- Include relevant files via the files parameter for targeted context (text files inlined in prompt, images trigger allowed-tools mode).
+- Use noSessionPersistence=true for stateless one-shot calls.`;
+export const reviewDescription = `Repo-aware code review powered by Claude Code CLI. Returns structured feedback on code changes with two modes:
+
+- Agentic (default): Claude explores the repo with Read, Grep, Glob, and git tools. Reads changed files, follows imports, and examines related code before reviewing. Best for thorough reviews. Default timeout: auto-scaled from diff size (3-10 minutes).
+- Quick (quick: true): Receives only the diff text. Fast single-pass review without repo exploration. Default timeout: 2 minutes.
+
+Cost: Both modes default to Opus (~$0.05-0.15 quick, ~$0.25-0.50 agentic). Override with model parameter. Use maxBudgetUsd to cap cost on large diffs.
+
+Tips:
+- Use the focus parameter to direct attention: "security", "performance", "error handling", "test coverage".
+- Set workingDirectory to the repo being reviewed (auto-resolves to git root).
+- Default reviews uncommitted changes (staged + unstaged). Use base to review a branch diff (e.g. base: "main").
+- Prefer agentic mode for important reviews, quick mode for rapid feedback during development.`;
+export const searchDescription = `Web search via Claude Code CLI using WebSearch and WebFetch tools. Searches the web and synthesizes a comprehensive answer with source URLs.
+
+Use for: current information, documentation lookups, API references, comparing libraries, and research questions.
+
+Cost: Typically ~$0.02-0.05/search with Sonnet.
+
+Tips:
+- Ask specific, focused questions for best results.
+- Results include source URLs for verification.
+- Use maxResponseLength to control response verbosity.
+- Increase timeout for complex research queries that may require multiple web fetches.`;
+export const structuredDescription = `Generate JSON conforming to a provided JSON Schema. Uses Claude CLI's native --json-schema flag for validated output (not client-side validation).
+
+Use for: data extraction from text/files, classification, entity parsing, or any task needing machine-parseable output.
+
+Cost: Similar to query (~$0.01-0.10/call). Schema complexity doesn't significantly affect cost.
+
+Tips:
+- Pass the JSON Schema as a JSON string in the schema parameter.
+- Schema max size: 20KB. Keep schemas focused for reliable output.
+- For extraction tasks, include source text via the files parameter or inline in the prompt.`;
+export const listSessionsDescription = `List active Claude CLI sessions tracked by this server. Returns session metadata (IDs, models, timing, turn counts, cumulative cost) for orchestration. Use to check available sessions before resuming with sessionId. No cost (local lookup only).`;
+export const pingDescription = `Health check: verifies Claude CLI is installed and authenticated, reports versions, capabilities, and configuration. No cost (local check only).`;
+//# sourceMappingURL=descriptions.js.map

package/dist/descriptions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"descriptions.js","sourceRoot":"","sources":["../src/descriptions.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,MAAM,CAAC,MAAM,gBAAgB,GAAG;;;;;;;;;;;8DAW8B,CAAC;AAE/D,MAAM,CAAC,MAAM,iBAAiB,GAAG;;;;;;;;;;;+FAW8D,CAAC;AAEhG,MAAM,CAAC,MAAM,iBAAiB,GAAG;;;;;;;;;;uFAUsD,CAAC;AAExF,MAAM,CAAC,MAAM,qBAAqB,GAAG;;;;;;;;;6FASwD,CAAC;AAE9F,MAAM,CAAC,MAAM,uBAAuB,GAAG,sPAAsP,CAAC;AAE9R,MAAM,CAAC,MAAM,eAAe,GAAG,kJAAkJ,CAAC"}