@leo000001/claude-code-mcp 1.5.0 → 1.7.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 +38 -0
- package/CODE_OF_CONDUCT.md +4 -4
- package/CONTRIBUTING.md +2 -2
- package/README.md +220 -129
- package/SECURITY.md +3 -3
- package/dist/index.js +1684 -1055
- package/dist/index.js.map +1 -1
- package/package.json +5 -3
- package/DESIGN.md +0 -238
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,43 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
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)
|
|
30
|
+
|
|
31
|
+
### Bug Fixes
|
|
32
|
+
- Windows: fixed Git Bash auto-detection path derivation and improved candidate search
|
|
33
|
+
|
|
34
|
+
### Security
|
|
35
|
+
- `claude_code_session includeSensitive=true` no longer leaks extra fields (e.g. `env`, `debugFile`, `mcpServers`, `sandbox`) beyond the documented sensitive set
|
|
36
|
+
|
|
37
|
+
### Documentation
|
|
38
|
+
- README: clarify `Task` is required for subagent invocation and how `allowedTools` interacts with `mcpServers`
|
|
39
|
+
- README: clarify `includePartialMessages` is not streamed over MCP responses
|
|
40
|
+
|
|
3
41
|
## 1.4.0 (2026-02-11)
|
|
4
42
|
|
|
5
43
|
### Features
|
package/CODE_OF_CONDUCT.md
CHANGED
|
@@ -28,10 +28,10 @@ Examples of unacceptable behavior:
|
|
|
28
28
|
|
|
29
29
|
## Enforcement
|
|
30
30
|
|
|
31
|
-
Instances of abusive, harassing, or otherwise unacceptable behavior may be
|
|
32
|
-
|
|
33
|
-
(preferred for sensitive reports)
|
|
34
|
-
[GitHub Issues](https://github.com/xihuai18/claude-code-mcp/issues) for non-sensitive matters
|
|
31
|
+
Instances of abusive, harassing, or otherwise unacceptable behavior may be reported:
|
|
32
|
+
|
|
33
|
+
- Privately via [GitHub Security Advisories](https://github.com/xihuai18/claude-code-mcp/security/advisories/new) (preferred for sensitive reports)
|
|
34
|
+
- Publicly via [GitHub Issues](https://github.com/xihuai18/claude-code-mcp/issues) for non-sensitive matters
|
|
35
35
|
|
|
36
36
|
For security vulnerabilities, please follow [SECURITY.md](SECURITY.md).
|
|
37
37
|
|
package/CONTRIBUTING.md
CHANGED
|
@@ -12,7 +12,7 @@ npm install
|
|
|
12
12
|
|
|
13
13
|
## Development Workflow
|
|
14
14
|
|
|
15
|
-
1. Create a feature branch from
|
|
15
|
+
1. Create a feature branch from the default branch
|
|
16
16
|
2. Make your changes
|
|
17
17
|
3. Ensure all checks pass:
|
|
18
18
|
```bash
|
|
@@ -22,7 +22,7 @@ npm install
|
|
|
22
22
|
npm run format:check # Prettier
|
|
23
23
|
```
|
|
24
24
|
4. Commit your changes (pre-commit hooks will run lint-staged + typecheck + test)
|
|
25
|
-
5. Open a Pull Request against
|
|
25
|
+
5. Open a Pull Request against the default branch
|
|
26
26
|
|
|
27
27
|
## Code Style
|
|
28
28
|
|
package/README.md
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
# claude-code-mcp
|
|
2
2
|
|
|
3
3
|
[](https://www.npmjs.com/package/@leo000001/claude-code-mcp)
|
|
4
|
-
[](https://github.com/xihuai18/claude-code-mcp/blob/
|
|
4
|
+
[](https://github.com/xihuai18/claude-code-mcp/blob/HEAD/LICENSE)
|
|
5
5
|
[](https://nodejs.org)
|
|
6
6
|
|
|
7
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.
|
|
@@ -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,92 +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`.
|
|
140
|
+
|
|
141
|
+
> Notes:
|
|
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.
|
|
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).
|
|
125
145
|
|
|
126
146
|
### `claude_code_reply` — Continue a session
|
|
127
147
|
|
|
128
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.
|
|
129
149
|
|
|
130
|
-
| Parameter
|
|
131
|
-
|
|
|
132
|
-
| `sessionId`
|
|
133
|
-
| `prompt`
|
|
134
|
-
| `forkSession`
|
|
135
|
-
| `
|
|
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 |
|
|
136
158
|
|
|
137
159
|
<details>
|
|
138
|
-
<summary
|
|
139
|
-
|
|
140
|
-
| Parameter
|
|
141
|
-
|
|
|
142
|
-
| `
|
|
143
|
-
| `
|
|
144
|
-
| `
|
|
145
|
-
| `
|
|
146
|
-
| `
|
|
147
|
-
| `
|
|
148
|
-
| `maxTurns`
|
|
149
|
-
| `model`
|
|
150
|
-
| `systemPrompt`
|
|
151
|
-
| `agents`
|
|
152
|
-
| `
|
|
153
|
-
| `
|
|
154
|
-
| `
|
|
155
|
-
| `
|
|
156
|
-
| `
|
|
157
|
-
| `
|
|
158
|
-
| `
|
|
159
|
-
| `
|
|
160
|
-
| `
|
|
161
|
-
| `mcpServers`
|
|
162
|
-
| `sandbox`
|
|
163
|
-
| `fallbackModel`
|
|
164
|
-
| `enableFileCheckpointing`
|
|
165
|
-
| `includePartialMessages`
|
|
166
|
-
| `strictMcpConfig`
|
|
167
|
-
| `settingSources`
|
|
168
|
-
| `debug`
|
|
169
|
-
| `debugFile`
|
|
170
|
-
| `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) |
|
|
171
193
|
|
|
172
194
|
</details>
|
|
173
195
|
|
|
174
|
-
**Returns:** `{ sessionId,
|
|
196
|
+
**Returns:** `{ sessionId, status: "running", pollInterval, resumeToken? }`
|
|
175
197
|
|
|
176
|
-
|
|
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).
|
|
177
205
|
|
|
178
206
|
### `claude_code_session` — Manage sessions
|
|
179
207
|
|
|
@@ -183,48 +211,112 @@ List, inspect, or cancel sessions.
|
|
|
183
211
|
| ------------------ | ------- | -------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
184
212
|
| `action` | string | Yes | `"list"`, `"get"`, or `"cancel"` |
|
|
185
213
|
| `sessionId` | string | For get/cancel | Target session ID |
|
|
186
|
-
| `includeSensitive` | boolean | No | Include `cwd`/`systemPrompt`/`agents`/`additionalDirectories` (default: false
|
|
214
|
+
| `includeSensitive` | boolean | No | Include `cwd`/`systemPrompt`/`agents`/`additionalDirectories` (default: false) |
|
|
187
215
|
|
|
188
216
|
**Returns:** `{ sessions, message?, isError? }`
|
|
189
217
|
|
|
190
|
-
### `
|
|
218
|
+
### `claude_code_check` — Poll events and respond to permission requests
|
|
191
219
|
|
|
192
|
-
|
|
220
|
+
Poll session events/results and approve/deny pending permission requests.
|
|
193
221
|
|
|
194
|
-
| Parameter
|
|
195
|
-
|
|
|
196
|
-
| `action`
|
|
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"` |
|
|
197
250
|
|
|
198
|
-
|
|
251
|
+
</details>
|
|
252
|
+
|
|
253
|
+
<details>
|
|
254
|
+
<summary><code>permissionOptions</code> object parameters (2 advanced permission response options)</summary>
|
|
255
|
+
|
|
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 |
|
|
260
|
+
|
|
261
|
+
</details>
|
|
262
|
+
|
|
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.
|
|
199
273
|
|
|
200
274
|
## Usage Example
|
|
201
275
|
|
|
202
276
|
```python
|
|
203
|
-
# 1
|
|
204
|
-
|
|
277
|
+
# 1) Start a new session (async start)
|
|
278
|
+
start = await mcp.call_tool("claude_code", {
|
|
205
279
|
"prompt": "Fix the authentication bug in src/auth.ts",
|
|
206
280
|
"cwd": "/path/to/project",
|
|
207
281
|
"allowedTools": ["Read", "Edit", "Bash", "Glob", "Grep"],
|
|
208
|
-
"
|
|
209
|
-
|
|
210
|
-
|
|
211
|
-
|
|
212
|
-
# 2. Continue the session
|
|
213
|
-
result = await mcp.call_tool("claude_code_reply", {
|
|
214
|
-
"sessionId": session_id,
|
|
215
|
-
"prompt": "Now add unit tests for the fix"
|
|
216
|
-
})
|
|
217
|
-
|
|
218
|
-
# 3. List all sessions
|
|
219
|
-
result = await mcp.call_tool("claude_code_session", {
|
|
220
|
-
"action": "list"
|
|
221
|
-
})
|
|
222
|
-
|
|
223
|
-
# 4. Cancel a running session
|
|
224
|
-
result = await mcp.call_tool("claude_code_session", {
|
|
225
|
-
"action": "cancel",
|
|
226
|
-
"sessionId": session_id
|
|
282
|
+
"advanced": {
|
|
283
|
+
"effort": "high",
|
|
284
|
+
"maxBudgetUsd": 5.0
|
|
285
|
+
}
|
|
227
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"})
|
|
228
320
|
```
|
|
229
321
|
|
|
230
322
|
## Windows Support
|
|
@@ -280,25 +372,25 @@ setx CLAUDE_CODE_GIT_BASH_PATH "C:\Program Files\Git\bin\bash.exe"
|
|
|
280
372
|
|
|
281
373
|
## Security
|
|
282
374
|
|
|
283
|
-
-
|
|
284
|
-
-
|
|
285
|
-
- **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.
|
|
286
|
-
-
|
|
287
|
-
- `
|
|
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.
|
|
288
383
|
- Sessions auto-expire after 30 minutes of inactivity.
|
|
289
384
|
|
|
290
385
|
## Environment Variables
|
|
291
386
|
|
|
292
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).
|
|
293
388
|
|
|
294
|
-
| Variable
|
|
295
|
-
|
|
|
296
|
-
| `CLAUDE_CODE_GIT_BASH_PATH`
|
|
297
|
-
| `CLAUDE_CODE_MCP_ALLOW_DISK_RESUME`
|
|
298
|
-
| `
|
|
299
|
-
| `CLAUDE_CODE_MCP_SESSION_TTL_MS` | Idle session time-to-live in milliseconds | `1800000` (30 min) |
|
|
300
|
-
| `CLAUDE_CODE_MCP_RUNNING_SESSION_MAX_MS` | Maximum wall-clock time for a running session before forced cleanup | `14400000` (4 hr) |
|
|
301
|
-
| `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)* |
|
|
302
394
|
|
|
303
395
|
### How to configure
|
|
304
396
|
|
|
@@ -312,7 +404,7 @@ All environment variables are optional. They are set on the MCP server process (
|
|
|
312
404
|
"args": ["-y", "@leo000001/claude-code-mcp"],
|
|
313
405
|
"env": {
|
|
314
406
|
"CLAUDE_CODE_MCP_ALLOW_DISK_RESUME": "1",
|
|
315
|
-
"
|
|
407
|
+
"CLAUDE_CODE_MCP_RESUME_SECRET": "change-me"
|
|
316
408
|
}
|
|
317
409
|
}
|
|
318
410
|
}
|
|
@@ -328,7 +420,7 @@ args = ["-y", "@leo000001/claude-code-mcp"]
|
|
|
328
420
|
|
|
329
421
|
[mcp_servers.claude-code.env]
|
|
330
422
|
CLAUDE_CODE_MCP_ALLOW_DISK_RESUME = "1"
|
|
331
|
-
|
|
423
|
+
CLAUDE_CODE_MCP_RESUME_SECRET = "change-me"
|
|
332
424
|
```
|
|
333
425
|
|
|
334
426
|
**System-wide** — set via your shell profile or OS settings so all processes inherit them:
|
|
@@ -336,9 +428,11 @@ CLAUDE_CODE_MCP_SESSION_TTL_MS = "3600000"
|
|
|
336
428
|
```bash
|
|
337
429
|
# bash / zsh
|
|
338
430
|
export CLAUDE_CODE_MCP_ALLOW_DISK_RESUME=1
|
|
431
|
+
export CLAUDE_CODE_MCP_RESUME_SECRET=change-me
|
|
339
432
|
|
|
340
433
|
# PowerShell (permanent, requires new terminal)
|
|
341
434
|
setx CLAUDE_CODE_MCP_ALLOW_DISK_RESUME 1
|
|
435
|
+
setx CLAUDE_CODE_MCP_RESUME_SECRET change-me
|
|
342
436
|
```
|
|
343
437
|
|
|
344
438
|
## Development
|
|
@@ -359,13 +453,9 @@ MCP Client ←→ (stdio/JSON-RPC) ←→ MCP Server
|
|
|
359
453
|
└── Claude Agent SDK (query())
|
|
360
454
|
```
|
|
361
455
|
|
|
362
|
-
**Session persistence:** The MCP server's Session Manager holds **in-memory** session metadata
|
|
363
|
-
|
|
364
|
-
**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`.
|
|
365
457
|
|
|
366
|
-
|
|
367
|
-
- `CLAUDE_CODE_MCP_RUNNING_SESSION_MAX_MS` (default: 14400000)
|
|
368
|
-
- `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.
|
|
369
459
|
|
|
370
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.
|
|
371
461
|
|
|
@@ -377,6 +467,7 @@ MCP server validation/policy errors are returned as `Error [CODE]: message` wher
|
|
|
377
467
|
- `SESSION_NOT_FOUND` — session not found in memory (expired or server restarted)
|
|
378
468
|
- `SESSION_BUSY` — session currently running
|
|
379
469
|
- `PERMISSION_DENIED` — operation not allowed by server policy
|
|
470
|
+
- `PERMISSION_REQUEST_NOT_FOUND` — permission request ID not found (already finished or expired)
|
|
380
471
|
- `TIMEOUT` — operation timed out
|
|
381
472
|
- `CANCELLED` — session was cancelled
|
|
382
473
|
- `INTERNAL` — unexpected error or protocol mismatch
|