@leo000001/claude-code-mcp 2.8.3 → 2.8.6

package/CHANGELOG.md

@@ -8,7 +8,7 @@
 - Expand SDK stream/event mapping for `rate_limit_event`, `system/api_retry`, `system/local_command_output`, `system/elicitation_complete`, `system/compact_boundary`, and partial `stream_event` output.
 - Preserve newer SDK metadata in session/results, including `fastModeState` and richer permission prompt labels (`title`, `displayName`).
 - Prefer SDK permission `suggestions` for `allow_for_session` responses and sync session metadata from `system/init` (for example actual model / permission mode).
-- Add default Claude executable resolution with explicit env overrides (`CLAUDE_CODE_MCP_DEFAULT_CLAUDE_PATH` / `CLAUDE_CODE_MCP_DEFAULT_CLAUDE_COMMAND`) and auto-detection order `claude` -> `claude-internal` -> SDK-bundled.
+- Add default Claude executable resolution with explicit env overrides (`CLAUDE_CODE_MCP_PATH` / `CLAUDE_CODE_MCP_COMMAND`) and auto-detection order `claude` -> `claude-internal` -> SDK-bundled.
 
 ### Documentation
 

package/README.md

@@ -43,7 +43,7 @@ See `CHANGELOG.md` for release history.
 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`). When no explicit `pathToClaudeCodeExecutable` is provided, this server now prefers a detected local `claude` command, then `claude-internal`, and falls back to the SDK-bundled CLI if neither is found.
 
 - The SDK bundles a Claude Code CLI; its version generally tracks the SDK package version, but the exact scheme is not guaranteed
-- Default executable resolution order is: request-level `pathToClaudeCodeExecutable` -> `CLAUDE_CODE_MCP_DEFAULT_CLAUDE_PATH` -> `CLAUDE_CODE_MCP_DEFAULT_CLAUDE_COMMAND` -> auto-detected `claude` -> auto-detected `claude-internal` -> SDK-bundled CLI
+- Default executable resolution order is: request-level `pathToClaudeCodeExecutable` -> `CLAUDE_CODE_MCP_PATH` -> `CLAUDE_CODE_MCP_COMMAND` -> auto-detected `claude` -> auto-detected `claude-internal` -> SDK-bundled CLI
 - **Configuration is shared** — the bundled CLI reads API keys and settings from `~/.claude/`, same as the system-installed `claude`
 - **All local settings are loaded by default** — unlike the raw SDK (which defaults to isolation mode), this MCP server loads `user`, `project`, and `local` settings automatically, including `CLAUDE.md` project context. Pass `advanced.settingSources: []` to opt out
 - You must have Claude Code configured (API key set up) before using this MCP server: see [Claude Code documentation](https://docs.anthropic.com/en/docs/claude-code/overview)
@@ -383,7 +383,7 @@ Notes:
 - `permission_result` event data is `{ requestId, toolName, behavior, source, message?, interrupt? }` (denial details only present for `deny`).
 - `result.fastModeState` may be present when the SDK reports fast-mode state, and `claude_code_session` surfaces the latest known `fastModeState` for each session.
 - In `"minimal"` mode (default): assistant message events are slimmed (strips `usage`, `model`, `id`, `cache_control` from content blocks); noisy SDK progress subtypes (`tool_progress`, `auth_status`, `system/api_retry`, `system/task_progress`, `system/hook_progress`) are filtered out; `lastEventId`/`lastToolUseId` are omitted; `AgentResult` omits `durationApiMs`/`sessionTotalTurns`/`sessionTotalCostUsd`. Use `responseMode: "full"` or individual `include*` flags to restore any of these.
-- In `"delta_compact"` mode: defaults are optimized for high-frequency polling (`events` and top-level `result` omitted unless explicitly enabled via `pollOptions`), while still returning session status/actions/cursors.
+- In `"delta_compact"` mode: defaults minimize per-poll payload size (`events` and top-level `result` omitted unless explicitly enabled via `pollOptions`), while still returning session status/actions/cursors. Note: this does not change the recommended poll interval — `running` sessions should still be polled at >=2 minute intervals.
 
 ## Usage Example
 
@@ -520,21 +520,21 @@ setx CLAUDE_CODE_GIT_BASH_PATH "C:\Program Files\Git\bin\bash.exe"
 
 All environment variables are optional. They are set on the MCP server process (not on the Claude Code child process — for that, use the `env` tool parameter).
 
-| Variable                                     | Description                                                                                                                                                                           | Default        |
-| -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------- |
-| `CLAUDE_CODE_GIT_BASH_PATH`                  | Path to `bash.exe` on Windows (see [Windows Support](#windows-support))                                                                                                               | Auto-detected  |
-| `CLAUDE_CODE_MCP_DEFAULT_CLAUDE_COMMAND`     | Exact command name to resolve from `PATH` as the default Claude executable (for example `claude` or `claude-internal`). Mutually exclusive with `CLAUDE_CODE_MCP_DEFAULT_CLAUDE_PATH` | _(unset)_      |
-| `CLAUDE_CODE_MCP_DEFAULT_CLAUDE_PATH`        | Explicit filesystem path to use as the default Claude executable. Mutually exclusive with `CLAUDE_CODE_MCP_DEFAULT_CLAUDE_COMMAND`                                                    | _(unset)_      |
-| `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`           |
-| `CLAUDE_CODE_MCP_EVENT_BUFFER_MAX_SIZE`      | Soft limit for in-memory event buffer per session (`0` is not supported)                                                                                                              | `1000`         |
-| `CLAUDE_CODE_MCP_EVENT_BUFFER_HARD_MAX_SIZE` | Hard limit for in-memory event buffer per session (clamped to be `>= max`; `0` is not supported)                                                                                      | `2000`         |
+| Variable                                     | Description                                                                                                                                                            | Default        |
+| -------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------- |
+| `CLAUDE_CODE_GIT_BASH_PATH`                  | Path to `bash.exe` on Windows (see [Windows Support](#windows-support))                                                                                                | Auto-detected  |
+| `CLAUDE_CODE_MCP_COMMAND`                    | Exact command name to resolve from `PATH` as the default Claude executable (for example `claude` or `claude-internal`). Mutually exclusive with `CLAUDE_CODE_MCP_PATH` | _(unset)_      |
+| `CLAUDE_CODE_MCP_PATH`                       | Explicit filesystem path to use as the default Claude executable. Mutually exclusive with `CLAUDE_CODE_MCP_COMMAND`                                                    | _(unset)_      |
+| `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`           |
+| `CLAUDE_CODE_MCP_EVENT_BUFFER_MAX_SIZE`      | Soft limit for in-memory event buffer per session (`0` is not supported)                                                                                               | `1000`         |
+| `CLAUDE_CODE_MCP_EVENT_BUFFER_HARD_MAX_SIZE` | Hard limit for in-memory event buffer per session (clamped to be `>= max`; `0` is not supported)                                                                       | `2000`         |
 
 ### Choosing the default Claude executable
 
-- `CLAUDE_CODE_MCP_DEFAULT_CLAUDE_PATH` and `CLAUDE_CODE_MCP_DEFAULT_CLAUDE_COMMAND` are mutually exclusive.
+- `CLAUDE_CODE_MCP_PATH` and `CLAUDE_CODE_MCP_COMMAND` are mutually exclusive.
 - If neither is set, the server auto-detects `claude`, then `claude-internal`, then falls back to the SDK-bundled CLI.
 - Request-level `pathToClaudeCodeExecutable` still overrides these server defaults.
 - Invalid values for these env vars are treated as startup misconfiguration and will fail the server fast.

package/dist/index.js

@@ -920,6 +920,8 @@ import { existsSync as existsSync3, statSync as statSync2 } from "fs";
 var EFFORT_LEVELS = ["low", "medium", "high", "max"];
 var SESSION_ACTIONS = ["list", "get", "cancel", "interrupt"];
 var DEFAULT_SETTING_SOURCES = ["user", "project", "local"];
+var DEFAULT_POLL_INTERVAL_RUNNING_MS = 12e4;
+var DEFAULT_POLL_INTERVAL_WAITING_MS = 1e3;
 var CHECK_ACTIONS = ["poll", "respond_permission"];
 var CHECK_RESPONSE_MODES = ["minimal", "full", "delta_compact"];
 var ErrorCode = /* @__PURE__ */ ((ErrorCode2) => {
@@ -1952,8 +1954,8 @@ function toSessionCreateParams(input) {
 // src/utils/claude-executable.ts
 import { accessSync, constants, existsSync as existsSync2, statSync } from "fs";
 import path3 from "path";
-var DEFAULT_CLAUDE_COMMAND_ENV = "CLAUDE_CODE_MCP_DEFAULT_CLAUDE_COMMAND";
-var DEFAULT_CLAUDE_PATH_ENV = "CLAUDE_CODE_MCP_DEFAULT_CLAUDE_PATH";
+var CLAUDE_COMMAND_ENV = "CLAUDE_CODE_MCP_COMMAND";
+var CLAUDE_PATH_ENV = "CLAUDE_CODE_MCP_PATH";
 var AUTO_CLAUDE_COMMANDS = ["claude", "claude-internal"];
 function trimEnv(name) {
   const value = process.env[name];
@@ -2000,7 +2002,7 @@ function windowsExecutableNames(command) {
 function resolveCommandFromPath(command) {
   if (command.includes("/") || command.includes("\\")) {
     throw new Error(
-      `${DEFAULT_CLAUDE_COMMAND_ENV} must be a command name without path separators. Use ${DEFAULT_CLAUDE_PATH_ENV} for filesystem paths.`
+      `${CLAUDE_COMMAND_ENV} must be a command name without path separators. Use ${CLAUDE_PATH_ENV} for filesystem paths.`
     );
   }
   const names = process.platform === "win32" ? windowsExecutableNames(command) : [command];
@@ -2019,17 +2021,17 @@ function resolveConfiguredPath(rawPath) {
   const normalized = normalizeMaybeQuotedPath2(rawPath);
   const resolved = path3.isAbsolute(normalized) ? normalized : path3.resolve(normalized);
   if (!isUsableExecutablePath(resolved)) {
-    throw new Error(`${DEFAULT_CLAUDE_PATH_ENV} does not point to an executable file: ${resolved}`);
+    throw new Error(`${CLAUDE_PATH_ENV} does not point to an executable file: ${resolved}`);
   }
   return path3.normalize(resolved);
 }
 function resolveDefaultClaudeExecutable() {
-  const configuredPath = trimEnv(DEFAULT_CLAUDE_PATH_ENV);
-  const configuredCommandRaw = trimEnv(DEFAULT_CLAUDE_COMMAND_ENV);
+  const configuredPath = trimEnv(CLAUDE_PATH_ENV);
+  const configuredCommandRaw = trimEnv(CLAUDE_COMMAND_ENV);
   const configuredCommand = configuredCommandRaw ? normalizeMaybeQuotedToken(configuredCommandRaw) : void 0;
   if (configuredPath && configuredCommand) {
     throw new Error(
-      `${DEFAULT_CLAUDE_PATH_ENV} and ${DEFAULT_CLAUDE_COMMAND_ENV} are mutually exclusive; set only one.`
+      `${CLAUDE_PATH_ENV} and ${CLAUDE_COMMAND_ENV} are mutually exclusive; set only one.`
     );
   }
   if (configuredPath) {
@@ -2041,9 +2043,7 @@ function resolveDefaultClaudeExecutable() {
   if (configuredCommand) {
     const resolved = resolveCommandFromPath(configuredCommand);
     if (!resolved) {
-      throw new Error(
-        `${DEFAULT_CLAUDE_COMMAND_ENV}='${configuredCommand}' was not found in PATH.`
-      );
+      throw new Error(`${CLAUDE_COMMAND_ENV}='${configuredCommand}' was not found in PATH.`);
     }
     return {
       source: "env_command",
@@ -2175,7 +2175,7 @@ async function executeClaudeCode(input, sessionManager, serverCwd, toolCache, re
     return {
       sessionId,
       status: "running",
-      pollInterval: 3e3,
+      pollInterval: DEFAULT_POLL_INTERVAL_RUNNING_MS,
       resumeToken: resumeSecret ? computeResumeToken(sessionId, resumeSecret) : void 0
     };
   } catch (err) {
@@ -2361,7 +2361,7 @@ async function executeClaudeCodeReply(input, sessionManager, toolCache, requestS
       return {
         sessionId: input.sessionId,
         status: "running",
-        pollInterval: 3e3,
+        pollInterval: DEFAULT_POLL_INTERVAL_RUNNING_MS,
         resumeToken: computeResumeToken(input.sessionId, resumeSecret)
       };
     } catch (err) {
@@ -2508,7 +2508,7 @@ async function executeClaudeCodeReply(input, sessionManager, toolCache, requestS
     return {
       sessionId,
       status: "running",
-      pollInterval: 3e3,
+      pollInterval: DEFAULT_POLL_INTERVAL_RUNNING_MS,
       resumeToken: resumeSecret ? computeResumeToken(sessionId, resumeSecret) : void 0
     };
   } catch (err) {
@@ -2709,8 +2709,8 @@ function buildInternalToolsDescription(tools) {
 
 // src/tools/claude-code-check.ts
 function pollIntervalForStatus(status) {
-  if (status === "waiting_permission") return 1e3;
-  if (status === "running") return 3e3;
+  if (status === "waiting_permission") return DEFAULT_POLL_INTERVAL_WAITING_MS;
+  if (status === "running") return DEFAULT_POLL_INTERVAL_RUNNING_MS;
   return void 0;
 }
 function toPermissionResult(params) {
@@ -3496,8 +3496,8 @@ function registerResources(server, deps) {
             ),
             eventBuffer: deps.sessionManager.getEventBufferConfig(),
             pollDefaults: {
-              runningMs: 3e3,
-              waitingPermissionMs: 1e3
+              runningMs: DEFAULT_POLL_INTERVAL_RUNNING_MS,
+              waitingPermissionMs: DEFAULT_POLL_INTERVAL_WAITING_MS
             }
           }
         };
@@ -3606,7 +3606,7 @@ function registerResources(server, deps) {
         "",
         "- This backend is asynchronous: `claude_code` and `claude_code_reply` start work, and the final result arrives later via polling.",
         "- Claude Code may keep working for 10+ minutes on larger tasks, especially with `effort='high'` or `effort='max'`; keep polling and be patient before treating it as stuck.",
-        "- Adjust poll intervals to the current progress: poll faster while new events or permission actions are arriving, and slower while the session is quietly thinking with no new output.",
+        "- **Poll frequency**: For `running` sessions, sleep at least 2 minutes between polls; increase for complex tasks. Do NOT high-frequency poll \u2014 it wastes tokens. Only poll frequently (~1s) when `waiting_permission`. Adapt interval based on task complexity and whether the previous poll returned new events.",
         "- `model` is optional. If omitted, Claude Code chooses the effective model from its own defaults/settings.",
         "- `allowedTools` is pre-approval by default; set `strictAllowedTools=true` when you need a strict allowlist.",
         "- `allow_for_session` usually works best when the same tool will be used repeatedly in one session.",
@@ -3621,7 +3621,7 @@ function registerResources(server, deps) {
         "Notes:",
         "- `respond_user_input` is not supported. Use only `respond_permission` for approvals.",
         "- OpenCode/Codex-style clients usually work best when they store `sessionId` + `nextCursor` and answer approvals with `decision=allow_for_session`.",
-        "- Prefer `responseMode='delta_compact'` for high-frequency polling."
+        "- Prefer `responseMode='delta_compact'` to reduce per-poll payload size (does not change recommended poll interval)."
       ].join("\n"),
       "text/markdown"
     )
@@ -3728,9 +3728,9 @@ function registerResources(server, deps) {
         recommendedSettings: {
           responseMode: "delta_compact",
           poll: {
-            runningMs: 3e3,
-            waitingPermissionMs: 1e3,
-            cursorStrategy: "Persist nextCursor and de-duplicate by event.id."
+            runningMs: DEFAULT_POLL_INTERVAL_RUNNING_MS,
+            waitingPermissionMs: DEFAULT_POLL_INTERVAL_WAITING_MS,
+            cursorStrategy: "Persist nextCursor and de-duplicate by event.id. Do NOT high-frequency poll running sessions."
           },
           timeouts: {
             sessionInitTimeoutMs: 1e4,
@@ -3743,9 +3743,9 @@ function registerResources(server, deps) {
           "Treat tool descriptions and MCP resources as agent-visible guidance; do not assume README-level documentation is visible to the model.",
           "Use allowedTools/disallowedTools only with exact runtime tool names.",
           "Set strictAllowedTools=true when you need allowedTools to behave as a strict allowlist.",
-          "Default Claude executable selection prefers request path, then CLAUDE_CODE_MCP_DEFAULT_CLAUDE_PATH, then CLAUDE_CODE_MCP_DEFAULT_CLAUDE_COMMAND, then auto-detected 'claude'/'claude-internal', then SDK-bundled.",
+          "Default Claude executable selection prefers request path, then CLAUDE_CODE_MCP_PATH, then CLAUDE_CODE_MCP_COMMAND, then auto-detected 'claude'/'claude-internal', then SDK-bundled.",
           "This server assumes MCP client and server run on the same machine/platform.",
-          "For high-frequency status checks, prefer responseMode='delta_compact'.",
+          "Prefer responseMode='delta_compact' to reduce per-poll payload size. Running sessions should still poll at >=2 minute intervals.",
           "respond_user_input is not supported on this backend; use poll/respond_permission flow."
         ],
         toolCounts: {
@@ -3911,7 +3911,7 @@ function registerResources(server, deps) {
             clientFamily: "codex",
             detectedMismatches: [],
             recommendations: [
-              "Prefer responseMode='delta_compact' for fast status loops.",
+              "Prefer responseMode='delta_compact' to reduce per-poll payload size. Poll running sessions at >=2 minute intervals.",
               "Enable pollOptions.includeTools=true when exact runtime tool names are required.",
               "Do not assume human-facing README guidance is visible to the agent; keep critical calling rules in tool descriptions or MCP resources."
             ]
@@ -3946,7 +3946,7 @@ function registerResources(server, deps) {
           detectedMismatches: [],
           recommendations: [
             "Persist nextCursor and de-duplicate by event.id.",
-            "Use responseMode='delta_compact' for high-frequency polling, full mode only for diagnostics.",
+            "Use responseMode='delta_compact' to reduce payload size; use 'full' only for diagnostics. Poll running sessions at >=2 minute intervals.",
             "Do not assume repository docs are model-visible; tool descriptions and resources are safer places for runtime guidance."
           ]
         };
@@ -3962,9 +3962,9 @@ function registerResources(server, deps) {
             recommendedSettings: {
               responseMode: "delta_compact",
               poll: {
-                runningMs: 3e3,
-                waitingPermissionMs: 1e3,
-                cursorStrategy: "Persist nextCursor and de-duplicate by event.id."
+                runningMs: DEFAULT_POLL_INTERVAL_RUNNING_MS,
+                waitingPermissionMs: DEFAULT_POLL_INTERVAL_WAITING_MS,
+                cursorStrategy: "Persist nextCursor and de-duplicate by event.id. Do NOT high-frequency poll running sessions."
               }
             }
           }
@@ -3975,7 +3975,7 @@ function registerResources(server, deps) {
 }
 
 // src/server.ts
-var SERVER_VERSION = true ? "2.8.3" : "0.0.0-dev";
+var SERVER_VERSION = true ? "2.8.6" : "0.0.0-dev";
 function createServerContext(serverCwd) {
   const sessionManager = new SessionManager();
   const server = new McpServer(
@@ -4372,7 +4372,15 @@ function createServerContext(serverCwd) {
   server.registerTool(
     "claude_code_check",
     {
-      description: "Poll session state or answer a pending permission request. Main loop: call action='poll', persist nextCursor, and use action='respond_permission' for approvals. respond_user_input is not supported.",
+      description: `Poll session state or answer a pending permission request.
+
+POLLING FREQUENCY: Do NOT poll every turn. Claude Code tasks take minutes, not seconds.
+- "running": sleep at least 2 minutes between polls; increase for complex tasks. Do NOT high-frequency poll \u2014 it wastes tokens.
+- "waiting_permission": poll ~1s and respond quickly.
+- "idle"/"error"/"cancelled": stop polling.
+- Adapt interval based on task complexity and whether the previous poll returned new events.
+
+Main loop: call action='poll', persist nextCursor, and use action='respond_permission' for approvals.`,
       inputSchema: {
         action: z.enum(CHECK_ACTIONS).describe(
           "'poll' fetches new events/actions/result; 'respond_permission' answers one pending permission request."
@@ -4382,7 +4390,7 @@ function createServerContext(serverCwd) {
           "Default: 0. Pass the previous nextCursor to avoid replaying old buffered events."
         ),
         responseMode: z.enum(CHECK_RESPONSE_MODES).optional().describe(
-          "Default: 'minimal'. Use 'delta_compact' for lightweight high-frequency polling; use 'full' mainly for diagnostics."
+          "Default: 'minimal'. Use 'delta_compact' for compact event payloads; use 'full' mainly for diagnostics."
         ),
         maxEvents: z.number().int().positive().optional().describe("Default: 200 (minimal), unlimited (full/delta_compact)"),
         requestId: z.string().optional().describe("Default: none. Required for action='respond_permission'."),