npm - @leo000001/claude-code-mcp - Versions diffs - 2.0.3 → 2.2.0 - Mend

@leo000001/claude-code-mcp 2.0.3 → 2.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (9) hide show

package/CHANGELOG.md CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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 ADDED Viewed

@@ -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 CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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 ADDED Viewed

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