bashterm-mcp 0.1.7

package/CHANGELOG.md

@@ -0,0 +1,57 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [0.1.7] - 2026-05-29
+
+### Added
+- Windows 平台完整支持：IPC 改用 Windows named pipe
+- 命令执行改用 `child_process.exec()` 直接捕获输出，兼容所有平台
+- Windows 下自动检测并解码 GBK 中文输出
+
+### Fixed
+- 修复 Windows 上 Unix socket `EACCES` 权限错误
+- 修复 Shell Integration API 在不支持的终端环境下不触发的问题
+- 修复 Windows 中文输出乱码
+
+## [0.1.6] - 2026-03-19 18:18 PDT
+
+### Added
+- Screenshots in README for marketplace (run, exec, permission dialog)
+- Custom terminal tab names with date format (e.g., `MCP: BashTerm-26-03-19-17-30`)
+- `name` parameter in `run` tool for custom terminal names
+- Unique IPC socket per workspace to prevent conflicts between multiple VSCode instances
+- Large output handling documentation
+- Development workflow docs for extension cache workaround
+
+### Fixed
+- Clean output format for all tools (`run`, `exec`, `read`, `list`, `close`, `input`) — no more raw JSON responses
+- `waitForCompletion: false` not working (`z.coerce.boolean()` converted string `"false"` to `true`)
+- Idle reaper killing sessions with running commands — reaper disabled, user closes sessions manually
+
+## [0.1.5] - 2026-03-18 14:50 PDT
+
+### Added
+- npm publish with `bin` entry for `npx bashterm-mcp` support
+- Published to VSCode Marketplace and MCP Registry
+
+## [0.1.3] - 2026-03-18 11:00 PDT
+
+### Added
+- `run` tool combining create + exec in one step
+- Session reuse: `run` finds idle sessions before creating new ones
+- Busy session detection: won't reuse sessions with running commands
+
+### Fixed
+- First-command timing fix with shell initialization delay
+
+## [0.1.0] - 2026-03-18 10:00 PDT
+
+### Added
+- Initial release
+- Tools: `create`, `exec`, `read`, `input`, `list`, `close`
+- Shell Integration API for output capture and exit code detection
+- Circular output buffer with pagination support
+- Subagent isolation with `agentId`
+- Command blocklist security
+- IPC bridge for MCP stdio-to-socket communication

package/CLAUDE.md

@@ -0,0 +1,84 @@
+# Project: bashterm-mcp
+
+MCP server that runs commands in visible VSCode terminal tabs.
+
+## Release Process
+
+When publishing a new version, follow these steps in order:
+
+### 1. Update version
+
+```bash
+# In package.json, bump the version
+# e.g., "version": "0.1.6" → "version": "0.1.7"
+```
+
+### 2. Update CHANGELOG.md
+
+Add a new entry at the top with the new version and date:
+
+```markdown
+## [0.1.7] - YYYY-MM-DD
+
+### Added
+- ...
+
+### Fixed
+- ...
+```
+
+### 3. Update README.md
+
+Replace the "Latest Changes" section with the new version's changes. Keep only the latest version in README — full history lives in CHANGELOG.md.
+
+### 4. Build and publish
+
+```bash
+# Build
+npm run build
+
+# Publish to npm
+npm publish --access public
+
+# Package vsix
+npx vsce package --allow-missing-repository
+
+# Install locally for testing
+cp dist/extension.js dist/mcp-entry.js ~/.vscode/extensions/hcdb.bashterm-mcp-<version>/dist/
+```
+
+### 5. Upload to VSCode Marketplace
+
+1. Go to https://marketplace.visualstudio.com/manage/publishers/hcdb
+2. Click "..." next to Terminal MCP → "Update"
+3. Upload the `.vsix` file
+
+### 6. Commit and push
+
+```bash
+git add -A
+git commit -m "v0.1.7: <summary of changes>"
+git push
+```
+
+## Extension Cache Workaround
+
+VSCode aggressively caches extensions. When developing locally:
+
+```bash
+# Quick update (after modifying source)
+npm run build
+cp dist/extension.js ~/.vscode/extensions/hcdb.bashterm-mcp-<version>/dist/extension.js
+# Then "Developer: Reload Window"
+
+# If reload doesn't pick up changes, close and reopen VSCode completely
+```
+
+## Terminal Execution
+
+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.
+
+For commands that may take longer than 30 seconds or produce large output, use pull mode:
+1. Call `run` with `waitForCompletion: false`
+2. Call `read` with `offset: -10` to check progress
+3. Repeat until done

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 sirlordt
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,319 @@
+# bashterm-mcp
+
+[![中文文档](https://img.shields.io/badge/README-中文-red)](README.zh-CN.md) [![release](https://img.shields.io/badge/release-v0.1.7-green)](https://github.com/1170953489/bashterm-mcp/releases) [![npm](https://img.shields.io/badge/npm-bashterm--mcp-blue)](https://www.npmjs.com/package/bashterm-mcp) [![VSIX](https://img.shields.io/badge/vsix-v0.1.7-lightgrey)](https://github.com/1170953489/bashterm-mcp/releases)
+
+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.
+
+## Key Features
+
+- **Visible Terminals**: Commands run in real VSCode terminal tabs, not hidden processes. You see everything in real time.
+- **Session Reuse**: The `run` tool automatically reuses idle sessions, creating new terminals only when needed.
+- **Long-Running Support**: Fire-and-forget execution with `waitForCompletion: false`, then poll output incrementally with `read`.
+- **Subagent Isolation**: Tag sessions with `agentId` to keep parallel agent workloads separated.
+
+> **Windows Compatible** — This fork fully supports Windows, including Chinese output without garbled text.
+
+## Requirements
+
+- VS Code 1.93+
+- Node.js 20+
+
+## Getting Started
+
+### Claude Code
+
+```bash
+claude mcp add BashTerm -- npx bashterm-mcp@latest
+```
+
+### VS Code / Copilot
+
+Add to your `.vscode/mcp.json`:
+
+```json
+{
+  "servers": {
+    "BashTerm": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["bashterm-mcp@latest"]
+    }
+  }
+}
+```
+
+<details>
+<summary>Cursor</summary>
+
+Add to your `.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "BashTerm": {
+      "command": "npx",
+      "args": ["-y", "bashterm-mcp@latest"]
+    }
+  }
+}
+```
+
+</details>
+
+<details>
+<summary>Claude Desktop</summary>
+
+Add to your `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "BashTerm": {
+      "command": "npx",
+      "args": ["-y", "bashterm-mcp@latest"]
+    }
+  }
+}
+```
+
+</details>
+
+### Your First Prompt
+
+After installation, try asking:
+
+> Run `ls -la` in the terminal
+
+You should see a new terminal tab open in VSCode with the command output.
+
+## Screenshots
+
+### Running a command with `run`
+
+![Run command output](docs/images/run_finished.png)
+
+### Permission dialog for `exec`
+
+![Exec permission dialog](docs/images/ask_exec_permission.png)
+
+### Exec result with clean output
+
+![Exec finished](docs/images/exec_finished.png)
+
+## Tools
+
+### Quick Execution
+
+| Tool | Description |
+|------|-------------|
+| `run` | Create (or reuse) a terminal and execute a command in one step. Returns clean output with exit code. |
+
+### Session Management
+
+| Tool | Description |
+|------|-------------|
+| `create` | Create a new visible terminal session. Returns a `sessionId`. |
+| `exec` | Execute a command in an existing session and capture output. |
+| `read` | Read output from a session with pagination. Supports incremental reads and tail mode (`offset: -N`). |
+| `input` | Send text to an interactive terminal (prompts, REPLs, confirmations). |
+| `list` | List active sessions. Optionally filter by `agentId`. |
+| `close` | Close a terminal session and its VSCode tab. |
+
+## Usage Patterns
+
+### Simple Command
+
+The `run` tool handles everything — creates a terminal if needed, executes, and returns clean output:
+
+```
+> Run npm test
+```
+
+```
+$ npm test
+PASS src/utils.test.ts (3 tests)
+PASS src/index.test.ts (5 tests)
+
+[exit: 0 | 1243ms | session-abc123]
+```
+
+### Long-Running Process
+
+For builds, deployments, or any command that takes a while:
+
+```
+> Start `npm run build` without waiting, then check progress
+```
+
+The agent will:
+1. Call `run` with `waitForCompletion: false` — returns immediately
+2. Call `read` with `offset: -10` to check the last 10 lines
+3. Repeat until the process completes
+
+### Interactive Commands
+
+For commands that need user input:
+
+```
+> Run npm init and answer the prompts
+```
+
+The agent will:
+1. Call `run` with `npm init`
+2. Call `read` to see the prompt
+3. Call `input` to send the answer
+
+### Parallel Agents
+
+Subagents can work in isolated terminals using `agentId`:
+
+```
+> Have one agent run tests while another runs the linter
+```
+
+Each subagent gets its own terminal tagged with its `agentId`, preventing output from mixing.
+
+## Configuration
+
+The extension reads configuration from VSCode settings under `terminalMcp.*`:
+
+| Setting | Type | Default | Description |
+|---------|------|---------|-------------|
+| `terminalMcp.maxSessions` | number | 10 | Maximum concurrent terminal sessions |
+| `terminalMcp.commandTimeout` | number | 30000 | Default command timeout in ms |
+| `terminalMcp.maxOutputLines` | number | 5000 | Max lines kept in output buffer per session |
+| `terminalMcp.idleTimeout` | number | 1800000 | Close idle sessions after this many ms (0 = disabled) |
+| `terminalMcp.blockedCommands` | string[] | `["rm -rf /"]` | Commands that will be rejected |
+
+## Recommended: Set as Preferred Tool
+
+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.**
+
+Add the following to your project's `CLAUDE.md` (or equivalent instructions file):
+
+```markdown
+## Terminal Execution
+
+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.
+Only fall back to the built-in Bash tool for simple, non-interactive operations like reading environment variables.
+
+For commands that may take longer than 30 seconds or produce large amounts of output (builds, test suites,
+deployments, installs), use the pull mode pattern:
+1. Call `run` with `waitForCompletion: false` to launch the command without blocking.
+2. Call `read` with `offset: -10` to check the last 10 lines of output.
+3. Repeat step 2 until you see the command has finished (look for exit messages, prompts, or "Done").
+4. Report the final result to the user.
+
+This prevents conversation timeouts and lets the user watch progress in the terminal in real time.
+```
+
+**Why this matters:**
+
+| | Built-in Bash | BashTerm MCP |
+|---|---|---|
+| Output visibility | Embedded in chat, hard to scroll | Visible in VSCode terminal tab |
+| Real-time feedback | User sees nothing until command finishes | User watches output live |
+| Long-running commands | Blocks the conversation until timeout | Fire-and-forget + polling |
+| Session state | Each command is isolated | Persistent sessions with history |
+| Interactive commands | Not supported | Send input to prompts/REPLs |
+
+## Development: Updating the Extension
+
+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:
+
+### Quick update (no restart needed)
+
+After modifying source files, build and copy directly into the installed extension directory:
+
+```bash
+cd /path/to/bashterm-mcp
+npm run build
+cp dist/extension.js ~/.vscode/extensions/hcdb.bashterm-mcp-<version>/dist/extension.js
+```
+
+Then run **"Developer: Reload Window"** (`Ctrl+Shift+P`).
+
+### Full reinstall (when quick update doesn't work)
+
+If VSCode still uses old code:
+
+```bash
+# 1. Uninstall and remove all copies
+code --uninstall-extension hcdb.bashterm-mcp
+rm -rf ~/.vscode/extensions/hcdb.bashterm-mcp-*
+
+# 2. Check for ghost entries with old publisher names
+# Look in ~/.vscode/extensions/extensions.json for stale entries
+# Remove any entries with old publisher IDs (e.g., "terminal-mcp.bashterm-mcp")
+
+# 3. Close VSCode completely (not just reload)
+
+# 4. Rebuild and install
+npm run build
+npx vsce package --allow-missing-repository
+code --install-extension bashterm-mcp-<version>.vsix --force
+
+# 5. Open VSCode
+```
+
+### Verify the correct version is loaded
+
+```bash
+# Check which extension directories exist
+ls ~/.vscode/extensions/ | grep terminal
+
+# Verify your changes are in the installed extension
+grep "YOUR_UNIQUE_STRING" ~/.vscode/extensions/hcdb.bashterm-mcp-*/dist/extension.js
+
+# Compare checksums
+md5sum dist/extension.js ~/.vscode/extensions/hcdb.bashterm-mcp-*/dist/extension.js
+```
+
+## Large Output Handling
+
+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.
+
+To extract the relevant content:
+
+```bash
+# Get the last 50 lines (most relevant for status)
+tail -50 /path/to/saved/file.txt
+
+# Or parse the JSON to extract the text content
+python3 -c "import json; data=json.load(open('/path/to/file.txt')); print(data[0]['text'][-2000:])"
+```
+
+The file format is JSON: `[{"type": "text", "text": "..."}]`
+
+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.
+
+## How It Works
+
+1. The **VSCode extension** activates and starts an IPC server (Named Pipe on Windows, Unix socket on macOS/Linux)
+2. The **MCP entry point** (`mcp-entry.js`) is spawned by the MCP client and bridges JSON-RPC stdio with the IPC socket
+3. Commands execute via `child_process.exec()` for reliable cross-platform output capture and exit code detection
+4. Output is stored in circular buffers with pagination support for efficient reading
+
+## Latest Changes (0.1.7)
+
+- **Full Windows support**: IPC uses Named Pipe instead of Unix socket (fixes `EACCES` error)
+- **Chinese character encoding**: Automatic GBK decoding on Windows (no more garbled text)
+- **Reliable command execution**: Uses `child_process.exec()` instead of Shell Integration API
+- Added `README.zh-CN.md` (中文说明文档)
+
+### Previous (0.1.6)
+
+- Screenshots in README for marketplace
+- Clean output format for all tools — no more raw JSON
+- Fixed `waitForCompletion: false` not working
+- Disabled idle reaper — user closes sessions manually
+- Unique IPC socket per workspace (multi-instance support)
+- Custom terminal tab names with date format
+- Large output handling documentation
+
+See [CHANGELOG.md](CHANGELOG.md) for full history.
+
+## License
+
+MIT