@leo000001/claude-code-mcp 2.5.0 → 2.8.1

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 (6) hide show
  1. package/CHANGELOG.md +12 -1
  2. package/NOTICE.md +1 -1
  3. package/README.md +90 -22
  4. package/dist/index.js +132 -23
  5. package/dist/index.js.map +1 -1
  6. package/package.json +2 -2
package/CHANGELOG.md CHANGED
@@ -2,7 +2,18 @@
2
2
 
3
3
  ## Unreleased
4
4
 
5
- - (TBD)
5
+ ### Improvements
6
+
7
+ - Upgrade `@anthropic-ai/claude-agent-sdk` to `^0.2.81` and align exposed option passthrough with current SDK fields (`toolConfig`, `agentProgressSummaries`, `settings`).
8
+ - 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.
9
+ - Preserve newer SDK metadata in session/results, including `fastModeState` and richer permission prompt labels (`title`, `displayName`).
10
+ - Prefer SDK permission `suggestions` for `allow_for_session` responses and sync session metadata from `system/init` (for example actual model / permission mode).
11
+
12
+ ### Documentation
13
+
14
+ - Add OpenCode-specific setup and usage guidance, including local MCP config examples and async polling recommendations.
15
+ - Sync README and DESIGN option/message matrices with the current SDK 0.2.81 surface.
16
+ - 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.
6
17
 
7
18
  ## 2.5.0 (2026-02-27)
8
19
 
package/NOTICE.md CHANGED
@@ -9,7 +9,7 @@ requirements on redistribution and use.
9
9
 
10
10
  ### Direct dependencies (from `package.json`)
11
11
 
12
- - `@anthropic-ai/claude-agent-sdk@0.2.62` — 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.
12
+ - `@anthropic-ai/claude-agent-sdk@0.2.81` — 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.
13
13
  - `@modelcontextprotocol/sdk@1.27.1` — MIT License
14
14
  - `zod@4.3.6` — MIT License
15
15
 
package/README.md CHANGED
@@ -4,7 +4,7 @@
4
4
  [![license](https://img.shields.io/npm/l/@leo000001/claude-code-mcp.svg)](https://github.com/xihuai18/claude-code-mcp/blob/HEAD/LICENSE)
5
5
  [![node](https://img.shields.io/node/v/@leo000001/claude-code-mcp.svg)](https://nodejs.org)
6
6
 
7
- 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.
7
+ 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. It works especially well with OpenCode/Codex-style clients that prefer async polling and explicit permission decisions.
8
8
 
9
9
  Inspired by the [Codex MCP](https://developers.openai.com/codex/guides/agents-sdk/) design philosophy — minimum tools, maximum capability.
10
10
 
@@ -70,6 +70,26 @@ Add to your MCP client configuration (Claude Desktop, Cursor, etc.):
70
70
  claude mcp add --transport stdio claude-code -- npx -y @leo000001/claude-code-mcp
71
71
  ```
72
72
 
73
+ ### OpenCode
74
+
75
+ Add a local MCP entry in `opencode.json` / `opencode.jsonc` (project) or the global OpenCode config under `~/.config/opencode/`:
76
+
77
+ ```json
78
+ {
79
+ "mcp": {
80
+ "claude-code": {
81
+ "type": "local",
82
+ "command": ["npx", "-y", "@leo000001/claude-code-mcp"],
83
+ "enabled": true
84
+ }
85
+ }
86
+ }
87
+ ```
88
+
89
+ OpenCode tip: start with `claude_code`, keep the returned `sessionId`, then background-poll with `claude_code_check`. When approvals appear, `decision: "allow_for_session"` is usually the best UX because it reduces repeated prompts for the same tool in a session.
90
+
91
+ > OpenCode project configs can launch local commands. Only enable repository-level MCP configs in repos you trust.
92
+
73
93
  ### OpenAI Codex CLI
74
94
 
75
95
  ```bash
@@ -117,7 +137,7 @@ Start a new Claude Code session. The agent autonomously performs coding tasks: r
117
137
  | `advanced` | object | No | Advanced/low-frequency parameters (see below) |
118
138
 
119
139
  <details>
120
- <summary><code>advanced</code> object parameters (21 low-frequency parameters)</summary>
140
+ <summary><code>advanced</code> object parameters (24 low-frequency parameters)</summary>
121
141
 
122
142
  | Parameter | Type | Description |
123
143
  | ------------------------------------- | ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
@@ -135,9 +155,12 @@ Start a new Claude Code session. The agent autonomously performs coding tasks: r
135
155
  | `advanced.sandbox` | object | Sandbox configuration for isolating shell command execution (e.g., Docker container settings). Default: SDK/Claude Code default |
136
156
  | `advanced.fallbackModel` | string | Fallback model if the primary model fails or is unavailable. Default: none |
137
157
  | `advanced.enableFileCheckpointing` | boolean | Enable file checkpointing to track file changes during the session. Default: `false` |
158
+ | `advanced.toolConfig` | object | Per-tool built-in configuration. Example: `{ askUserQuestion: { previewFormat: "html" } }`. Default: none |
138
159
  | `advanced.includePartialMessages` | boolean | When true, includes intermediate streaming messages in the response. Useful for real-time progress monitoring. Default: false |
139
160
  | `advanced.promptSuggestions` | boolean | When true, emits post-turn prompt suggestion events (`prompt_suggestion`). Default: `false` |
161
+ | `advanced.agentProgressSummaries` | boolean | When true, emits AI-generated summaries on `system/task_progress` events for running subagents. Default: `false` |
140
162
  | `advanced.strictMcpConfig` | boolean | Enforce strict validation of MCP server configurations. Default: `false` |
163
+ | `advanced.settings` | string \| object | Extra Claude Code flag settings. Pass either a path to a settings JSON file or an inline settings object. Default: none |
141
164
  | `advanced.settingSources` | string[] | Which filesystem settings to load. Defaults to `["user", "project", "local"]` (loads all settings and CLAUDE.md). Pass `[]` for SDK isolation mode |
142
165
  | `advanced.debug` | boolean | Enable debug mode for verbose logging. Default: `false` |
143
166
  | `advanced.debugFile` | string | Write debug logs to a specific file path (implicitly enables debug mode). Default: omitted |
@@ -151,6 +174,8 @@ Notes:
151
174
 
152
175
  - `resumeToken` is omitted by default, and is only returned when `CLAUDE_CODE_MCP_RESUME_SECRET` is set on the server.
153
176
  - On error: `{ sessionId: "", status: "error", error }`
177
+ - `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.
178
+ - If you plan to continue with `claude_code_reply`, keep the session persistent (`advanced.persistSession=true`, which is already the default).
154
179
 
155
180
  Use `claude_code_check` to poll events and obtain the final `result`.
156
181
 
@@ -178,7 +203,7 @@ Continue an existing session by sending a follow-up message. The agent retains f
178
203
  | `diskResumeConfig` | object | No | Disk resume parameters (see below). Used when `CLAUDE_CODE_MCP_ALLOW_DISK_RESUME=1` and in-memory session is missing |
179
204
 
180
205
  <details>
181
- <summary><code>diskResumeConfig</code> object parameters (31 disk-resume-only parameters)</summary>
206
+ <summary><code>diskResumeConfig</code> object parameters (34 disk-resume-only parameters)</summary>
182
207
 
183
208
  | Parameter | Type | Description |
184
209
  | --------------------------------------------- | ------------------ | ----------------------------------------------------------------------------------------------- |
@@ -206,9 +231,12 @@ Continue an existing session by sending a follow-up message. The agent retains f
206
231
  | `diskResumeConfig.sandbox` | object | Sandbox config for command isolation. Default: SDK/Claude Code default |
207
232
  | `diskResumeConfig.fallbackModel` | string | Fallback model. Default: none |
208
233
  | `diskResumeConfig.enableFileCheckpointing` | boolean | Enable file checkpointing. Default: `false` |
234
+ | `diskResumeConfig.toolConfig` | object | Per-tool built-in configuration. Default: none |
209
235
  | `diskResumeConfig.includePartialMessages` | boolean | Include intermediate streaming messages. Default: `false` |
210
236
  | `diskResumeConfig.promptSuggestions` | boolean | Emit post-turn prompt suggestion events (`prompt_suggestion`). Default: `false` |
237
+ | `diskResumeConfig.agentProgressSummaries` | boolean | Emit AI-generated subagent progress summaries. Default: `false` |
211
238
  | `diskResumeConfig.strictMcpConfig` | boolean | Strict MCP config validation. Default: `false` |
239
+ | `diskResumeConfig.settings` | string \| object | Extra Claude Code flag settings (path or inline object). Default: none |
212
240
  | `diskResumeConfig.settingSources` | string[] | Which filesystem settings to load. Default: `["user", "project", "local"]` |
213
241
  | `diskResumeConfig.debug` | boolean | Debug mode. Default: `false` |
214
242
  | `diskResumeConfig.debugFile` | string | Debug log file path. Default: omitted |
@@ -228,10 +256,12 @@ Use `claude_code_check` to poll events and obtain the final `result`.
228
256
  Gotchas:
229
257
 
230
258
  - Permission approvals have a timeout (default 60s via `permissionRequestTimeoutMs`) and will auto-deny; watch `actions[].expiresAt` / `actions[].remainingMs`.
259
+ - `claude_code_reply` requires a persistent session or an enabled disk-resume setup; one-shot/non-persistent sessions cannot be resumed later.
231
260
  - `Read` has a per-call size cap in practice (often ~256KB); for large files use `offset`/`limit` or chunk with `Grep`.
232
261
  - `Edit` with `replace_all=true` is substring replacement; if no match is found the tool returns a clear error.
233
262
  - 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`.
234
263
  - 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.
264
+ - On Windows, Claude Code itself needs Git Bash; set `CLAUDE_CODE_GIT_BASH_PATH` in your MCP client config if auto-detection is unreliable.
235
265
  - `TeamDelete` may require members to reach `shutdown_approved` (otherwise you may see "active member" errors); cleanup can be asynchronous during shutdown.
236
266
  - Skills may become available later in the same session (early calls may show "Unknown", later succeed after skills are loaded/registered).
237
267
  - `toolCatalogCount` and `availableTools` are different views: catalog is server-known tools, while `availableTools` comes from each session's runtime `system/init.tools`.
@@ -260,15 +290,15 @@ Resource templates:
260
290
 
261
291
  List, inspect, cancel, or interrupt sessions.
262
292
 
263
- | Parameter | Type | Required | Description |
264
- | ------------------ | ------- | ------------------------ | ------------------------------------------------------------------------------ |
265
- | `action` | string | Yes | `"list"`, `"get"`, `"cancel"`, or `"interrupt"` |
266
- | `sessionId` | string | For get/cancel/interrupt | Target session ID |
267
- | `includeSensitive` | boolean | No | Include `cwd`/`systemPrompt`/`agents`/`additionalDirectories` (default: false) |
293
+ | Parameter | Type | Required | Description |
294
+ | ------------------ | ------- | ------------------------ | -------------------------------------------------------------------------------------------------------------------- |
295
+ | `action` | string | Yes | `"list"`, `"get"`, `"cancel"`, or `"interrupt"` |
296
+ | `sessionId` | string | For get/cancel/interrupt | Target session ID |
297
+ | `includeSensitive` | boolean | No | Include `cwd`/`systemPrompt`/`agents`/`additionalDirectories`/`toolConfig` (default: false; `settings` stays hidden) |
268
298
 
269
299
  **Returns:** `{ sessions, message?, isError? }`
270
300
 
271
- `sessions[]` now includes lightweight diagnostics fields: `pendingPermissionCount`, `eventCount`, `currentCursor`, `lastEventId`, `ttlMs`, `lastError?`, `lastErrorAt?`, and `redactions[]`.
301
+ `sessions[]` now includes lightweight diagnostics fields: `pendingPermissionCount`, `eventCount`, `currentCursor`, `lastEventId`, `ttlMs`, `lastError?`, `lastErrorAt?`, `fastModeState?`, and `redactions[]`.
272
302
 
273
303
  ### `claude_code_check` — Poll events and respond to permission requests
274
304
 
@@ -291,18 +321,18 @@ Poll session events/results and approve/deny pending permission requests.
291
321
  <details>
292
322
  <summary><code>pollOptions</code> object parameters (10 fine-grained poll controls)</summary>
293
323
 
294
- | Parameter | Type | Description |
295
- | ------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
296
- | `pollOptions.includeTools` | boolean | When true, includes `availableTools` (`poll` only). Default: `false` (omitted until session init is received). Derived from SDK `system/init.tools` (internal features may not appear). |
297
- | `pollOptions.includeEvents` | boolean | When false, omits `events` (but `nextCursor` still advances). Default: `true` |
298
- | `pollOptions.includeActions` | boolean | When false, omits `actions[]` even if `waiting_permission`. Default: `true` |
299
- | `pollOptions.includeResult` | boolean | When false, omits top-level `result` even when `idle`/`error`. Default: `true` |
300
- | `pollOptions.includeUsage` | boolean | Include `result.usage` (default: `true` in `"full"`, `false` in `"minimal"`/`"delta_compact"`) |
301
- | `pollOptions.includeModelUsage` | boolean | Include `result.modelUsage` (default: `true` in `"full"`, `false` in `"minimal"`/`"delta_compact"`) |
302
- | `pollOptions.includeStructuredOutput` | boolean | Include `result.structuredOutput` (default: `true` in `"full"`, `false` in `"minimal"`/`"delta_compact"`) |
303
- | `pollOptions.includeTerminalEvents` | boolean | When true, keeps terminal `result`/`error` events in `events` even if top-level `result` is included. Default: `false` in `"minimal"`/`"delta_compact"`, `true` in `"full"` |
304
- | `pollOptions.includeProgressEvents` | boolean | When true, includes noisy SDK progress subtypes (e.g. `tool_progress`, `auth_status`, `system/task_progress`, `system/hook_progress`) as MCP `progress` events. Default: `false` in `"minimal"`/`"delta_compact"`, `true` in `"full"` |
305
- | `pollOptions.maxBytes` | number | Approximate max JSON bytes for `events` in this response. When exceeded, events are truncated and `truncatedFields` includes `"events_bytes"`. Default: unlimited |
324
+ | Parameter | Type | Description |
325
+ | ------------------------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
326
+ | `pollOptions.includeTools` | boolean | When true, includes `availableTools` (`poll` only). Default: `false` (omitted until session init is received). Derived from SDK `system/init.tools` (internal features may not appear). |
327
+ | `pollOptions.includeEvents` | boolean | When false, omits `events` (but `nextCursor` still advances). Default: `true` |
328
+ | `pollOptions.includeActions` | boolean | When false, omits `actions[]` even if `waiting_permission`. Default: `true` |
329
+ | `pollOptions.includeResult` | boolean | When false, omits top-level `result` even when `idle`/`error`. Default: `true` |
330
+ | `pollOptions.includeUsage` | boolean | Include `result.usage` (default: `true` in `"full"`, `false` in `"minimal"`/`"delta_compact"`) |
331
+ | `pollOptions.includeModelUsage` | boolean | Include `result.modelUsage` (default: `true` in `"full"`, `false` in `"minimal"`/`"delta_compact"`) |
332
+ | `pollOptions.includeStructuredOutput` | boolean | Include `result.structuredOutput` (default: `true` in `"full"`, `false` in `"minimal"`/`"delta_compact"`) |
333
+ | `pollOptions.includeTerminalEvents` | boolean | When true, keeps terminal `result`/`error` events in `events` even if top-level `result` is included. Default: `false` in `"minimal"`/`"delta_compact"`, `true` in `"full"` |
334
+ | `pollOptions.includeProgressEvents` | boolean | When true, includes noisy SDK progress subtypes (e.g. `tool_progress`, `auth_status`, `system/api_retry`, `system/task_progress`, `system/hook_progress`) as MCP `progress` events. Default: `false` in `"minimal"`/`"delta_compact"`, `true` in `"full"` |
335
+ | `pollOptions.maxBytes` | number | Approximate max JSON bytes for `events` in this response. When exceeded, events are truncated and `truncatedFields` includes `"events_bytes"`. Default: unlimited |
306
336
 
307
337
  </details>
308
338
 
@@ -330,8 +360,11 @@ Notes:
330
360
  - `toolValidation` reports whether configured `allowedTools`/`disallowedTools` match runtime-discovered tool names.
331
361
  - `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.
332
362
  - Permission `actions[]` include `timeoutMs`, `expiresAt`, and best-effort `remainingMs` to help callers avoid auto-deny timeouts.
363
+ - Permission `actions[]` may also include SDK-provided `title` / `displayName` metadata; clients should prefer those strings when rendering approval UI.
364
+ - For `decision="allow_for_session"`, the server now prefers SDK-provided `suggestions` (for example `addDirectories`) when present, then falls back to a generic per-session tool allow rule.
333
365
  - `permission_result` event data is `{ requestId, toolName, behavior, source, message?, interrupt? }` (denial details only present for `deny`).
334
- - 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/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.
366
+ - `result.fastModeState` may be present when the SDK reports fast-mode state, and `claude_code_session` surfaces the latest known `fastModeState` for each session.
367
+ - 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.
335
368
  - 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.
336
369
 
337
370
  ## Usage Example
@@ -410,6 +443,23 @@ For JSON-based MCP clients (Claude Desktop, Cursor, etc.):
410
443
  }
411
444
  ```
412
445
 
446
+ For OpenCode (`opencode.json` / `opencode.jsonc`):
447
+
448
+ ```json
449
+ {
450
+ "mcp": {
451
+ "claude-code": {
452
+ "type": "local",
453
+ "command": ["npx", "-y", "@leo000001/claude-code-mcp"],
454
+ "enabled": true,
455
+ "environment": {
456
+ "CLAUDE_CODE_GIT_BASH_PATH": "C:\\Program Files\\Git\\bin\\bash.exe"
457
+ }
458
+ }
459
+ }
460
+ }
461
+ ```
462
+
413
463
  For OpenAI Codex CLI (`~/.codex/config.toml`):
414
464
 
415
465
  ```toml
@@ -493,6 +543,24 @@ CLAUDE_CODE_MCP_ALLOW_DISK_RESUME = "1"
493
543
  CLAUDE_CODE_MCP_RESUME_SECRET = "change-me"
494
544
  ```
495
545
 
546
+ **OpenCode** — add an `environment` block under the local MCP entry:
547
+
548
+ ```json
549
+ {
550
+ "mcp": {
551
+ "claude-code": {
552
+ "type": "local",
553
+ "command": ["npx", "-y", "@leo000001/claude-code-mcp"],
554
+ "enabled": true,
555
+ "environment": {
556
+ "CLAUDE_CODE_MCP_ALLOW_DISK_RESUME": "1",
557
+ "CLAUDE_CODE_MCP_RESUME_SECRET": "change-me"
558
+ }
559
+ }
560
+ }
561
+ }
562
+ ```
563
+
496
564
  **System-wide** — set via your shell profile or OS settings so all processes inherit them:
497
565
 
498
566
  ```bash