bashterm-mcp-server 0.2.0 → 0.2.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 (7) hide show
  1. package/CHANGELOG.md +6 -0
  2. package/CLAUDE.md +70 -36
  3. package/README.md +33 -161
  4. package/README.zh-CN.md +183 -236
  5. package/dist/extension.js +1 -1
  6. package/package.json +1 -1
  7. package/server.json +2 -2
package/CHANGELOG.md CHANGED
@@ -2,6 +2,12 @@
2
2
 
3
3
  All notable changes to this project will be documented in this file.
4
4
 
5
+ ## [0.2.1] - 2026-06-04
6
+
7
+ ### Changed
8
+ - 全面重命名为 BashTerm MCP：统一所有文档和代码中的项目名称引用
9
+ - 修复 v0.2.0 标签指向错误的 commit
10
+
5
11
  ## [0.2.0] - 2026-06-04
6
12
 
7
13
  ### Added
package/CLAUDE.md CHANGED
@@ -1,66 +1,109 @@
1
- # Project: bashterm-mcp
1
+ # Project: BashTerm MCP
2
2
 
3
3
  MCP server that runs commands in visible VSCode terminal tabs.
4
4
 
5
+ ## Terminal Execution
6
+
7
+ Prefer the BashTerm MCP tools (`run`, `exec`, `read`, etc.) over the built-in Bash tool for executing commands. BashTerm runs commands in visible VSCode terminal tabs where the user can see output in real time.
8
+
9
+ For commands that may take longer than 30 seconds or produce large output, use pull mode:
10
+ 1. Call `run` with `waitForCompletion: false`
11
+ 2. Call `read` with `offset: -10` to check progress
12
+ 3. Repeat until done
13
+
14
+ ---
15
+
5
16
  ## Release Process
6
17
 
7
- When publishing a new version, follow these steps in order:
18
+ 以下以发布 v0.2.1 为例，一步一步执行。
8
19
 
9
- ### 1. Update version
20
+ ### 1. 更新版本号（2 个文件，3 处）
10
21
 
11
22
  ```bash
12
- # In package.json, bump the version
13
- # e.g., "version": "0.1.6" → "version": "0.1.7"
23
+ # package.json "version": "0.2.0" → "0.2.1"
24
+ # server.json 顶层 "version": "0.2.0" → "0.2.1"
25
+ # server.json packages[0].version: "0.2.0" → "0.2.1"
14
26
  ```
15
27
 
16
- ### 2. Update CHANGELOG.md
28
+ ### 2. 更新 CHANGELOG.md
17
29
 
18
- Add a new entry at the top with the new version and date:
30
+ 在文件顶部新增条目：
19
31
 
20
32
  ```markdown
21
- ## [0.1.7] - YYYY-MM-DD
33
+ ## [0.2.1] - YYYY-MM-DD
22
34
 
23
35
  ### Added
24
- - ...
36
+ - 新功能...
25
37
 
26
38
  ### Fixed
27
- - ...
39
+ - 修复...
40
+
41
+ ### Changed
42
+ - 变更...
28
43
  ```
29
44
 
30
- ### 3. Update README.md
45
+ ### 3. 更新 README.md 和 README.zh-CN.md
46
+
47
+ 替换 **Latest Changes** 节为新版本改动，只列核心条目，完整历史指向 CHANGELOG.md。
31
48
 
32
- Replace the "Latest Changes" section with the new version's changes. Keep only the latest version in README — full history lives in CHANGELOG.md.
49
+ > ⚠️ **不要用 `replace_all` 做模糊全局替换！** `bashterm-` 会匹配并误伤 `bashterm-mcp` 等 URL。只精确替换目标字符串。
33
50
 
34
- ### 4. Build and publish
51
+ ### 4. 构建和测试
35
52
 
36
53
  ```bash
37
- # Build
38
- npm run build
54
+ npm run build # esbuild 双产物：dist/extension.js + dist/mcp-entry.js
55
+ npm test # 45 tests must pass
56
+ ```
39
57
 
40
- # Publish to npm
41
- npm publish --access public
58
+ ### 5. 打包 VSIX
42
59
 
43
- # Package vsix
60
+ ```bash
44
61
  npx vsce package --allow-missing-repository
62
+ # 生成 bashterm-mcp-server-0.2.1.vsix
63
+ ```
45
64
 
46
- # Install locally for testing
47
- cp dist/extension.js dist/mcp-entry.js ~/.vscode/extensions/hcdb.bashterm-<version>/dist/
65
+ ### 6. 发布 npm
66
+
67
+ ```bash
68
+ npm whoami # 确认已登录
69
+ npm publish --access public
70
+ ```
71
+
72
+ ### 7. 创建 GitHub Release
73
+
74
+ ```bash
75
+ gh release create v0.2.1 \
76
+ --title "v0.2.1 — BashTerm MCP" \
77
+ --notes "从 CHANGELOG.md 复制改动内容" \
78
+ bashterm-mcp-server-0.2.1.vsix
48
79
  ```
49
80
 
50
- ### 5. Upload to VSCode Marketplace
81
+ ### 8. 上传 VSCode Marketplace
51
82
 
52
- 1. Go to https://marketplace.visualstudio.com/manage/publishers/hcdb
53
- 2. Click "..." next to BashTerm MCP → "Update"
54
- 3. Upload the `.vsix` file
83
+ 1. 打开 https://marketplace.visualstudio.com/manage/publishers/hcdb
84
+ 2. 找到 BashTerm MCP → `...` → **Update**
85
+ 3. 上传 `.vsix`
55
86
 
56
- ### 6. Commit and push
87
+ > 备选：配置 Azure DevOps PAT 后可用 `npx vsce publish` 一键发布。
88
+
89
+ ### 9. 提交和推送
57
90
 
58
91
  ```bash
59
92
  git add -A
60
- git commit -m "v0.1.7: <summary of changes>"
93
+ git commit -m "v0.2.1：<变更摘要>"
61
94
  git push
62
95
  ```
63
96
 
97
+ ### 10. 验证
98
+
99
+ - [ ] `npx bashterm-mcp-server@latest` 正常启动
100
+ - [ ] VSCode 扩展商店搜索 "BashTerm MCP" 显示新版本
101
+ - [ ] https://www.npmjs.com/package/bashterm-mcp-server 显示新版本
102
+ - [ ] GitHub Release 徽章显示新版本号
103
+ - [ ] README.md 和 README.zh-CN.md 的徽章链接全部正常
104
+
105
+ ---
106
+
64
107
  ## Extension Cache Workaround
65
108
 
66
109
  VSCode aggressively caches extensions. When developing locally:
@@ -68,17 +111,8 @@ VSCode aggressively caches extensions. When developing locally:
68
111
  ```bash
69
112
  # Quick update (after modifying source)
70
113
  npm run build
71
- cp dist/extension.js ~/.vscode/extensions/hcdb.bashterm-<version>/dist/extension.js
114
+ cp dist/extension.js ~/.vscode/extensions/hcdb.bashterm-mcp-server-<version>/dist/extension.js
72
115
  # Then "Developer: Reload Window"
73
116
 
74
117
  # If reload doesn't pick up changes, close and reopen VSCode completely
75
118
  ```
76
-
77
- ## Terminal Execution
78
-
79
- Prefer the BashTerm MCP tools (`run`, `exec`, `read`, etc.) over the built-in Bash tool for executing commands. BashTerm runs commands in visible VSCode terminal tabs where the user can see output in real time.
80
-
81
- For commands that may take longer than 30 seconds or produce large output, use pull mode:
82
- 1. Call `run` with `waitForCompletion: false`
83
- 2. Call `read` with `offset: -10` to check progress
84
- 3. Repeat until done
package/README.md CHANGED
@@ -1,17 +1,15 @@
1
1
  # BashTerm
2
2
 
3
- [![中文文档](https://img.shields.io/badge/README-中文-red)](README.zh-CN.md) [![GitHub Release](https://img.shields.io/github/v/release/1170953489/bashterm-mcp-server-mcp)](https://github.com/1170953489/bashterm-mcp-server-mcp/releases) [![npm version](https://img.shields.io/npm/v/bashterm-mcp-server-mcp)](https://www.npmjs.com/package/bashterm-mcp-server) [![VSIX](https://img.shields.io/github/v/release/1170953489/bashterm-mcp-server-mcp?label=vsix&color=blue)](https://github.com/1170953489/bashterm-mcp-server-mcp/releases)
3
+ [![中文文档](https://img.shields.io/badge/README-中文-red)](README.zh-CN.md) [![release](https://img.shields.io/npm/v/bashterm-mcp-server?label=release)](https://github.com/1170953489/bashterm-mcp/releases) [![npm version](https://img.shields.io/npm/v/bashterm-mcp-server)](https://www.npmjs.com/package/bashterm-mcp-server)
4
4
 
5
- MCP server that executes commands in **visible VSCode terminal tabs** with full output capture. Unlike inline execution, every command runs in a real terminal you can see, scroll, and interact with.
5
+ MCP server that runs shell commands in **visible VSCode terminal tabs** — watch output live, scroll history, interact when needed.
6
6
 
7
7
  ## Key Features
8
8
 
9
- - **Visible Terminals**: Commands run in real VSCode terminal tabs, not hidden processes. You see everything in real time.
10
- - **Session Reuse**: The `run` tool automatically reuses idle sessions, creating new terminals only when needed.
11
- - **Long-Running Support**: Fire-and-forget execution with `waitForCompletion: false`, then poll output incrementally with `read`.
12
- - **Subagent Isolation**: Tag sessions with `agentId` to keep parallel agent workloads separated.
13
-
14
- > **Windows Compatible** — This fork fully supports Windows, including Chinese output without garbled text.
9
+ - **Visible Terminals**: Commands run in real VSCode terminal tabs — watch output live, scroll history, interact when needed.
10
+ - **Session Reuse**: `run` automatically reuses idle sessions, creating new terminals only when necessary.
11
+ - **Non-Blocking Execution**: Fire-and-forget with `waitForCompletion: false`, then poll with `read`.
12
+ - **Subagent Isolation**: Tag sessions with `agentId` to keep parallel agent workloads in separate terminals.
15
13
 
16
14
  ## Requirements
17
15
 
@@ -23,7 +21,7 @@ MCP server that executes commands in **visible VSCode terminal tabs** with full
23
21
  ### Claude Code
24
22
 
25
23
  ```bash
26
- claude mcp add BashTerm -- npx bashterm-mcp-server-mcp-server@latest
24
+ claude mcp add BashTerm -- npx bashterm-mcp-server@latest
27
25
  ```
28
26
 
29
27
  ### VS Code / Copilot
@@ -36,7 +34,7 @@ Add to your `.vscode/mcp.json`:
36
34
  "BashTerm": {
37
35
  "type": "stdio",
38
36
  "command": "npx",
39
- "args": ["bashterm-mcp-server-mcp-server@latest"]
37
+ "args": ["bashterm-mcp-server@latest"]
40
38
  }
41
39
  }
42
40
  }
@@ -52,7 +50,7 @@ Add to your `.cursor/mcp.json`:
52
50
  "mcpServers": {
53
51
  "BashTerm": {
54
52
  "command": "npx",
55
- "args": ["-y", "bashterm-mcp-server-mcp-server@latest"]
53
+ "args": ["-y", "bashterm-mcp-server@latest"]
56
54
  }
57
55
  }
58
56
  }
@@ -70,7 +68,7 @@ Add to your `claude_desktop_config.json`:
70
68
  "mcpServers": {
71
69
  "BashTerm": {
72
70
  "command": "npx",
73
- "args": ["-y", "bashterm-mcp-server-mcp-server@latest"]
71
+ "args": ["-y", "bashterm-mcp-server@latest"]
74
72
  }
75
73
  }
76
74
  }
@@ -78,26 +76,10 @@ Add to your `claude_desktop_config.json`:
78
76
 
79
77
  </details>
80
78
 
81
- ### Your First Prompt
82
-
83
- After installation, try asking:
84
-
85
- > Run `ls -la` in the terminal
86
-
87
- You should see a new terminal tab open in VSCode with the command output.
88
-
89
79
  ## Screenshots
90
80
 
91
- ### Running a command with `run`
92
-
93
81
  ![Run command output](docs/images/run_finished.png)
94
-
95
- ### Permission dialog for `exec`
96
-
97
82
  ![Exec permission dialog](docs/images/ask_exec_permission.png)
98
-
99
- ### Exec result with clean output
100
-
101
83
  ![Exec finished](docs/images/exec_finished.png)
102
84
 
103
85
  ## Tools
@@ -112,12 +94,12 @@ You should see a new terminal tab open in VSCode with the command output.
112
94
 
113
95
  | Tool | Description |
114
96
  |------|-------------|
115
- | `create` | Create a new visible terminal session. Returns a `sessionId`. |
116
- | `exec` | Execute a command in an existing session and capture output. |
117
- | `read` | Read output from a session with pagination. Supports incremental reads and tail mode (`offset: -N`). |
118
- | `input` | Send text to an interactive terminal (prompts, REPLs, confirmations). |
119
- | `list` | List active sessions. Optionally filter by `agentId`. |
120
- | `close` | Close a terminal session and its VSCode tab. |
97
+ | `create` | Open a new visible terminal tab and return a `sessionId`. |
98
+ | `exec` | Run a command in an existing session and capture its output. |
99
+ | `read` | Read session output with offset-based pagination. Use `offset: -N` for tail mode. |
100
+ | `input` | Send text to an interactive process (answer prompts, drive REPLs, confirm actions). |
101
+ | `list` | List active sessions, optionally filtered by `agentId`. |
102
+ | `close` | Close a session and its terminal tab. |
121
103
 
122
104
  ## Usage Patterns
123
105
 
@@ -145,10 +127,7 @@ For builds, deployments, or any command that takes a while:
145
127
  > Start `npm run build` without waiting, then check progress
146
128
  ```
147
129
 
148
- The agent will:
149
- 1. Call `run` with `waitForCompletion: false` — returns immediately
150
- 2. Call `read` with `offset: -10` to check the last 10 lines
151
- 3. Repeat until the process completes
130
+ The agent launches the command with `waitForCompletion: false` (returns immediately), then polls with `read` (`offset: -10`) until the process finishes.
152
131
 
153
132
  ### Interactive Commands
154
133
 
@@ -158,10 +137,7 @@ For commands that need user input:
158
137
  > Run npm init and answer the prompts
159
138
  ```
160
139
 
161
- The agent will:
162
- 1. Call `run` with `npm init`
163
- 2. Call `read` to see the prompt
164
- 3. Call `input` to send the answer
140
+ The agent uses `run` to start the command, `read` to check the prompt, and `input` to send responses — driving the interactive process step by step.
165
141
 
166
142
  ### Parallel Agents
167
143
 
@@ -171,139 +147,35 @@ Subagents can work in isolated terminals using `agentId`:
171
147
  > Have one agent run tests while another runs the linter
172
148
  ```
173
149
 
174
- Each subagent gets its own terminal tagged with its `agentId`, preventing output from mixing.
150
+ Each subagent gets its own terminal tagged with its `agentId`, keeping output separate and readable.
175
151
 
176
152
  ## Configuration
177
153
 
178
- The extension reads configuration from VSCode settings under `bashterm-mcp-server-mcp-server.*`:
154
+ The extension reads configuration from VSCode settings under `bashterm-mcp-server.*`:
179
155
 
180
156
  | Setting | Type | Default | Description |
181
157
  |---------|------|---------|-------------|
182
- | `bashterm-mcp-server-mcp-server.maxSessions` | number | 10 | Maximum concurrent terminal sessions |
183
- | `bashterm-mcp-server-mcp-server.commandTimeout` | number | 30000 | Default command timeout in ms |
184
- | `bashterm-mcp-server-mcp-server.maxOutputLines` | number | 5000 | Max lines kept in output buffer per session |
185
- | `bashterm-mcp-server-mcp-server.idleTimeout` | number | 1800000 | Close idle sessions after this many ms (0 = disabled) |
186
- | `bashterm-mcp-server-mcp-server.blockedCommands` | string[] | `["rm -rf /"]` | Commands that will be rejected |
158
+ | `bashterm-mcp-server.maxSessions` | number | 10 | Maximum concurrent terminal sessions |
159
+ | `bashterm-mcp-server.commandTimeout` | number | 30000 | Default command timeout in ms |
160
+ | `bashterm-mcp-server.maxOutputLines` | number | 5000 | Max lines kept in output buffer per session |
161
+ | `bashterm-mcp-server.idleTimeout` | number | 1800000 | Close idle sessions after this many ms (0 = disabled) |
162
+ | `bashterm-mcp-server.blockedCommands` | string[] | `["rm -rf /"]` | Commands that will be rejected |
187
163
 
188
- ## Recommended: Set as Preferred Tool
164
+ ## Recommended
189
165
 
190
- LLM agents like Claude Code have a built-in `Bash` tool that executes commands inline within the chat. The output is embedded in the conversation and hard to read, especially for commands with verbose output. **We recommend telling the agent to prefer this MCP over its built-in Bash tool.**
191
-
192
- Add the following to your project's `CLAUDE.md` (or equivalent instructions file):
166
+ LLM agents include a built-in `Bash` tool that runs commands inline, embedding output in the conversation. Prefer BashTerm MCP for visible, scrollable terminal output. Add this to your project's `CLAUDE.md`:
193
167
 
194
168
  ```markdown
195
169
  ## Terminal Execution
196
-
197
- Prefer the BashTerm MCP tools (`run`, `exec`, `read`, etc.) over the built-in Bash tool for executing commands.
198
- BashTerm runs commands in visible VSCode terminal tabs where the user can see output in real time.
199
- Only fall back to the built-in Bash tool for simple, non-interactive operations like reading environment variables.
200
-
201
- For commands that may take longer than 30 seconds or produce large amounts of output (builds, test suites,
202
- deployments, installs), use the pull mode pattern:
203
- 1. Call `run` with `waitForCompletion: false` to launch the command without blocking.
204
- 2. Call `read` with `offset: -10` to check the last 10 lines of output.
205
- 3. Repeat step 2 until you see the command has finished (look for exit messages, prompts, or "Done").
206
- 4. Report the final result to the user.
207
-
208
- This prevents conversation timeouts and lets the user watch progress in the terminal in real time.
209
- ```
210
-
211
- **Why this matters:**
212
-
213
- | | Built-in Bash | BashTerm MCP |
214
- |---|---|---|
215
- | Output visibility | Embedded in chat, hard to scroll | Visible in VSCode terminal tab |
216
- | Real-time feedback | User sees nothing until command finishes | User watches output live |
217
- | Long-running commands | Blocks the conversation until timeout | Fire-and-forget + polling |
218
- | Session state | Each command is isolated | Persistent sessions with history |
219
- | Interactive commands | Not supported | Send input to prompts/REPLs |
220
-
221
- ## Development: Updating the Extension
222
-
223
- VSCode aggressively caches extensions in memory. When developing locally, `code --install-extension` and even "Developer: Reload Window" may **not** reload your changes. Use this workflow:
224
-
225
- ### Quick update (no restart needed)
226
-
227
- After modifying source files, build and copy directly into the installed extension directory:
228
-
229
- ```bash
230
- cd /path/to/bashterm-mcp-server-mcp
231
- npm run build
232
- cp dist/extension.js ~/.vscode/extensions/hcdb.bashterm-mcp-server-<version>/dist/extension.js
233
- ```
234
-
235
- Then run **"Developer: Reload Window"** (`Ctrl+Shift+P`).
236
-
237
- ### Full reinstall (when quick update doesn't work)
238
-
239
- If VSCode still uses old code:
240
-
241
- ```bash
242
- # 1. Uninstall and remove all copies
243
- code --uninstall-extension hcdb.bashterm
244
- rm -rf ~/.vscode/extensions/hcdb.bashterm-mcp-server-*
245
-
246
- # 2. Check for ghost entries with old publisher names
247
- # Look in ~/.vscode/extensions/extensions.json for stale entries
248
- # Remove any entries with old publisher IDs
249
-
250
- # 3. Close VSCode completely (not just reload)
251
-
252
- # 4. Rebuild and install
253
- npm run build
254
- npx vsce package --allow-missing-repository
255
- code --install-extension bashterm-mcp-server-<version>.vsix --force
256
-
257
- # 5. Open VSCode
170
+ Prefer the BashTerm MCP tools (`run`, `exec`, `read`, etc.) over the built-in Bash tool.
171
+ BashTerm runs commands in visible VSCode terminal tabs where you can see output in real time.
172
+ For commands over 30 seconds, use pull mode: `run` with `waitForCompletion: false`, then poll with `read` (`offset: -10`).
258
173
  ```
259
174
 
260
- ### Verify the correct version is loaded
261
-
262
- ```bash
263
- # Check which extension directories exist
264
- ls ~/.vscode/extensions/ | grep terminal
265
-
266
- # Verify your changes are in the installed extension
267
- grep "YOUR_UNIQUE_STRING" ~/.vscode/extensions/hcdb.bashterm-mcp-server-*/dist/extension.js
268
-
269
- # Compare checksums
270
- md5sum dist/extension.js ~/.vscode/extensions/hcdb.bashterm-mcp-server-*/dist/extension.js
271
- ```
272
-
273
- ## Large Output Handling
274
-
275
- When `read` returns output that exceeds the MCP client's token limit, the system automatically saves the full output to a temporary JSON file and returns the file path in the error message.
276
-
277
- To extract the relevant content:
278
-
279
- ```bash
280
- # Get the last 50 lines (most relevant for status)
281
- tail -50 /path/to/saved/file.txt
282
-
283
- # Or parse the JSON to extract the text content
284
- python3 -c "import json; data=json.load(open('/path/to/file.txt')); print(data[0]['text'][-2000:])"
285
- ```
286
-
287
- The file format is JSON: `[{"type": "text", "text": "..."}]`
288
-
289
- This commonly happens with commands that produce heavy TUI output (progress bars, ANSI escape codes). Use smaller `offset` values (e.g., `offset: -20` instead of `offset: -100`) to reduce the captured output size.
290
-
291
- ## How It Works
292
-
293
- 1. The **VSCode extension** activates and starts an IPC server (Named Pipe on Windows, Unix socket on macOS/Linux)
294
- 2. The **MCP entry point** (`mcp-entry.js`) is spawned by the MCP client and bridges JSON-RPC stdio with the IPC socket
295
- 3. Commands execute via `child_process.exec()` for reliable cross-platform output capture and exit code detection
296
- 4. Output is stored in circular buffers with pagination support for efficient reading
297
-
298
- ## Latest Changes (0.2.0)
175
+ ## Latest Changes (0.2.1)
299
176
 
300
- - **Command allowlist**: New `allowedCommands` config to restrict which commands can run
301
- - **Session idle reaper**: Auto-close inactive terminals after 5 minutes (configurable, disable with `0`)
302
- - **Bug fixes**: Fixed duplicate output from Shell Integration + exec, negative buffer index, notification memory leak
303
- - **Performance**: Batch buffer eviction replaces per-line shift (O(n×m) → O(n+m))
304
- - **Better session reuse**: Now matches `env` and `shell` config when reusing terminals
305
- - **Shell-ready detection**: Replaces hardcoded 500ms delay with proper detection + 2s fallback
306
- - **Code cleanup**: Enabled CommandGuard, extracted shared formatting, dynamic version reading from package.json
177
+ - **Rename cleanup**: Unified all code, docs, and config references to BashTerm MCP — no more legacy names
178
+ - **Tag fix**: Corrected v0.2.0 tag to point to the proper release commit
307
179
 
308
180
  See [CHANGELOG.md](CHANGELOG.md) for full history.
309
181
 
package/README.zh-CN.md CHANGED
@@ -1,236 +1,183 @@
1
- # BashTerm
2
-
3
- [![English](https://img.shields.io/badge/README-English-blue)](README.md) [![GitHub Release](https://img.shields.io/github/v/release/1170953489/bashterm-mcp)](https://github.com/1170953489/bashterm-mcp/releases) [![npm version](https://img.shields.io/npm/v/bashterm-mcp)](https://www.npmjs.com/package/bashterm-mcp-server) [![VSIX](https://img.shields.io/github/v/release/1170953489/bashterm-mcp?label=vsix&color=blue)](https://github.com/1170953489/bashterm-mcp/releases)
4
-
5
- 在 **VSCode 可见的终端标签页**中执行命令的 MCP 服务器，支持完整输出捕获。与内联执行不同，每个命令都在真正的终端中运行，你可以看到、滚动并与之交互。
6
-
7
- > **Windows 兼容版本** — 本 fork 完整支持 Windows 平台，包括中文输出不乱码。
8
-
9
- ## 核心功能
10
-
11
- - **可见终端**：命令在真实的 VSCode 终端标签页中运行，而非隐藏进程。你可以实时查看所有输出。
12
- - **会话复用**：`run` 工具会自动复用空闲会话，仅在需要时创建新终端。
13
- - **长时间运行支持**：使用 `waitForCompletion: false` 实现"发射后不管"模式，随后用 `read` 逐步获取输出。
14
- - **子代理隔离**：通过 `agentId` 标记会话，将并行代理的工作负载彼此隔离。
15
- - **跨平台**：支持 Windows、macOS、Linux。Windows 上中文输出自动解码不乱码。
16
-
17
- ## 环境要求
18
-
19
- - VS Code 1.93+
20
- - Node.js 20+
21
-
22
- ## 快速开始
23
-
24
- ### Claude Code
25
-
26
- ```bash
27
- claude mcp add BashTerm -- npx bashterm-mcp-server@latest
28
- ```
29
-
30
- 或使用本 fork 的 Windows 优化版本：
31
-
32
- ```bash
33
- # 下载 .vsix 安装包
34
- # 从 Release 页面下载 bashterm-0.1.8.vsix
35
- code --install-extension bashterm-0.1.8.vsix
36
-
37
- # 添加 MCP 服务器（使用本地扩展内置的 mcp-entry）
38
- claude mcp add BashTerm -- node "C:\Users\<用户名>\.vscode\extensions\hcdb.bashterm-0.1.8\dist\mcp-entry.js"
39
- ```
40
-
41
- ### VS Code / Copilot
42
-
43
- 在 `.vscode/mcp.json` 中添加：
44
-
45
- ```json
46
- {
47
- "servers": {
48
- "BashTerm": {
49
- "type": "stdio",
50
- "command": "npx",
51
- "args": ["bashterm-mcp-server@latest"]
52
- }
53
- }
54
- }
55
- ```
56
-
57
- <details>
58
- <summary>Cursor</summary>
59
-
60
- 在 `.cursor/mcp.json` 中添加：
61
-
62
- ```json
63
- {
64
- "mcpServers": {
65
- "BashTerm": {
66
- "command": "npx",
67
- "args": ["-y", "bashterm-mcp-server@latest"]
68
- }
69
- }
70
- }
71
- ```
72
-
73
- </details>
74
-
75
- <details>
76
- <summary>Claude Desktop</summary>
77
-
78
- 在 `claude_desktop_config.json` 中添加：
79
-
80
- ```json
81
- {
82
- "mcpServers": {
83
- "BashTerm": {
84
- "command": "npx",
85
- "args": ["-y", "bashterm-mcp-server@latest"]
86
- }
87
- }
88
- }
89
- ```
90
-
91
- </details>
92
-
93
- ### 你的第一个提示
94
-
95
- 安装完成后，试试问：
96
-
97
- > 在终端中运行 `ls -la`
98
-
99
- 你应该能在 VSCode 中看到一个新的终端标签页打开，并显示命令输出。
100
-
101
- ## 工具
102
-
103
- ### 快速执行
104
-
105
- | 工具 | 说明 |
106
- |------|------|
107
- | `run` | 一步创建（或复用）终端并执行命令，返回清洁输出和退出码。 |
108
-
109
- ### 会话管理
110
-
111
- | 工具 | 说明 |
112
- |------|------|
113
- | `create` | 创建新的可见终端会话，返回 `sessionId`。 |
114
- | `exec` | 在已有会话中执行命令并捕获输出。 |
115
- | `read` | 分页读取会话输出，支持增量读取和 tail 模式（`offset: -N`）。 |
116
- | `input` | 向交互式终端发送文本（用于提示、REPL、确认等）。 |
117
- | `list` | 列出活动会话，可选按 `agentId` 过滤。 |
118
- | `close` | 关闭终端会话及其 VSCode 标签页。 |
119
-
120
- ## 使用模式
121
-
122
- ### 简单命令
123
-
124
- `run` 工具处理一切——按需创建终端、执行命令、返回清洁输出：
125
-
126
- ```
127
- > 运行 npm test
128
- ```
129
-
130
- ```
131
- $ npm test
132
- PASS src/utils.test.ts (3 tests)
133
- PASS src/index.test.ts (5 tests)
134
-
135
- [exit: 0 | 1243ms | session-abc123]
136
- ```
137
-
138
- ### 长时间运行
139
-
140
- 对于构建、部署或其他耗时命令：
141
-
142
- ```
143
- > 启动 npm run build 不等待，然后检查进度
144
- ```
145
-
146
- 代理会：
147
- 1. 调用 `run` 设置 `waitForCompletion: false` —— 立即返回
148
- 2. 调用 `read` 设置 `offset: -10` 查看最后 10 行
149
- 3. 重复直到进程完成
150
-
151
- ### 交互式命令
152
-
153
- 对于需要用户输入的命令：
154
-
155
- ```
156
- > 运行 npm init 并回答提示
157
- ```
158
-
159
- 代理会：
160
- 1. 调用 `run` 执行 `npm init`
161
- 2. 调用 `read` 查看提示
162
- 3. 调用 `input` 发送答案
163
-
164
- ### 并行代理
165
-
166
- 子代理可以使用 `agentId` 在隔离的终端中工作：
167
-
168
- ```
169
- > 让一个代理运行测试，另一个运行代码检查
170
- ```
171
-
172
- 每个子代理获得自己的终端，标记其 `agentId`，防止输出混淆。
173
-
174
- ## 配置
175
-
176
- 扩展从 VSCode 设置中读取 `bashterm-mcp-server.*` 配置：
177
-
178
- | 设置项 | 类型 | 默认值 | 说明 |
179
- |--------|------|--------|------|
180
- | `bashterm-mcp-server.maxSessions` | number | 10 | 最大并发终端会话数 |
181
- | `bashterm-mcp-server.commandTimeout` | number | 30000 | 默认命令超时（毫秒） |
182
- | `bashterm-mcp-server.maxOutputLines` | number | 5000 | 每个会话最大缓冲输出行数 |
183
- | `bashterm-mcp-server.idleTimeout` | number | 1800000 | 空闲会话自动关闭时间（毫秒，0=禁用） |
184
- | `bashterm-mcp-server.blockedCommands` | string[] | `["rm -rf /"]` | 禁止执行的命令列表 |
185
-
186
- ## 推荐：设为优先工具
187
-
188
- 像 Claude Code 这样的 LLM 代理内置了 `Bash` 工具，会在聊天中内联执行命令。输出嵌入在对话中，难以阅读，尤其是输出冗长的命令。**建议告诉代理优先使用本 MCP 工具，而非内置 Bash 工具。**
189
-
190
- 将以下内容添加到项目的 `CLAUDE.md`（或等效指令文件）中：
191
-
192
- ```markdown
193
- ## 终端执行
194
-
195
- 优先使用 BashTerm MCP 工具（`run`、`exec`、`read` 等）来执行命令，而不是使用内置的 Bash 工具。
196
- BashTerm 在可见的 VSCode 终端标签页中运行命令，用户可以实时查看输出。
197
- 仅在简单、非交互式操作（如读取环境变量）时回退到内置 Bash 工具。
198
-
199
- 对于可能超过 30 秒或产生大量输出的命令（构建、测试套件、部署、安装），使用 pull 模式：
200
- 1. 调用 `run` 设置 `waitForCompletion: false` 启动命令但不阻塞。
201
- 2. 调用 `read` 设置 `offset: -10` 查看最后 10 行输出。
202
- 3. 重复步骤 2 直到看到命令完成（查找退出消息、提示或 "Done"）。
203
- 4. 向用户报告最终结果。
204
-
205
- 这样可以防止对话超时，并让用户实时观察终端进度。
206
- ```
207
-
208
- **为什么重要：**
209
-
210
- | | 内置 Bash | BashTerm MCP |
211
- |---|---|---|
212
- | 输出可见性 | 嵌入聊天，难以滚动 | 在 VSCode 终端标签页中可见 |
213
- | 实时反馈 | 用户看不到任何输出直到命令完成 | 用户实时观看输出 |
214
- | 长时间命令 | 阻塞对话直到超时 | 发射后不管 + 轮询 |
215
- | 会话状态 | 每个命令隔离 | 持久化会话，带历史 |
216
- | 交互式命令 | 不支持 | 可向提示/REPL 发送输入 |
217
-
218
- ## 工作方式
219
-
220
- 1. **VSCode 扩展**激活并启动 IPC 服务器（Windows 上使用 Named Pipe，其他平台使用 Unix Socket）
221
- 2. **MCP 入口**（`mcp-entry.js`）由 MCP 客户端启动，在 JSON-RPC stdio 和 IPC socket 之间建立桥接
222
- 3. 命令通过 `child_process.exec()` 执行，输出直接捕获，不再依赖 Shell Integration API
223
- 4. 输出存储在循环缓冲区中，支持分页高效读取
224
-
225
- ## 最新更新 (0.1.8)
226
-
227
- - **项目改名 bashterm-mcp**：全面清理旧名称 vscode-terminal-mcp 引用
228
- - **修复 bin 路径**：更正 npm 二进制入口路径
229
- - **动态版本图标**：badge 徽章现在反映实际版本号
230
- - 中文 README 补充版本徽章
231
-
232
- 详见 [CHANGELOG.md](CHANGELOG.md) 查看完整历史。
233
-
234
- ## 许可证
235
-
236
- MIT
1
+ # BashTerm
2
+
3
+ [![English](https://img.shields.io/badge/README-English-blue)](README.md) [![release](https://img.shields.io/npm/v/bashterm-mcp-server?label=release)](https://github.com/1170953489/bashterm-mcp/releases) [![npm version](https://img.shields.io/npm/v/bashterm-mcp-server)](https://www.npmjs.com/package/bashterm-mcp-server)
4
+
5
+ 在 **VSCode 可见的终端标签页**中执行命令的 MCP 服务器——实时观看输出、滚动历史、按需交互。
6
+
7
+ ## 核心功能
8
+
9
+ - **可见终端**：命令在真实的 VSCode 终端标签页中运行——实时观看输出、滚动历史、按需交互。
10
+ - **会话复用**：`run` 自动复用空闲会话，仅在必要时创建新终端。
11
+ - **非阻塞执行**：`waitForCompletion: false` 发射后不管，随后用 `read` 轮询。
12
+ - **子代理隔离**：通过 `agentId` 标记会话，将并行代理的工作负载隔离在独立终端中。
13
+
14
+ ## 环境要求
15
+
16
+ - VS Code 1.93+
17
+ - Node.js 20+
18
+
19
+ ## 快速开始
20
+
21
+ ### Claude Code
22
+
23
+ ```bash
24
+ claude mcp add BashTerm -- npx bashterm-mcp-server@latest
25
+ ```
26
+
27
+ ### VS Code / Copilot
28
+
29
+ 在 `.vscode/mcp.json` 中添加：
30
+
31
+ ```json
32
+ {
33
+ "servers": {
34
+ "BashTerm": {
35
+ "type": "stdio",
36
+ "command": "npx",
37
+ "args": ["bashterm-mcp-server@latest"]
38
+ }
39
+ }
40
+ }
41
+ ```
42
+
43
+ <details>
44
+ <summary>Cursor</summary>
45
+
46
+ 在 `.cursor/mcp.json` 中添加：
47
+
48
+ ```json
49
+ {
50
+ "mcpServers": {
51
+ "BashTerm": {
52
+ "command": "npx",
53
+ "args": ["-y", "bashterm-mcp-server@latest"]
54
+ }
55
+ }
56
+ }
57
+ ```
58
+
59
+ </details>
60
+
61
+ <details>
62
+ <summary>Claude Desktop</summary>
63
+
64
+ 在 `claude_desktop_config.json` 中添加：
65
+
66
+ ```json
67
+ {
68
+ "mcpServers": {
69
+ "BashTerm": {
70
+ "command": "npx",
71
+ "args": ["-y", "bashterm-mcp-server@latest"]
72
+ }
73
+ }
74
+ }
75
+ ```
76
+
77
+ </details>
78
+
79
+ ## 截图
80
+
81
+ ![Run command output](docs/images/run_finished.png)
82
+ ![Exec permission dialog](docs/images/ask_exec_permission.png)
83
+ ![Exec finished](docs/images/exec_finished.png)
84
+
85
+ ## 工具
86
+
87
+ ### 快速执行
88
+
89
+ | 工具 | 说明 |
90
+ |------|------|
91
+ | `run` | 一步创建（或复用）终端并执行命令，返回清洁输出和退出码。 |
92
+
93
+ ### 会话管理
94
+
95
+ | 工具 | 说明 |
96
+ |------|------|
97
+ | `create` | 打开新的可见终端标签页，返回 `sessionId`。 |
98
+ | `exec` | 在已有会话中执行命令并捕获输出。 |
99
+ | `read` | 基于偏移量分页读取会话输出。使用 `offset: -N` 进入 tail 模式。 |
100
+ | `input` | 向交互式进程发送文本（回答提示、驱动 REPL、确认操作）。 |
101
+ | `list` | 列出活动会话，可按 `agentId` 过滤。 |
102
+ | `close` | 关闭会话及其终端标签页。 |
103
+
104
+ ## 使用模式
105
+
106
+ ### 简单命令
107
+
108
+ `run` 工具处理一切——按需创建终端、执行命令、返回清洁输出：
109
+
110
+ ```
111
+ > 运行 npm test
112
+ ```
113
+
114
+ ```
115
+ $ npm test
116
+ PASS src/utils.test.ts (3 tests)
117
+ PASS src/index.test.ts (5 tests)
118
+
119
+ [exit: 0 | 1243ms | session-abc123]
120
+ ```
121
+
122
+ ### 长时间运行
123
+
124
+ 对于构建、部署或其他耗时命令：
125
+
126
+ ```
127
+ > 启动 npm run build 不等待，然后检查进度
128
+ ```
129
+
130
+ 代理使用 `waitForCompletion: false` 启动命令（立即返回），然后通过 `read`（`offset: -10`）轮询直到进程完成。
131
+
132
+ ### 交互式命令
133
+
134
+ 对于需要用户输入的命令：
135
+
136
+ ```
137
+ > 运行 npm init 并回答提示
138
+ ```
139
+
140
+ 代理使用 `run` 启动命令、`read` 查看提示、`input` 发送响应——逐步驱动交互式进程。
141
+
142
+ ### 并行代理
143
+
144
+ 子代理可以使用 `agentId` 在隔离的终端中工作：
145
+
146
+ ```
147
+ > 让一个代理运行测试，另一个运行代码检查
148
+ ```
149
+
150
+ 每个子代理获得独立的终端，标记其 `agentId`，保持输出分离且可读。
151
+
152
+ ## 配置
153
+
154
+ 扩展从 VSCode 设置中读取 `bashterm-mcp-server.*` 配置：
155
+
156
+ | 设置项 | 类型 | 默认值 | 说明 |
157
+ |--------|------|--------|------|
158
+ | `bashterm-mcp-server.maxSessions` | number | 10 | 最大并发终端会话数 |
159
+ | `bashterm-mcp-server.commandTimeout` | number | 30000 | 默认命令超时（毫秒） |
160
+ | `bashterm-mcp-server.maxOutputLines` | number | 5000 | 每个会话最大缓冲输出行数 |
161
+ | `bashterm-mcp-server.idleTimeout` | number | 1800000 | 空闲会话自动关闭时间（毫秒，0=禁用） |
162
+ | `bashterm-mcp-server.blockedCommands` | string[] | `["rm -rf /"]` | 禁止执行的命令列表 |
163
+
164
+ ## 推荐
165
+
166
+ LLM 代理内置的 `Bash` 工具将输出内联在对话中，难以翻阅。建议优先使用 BashTerm MCP 在可见终端中执行命令。将以下内容添加到项目的 `CLAUDE.md`：
167
+
168
+ ```markdown
169
+ ## 终端执行
170
+ 优先使用 BashTerm MCP 工具（`run`、`exec`、`read` 等），而非内置 Bash 工具。
171
+ 对于超过 30 秒的命令，使用 pull 模式：`run` 设置 `waitForCompletion: false`，随后用 `read`（`offset: -10`）轮询。
172
+ ```
173
+
174
+ ## 最新更新 (0.2.1)
175
+
176
+ - **重命名清理**：统一所有代码、文档和配置中的项目名称为 BashTerm MCP，无遗留旧名
177
+ - **标签修复**：更正 v0.2.0 标签指向正确的发布 commit
178
+
179
+ 完整历史见 [CHANGELOG.md](CHANGELOG.md)。
180
+
181
+ ## 许可证
182
+
183
+ MIT
package/dist/extension.js CHANGED
@@ -5389,7 +5389,7 @@ var zodToJsonSchema = (schema, options) => {
5389
5389
  };
5390
5390
 
5391
5391
  // package.json
5392
- var version = "0.2.0";
5392
+ var version = "0.2.1";
5393
5393
 
5394
5394
  // src/mcp/tools/schemas.ts
5395
5395
  var coerceBoolean = external_exports.preprocess(
package/package.json CHANGED
@@ -2,7 +2,7 @@
2
2
  "name": "bashterm-mcp-server",
3
3
  "displayName": "BashTerm MCP",
4
4
  "description": "MCP server that executes commands in visible VSCode terminal tabs. Supports Windows, macOS and Linux.",
5
- "version": "0.2.0",
5
+ "version": "0.2.1",
6
6
  "publisher": "hcdb",
7
7
  "license": "MIT",
8
8
  "author": "hcdb",
package/server.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
3
3
  "name": "io.github.hcdb/bashterm-mcp-server",
4
- "version": "0.2.0",
4
+ "version": "0.2.1",
5
5
  "description": "BashTerm MCP — execute commands in visible VSCode terminal tabs with output capture and session reuse.",
6
6
  "author": "hcdb",
7
7
  "license": "MIT",
@@ -14,7 +14,7 @@
14
14
  {
15
15
  "registryType": "npm",
16
16
  "identifier": "bashterm-mcp-server",
17
- "version": "0.2.0",
17
+ "version": "0.2.1",
18
18
  "transport": {
19
19
  "type": "stdio"
20
20
  }