@leo000001/claude-code-mcp 1.6.0 → 2.0.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.
- package/CHANGELOG.md +27 -3
- package/README.md +216 -130
- package/SECURITY.md +3 -3
- package/dist/index.js +1634 -1041
- package/dist/index.js.map +1 -1
- package/package.json +2 -2
package/CHANGELOG.md
CHANGED
|
@@ -1,11 +1,35 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
-
##
|
|
3
|
+
## Unreleased
|
|
4
|
+
|
|
5
|
+
### Breaking Changes
|
|
6
|
+
- `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`.
|
|
7
|
+
- Removed tool: `claude_code_configure`
|
|
8
|
+
- New tool: `claude_code_check` (poll + respond_permission)
|
|
9
|
+
- **Parameter nesting refactor**: low-frequency parameters have been folded into nested objects to reduce top-level clutter. This is a breaking change for callers that pass these parameters at the top level:
|
|
10
|
+
- `claude_code`: 22 low-frequency params moved into `advanced` object (e.g. `effort` → `advanced.effort`, `tools` → `advanced.tools`, `agents` → `advanced.agents`, `env` → `advanced.env`)
|
|
11
|
+
- `claude_code_reply`: 28 disk-resume params moved into `diskResumeConfig` object (e.g. `resumeToken` → `diskResumeConfig.resumeToken`, `cwd` → `diskResumeConfig.cwd`)
|
|
12
|
+
- `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`)
|
|
13
|
+
|
|
14
|
+
### Features
|
|
15
|
+
- New module: `src/tools/query-consumer.ts` — shared background query consumer (`consumeQuery`) for start, resume, and disk-resume code paths
|
|
16
|
+
- New module: `src/tools/tool-discovery.ts` — runtime tool discovery with `TOOL_CATALOG`, `ToolDiscoveryCache`, and dynamic `claude_code` description generation
|
|
17
|
+
- New module: `src/utils/build-options.ts` — centralized SDK `Partial<Options>` construction from flat input objects
|
|
18
|
+
- New module: `src/utils/race-with-abort.ts` — race a promise against an AbortSignal with cleanup
|
|
19
|
+
- New module: `src/utils/resume-token.ts` — HMAC-SHA256 resume token generation/validation for secure disk resume
|
|
20
|
+
|
|
21
|
+
### Improvements
|
|
22
|
+
- `claude_code_check`: default `responseMode="minimal"` to reduce payload size; supports `maxEvents` pagination with `truncated`/`truncatedFields`
|
|
23
|
+
- `claude_code_check`: minimal mode now slims assistant message events (strips `usage`, `model`, `id`, `cache_control` from content blocks)
|
|
24
|
+
- `claude_code_check`: minimal mode filters out noisy progress events (`tool_progress`, `auth_status`); use `includeProgressEvents: true` to restore
|
|
25
|
+
- `claude_code_check`: minimal mode omits `lastEventId`/`lastToolUseId` from top-level response and `durationApiMs`/`sessionTotalTurns`/`sessionTotalCostUsd` from AgentResult
|
|
26
|
+
- `claude_code_check`: includes lightweight session diagnostics (`cancelledAt`/`cancelledReason`/`cancelledSource`, `lastEventId`, `lastToolUseId`)
|
|
27
|
+
- Disk resume security: disk resume fallback requires `CLAUDE_CODE_MCP_RESUME_SECRET` + `resumeToken`
|
|
28
|
+
|
|
29
|
+
## 1.6.0 (2026-02-12)
|
|
4
30
|
|
|
5
31
|
### Bug Fixes
|
|
6
32
|
- Windows: fixed Git Bash auto-detection path derivation and improved candidate search
|
|
7
|
-
- Server: internal exceptions in `claude_code`/`claude_code_reply` now return JSON-shaped error results (consistent parsing)
|
|
8
|
-
- Server: tightened input validation for `prompt`, `sessionId`, and `cwd` (trim + non-empty)
|
|
9
33
|
|
|
10
34
|
### Security
|
|
11
35
|
- `claude_code_session includeSensitive=true` no longer leaks extra fields (e.g. `env`, `debugFile`, `mcpServers`, `sandbox`) beyond the documented sensitive set
|
package/README.md
CHANGED
|
@@ -10,15 +10,15 @@ Inspired by the [Codex MCP](https://developers.openai.com/codex/guides/agents-sd
|
|
|
10
10
|
|
|
11
11
|
## Features
|
|
12
12
|
|
|
13
|
-
- **4 tools** covering the full agent lifecycle: start, continue,
|
|
13
|
+
- **4 tools** covering the full agent lifecycle: start, continue, check/poll, manage
|
|
14
14
|
- **Session management** with resume and fork support
|
|
15
15
|
- **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
|
|
16
|
-
- **
|
|
16
|
+
- **Async permissions** — allow/deny lists + explicit approvals via `claude_code_check`
|
|
17
17
|
- **Custom subagents** — define specialized agents per session
|
|
18
18
|
- **Cost tracking** — per-session turn and cost accounting
|
|
19
19
|
- **Session cancellation** via AbortController
|
|
20
20
|
- **Auto-cleanup** — 30-minute idle timeout for expired sessions
|
|
21
|
-
- **Security** —
|
|
21
|
+
- **Security** — callers control tool permissions via allow/deny lists + explicit permission decisions
|
|
22
22
|
|
|
23
23
|
## Prerequisites
|
|
24
24
|
|
|
@@ -28,7 +28,7 @@ This MCP server uses the [`@anthropic-ai/claude-agent-sdk`](https://www.npmjs.co
|
|
|
28
28
|
|
|
29
29
|
- The SDK's bundled CLI version is determined by the SDK package version (e.g. SDK 0.2.38 = Claude Code 2.1.38)
|
|
30
30
|
- **Configuration is shared** — the bundled CLI reads API keys and settings from `~/.claude/`, same as the system-installed `claude`
|
|
31
|
-
- **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 `settingSources: []` to opt out
|
|
31
|
+
- **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
|
|
32
32
|
- 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)
|
|
33
33
|
|
|
34
34
|
> **Note:** The bundled CLI version may differ from your system-installed `claude`. To check: `claude --version` (system) vs `npm ls @anthropic-ai/claude-agent-sdk` (SDK).
|
|
@@ -88,97 +88,120 @@ npm start
|
|
|
88
88
|
|
|
89
89
|
Start a new Claude Code session. The agent autonomously performs coding tasks: reading/writing files, running shell commands, searching code, managing git, and interacting with APIs.
|
|
90
90
|
|
|
91
|
-
| Parameter | Type | Required | Description
|
|
92
|
-
| ---------------------------- | ------------------ | -------- |
|
|
93
|
-
| `prompt` | string | Yes | Task or question for Claude Code
|
|
94
|
-
| `cwd` | string | No | Working directory (defaults to server cwd)
|
|
95
|
-
| `allowedTools` | string[] | No |
|
|
96
|
-
| `disallowedTools` | string[] | No |
|
|
97
|
-
| `
|
|
98
|
-
| `
|
|
99
|
-
| `
|
|
100
|
-
| `
|
|
101
|
-
| `
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
|
107
|
-
|
|
|
108
|
-
| `
|
|
109
|
-
| `
|
|
110
|
-
| `
|
|
111
|
-
| `
|
|
112
|
-
| `agent`
|
|
113
|
-
| `
|
|
114
|
-
| `
|
|
115
|
-
| `
|
|
116
|
-
| `
|
|
117
|
-
| `
|
|
118
|
-
| `
|
|
119
|
-
| `
|
|
120
|
-
| `
|
|
121
|
-
| `
|
|
122
|
-
| `
|
|
123
|
-
|
|
124
|
-
|
|
91
|
+
| Parameter | Type | Required | Description |
|
|
92
|
+
| ---------------------------- | ------------------ | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
93
|
+
| `prompt` | string | Yes | Task or question for Claude Code |
|
|
94
|
+
| `cwd` | string | No | Working directory (defaults to server cwd) |
|
|
95
|
+
| `allowedTools` | string[] | No | Auto-approved tool names. Default: `[]` (none). Tools not in `allowedTools`/`disallowedTools` may surface permission requests via `claude_code_check`. Example: `["Bash", "Read", "Write", "Edit"]` |
|
|
96
|
+
| `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 |
|
|
97
|
+
| `maxTurns` | number | No | Maximum number of agent reasoning steps. Each step may involve one or more tool calls. Default: SDK/Claude Code default |
|
|
98
|
+
| `model` | string | No | Model to use (e.g. `"claude-sonnet-4-5-20250929"`). Default: SDK/Claude Code default |
|
|
99
|
+
| `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 |
|
|
100
|
+
| `permissionRequestTimeoutMs` | number | No | Timeout in milliseconds waiting for permission decisions. Default: `60000` |
|
|
101
|
+
| `advanced` | object | No | Advanced/low-frequency parameters (see below) |
|
|
102
|
+
|
|
103
|
+
<details>
|
|
104
|
+
<summary><code>advanced</code> object parameters (22 low-frequency parameters)</summary>
|
|
105
|
+
|
|
106
|
+
| Parameter | Type | Description |
|
|
107
|
+
| ---------------------------------- | ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
108
|
+
| `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 |
|
|
109
|
+
| `advanced.persistSession` | boolean | Persist session history to disk (`~/.claude/projects/`). Default: `true`. Set `false` to disable. |
|
|
110
|
+
| `advanced.sessionInitTimeoutMs` | number | Timeout in milliseconds waiting for `system/init`. Default: `10000` |
|
|
111
|
+
| `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. |
|
|
112
|
+
| `advanced.agent` | string | Name of a custom agent (defined in `agents`) to use as the primary agent. Default: omitted |
|
|
113
|
+
| `advanced.maxBudgetUsd` | number | Maximum budget in USD. Default: SDK/Claude Code default |
|
|
114
|
+
| `advanced.effort` | string | Effort level: `"low"`, `"medium"`, `"high"`, `"max"`. Default: SDK/Claude Code default |
|
|
115
|
+
| `advanced.betas` | string[] | Beta features (e.g. `["context-1m-2025-08-07"]`). Default: none |
|
|
116
|
+
| `advanced.additionalDirectories` | string[] | Additional directories the agent can access beyond cwd. Default: none |
|
|
117
|
+
| `advanced.outputFormat` | object | Structured output: `{ type: "json_schema", schema: {...} }`. Default: omitted (plain text) |
|
|
118
|
+
| `advanced.thinking` | object | Thinking mode: `{ type: "adaptive" }`, `{ type: "enabled", budgetTokens: N }`, or `{ type: "disabled" }`. Default: SDK/Claude Code default |
|
|
119
|
+
| `advanced.pathToClaudeCodeExecutable` | string | Path to the Claude Code executable. Default: SDK-bundled Claude Code (cli.js) |
|
|
120
|
+
| `advanced.mcpServers` | object | MCP server configurations (key: server name, value: server config). Default: none |
|
|
121
|
+
| `advanced.sandbox` | object | Sandbox configuration for isolating shell command execution (e.g., Docker container settings). Default: SDK/Claude Code default |
|
|
122
|
+
| `advanced.fallbackModel` | string | Fallback model if the primary model fails or is unavailable. Default: none |
|
|
123
|
+
| `advanced.enableFileCheckpointing` | boolean | Enable file checkpointing to track file changes during the session. Default: `false` |
|
|
124
|
+
| `advanced.includePartialMessages` | boolean | When true, includes intermediate streaming messages in the response. Useful for real-time progress monitoring. Default: false |
|
|
125
|
+
| `advanced.strictMcpConfig` | boolean | Enforce strict validation of MCP server configurations. Default: `false` |
|
|
126
|
+
| `advanced.settingSources` | string[] | Which filesystem settings to load. Defaults to `["user", "project", "local"]` (loads all settings and CLAUDE.md). Pass `[]` for SDK isolation mode |
|
|
127
|
+
| `advanced.debug` | boolean | Enable debug mode for verbose logging. Default: `false` |
|
|
128
|
+
| `advanced.debugFile` | string | Write debug logs to a specific file path (implicitly enables debug mode). Default: omitted |
|
|
129
|
+
| `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 |
|
|
130
|
+
|
|
131
|
+
</details>
|
|
132
|
+
|
|
133
|
+
**Returns:** `{ sessionId, status: "running", pollInterval, resumeToken? }`
|
|
134
|
+
|
|
135
|
+
Notes:
|
|
136
|
+
- `resumeToken` is omitted by default, and is only returned when `CLAUDE_CODE_MCP_RESUME_SECRET` is set on the server.
|
|
137
|
+
- On error: `{ sessionId: "", status: "error", error }`
|
|
138
|
+
|
|
139
|
+
Use `claude_code_check` to poll events and obtain the final `result`.
|
|
125
140
|
|
|
126
141
|
> Notes:
|
|
127
142
|
> - **Subagents require the `Task` tool** to be available to the primary agent. If you use `allowedTools`, include `"Task"` or the agent will be unable to invoke subagents.
|
|
128
|
-
> - If you configure `mcpServers` and want the agent to
|
|
129
|
-
> - `includePartialMessages` affects the underlying SDK event stream
|
|
143
|
+
> - If you configure `advanced.mcpServers` and want the agent to auto-use tools from those servers without approvals, include the exact tool names in `allowedTools` (e.g. `["mcp__my_server__tools/list"]`). Otherwise you will see permission requests via `claude_code_check`.
|
|
144
|
+
> - `advanced.includePartialMessages` affects the underlying SDK event stream; intermediate messages are captured as events and returned via `claude_code_check` (the `claude_code` call itself does not stream).
|
|
130
145
|
|
|
131
146
|
### `claude_code_reply` — Continue a session
|
|
132
147
|
|
|
133
148
|
Continue an existing session by sending a follow-up message. The agent retains full context from previous turns including files read, code analysis, and conversation history.
|
|
134
149
|
|
|
135
|
-
| Parameter
|
|
136
|
-
|
|
|
137
|
-
| `sessionId`
|
|
138
|
-
| `prompt`
|
|
139
|
-
| `forkSession`
|
|
140
|
-
| `
|
|
150
|
+
| Parameter | Type | Required | Description |
|
|
151
|
+
| ---------------------------- | ------- | -------- | ---------------------------------------------------------------------------------------------------------------- |
|
|
152
|
+
| `sessionId` | string | Yes | Session ID from a previous `claude_code` call |
|
|
153
|
+
| `prompt` | string | Yes | Follow-up prompt |
|
|
154
|
+
| `forkSession` | boolean | No | Create a branched copy of this session. Default: `false` |
|
|
155
|
+
| `permissionRequestTimeoutMs` | number | No | Timeout in milliseconds waiting for permission decisions. Default: `60000` |
|
|
156
|
+
| `sessionInitTimeoutMs` | number | No | Timeout in milliseconds waiting for fork `system/init`. Default: `10000` |
|
|
157
|
+
| `diskResumeConfig` | object | No | Disk resume parameters (see below). Used when `CLAUDE_CODE_MCP_ALLOW_DISK_RESUME=1` and in-memory session is missing |
|
|
141
158
|
|
|
142
159
|
<details>
|
|
143
|
-
<summary
|
|
144
|
-
|
|
145
|
-
| Parameter
|
|
146
|
-
|
|
|
147
|
-
| `
|
|
148
|
-
| `
|
|
149
|
-
| `
|
|
150
|
-
| `
|
|
151
|
-
| `
|
|
152
|
-
| `
|
|
153
|
-
| `maxTurns`
|
|
154
|
-
| `model`
|
|
155
|
-
| `systemPrompt`
|
|
156
|
-
| `agents`
|
|
157
|
-
| `
|
|
158
|
-
| `
|
|
159
|
-
| `
|
|
160
|
-
| `
|
|
161
|
-
| `
|
|
162
|
-
| `
|
|
163
|
-
| `
|
|
164
|
-
| `
|
|
165
|
-
| `
|
|
166
|
-
| `mcpServers`
|
|
167
|
-
| `sandbox`
|
|
168
|
-
| `fallbackModel`
|
|
169
|
-
| `enableFileCheckpointing`
|
|
170
|
-
| `includePartialMessages`
|
|
171
|
-
| `strictMcpConfig`
|
|
172
|
-
| `settingSources`
|
|
173
|
-
| `debug`
|
|
174
|
-
| `debugFile`
|
|
175
|
-
| `env`
|
|
160
|
+
<summary><code>diskResumeConfig</code> object parameters (28 disk-resume-only parameters)</summary>
|
|
161
|
+
|
|
162
|
+
| Parameter | Type | Description |
|
|
163
|
+
| -------------------------------------------- | ------------------ | --------------------------------------------------- |
|
|
164
|
+
| `diskResumeConfig.resumeToken` | string | Resume token returned by `claude_code` / `claude_code_reply`. Required for disk resume fallback |
|
|
165
|
+
| `diskResumeConfig.cwd` | string | Working directory. Required for disk resume. |
|
|
166
|
+
| `diskResumeConfig.allowedTools` | string[] | Auto-approved tool names (see `claude_code`). Default: `[]` |
|
|
167
|
+
| `diskResumeConfig.disallowedTools` | string[] | Forbidden tool names (see `claude_code`). Default: `[]` |
|
|
168
|
+
| `diskResumeConfig.tools` | string[] \| object | Base tool set (see `claude_code`). Default: SDK/Claude Code default |
|
|
169
|
+
| `diskResumeConfig.persistSession` | boolean | Persist session history to disk. Default: `true` |
|
|
170
|
+
| `diskResumeConfig.maxTurns` | number | Maximum number of agent reasoning steps. Default: SDK/Claude Code default |
|
|
171
|
+
| `diskResumeConfig.model` | string | Model to use. Default: SDK/Claude Code default |
|
|
172
|
+
| `diskResumeConfig.systemPrompt` | string \| object | Override the agent's system prompt. Default: SDK/Claude Code default |
|
|
173
|
+
| `diskResumeConfig.agents` | object | Custom sub-agent definitions (see `claude_code`). Default: none |
|
|
174
|
+
| `diskResumeConfig.agent` | string | Primary agent name (see `claude_code` tool). Default: omitted |
|
|
175
|
+
| `diskResumeConfig.maxBudgetUsd` | number | Maximum budget in USD. Default: SDK/Claude Code default |
|
|
176
|
+
| `diskResumeConfig.effort` | string | Effort level. Default: SDK/Claude Code default |
|
|
177
|
+
| `diskResumeConfig.betas` | string[] | Beta features. Default: none |
|
|
178
|
+
| `diskResumeConfig.additionalDirectories` | string[] | Additional directories. Default: none |
|
|
179
|
+
| `diskResumeConfig.outputFormat` | object | Structured output format. Default: omitted (plain text) |
|
|
180
|
+
| `diskResumeConfig.thinking` | object | Thinking mode. Default: SDK/Claude Code default |
|
|
181
|
+
| `diskResumeConfig.resumeSessionAt` | string | Resume only up to and including a specific message UUID. Default: omitted |
|
|
182
|
+
| `diskResumeConfig.pathToClaudeCodeExecutable` | string | Path to Claude Code executable. Default: SDK-bundled Claude Code (cli.js) |
|
|
183
|
+
| `diskResumeConfig.mcpServers` | object | MCP server configurations. Default: none |
|
|
184
|
+
| `diskResumeConfig.sandbox` | object | Sandbox config for command isolation. Default: SDK/Claude Code default |
|
|
185
|
+
| `diskResumeConfig.fallbackModel` | string | Fallback model. Default: none |
|
|
186
|
+
| `diskResumeConfig.enableFileCheckpointing` | boolean | Enable file checkpointing. Default: `false` |
|
|
187
|
+
| `diskResumeConfig.includePartialMessages` | boolean | Include intermediate streaming messages. Default: `false` |
|
|
188
|
+
| `diskResumeConfig.strictMcpConfig` | boolean | Strict MCP config validation. Default: `false` |
|
|
189
|
+
| `diskResumeConfig.settingSources` | string[] | Which filesystem settings to load. Default: `["user", "project", "local"]` |
|
|
190
|
+
| `diskResumeConfig.debug` | boolean | Debug mode. Default: `false` |
|
|
191
|
+
| `diskResumeConfig.debugFile` | string | Debug log file path. Default: omitted |
|
|
192
|
+
| `diskResumeConfig.env` | object | Environment variables. Default: inherit process.env (user values override) |
|
|
176
193
|
|
|
177
194
|
</details>
|
|
178
195
|
|
|
179
|
-
**Returns:** `{ sessionId,
|
|
196
|
+
**Returns:** `{ sessionId, status: "running", pollInterval, resumeToken? }`
|
|
180
197
|
|
|
181
|
-
|
|
198
|
+
Notes:
|
|
199
|
+
- `resumeToken` is omitted by default, and is only returned when `CLAUDE_CODE_MCP_RESUME_SECRET` is set on the server.
|
|
200
|
+
- On error: `{ sessionId, status: "error", error }`
|
|
201
|
+
|
|
202
|
+
Use `claude_code_check` to poll events and obtain the final `result`.
|
|
203
|
+
|
|
204
|
+
**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).
|
|
182
205
|
|
|
183
206
|
### `claude_code_session` — Manage sessions
|
|
184
207
|
|
|
@@ -188,48 +211,112 @@ List, inspect, or cancel sessions.
|
|
|
188
211
|
| ------------------ | ------- | -------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
189
212
|
| `action` | string | Yes | `"list"`, `"get"`, or `"cancel"` |
|
|
190
213
|
| `sessionId` | string | For get/cancel | Target session ID |
|
|
191
|
-
| `includeSensitive` | boolean | No | Include `cwd`/`systemPrompt`/`agents`/`additionalDirectories` (default: false
|
|
214
|
+
| `includeSensitive` | boolean | No | Include `cwd`/`systemPrompt`/`agents`/`additionalDirectories` (default: false) |
|
|
192
215
|
|
|
193
216
|
**Returns:** `{ sessions, message?, isError? }`
|
|
194
217
|
|
|
195
|
-
### `
|
|
218
|
+
### `claude_code_check` — Poll events and respond to permission requests
|
|
219
|
+
|
|
220
|
+
Poll session events/results and approve/deny pending permission requests.
|
|
221
|
+
|
|
222
|
+
| Parameter | Type | Required | Description |
|
|
223
|
+
| ------------------------- | ------- | ---------------------- | -------------------------------------------------------------------------------------------------------------------------- |
|
|
224
|
+
| `action` | string | Yes | `"poll"` or `"respond_permission"` |
|
|
225
|
+
| `sessionId` | string | Yes | Target session ID |
|
|
226
|
+
| `cursor` | number | No | Event cursor for incremental polling (`poll` only). Default: omitted (starts from the beginning of the buffer) |
|
|
227
|
+
| `responseMode` | string | No | `"minimal"` (default) or `"full"` — controls payload size and redaction behavior |
|
|
228
|
+
| `maxEvents` | number | No | Max events per poll (pagination via `nextCursor`). Default: `200` in `"minimal"`; unlimited in `"full"` |
|
|
229
|
+
| `requestId` | string | For respond_permission | Permission request ID |
|
|
230
|
+
| `decision` | string | For respond_permission | `"allow"` or `"deny"` |
|
|
231
|
+
| `denyMessage` | string | No | Deny reason shown to Claude (`deny` only). Default: `"Permission denied by caller"` |
|
|
232
|
+
| `interrupt` | boolean | No | When true, denying also interrupts the whole agent (`deny` only). Default: `false` |
|
|
233
|
+
| `pollOptions` | object | No | Fine-grained poll control options (see below) |
|
|
234
|
+
| `permissionOptions` | object | No | Advanced permission response options (see below) |
|
|
235
|
+
|
|
236
|
+
<details>
|
|
237
|
+
<summary><code>pollOptions</code> object parameters (9 fine-grained poll controls)</summary>
|
|
238
|
+
|
|
239
|
+
| Parameter | Type | Description |
|
|
240
|
+
| ---------------------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------- |
|
|
241
|
+
| `pollOptions.includeTools` | boolean | When true, includes `availableTools` (`poll` only). Default: `false` (omitted until session init is received) |
|
|
242
|
+
| `pollOptions.includeEvents` | boolean | When false, omits `events` (but `nextCursor` still advances). Default: `true` |
|
|
243
|
+
| `pollOptions.includeActions` | boolean | When false, omits `actions[]` even if `waiting_permission`. Default: `true` |
|
|
244
|
+
| `pollOptions.includeResult` | boolean | When false, omits top-level `result` even when `idle`/`error`. Default: `true` |
|
|
245
|
+
| `pollOptions.includeUsage` | boolean | Include `result.usage` (default: true in full mode, false in minimal mode) |
|
|
246
|
+
| `pollOptions.includeModelUsage` | boolean | Include `result.modelUsage` (default: true in full mode, false in minimal mode) |
|
|
247
|
+
| `pollOptions.includeStructuredOutput` | boolean | Include `result.structuredOutput` (default: true in full mode, false in minimal mode) |
|
|
248
|
+
| `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"` |
|
|
249
|
+
| `pollOptions.includeProgressEvents` | boolean | When true, includes progress events (`tool_progress`, `auth_status`) in the events stream. Default: `false` in `"minimal"`, `true` in `"full"` |
|
|
250
|
+
|
|
251
|
+
</details>
|
|
252
|
+
|
|
253
|
+
<details>
|
|
254
|
+
<summary><code>permissionOptions</code> object parameters (2 advanced permission response options)</summary>
|
|
196
255
|
|
|
197
|
-
|
|
256
|
+
| Parameter | Type | Description |
|
|
257
|
+
| ---------------------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------- |
|
|
258
|
+
| `permissionOptions.updatedInput` | object | Modified tool input to run (`allow` only). Default: none |
|
|
259
|
+
| `permissionOptions.updatedPermissions` | array | Permission rule updates suggested/applied (`allow` only). Default: none |
|
|
198
260
|
|
|
199
|
-
|
|
200
|
-
| --------- | ------ | -------- | -------------------------------------------------------- |
|
|
201
|
-
| `action` | string | Yes | `"enable_bypass"`, `"disable_bypass"`, or `"get_config"` |
|
|
261
|
+
</details>
|
|
202
262
|
|
|
203
|
-
**Returns:** `{
|
|
263
|
+
**Returns (poll and respond_permission):** `{ sessionId, status, pollInterval?, cursorResetTo?, truncated?, truncatedFields?, events, nextCursor?, availableTools?, actions?, result?, cancelledAt?, cancelledReason?, cancelledSource?, lastEventId?, lastToolUseId? }`
|
|
264
|
+
|
|
265
|
+
Notes:
|
|
266
|
+
|
|
267
|
+
- On error (e.g. invalid arguments, missing/expired session): `{ sessionId, isError: true, error }`
|
|
268
|
+
- Always treat `cursor` as an incremental position: store `nextCursor` and pass it back on the next poll to avoid replaying old events.
|
|
269
|
+
- If `cursorResetTo` is present, your `cursor` was too old (events were evicted); reset your cursor to `cursorResetTo`.
|
|
270
|
+
- For safety, de-duplicate events by `event.id` on the client side.
|
|
271
|
+
- If `truncated=true`, the server intentionally limited the payload (e.g. `maxEvents`) — continue polling with `nextCursor`.
|
|
272
|
+
- 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.
|
|
204
273
|
|
|
205
274
|
## Usage Example
|
|
206
275
|
|
|
207
276
|
```python
|
|
208
|
-
# 1
|
|
209
|
-
|
|
277
|
+
# 1) Start a new session (async start)
|
|
278
|
+
start = await mcp.call_tool("claude_code", {
|
|
210
279
|
"prompt": "Fix the authentication bug in src/auth.ts",
|
|
211
280
|
"cwd": "/path/to/project",
|
|
212
281
|
"allowedTools": ["Read", "Edit", "Bash", "Glob", "Grep"],
|
|
213
|
-
"
|
|
214
|
-
|
|
215
|
-
|
|
216
|
-
|
|
217
|
-
# 2. Continue the session
|
|
218
|
-
result = await mcp.call_tool("claude_code_reply", {
|
|
219
|
-
"sessionId": session_id,
|
|
220
|
-
"prompt": "Now add unit tests for the fix"
|
|
221
|
-
})
|
|
222
|
-
|
|
223
|
-
# 3. List all sessions
|
|
224
|
-
result = await mcp.call_tool("claude_code_session", {
|
|
225
|
-
"action": "list"
|
|
226
|
-
})
|
|
227
|
-
|
|
228
|
-
# 4. Cancel a running session
|
|
229
|
-
result = await mcp.call_tool("claude_code_session", {
|
|
230
|
-
"action": "cancel",
|
|
231
|
-
"sessionId": session_id
|
|
282
|
+
"advanced": {
|
|
283
|
+
"effort": "high",
|
|
284
|
+
"maxBudgetUsd": 5.0
|
|
285
|
+
}
|
|
232
286
|
})
|
|
287
|
+
session_id = json.loads(start)["sessionId"]
|
|
288
|
+
cursor = None
|
|
289
|
+
|
|
290
|
+
# 2) Poll until idle/error/cancelled
|
|
291
|
+
while True:
|
|
292
|
+
polled = await mcp.call_tool("claude_code_check", {
|
|
293
|
+
"action": "poll",
|
|
294
|
+
"sessionId": session_id,
|
|
295
|
+
"cursor": cursor,
|
|
296
|
+
"pollOptions": {
|
|
297
|
+
"includeProgressEvents": True
|
|
298
|
+
}
|
|
299
|
+
})
|
|
300
|
+
data = json.loads(polled)
|
|
301
|
+
cursor = data.get("nextCursor", cursor)
|
|
302
|
+
|
|
303
|
+
# If permission is needed, approve/deny via respond_permission
|
|
304
|
+
for action in data.get("actions", []) or []:
|
|
305
|
+
if action.get("type") == "permission":
|
|
306
|
+
await mcp.call_tool("claude_code_check", {
|
|
307
|
+
"action": "respond_permission",
|
|
308
|
+
"sessionId": session_id,
|
|
309
|
+
"requestId": action["requestId"],
|
|
310
|
+
"decision": "allow"
|
|
311
|
+
})
|
|
312
|
+
|
|
313
|
+
# Final result is available when status becomes idle/error
|
|
314
|
+
if data.get("status") in ["idle", "error", "cancelled"]:
|
|
315
|
+
final_result = data.get("result")
|
|
316
|
+
break
|
|
317
|
+
|
|
318
|
+
# 3) Manage sessions (list/get/cancel)
|
|
319
|
+
result = await mcp.call_tool("claude_code_session", {"action": "list"})
|
|
233
320
|
```
|
|
234
321
|
|
|
235
322
|
## Windows Support
|
|
@@ -285,25 +372,25 @@ setx CLAUDE_CODE_GIT_BASH_PATH "C:\Program Files\Git\bin\bash.exe"
|
|
|
285
372
|
|
|
286
373
|
## Security
|
|
287
374
|
|
|
288
|
-
-
|
|
289
|
-
-
|
|
290
|
-
- **Environment variables are inherited** — the spawned Claude Code process inherits all environment variables (including `ANTHROPIC_API_KEY`) from the parent process by default. The `env` parameter **merges** with `process.env` (user-provided values take precedence), so you can safely add or override individual variables without losing existing ones.
|
|
291
|
-
-
|
|
292
|
-
- `
|
|
375
|
+
- **Async permission approvals** — when a tool call needs approval, the session transitions to `waiting_permission` and surfaces requests via `claude_code_check` (`actions[]`).
|
|
376
|
+
- **No runtime privilege escalation tool** — permission decisions are per-session (allow/deny lists + explicit approvals), and the server does not expose a `claude_code_configure` bypass switch.
|
|
377
|
+
- **Environment variables are inherited** — the spawned Claude Code process inherits all environment variables (including `ANTHROPIC_API_KEY`) from the parent process by default. The `advanced.env` parameter **merges** with `process.env` (user-provided values take precedence), so you can safely add or override individual variables without losing existing ones.
|
|
378
|
+
- Tool visibility vs approvals:
|
|
379
|
+
- Use `advanced.tools` to restrict which tools the agent can *see* (hidden tools cannot be called).
|
|
380
|
+
- Use `allowedTools` to auto-approve specific tools without prompting (the SDK may still prompt for path-based restrictions like `blockedPath`).
|
|
381
|
+
- Use `disallowedTools` to hard-block tools; they are denied even if later approved via `claude_code_check`.
|
|
382
|
+
- `maxTurns` and `advanced.maxBudgetUsd` prevent runaway execution.
|
|
293
383
|
- Sessions auto-expire after 30 minutes of inactivity.
|
|
294
384
|
|
|
295
385
|
## Environment Variables
|
|
296
386
|
|
|
297
387
|
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).
|
|
298
388
|
|
|
299
|
-
| Variable
|
|
300
|
-
|
|
|
301
|
-
| `CLAUDE_CODE_GIT_BASH_PATH`
|
|
302
|
-
| `CLAUDE_CODE_MCP_ALLOW_DISK_RESUME`
|
|
303
|
-
| `
|
|
304
|
-
| `CLAUDE_CODE_MCP_SESSION_TTL_MS` | Idle session time-to-live in milliseconds | `1800000` (30 min) |
|
|
305
|
-
| `CLAUDE_CODE_MCP_RUNNING_SESSION_MAX_MS` | Maximum wall-clock time for a running session before forced cleanup | `14400000` (4 hr) |
|
|
306
|
-
| `CLAUDE_CODE_MCP_CLEANUP_INTERVAL_MS` | How often the cleanup timer runs | `60000` (1 min) |
|
|
389
|
+
| Variable | Description | Default |
|
|
390
|
+
| ------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- | ------------------ |
|
|
391
|
+
| `CLAUDE_CODE_GIT_BASH_PATH` | Path to `bash.exe` on Windows (see [Windows Support](#windows-support)) | Auto-detected |
|
|
392
|
+
| `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) |
|
|
393
|
+
| `CLAUDE_CODE_MCP_RESUME_SECRET` | HMAC secret used to validate `resumeToken` for disk resume fallback (recommended if disk resume is enabled) | *(unset)* |
|
|
307
394
|
|
|
308
395
|
### How to configure
|
|
309
396
|
|
|
@@ -317,7 +404,7 @@ All environment variables are optional. They are set on the MCP server process (
|
|
|
317
404
|
"args": ["-y", "@leo000001/claude-code-mcp"],
|
|
318
405
|
"env": {
|
|
319
406
|
"CLAUDE_CODE_MCP_ALLOW_DISK_RESUME": "1",
|
|
320
|
-
"
|
|
407
|
+
"CLAUDE_CODE_MCP_RESUME_SECRET": "change-me"
|
|
321
408
|
}
|
|
322
409
|
}
|
|
323
410
|
}
|
|
@@ -333,7 +420,7 @@ args = ["-y", "@leo000001/claude-code-mcp"]
|
|
|
333
420
|
|
|
334
421
|
[mcp_servers.claude-code.env]
|
|
335
422
|
CLAUDE_CODE_MCP_ALLOW_DISK_RESUME = "1"
|
|
336
|
-
|
|
423
|
+
CLAUDE_CODE_MCP_RESUME_SECRET = "change-me"
|
|
337
424
|
```
|
|
338
425
|
|
|
339
426
|
**System-wide** — set via your shell profile or OS settings so all processes inherit them:
|
|
@@ -341,9 +428,11 @@ CLAUDE_CODE_MCP_SESSION_TTL_MS = "3600000"
|
|
|
341
428
|
```bash
|
|
342
429
|
# bash / zsh
|
|
343
430
|
export CLAUDE_CODE_MCP_ALLOW_DISK_RESUME=1
|
|
431
|
+
export CLAUDE_CODE_MCP_RESUME_SECRET=change-me
|
|
344
432
|
|
|
345
433
|
# PowerShell (permanent, requires new terminal)
|
|
346
434
|
setx CLAUDE_CODE_MCP_ALLOW_DISK_RESUME 1
|
|
435
|
+
setx CLAUDE_CODE_MCP_RESUME_SECRET change-me
|
|
347
436
|
```
|
|
348
437
|
|
|
349
438
|
## Development
|
|
@@ -364,13 +453,9 @@ MCP Client ←→ (stdio/JSON-RPC) ←→ MCP Server
|
|
|
364
453
|
└── Claude Agent SDK (query())
|
|
365
454
|
```
|
|
366
455
|
|
|
367
|
-
**Session persistence:** The MCP server's Session Manager holds **in-memory** session metadata
|
|
368
|
-
|
|
369
|
-
**Session cleanup tuning (optional):** Configure in-memory session cleanup with:
|
|
456
|
+
**Session persistence:** The MCP server's Session Manager holds **in-memory** session metadata, a snapshot of session options (tool config, limits, `cwd`, allow/deny lists, etc.), and an event buffer used by `claude_code_check`. This metadata is **not** persisted to disk by the MCP server. The actual conversation history is persisted to disk by the Claude Code CLI (under `~/.claude/projects/`) — this is managed by the SDK, not by this MCP server. By default, if the MCP server restarts or the session expires from memory, `claude_code_reply` will return `SESSION_NOT_FOUND` even though the CLI transcript may still exist on disk. You can opt into disk-resume behavior by setting `CLAUDE_CODE_MCP_ALLOW_DISK_RESUME=1`.
|
|
370
457
|
|
|
371
|
-
|
|
372
|
-
- `CLAUDE_CODE_MCP_RUNNING_SESSION_MAX_MS` (default: 14400000)
|
|
373
|
-
- `CLAUDE_CODE_MCP_CLEANUP_INTERVAL_MS` (default: 60000)
|
|
458
|
+
Sessions are automatically cleaned up after 30 minutes of idle time, or after 4 hours of continuous running.
|
|
374
459
|
|
|
375
460
|
**Turn/Cost semantics:** `numTurns` and `totalCostUsd` are per-call increments. For cumulative per-session totals, use `sessionTotalTurns` and `sessionTotalCostUsd`. When `forkSession=true`, the returned `sessionId` (and `sessionTotal*`) refer to the forked session; the original session totals are preserved.
|
|
376
461
|
|
|
@@ -382,6 +467,7 @@ MCP server validation/policy errors are returned as `Error [CODE]: message` wher
|
|
|
382
467
|
- `SESSION_NOT_FOUND` — session not found in memory (expired or server restarted)
|
|
383
468
|
- `SESSION_BUSY` — session currently running
|
|
384
469
|
- `PERMISSION_DENIED` — operation not allowed by server policy
|
|
470
|
+
- `PERMISSION_REQUEST_NOT_FOUND` — permission request ID not found (already finished or expired)
|
|
385
471
|
- `TIMEOUT` — operation timed out
|
|
386
472
|
- `CANCELLED` — session was cancelled
|
|
387
473
|
- `INTERNAL` — unexpected error or protocol mismatch
|
package/SECURITY.md
CHANGED
|
@@ -18,9 +18,9 @@ We aim to acknowledge reports within 48 hours and provide a fix or mitigation pl
|
|
|
18
18
|
|
|
19
19
|
## Security Considerations
|
|
20
20
|
|
|
21
|
-
-
|
|
21
|
+
- 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`.
|
|
22
22
|
- The MCP server uses the Claude Agent SDK's bundled CLI (`cli.js`), not the system-installed `claude` binary
|
|
23
23
|
- 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)
|
|
24
|
-
- Disk resume is disabled by default. If you set `CLAUDE_CODE_MCP_ALLOW_DISK_RESUME=1`,
|
|
25
|
-
- `claude_code_session` redacts sensitive fields by default; `includeSensitive`
|
|
24
|
+
- 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`.
|
|
25
|
+
- `claude_code_session` redacts sensitive fields (cwd, systemPrompt, agents, additionalDirectories) by default; use `includeSensitive=true` to include them
|
|
26
26
|
- Sessions auto-expire after 30 minutes of inactivity
|