@leo000001/claude-code-mcp 2.0.3 → 2.2.0

package/CHANGELOG.md

@@ -2,6 +2,59 @@
 
 ## Unreleased
 
+### Improvements
+
+- Add `CLAUDE_CODE_MCP_MAX_SESSIONS` (default: `128`) to cap in-memory session count and reduce risk of memory exhaustion.
+- Add `CLAUDE_CODE_MCP_MAX_PENDING_PERMISSIONS` (default: `64`) to cap outstanding permission requests per session.
+- Promote `effort` and `thinking` to top-level parameters on `claude_code` and `claude_code_reply` (deprecated aliases: `advanced.effort`, `advanced.thinking`).
+- Tool responses now include `structuredContent` (in addition to JSON text) for easier MCP client consumption.
+- Emit `tools/list_changed` and `resources/list_changed` once after connect; update `claude_code` tool description dynamically when runtime tool discovery changes.
+- Align declared MCP capabilities with implemented primitives (`logging`, `tools`, `resources`) and remove prompt primitive exposure.
+- Add unit tests for `build-options.ts` and `race-with-abort.ts`.
+
+### Bug Fixes
+
+- Fork resume: restore original session state before creating the forked session record to avoid a brief `AbortController` sharing window.
+- Session totals: prevent `totalTurns`/`totalCostUsd` from being overwritten when SDK-provided session totals look incremental.
+- Permission audit: include allow-side `updatedInput`/`updatedPermissions` in `permission_result` events.
+
+### Refactors
+
+- Extract shared Zod schema fields for `advanced` and `diskResumeConfig` in `src/server.ts`.
+- Deduplicate `SessionManager.create()` call payloads via a shared helper.
+- Remove `server.close` monkey-patch; perform `sessionManager.destroy()` in the shutdown flow.
+
+### Documentation
+
+- Changelog: move released 2.x items out of `Unreleased` and add missing 2.0.0–2.0.3 entries.
+- SECURITY: update supported versions table for 2.x.
+- Docs: clarify same-platform assumption (MCP server and client run on the same machine) across README, AGENTS, SECURITY, and mcp_demo.
+
+## 2.0.3 (2026-02-15)
+
+### Improvements
+
+- Version bump only.
+
+## 2.0.2 (2026-02-15)
+
+### Features
+
+- MCP resources: `server-info`, `internal-tools`, and `gotchas`
+- Permission workflow: include timeout/expiration metadata in permission actions; support `updatedInput` normalization
+
+### Bug Fixes
+
+- Windows: normalize MSYS-style paths for `NotebookEdit` where possible
+
+## 2.0.1 (2026-02-15)
+
+### Improvements
+
+- Refined server schema descriptions/default annotations to reduce token overhead for calling models
+
+## 2.0.0 (2026-02-15)
+
 ### Breaking Changes
 
 - `claude_code` and `claude_code_reply` now start asynchronously and return `{ sessionId, status: "running", pollInterval }`. Use `claude_code_check` to poll events and fetch the final `result`.
@@ -11,7 +64,6 @@
   - `claude_code`: 22 low-frequency params moved into `advanced` object (e.g. `effort` → `advanced.effort`, `tools` → `advanced.tools`, `agents` → `advanced.agents`, `env` → `advanced.env`)
   - `claude_code_reply`: 28 disk-resume params moved into `diskResumeConfig` object (e.g. `resumeToken` → `diskResumeConfig.resumeToken`, `cwd` → `diskResumeConfig.cwd`)
   - `claude_code_check`: 9 poll control params moved into `pollOptions` object (e.g. `includeTools` → `pollOptions.includeTools`); 2 permission response params moved into `permissionOptions` object (e.g. `updatedInput` → `permissionOptions.updatedInput`)
-  - Schema descriptions for nested object fields have been compacted (self-explanatory fields no longer carry `.describe()` text; object-level descriptions enhanced as summaries) to reduce token overhead for calling models
 
 ### Features
 
@@ -28,10 +80,8 @@
 - `claude_code_check`: minimal mode filters out noisy progress events (`tool_progress`, `auth_status`); use `includeProgressEvents: true` to restore
 - `claude_code_check`: minimal mode omits `lastEventId`/`lastToolUseId` from top-level response and `durationApiMs`/`sessionTotalTurns`/`sessionTotalCostUsd` from AgentResult
 - `claude_code_check`: includes lightweight session diagnostics (`cancelledAt`/`cancelledReason`/`cancelledSource`, `lastEventId`, `lastToolUseId`)
-- `claude_code_check`: permission actions now include `timeoutMs`, `expiresAt`, and best-effort `remainingMs`
 - Permission result events now include `toolName`, and denial details (`message`, `interrupt`) when applicable
 - Disk resume security: disk resume fallback requires `CLAUDE_CODE_MCP_RESUME_SECRET` + `resumeToken`
-- MCP resources: server info, internal tool catalog, and gotchas
 
 ## 1.6.0 (2026-02-12)
 

package/CONTRIBUTING.md

@@ -35,7 +35,7 @@ npm install
 
 - Keep PRs focused on a single change
 - Include tests for new functionality
-- Update documentation (README, DESIGN.md) if the public API changes
+- Update documentation (README, docs/DESIGN.md) if the public API changes
 - Ensure CI passes before requesting review
 
 ## Reporting Issues
@@ -43,3 +43,12 @@ npm install
 - Use GitHub Issues for bug reports and feature requests
 - Include reproduction steps for bugs
 - For security vulnerabilities, see [SECURITY.md](SECURITY.md)
+
+## Release Checklist
+
+1. Update `CHANGELOG.md` with the upcoming version and confirm `package.json` reflects that version.
+2. Run `npm run format:check`, `npm run lint`, `npm run typecheck` (now covers `src` + `tests`), and `npm test` to prove the working tree is clean.
+3. Build the bundle (`npm run build`) and verify `dist/` contains the expected entry points.
+4. Refresh any documentation (README/CONTRIBUTING/docs) that describe public behavior or APIs touched by the release.
+5. Ensure `NOTICE.md` lists the third-party components bundled in the release and contains links or pointers to their licenses.
+6. Double-check `files`, `bin`, and other package metadata so the published package only ships the intended assets.

package/NOTICE.md

@@ -0,0 +1,27 @@
+# NOTICE
+
+This project (`@leo000001/claude-code-mcp`) is licensed under the MIT License (see `LICENSE`).
+
+## Third-party components
+
+This project depends on third-party packages. Their licenses and terms may impose additional
+requirements on redistribution and use.
+
+### Direct dependencies (from `package.json`)
+
+- `@anthropic-ai/claude-agent-sdk@0.2.38` — license is declared as “SEE LICENSE IN README.md” in the package metadata. This package bundles a Claude Code CLI; please review Anthropic's documentation and legal terms referenced by that project before redistributing or deploying.
+- `@modelcontextprotocol/sdk@1.26.0` — MIT License
+- `zod@4.3.6` — MIT License
+
+For a complete dependency graph, see `package-lock.json`. When installed, each dependency’s
+license information is included with the package itself (typically under its `LICENSE` file or
+`package.json` fields).
+
+### Optional native dependencies
+
+Some optional dependencies pulled in by the Claude Agent SDK (or its transitive dependencies)
+may include prebuilt native binaries with licenses such as LGPL. These packages are platform-
+specific (e.g., `@img/sharp-*` and related `libvips` packages).
+
+If you redistribute this project (or produce bundled artifacts), you are responsible for ensuring
+you comply with any applicable third-party license obligations and include required notices.

package/README.md

@@ -4,13 +4,14 @@
 [![license](https://img.shields.io/npm/l/@leo000001/claude-code-mcp.svg)](https://github.com/xihuai18/claude-code-mcp/blob/HEAD/LICENSE)
 [![node](https://img.shields.io/node/v/@leo000001/claude-code-mcp.svg)](https://nodejs.org)
 
-MCP server that wraps [Claude Code (Claude Agent SDK)](https://docs.anthropic.com/en/docs/claude-code/overview) as tools, enabling any MCP client to invoke Claude Code for autonomous coding tasks.
+MCP server that wraps [Claude Code (Claude Agent SDK)](https://docs.anthropic.com/en/docs/claude-code/overview) as tools, enabling any MCP client to invoke Claude Code for autonomous coding tasks. Designed for local use — the MCP server and client are expected to run on the same machine.
 
 Inspired by the [Codex MCP](https://developers.openai.com/codex/guides/agents-sdk/) design philosophy — minimum tools, maximum capability.
 
 ## Features
 
 - **4 tools** covering the full agent lifecycle: start, continue, check/poll, manage
+- **Read-only MCP resources** for server info, internal tool catalog, and compatibility diagnostics
 - **Session management** with resume and fork support
 - **Local settings loaded by default** — automatically reads `~/.claude/settings.json`, `.claude/settings.json`, `.claude/settings.local.json`, and `CLAUDE.md` so the agent behaves like your local Claude Code CLI
 - **Async permissions** — allow/deny lists + explicit approvals via `claude_code_check`
@@ -20,9 +21,12 @@ Inspired by the [Codex MCP](https://developers.openai.com/codex/guides/agents-sd
 - **Auto-cleanup** — 30-minute idle timeout for expired sessions
 - **Security** — callers control tool permissions via allow/deny lists + explicit permission decisions
 
+See `CHANGELOG.md` for release history.
+
 ## Prerequisites
 
 - **Node.js >= 18** is required.
+- **Same-platform deployment** — this MCP server is designed to run on the same machine as the MCP client. It communicates via stdio (child process), reads local Claude configuration files from `~/.claude/`, and accesses the local file system directly. Remote deployment is not supported.
 
 This MCP server uses the [`@anthropic-ai/claude-agent-sdk`](https://www.npmjs.com/package/@anthropic-ai/claude-agent-sdk) package, which **bundles its own Claude Code CLI** (`cli.js`). It does not use the `claude` binary from your system PATH.
 
@@ -56,6 +60,14 @@ Add to your MCP client configuration (Claude Desktop, Cursor, etc.):
 }
 ```
 
+> Some clients cache tool definitions at connect-time. This server emits `notifications/tools/list_changed` after runtime tool discovery so clients can refresh the `claude_code` tool description.
+
+### Anthropic Claude Code CLI (as an MCP client)
+
+```bash
+claude mcp add --transport stdio claude-code -- npx -y @leo000001/claude-code-mcp
+```
+
 ### OpenAI Codex CLI
 
 ```bash
@@ -96,26 +108,27 @@ Start a new Claude Code session. The agent autonomously performs coding tasks: r
 | `disallowedTools`            | string[]         | No       | Forbidden tool names. Default: `[]` (none). SDK behavior: disallowed tools are removed from the model's context. Takes precedence over `allowedTools` and will be denied even if later approved interactively |
 | `maxTurns`                   | number           | No       | Maximum number of agent reasoning steps. Each step may involve one or more tool calls. Default: SDK/Claude Code default                                                                                       |
 | `model`                      | string           | No       | Model to use (e.g. `"claude-sonnet-4-5-20250929"`). Default: SDK/Claude Code default                                                                                                                          |
+| `effort`                     | string           | No       | Effort level: `"low"`, `"medium"`, `"high"`, `"max"`. Default: SDK/Claude Code default                                                                                                                                                 |
+| `thinking`                   | object           | No       | Thinking mode: `{ type: "adaptive" }`, `{ type: "enabled", budgetTokens: N }`, or `{ type: "disabled" }`. Default: SDK/Claude Code default                                                                                             |
 | `systemPrompt`               | string \| object | No       | Override the agent's system prompt. Default: SDK/Claude Code default. Pass a string for full replacement, or `{ type: "preset", preset: "claude_code", append?: "..." }` to extend the default prompt         |
-| `permissionRequestTimeoutMs` | number           | No       | Timeout in milliseconds waiting for permission decisions. Default: `60000`                                                                                                                                    |
+| `permissionRequestTimeoutMs` | number           | No       | Timeout in milliseconds waiting for permission decisions, auto-deny on expiry. Default: `60000` (server-clamped to 5min)                                                                                                            |
+| `sessionInitTimeoutMs`       | number           | No       | **Compatibility alias** for `advanced.sessionInitTimeoutMs` (deprecated for `claude_code`). Default: `10000`. If both are provided, `advanced.sessionInitTimeoutMs` wins                                                                 |
 | `advanced`                   | object           | No       | Advanced/low-frequency parameters (see below)                                                                                                                                                                 |
 
 <details>
-<summary><code>advanced</code> object parameters (22 low-frequency parameters)</summary>
+<summary><code>advanced</code> object parameters (20 low-frequency parameters)</summary>
 
 | Parameter                             | Type               | Description                                                                                                                                                                                                                            |
 | ------------------------------------- | ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `advanced.tools`                      | string[] \| object | Define the base tool set. Default: SDK/Claude Code default toolset. Array of tool name strings, or `{ type: "preset", preset: "claude_code" }` for the default toolset. `allowedTools`/`disallowedTools` further filter on top of this |
 | `advanced.persistSession`             | boolean            | Persist session history to disk (`~/.claude/projects/`). Default: `true`. Set `false` to disable.                                                                                                                                      |
-| `advanced.sessionInitTimeoutMs`       | number             | Timeout in milliseconds waiting for `system/init`. Default: `10000`                                                                                                                                                                    |
+| `advanced.sessionInitTimeoutMs`       | number             | Session init timeout in milliseconds waiting for `system/init`. Default: `10000`. **Recommended location for `claude_code` callers.**                                                                                                                                    |
 | `advanced.agents`                     | object             | Define custom sub-agents the main agent can delegate tasks to. Default: none. SDK default: if a sub-agent omits `tools`, it inherits all tools from the parent.                                                                        |
 | `advanced.agent`                      | string             | Name of a custom agent (defined in `agents`) to use as the primary agent. Default: omitted                                                                                                                                             |
 | `advanced.maxBudgetUsd`               | number             | Maximum budget in USD. Default: SDK/Claude Code default                                                                                                                                                                                |
-| `advanced.effort`                     | string             | Effort level: `"low"`, `"medium"`, `"high"`, `"max"`. Default: SDK/Claude Code default                                                                                                                                                 |
 | `advanced.betas`                      | string[]           | Beta features (e.g. `["context-1m-2025-08-07"]`). Default: none                                                                                                                                                                        |
 | `advanced.additionalDirectories`      | string[]           | Additional directories the agent can access beyond cwd. Default: none                                                                                                                                                                  |
 | `advanced.outputFormat`               | object             | Structured output: `{ type: "json_schema", schema: {...} }`. Default: omitted (plain text)                                                                                                                                             |
-| `advanced.thinking`                   | object             | Thinking mode: `{ type: "adaptive" }`, `{ type: "enabled", budgetTokens: N }`, or `{ type: "disabled" }`. Default: SDK/Claude Code default                                                                                             |
 | `advanced.pathToClaudeCodeExecutable` | string             | Path to the Claude Code executable. Default: SDK-bundled Claude Code (cli.js)                                                                                                                                                          |
 | `advanced.mcpServers`                 | object             | MCP server configurations (key: server name, value: server config). Default: none                                                                                                                                                      |
 | `advanced.sandbox`                    | object             | Sandbox configuration for isolating shell command execution (e.g., Docker container settings). Default: SDK/Claude Code default                                                                                                        |
@@ -128,6 +141,8 @@ Start a new Claude Code session. The agent autonomously performs coding tasks: r
 | `advanced.debugFile`                  | string             | Write debug logs to a specific file path (implicitly enables debug mode). Default: omitted                                                                                                                                             |
 | `advanced.env`                        | object             | Environment variables to merge with process.env and pass to the Claude Code process (user values take precedence). Default: inherit process.env                                                                                        |
 
+Deprecated aliases: `advanced.effort` and `advanced.thinking` are still accepted for compatibility, but prefer top-level `effort` / `thinking` (top-level wins if both are set).
+
 </details>
 
 **Returns:** `{ sessionId, status: "running", pollInterval, resumeToken? }`
@@ -136,6 +151,7 @@ Notes:
 
 - `resumeToken` is omitted by default, and is only returned when `CLAUDE_CODE_MCP_RESUME_SECRET` is set on the server.
 - On error: `{ sessionId: "", status: "error", error }`
+- If `sessionInitTimeoutMs` (top-level alias) is used, `claude_code` may return `compatWarnings` to guide migration to `advanced.sessionInitTimeoutMs`.
 
 Use `claude_code_check` to poll events and obtain the final `result`.
 
@@ -156,8 +172,10 @@ Continue an existing session by sending a follow-up message. The agent retains f
 | `sessionId`                  | string  | Yes      | Session ID from a previous `claude_code` call                                                                        |
 | `prompt`                     | string  | Yes      | Follow-up prompt                                                                                                     |
 | `forkSession`                | boolean | No       | Create a branched copy of this session. Default: `false`                                                             |
-| `permissionRequestTimeoutMs` | number  | No       | Timeout in milliseconds waiting for permission decisions. Default: `60000`                                           |
-| `sessionInitTimeoutMs`       | number  | No       | Timeout in milliseconds waiting for fork `system/init`. Default: `10000`                                             |
+| `effort`                     | string  | No       | Effort level override for this run (and for future replies when not forking). Default: SDK/Claude Code default      |
+| `thinking`                   | object  | No       | Thinking mode override for this run (and for future replies when not forking). Default: SDK/Claude Code default     |
+| `permissionRequestTimeoutMs` | number  | No       | Timeout in milliseconds waiting for permission decisions, auto-deny on expiry. Default: `60000`                      |
+| `sessionInitTimeoutMs`       | number  | No       | Fork init timeout in milliseconds (only when `forkSession=true`). Default: `10000`                                   |
 | `diskResumeConfig`           | object  | No       | Disk resume parameters (see below). Used when `CLAUDE_CODE_MCP_ALLOW_DISK_RESUME=1` and in-memory session is missing |
 
 <details>
@@ -211,7 +229,8 @@ Gotchas:
 - Permission approvals have a timeout (default 60s via `permissionRequestTimeoutMs`) and will auto-deny; watch `actions[].expiresAt` / `actions[].remainingMs`.
 - `Read` has a per-call size cap in practice (often ~256KB); for large files use `offset`/`limit` or chunk with `Grep`.
 - `Edit` with `replace_all=true` is substring replacement; if no match is found the tool returns a clear error.
-- `NotebookEdit` expects native Windows paths (e.g. `D:\path\file.ipynb`); this server normalizes MSYS paths like `/d/...` when possible.
+- On Windows, this server normalizes common MSYS-style paths (e.g. `/d/...`, `/mnt/c/...`, `/cygdrive/c/...`, `//server/share/...`) for `cwd`, `additionalDirectories`, and tool inputs that include `file_path`.
+- On Windows, POSIX home paths like `/home/user/...` are **not** rewritten to drive paths; prefer absolute Windows paths under your current `cwd` to avoid out-of-bounds permission prompts.
 - `TeamDelete` may require members to reach `shutdown_approved` (otherwise you may see "active member" errors); cleanup can be asynchronous during shutdown.
 - Skills may become available later in the same session (early calls may show "Unknown", later succeed after skills are loaded/registered).
 - Some internal features (e.g. ToolSearch) may not appear in `availableTools` (derived from SDK `system/init.tools`).
@@ -220,9 +239,10 @@ Gotchas:
 
 If your MCP client supports resources, this server exposes a couple of **read-only** MCP resources:
 
-- `claude-code-mcp:///server-info` (JSON): static server metadata (version/platform/runtime)
-- `claude-code-mcp:///internal-tools` (JSON): internal tool catalog (static + runtime-discovered)
+- `claude-code-mcp:///server-info` (JSON): server metadata (version/platform/runtime)
+- `claude-code-mcp:///internal-tools` (JSON): internal tool catalog (runtime-aware)
 - `claude-code-mcp:///gotchas` (Markdown): practical limits/gotchas
+- `claude-code-mcp:///compat-report` (JSON): compatibility report (transport/platform assumptions, runtime warnings, guidance)
 
 **Disk resume (optional):** By default, `claude_code_reply` requires the session to exist in the MCP server's in-memory Session Manager. If you set `CLAUDE_CODE_MCP_ALLOW_DISK_RESUME=1`, it can attempt to resume using the Claude Code CLI's on-disk transcript even when the in-memory session is missing (e.g. after a restart / TTL cleanup). For safety, disk resume fallback requires `CLAUDE_CODE_MCP_RESUME_SECRET` to be set on the server and requires callers to pass `diskResumeConfig.resumeToken` (returned by `claude_code` / `claude_code_reply` when `CLAUDE_CODE_MCP_RESUME_SECRET` is set).
 
@@ -257,7 +277,7 @@ Poll session events/results and approve/deny pending permission requests.
 | `permissionOptions` | object  | No                     | Advanced permission response options (see below)                                                               |
 
 <details>
-<summary><code>pollOptions</code> object parameters (9 fine-grained poll controls)</summary>
+<summary><code>pollOptions</code> object parameters (10 fine-grained poll controls)</summary>
 
 | Parameter                             | Type    | Description                                                                                                                                                                             |
 | ------------------------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
@@ -270,6 +290,7 @@ Poll session events/results and approve/deny pending permission requests.
 | `pollOptions.includeStructuredOutput` | boolean | Include `result.structuredOutput` (default: true in full mode, false in minimal mode)                                                                                                   |
 | `pollOptions.includeTerminalEvents`   | boolean | When true, keeps terminal `result`/`error` events in `events` even if top-level `result` is included. Default: `false` in `"minimal"`, `true` in `"full"`                               |
 | `pollOptions.includeProgressEvents`   | boolean | When true, includes progress events (`tool_progress`, `auth_status`) in the events stream. Default: `false` in `"minimal"`, `true` in `"full"`                                          |
+| `pollOptions.maxBytes`                | number  | Approximate max JSON bytes for `events` in this response. When exceeded, events are truncated and `truncatedFields` includes `"events_bytes"`. Default: unlimited                         |
 
 </details>
 
@@ -283,7 +304,7 @@ Poll session events/results and approve/deny pending permission requests.
 
 </details>
 
-**Returns (poll and respond_permission):** `{ sessionId, status, pollInterval?, cursorResetTo?, truncated?, truncatedFields?, events, nextCursor?, availableTools?, actions?, result?, cancelledAt?, cancelledReason?, cancelledSource?, lastEventId?, lastToolUseId? }`
+**Returns (poll and respond_permission):** `{ sessionId, status, pollInterval?, cursorResetTo?, truncated?, truncatedFields?, events, nextCursor?, availableTools?, toolValidation?, compatWarnings?, actions?, result?, cancelledAt?, cancelledReason?, cancelledSource?, lastEventId?, lastToolUseId? }`
 
 Notes:
 
@@ -292,6 +313,9 @@ Notes:
 - If `cursorResetTo` is present, your `cursor` was too old (events were evicted); reset your cursor to `cursorResetTo`.
 - For safety, de-duplicate events by `event.id` on the client side.
 - If `truncated=true`, the server intentionally limited the payload (e.g. `maxEvents`) — continue polling with `nextCursor`.
+- `nextCursor` can remain unchanged with `events=[]` during quiet intervals; this is normal transient behavior. Retry a few times (for example up to 3) before treating it as abnormal.
+- `toolValidation` reports whether configured `allowedTools`/`disallowedTools` match runtime-discovered tool names.
+- `compatWarnings` surfaces compatibility hints (for example, unresolved tool names or path/platform mismatch signals) and is **non-blocking**; treat it as advisory unless the session actually fails.
 - Permission `actions[]` include `timeoutMs`, `expiresAt`, and best-effort `remainingMs` to help callers avoid auto-deny timeouts.
 - `permission_result` event data is `{ requestId, toolName, behavior, source, message?, interrupt? }` (denial details only present for `deny`).
 - In `"minimal"` mode (default): assistant message events are slimmed (strips `usage`, `model`, `id`, `cache_control` from content blocks); noisy progress events (`tool_progress`, `auth_status`) are filtered out; `lastEventId`/`lastToolUseId` are omitted; `AgentResult` omits `durationApiMs`/`sessionTotalTurns`/`sessionTotalCostUsd`. Use `responseMode: "full"` or individual `include*` flags to restore any of these.
@@ -304,13 +328,13 @@ start = await mcp.call_tool("claude_code", {
     "prompt": "Fix the authentication bug in src/auth.ts",
     "cwd": "/path/to/project",
     "allowedTools": ["Read", "Edit", "Bash", "Glob", "Grep"],
+    "effort": "high",
     "advanced": {
-        "effort": "high",
         "maxBudgetUsd": 5.0
     }
 })
 session_id = json.loads(start)["sessionId"]
-cursor = None
+cursor = 0
 
 # 2) Poll until idle/error/cancelled
 while True:
@@ -354,7 +378,7 @@ Claude Code on Windows requires git-bash (https://git-scm.com/downloads/win).
 
 This means the spawned CLI process cannot locate `bash.exe`. Your locally installed `claude` command may work fine — the issue is that the MCP server's child process may not inherit your shell environment.
 
-**Fix: set `CLAUDE_CODE_GIT_BASH_PATH` in your MCP server config.**
+`claude-code-mcp` will try to auto-detect Git Bash from common install locations and set `CLAUDE_CODE_GIT_BASH_PATH` for child processes. If you still see this error, set `CLAUDE_CODE_GIT_BASH_PATH` explicitly in your MCP server config:
 
 For JSON-based MCP clients (Claude Desktop, Cursor, etc.):
 
@@ -407,6 +431,7 @@ setx CLAUDE_CODE_GIT_BASH_PATH "C:\Program Files\Git\bin\bash.exe"
   - Use `disallowedTools` to hard-block tools; they are denied even if later approved via `claude_code_check`.
 - `maxTurns` and `advanced.maxBudgetUsd` prevent runaway execution.
 - Sessions auto-expire after 30 minutes of inactivity.
+- Vulnerability reporting: see `SECURITY.md`.
 
 ## Environment Variables
 
@@ -417,6 +442,8 @@ All environment variables are optional. They are set on the MCP server process (
 | `CLAUDE_CODE_GIT_BASH_PATH`         | Path to `bash.exe` on Windows (see [Windows Support](#windows-support))                                          | Auto-detected  |
 | `CLAUDE_CODE_MCP_ALLOW_DISK_RESUME` | Set to `1` to allow `claude_code_reply` to resume from on-disk transcripts when the in-memory session is missing | `0` (disabled) |
 | `CLAUDE_CODE_MCP_RESUME_SECRET`     | HMAC secret used to validate `resumeToken` for disk resume fallback (recommended if disk resume is enabled)      | _(unset)_      |
+| `CLAUDE_CODE_MCP_MAX_SESSIONS`      | Maximum number of in-memory sessions (set `0` to disable the limit)                                              | `128`          |
+| `CLAUDE_CODE_MCP_MAX_PENDING_PERMISSIONS` | Maximum number of outstanding permission requests per session (set `0` to disable the limit)                | `64`           |
 
 ### How to configure
 
@@ -471,10 +498,32 @@ npm test             # Run tests with vitest
 npm run dev          # Watch mode build
 ```
 
+### E2E regression commands
+
+```bash
+# Run cancel->poll regression loop (single mode)
+npm run e2e:stdio:cancel
+
+# Run waiting_permission + cancel regression loop
+npm run e2e:stdio:cancel:wp
+
+# Run both modes and output one summary report
+npm run e2e:stdio:runner
+```
+
+### E2E notes (Codex and other clients)
+
+- Some clients do not expose `tools/list` directly in the chat loop. In those clients, treat "tool is callable" as the primary discovery signal, and use `tools/list` only when available.
+- `allowedTools: ["Read", "Write"]` does not guarantee the model will never attempt `Bash`. For deterministic smoke tests, add `disallowedTools: ["Bash"]` and state "do not use Bash" in the prompt.
+- For `claude_code_session(action="get", includeSensitive=true)`, only assert fields that were actually configured. Optional fields that were never set may be omitted.
+- If a client reports `Transport closed` during E2E cleanup, reconnect the MCP server first, then run `claude_code_session(action="list")` and cancel any remaining `running` / `waiting_permission` sessions.
+
+For an end-to-end local test plan (third-party CLI/client integration + real coding tasks), see `docs/E2E_LOCAL_TEST_PLAN.md`.
+
 ## Architecture
 
 ```
-MCP Client ←→ (stdio/JSON-RPC) ←→ MCP Server
+MCP Client ←→ (stdio/JSON-RPC) ←→ MCP Server     [same machine]
                                       ├── Session Manager (Map<id, state>)
                                       └── Claude Agent SDK (query())
 ```
@@ -494,6 +543,7 @@ MCP server validation/policy errors are returned as `Error [CODE]: message` wher
 - `SESSION_BUSY` — session currently running
 - `PERMISSION_DENIED` — operation not allowed by server policy
 - `PERMISSION_REQUEST_NOT_FOUND` — permission request ID not found (already finished or expired)
+- `RESOURCE_EXHAUSTED` — resource limit reached (e.g. max sessions or max pending permissions)
 - `TIMEOUT` — operation timed out
 - `CANCELLED` — session was cancelled
 - `INTERNAL` — unexpected error or protocol mismatch
@@ -510,3 +560,4 @@ See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup and guidelines.
 
 - [Security Policy](SECURITY.md)
 - [Code of Conduct](CODE_OF_CONDUCT.md)
+- [Third-party Notices](NOTICE.md)

package/SECURITY.md

@@ -4,7 +4,8 @@
 
 | Version | Supported |
 | ------- | --------- |
-| 1.x     | Yes       |
+| 2.x     | Yes       |
+| 1.x     | No        |
 
 ## Reporting a Vulnerability
 
@@ -18,9 +19,11 @@ We aim to acknowledge reports within 48 hours and provide a fix or mitigation pl
 
 ## Security Considerations
 
+- This MCP server is designed for local use only — the server and client must run on the same machine. It communicates via stdio (child process), reads local configuration from `~/.claude/`, and accesses the local file system directly. Remote deployment is not supported.
 - This server uses an async permission flow: when a tool call needs approval, the session pauses (`waiting_permission`) and surfaces requests via `claude_code_check` (`actions[]`). Callers must explicitly approve/deny via `respond_permission`.
 - The MCP server uses the Claude Agent SDK's bundled CLI (`cli.js`), not the system-installed `claude` binary
 - Session metadata is held in-memory only and is not persisted to disk by the MCP server (the SDK's CLI persists conversation history separately)
+- To reduce memory exhaustion risk, the server caps in-memory session count via `CLAUDE_CODE_MCP_MAX_SESSIONS` (default: `128`).
 - Disk resume is disabled by default (`CLAUDE_CODE_MCP_ALLOW_DISK_RESUME=0`). If you set `CLAUDE_CODE_MCP_ALLOW_DISK_RESUME=1`, disk resume fallback also requires `CLAUDE_CODE_MCP_RESUME_SECRET` (default: unset) and a valid `resumeToken` from `claude_code`/`claude_code_reply`.
 - `claude_code_session` redacts sensitive fields (cwd, systemPrompt, agents, additionalDirectories) by default; use `includeSensitive=true` to include them
 - Sessions auto-expire after 30 minutes of inactivity

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+
+export {  }