claude-mcp-bridge 0.1.0 → 0.3.0

package/README.md

@@ -44,7 +44,9 @@ claude -p --bare --max-budget-usd 0.50 "Is this retry logic sound?"
 
 - Node.js >= 18
 - [Claude Code CLI](https://github.com/anthropics/claude-code) installed and on PATH
-- `ANTHROPIC_API_KEY` set for bare mode
+- 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
 
@@ -201,25 +203,58 @@ Web search via Claude Code CLI using WebSearch and WebFetch tools.
 | `maxBudgetUsd` | number | | Cost cap in USD |
 | `effort` | string | `medium` | `low`, `medium`, `high`, or `max` |
 
+### `listSessions`
+
+List active Claude CLI sessions tracked by this server. Returns session metadata for orchestration.
+
+```json
+[
+  {
+    "sessionId": "abc-123",
+    "model": "sonnet",
+    "createdAt": 1712700000000,
+    "lastUsedAt": 1712703600000,
+    "turnCount": 5,
+    "totalCostUsd": 0.23
+  }
+]
+```
+
+No parameters. Sessions are stored in-memory (TTL 24h, LRU eviction at 100). Use to check available sessions before resuming with `sessionId`.
+
 ### `ping`
 
 Health check. No parameters. Returns CLI availability, auth status, configured models, server version, and capability flags.
 
 ```
 cliFound: true
-version: 1.0.33 (Claude Code)
-authStatus: ok
+version: 2.1.92 (Claude Code)
+authMethod: subscription
+subscriptionType: max
 defaultModel: sonnet
 fallbackModel: haiku
 serverVersion: 0.1.0
-nodeVersion: v22.12.0
+nodeVersion: v22.22.0
 maxConcurrent: 3
 capabilities: bareMode=true, jsonOutput=true, jsonSchema=true, sessionResume=true
 ```
 
+`authMethod` is one of: `api-key` (ANTHROPIC_API_KEY set), `subscription` (logged in via `claude login`), or `none`.
+
 ## Configuration
 
-All configuration is through environment variables. None are required if Claude CLI is on PATH and `ANTHROPIC_API_KEY` is already set in your environment.
+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
 
@@ -280,6 +315,37 @@ CLI output is scanned for sensitive patterns before being returned: Anthropic AP
 | Hard timeout cap | 10 minutes |
 | Concurrency queue timeout | 30 seconds |
 
+## Response metadata
+
+Every tool response includes a `_meta` object with execution metadata:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `durationMs` | number | Wall-clock execution time |
+| `model` | string? | Model used (e.g. "sonnet", "opus") |
+| `sessionId` | string? | Session ID for resume |
+| `totalCostUsd` | number? | Cost for this call in USD |
+| `inputTokens` | number? | Input tokens consumed |
+| `outputTokens` | number? | Output tokens generated |
+| `cacheReadTokens` | number? | Tokens read from prompt cache |
+| `timedOut` | boolean? | `true` if subprocess exceeded timeout (omitted otherwise) |
+
+All tools also declare [MCP annotations](https://modelcontextprotocol.io/specification/2025-06-18/server/tools#annotations) (`readOnlyHint`, `destructiveHint`, `idempotentHint`, `openWorldHint`) so clients can make informed permission and safety decisions.
+
+## Sessions
+
+Session state is tracked in-memory across calls. When a tool returns a `sessionId` in `_meta`, pass it back on subsequent calls to resume the conversation via Claude CLI's `--resume` flag.
+
+- **Cumulative cost**: `totalCostUsd` in `_meta` is the cost for that call only. Cumulative cost across turns is tracked per-session and visible via `listSessions`
+- **Reset**: Pass `resetSession: true` on the query tool to clear stored state and start fresh
+- **TTL**: Sessions expire after 24 hours of inactivity
+- **Capacity**: LRU eviction at 100 sessions (oldest by `lastUsedAt` is evicted)
+- **Ephemeral**: Session state is in-memory only, lost on server restart
+
+## Progress notifications
+
+Query, review, and search tools emit MCP [`notifications/progress`](https://modelcontextprotocol.io/specification/2025-06-18/server/utilities/progress) during subprocess execution when the client provides a `progressToken` in the request's `_meta`. Heartbeats fire every 15 seconds with elapsed time. Notifications are fire-and-forget; clients that don't support progress notifications are unaffected.
+
 ## 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.

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: 5 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,mhCAWiE,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: 5 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"}