@leo000001/claude-code-mcp 2.8.0 → 2.8.1

package/CHANGELOG.md

@@ -13,6 +13,7 @@
 
 - Add OpenCode-specific setup and usage guidance, including local MCP config examples and async polling recommendations.
 - Sync README and DESIGN option/message matrices with the current SDK 0.2.81 surface.
+- Add usage reminders in model-visible guidance: long Claude Code runs are normal, and follow-up questions should use `claude_code_reply` with the existing session.
 
 ## 2.5.0 (2026-02-27)
 

package/README.md

@@ -174,6 +174,8 @@ 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 }`
+- `model` is optional. If omitted, Claude Code chooses the effective model from its own defaults/settings; inspect session/result metadata if you need to know what actually ran.
+- If you plan to continue with `claude_code_reply`, keep the session persistent (`advanced.persistSession=true`, which is already the default).
 
 Use `claude_code_check` to poll events and obtain the final `result`.
 
@@ -254,10 +256,12 @@ Use `claude_code_check` to poll events and obtain the final `result`.
 Gotchas:
 
 - Permission approvals have a timeout (default 60s via `permissionRequestTimeoutMs`) and will auto-deny; watch `actions[].expiresAt` / `actions[].remainingMs`.
+- `claude_code_reply` requires a persistent session or an enabled disk-resume setup; one-shot/non-persistent sessions cannot be resumed later.
 - `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.
 - 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.
+- On Windows, Claude Code itself needs Git Bash; set `CLAUDE_CODE_GIT_BASH_PATH` in your MCP client config if auto-detection is unreliable.
 - `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).
 - `toolCatalogCount` and `availableTools` are different views: catalog is server-known tools, while `availableTools` comes from each session's runtime `system/init.tools`.

package/dist/index.js

@@ -2553,7 +2553,7 @@ function groupByCategory(tools) {
 function buildInternalToolsDescription(tools) {
   const grouped = groupByCategory(tools);
   const categories = Object.keys(grouped).sort((a, b) => a.localeCompare(b));
-  let desc = "Start a Claude Code session and return sessionId.\nUse claude_code_check to poll events/results and handle permissions.\n\n";
+  let desc = "Start a Claude Code session and return sessionId.\nUse claude_code_check to poll events/results and handle permissions.\nAdjust polling cadence to progress: poll faster while new events/actions are arriving, and slower when the session is quietly thinking.\nLong-running work is normal: Claude Code can keep working for 10+ minutes, especially with high/max effort, so wait for polling to settle before assuming it is stuck.\nIf you want to continue after a run pauses or finishes, use claude_code_reply with the same sessionId instead of starting a brand-new claude_code session.\n\n";
   desc += "Internal tools (authoritative list: includeTools=true in claude_code_check):\n";
   for (const category of categories) {
     desc += `
@@ -3437,6 +3437,18 @@ function registerResources(server, deps) {
         "3. If actions are returned, respond with `claude_code_check(action='respond_permission')`.",
         "4. Continue polling until status becomes `idle` / `error` / `cancelled`.",
         "",
+        "Usage reminders:",
+        "- 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.",
+        "- If Claude Code stops and you want to keep going, call `claude_code_reply` with the existing `sessionId` instead of starting a fresh `claude_code` session.",
+        "",
+        "Common mistakes:",
+        "- Do not call `claude_code_reply` on a non-persistent session; if you plan to continue later, start with `advanced.persistSession=true`.",
+        "- `model` is optional. If omitted, Claude Code chooses the effective model from its own defaults/settings.",
+        "- Store `nextCursor` and feed it back into the next `claude_code_check(action='poll')`; otherwise you will keep replaying old events.",
+        "- On Windows, set `CLAUDE_CODE_GIT_BASH_PATH` or Claude Code may fail before the session starts.",
+        "- If `decision='allow_for_session'` still shows a permission request, inspect `actions[].suggestions` / `blockedPath`; directory access may need a more specific permission update.",
+        "",
         "Notes:",
         "- `respond_user_input` is not supported on this backend.",
         "- `allowedTools` is pre-approval by default; set `strictAllowedTools=true` for strict allowlist behavior.",
@@ -3783,7 +3795,7 @@ function registerResources(server, deps) {
 }
 
 // src/server.ts
-var SERVER_VERSION = true ? "2.8.0" : "0.0.0-dev";
+var SERVER_VERSION = true ? "2.8.1" : "0.0.0-dev";
 function createServerContext(serverCwd) {
   const sessionManager = new SessionManager();
   const server = new McpServer(
@@ -3964,7 +3976,9 @@ function createServerContext(serverCwd) {
     {
       description: buildInternalToolsDescription(toolCache.getTools()),
       inputSchema: {
-        prompt: z.string().describe("Prompt"),
+        prompt: z.string().describe(
+          "Prompt. Long runs are normal; keep polling, adapt poll cadence to current progress, and reuse sessionId with claude_code_reply if you want to continue."
+        ),
         cwd: z.string().optional().describe("Working dir. Default: server cwd"),
         allowedTools: z.array(z.string()).optional().describe("Default: []"),
         disallowedTools: z.array(z.string()).optional().describe("Default: []"),
@@ -4028,10 +4042,12 @@ function createServerContext(serverCwd) {
   server.registerTool(
     "claude_code_reply",
     {
-      description: "Send a follow-up to an existing session. Returns immediately; use claude_code_check to poll.",
+      description: "Send a follow-up to an existing session. Reuse the same sessionId instead of starting a new claude_code session when you want to continue. Returns immediately; use claude_code_check to poll, and adjust poll cadence to current progress.",
       inputSchema: {
-        sessionId: z.string().describe("Session ID"),
-        prompt: z.string().describe("Prompt"),
+        sessionId: z.string().describe(
+          "Session ID from the existing conversation you want to continue; prefer this over starting a fresh claude_code session."
+        ),
+        prompt: z.string().describe("Follow-up prompt for the existing session."),
         forkSession: z.boolean().optional().describe("Default: false"),
         effort: effortOptionSchema.describe("Default: SDK"),
         thinking: thinkingOptionSchema.describe("Default: SDK"),
@@ -4134,12 +4150,14 @@ function createServerContext(serverCwd) {
   server.registerTool(
     "claude_code_check",
     {
-      description: "Poll session events or respond to permission requests.",
+      description: "Poll session events or respond to permission requests. Long Claude Code runs are normal, especially with high/max effort; poll faster when progress is active and slower when the session is quietly thinking.",
       inputSchema: {
         action: z.enum(CHECK_ACTIONS),
         sessionId: z.string().describe("Session ID"),
         cursor: z.number().int().nonnegative().optional().describe("Default: 0"),
-        responseMode: z.enum(CHECK_RESPONSE_MODES).optional().describe("Default: 'minimal'. Use 'delta_compact' for lightweight polling."),
+        responseMode: z.enum(CHECK_RESPONSE_MODES).optional().describe(
+          "Default: 'minimal'. Use 'delta_compact' for lightweight polling, especially for faster adaptive polling loops."
+        ),
         maxEvents: z.number().int().positive().optional().describe("Default: 200 (minimal), unlimited (full/delta_compact)"),
         requestId: z.string().optional().describe("Default: none"),
         decision: z.enum(["allow", "deny", "allow_for_session"]).optional().describe("Default: none"),