vscode-terminal-mcp 0.1.5 → 0.1.6

package/CHANGELOG.md

@@ -0,0 +1,45 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [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 vscode-terminal-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: vscode-terminal-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/sirlordt.vscode-terminal-mcp-<version>/dist/
+```
+
+### 5. Upload to VSCode Marketplace
+
+1. Go to https://marketplace.visualstudio.com/manage/publishers/sirlordt
+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/sirlordt.vscode-terminal-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/README.md

@@ -84,6 +84,20 @@ After installation, try asking:
 
 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
@@ -202,6 +216,76 @@ This prevents conversation timeouts and lets the user watch progress in the term
 | 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/vscode-terminal-mcp
+npm run build
+cp dist/extension.js ~/.vscode/extensions/sirlordt.vscode-terminal-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 sirlordt.vscode-terminal-mcp
+rm -rf ~/.vscode/extensions/sirlordt.vscode-terminal-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.vscode-terminal-mcp")
+
+# 3. Close VSCode completely (not just reload)
+
+# 4. Rebuild and install
+npm run build
+npx vsce package --allow-missing-repository
+code --install-extension vscode-terminal-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/sirlordt.vscode-terminal-mcp-*/dist/extension.js
+
+# Compare checksums
+md5sum dist/extension.js ~/.vscode/extensions/sirlordt.vscode-terminal-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 on a Unix socket
@@ -209,6 +293,18 @@ This prevents conversation timeouts and lets the user watch progress in the term
 3. Commands execute in real VSCode terminals using the **Shell Integration API** for reliable output capture and exit code detection
 4. Output is stored in circular buffers with pagination support for efficient reading
 
+## Latest Changes (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

package/dist/extension.js

@@ -5446,21 +5446,13 @@ async function handleTerminalCreate(params, sessionManager2) {
     shell: input.shell,
     agentId: input.agentId
   });
+  const parts = [`Terminal created: ${sessionInfo.name}`, `session: ${sessionInfo.sessionId}`, `cwd: ${sessionInfo.cwd}`];
+  if (sessionInfo.agentId) parts.push(`agent: ${sessionInfo.agentId}`);
   return {
     content: [
       {
         type: "text",
-        text: JSON.stringify(
-          {
-            status: "created",
-            sessionId: sessionInfo.sessionId,
-            name: sessionInfo.name,
-            cwd: sessionInfo.cwd,
-            agentId: sessionInfo.agentId
-          },
-          null,
-          2
-        )
+        text: parts.join(" | ")
       }
     ]
   };
@@ -5500,24 +5492,29 @@ async function handleTerminalExecute(params, sessionManager2) {
     timeoutMs,
     waitForCompletion
   );
-  const response = {
-    sessionId: input.sessionId,
-    commandId: result.commandId,
-    exitCode: result.exitCode,
-    timedOut: result.timedOut,
-    durationMs: result.durationMs,
-    output: result.output
-  };
+  let cleanOutput = result.output.replace(/\x1b\[[0-9;]*[a-zA-Z]/g, "").replace(/\x1b\][^\x07]*\x07/g, "").replace(/\r\n/g, "\n").replace(/\r/g, "").trim();
+  const lines = cleanOutput.split("\n");
+  if (lines.length > 0 && lines[0].trim() === input.command.trim()) {
+    lines.shift();
+    cleanOutput = lines.join("\n").trim();
+  }
+  const statusParts = [`exit: ${result.exitCode ?? "n/a"}`, `${result.durationMs}ms`, input.sessionId];
+  let text = `$ ${input.command}
+${cleanOutput}
+
+[${statusParts.join(" | ")}]`;
   if (result.timedOut) {
-    response.warning = `Command timed out after ${timeoutMs}ms. Output may be incomplete. The terminal session is still active.`;
+    text += `
+[TIMED OUT after ${timeoutMs}ms - session still active, use read to get more output]`;
   }
   return {
     content: [
       {
         type: "text",
-        text: JSON.stringify(response, null, 2)
+        text
       }
-    ]
+    ],
+    isError: result.exitCode !== null && result.exitCode !== 0
   };
 }
 
@@ -5537,7 +5534,11 @@ async function handleTerminalRun(params, sessionManager2) {
   }
   if (!sessionId) {
     const sessionInfo = sessionManager2.createSession({
-      name: input.name ?? `run-${Date.now()}`,
+      name: input.name ?? (() => {
+        const d = /* @__PURE__ */ new Date();
+        const pad = (n) => String(n).padStart(2, "0");
+        return `BashTerm-${pad(d.getFullYear() % 100)}-${pad(d.getMonth() + 1)}-${pad(d.getDate())}-${pad(d.getHours())}-${pad(d.getMinutes())}`;
+      })(),
       cwd: input.cwd,
       env: input.env,
       shell: input.shell,
@@ -5634,18 +5635,23 @@ async function handleTerminalReadOutput(params, sessionManager2) {
 async function handleTerminalList(params, sessionManager2) {
   const input = terminalListSchema.parse(params ?? {});
   const sessions = sessionManager2.listSessions(input.agentId);
+  if (sessions.length === 0) {
+    return {
+      content: [{ type: "text", text: "No active sessions." }]
+    };
+  }
+  const lines = sessions.map((s) => {
+    const age = Math.round((Date.now() - s.createdAt) / 1e3);
+    const parts = [s.sessionId, s.name, `cwd: ${s.cwd}`, `${age}s old`, `${s.outputLineCount} lines`];
+    if (s.agentId) parts.push(`agent: ${s.agentId}`);
+    return parts.join(" | ");
+  });
   return {
     content: [
       {
         type: "text",
-        text: JSON.stringify(
-          {
-            count: sessions.length,
-            sessions
-          },
-          null,
-          2
-        )
+        text: `${sessions.length} active session(s):
+${lines.join("\n")}`
       }
     ]
   };
@@ -5670,10 +5676,7 @@ async function handleTerminalClose(params, sessionManager2) {
     content: [
       {
         type: "text",
-        text: JSON.stringify({
-          status: "closed",
-          sessionId: input.sessionId
-        })
+        text: `Session closed: ${input.sessionId}`
       }
     ]
   };
@@ -5699,12 +5702,7 @@ async function handleTerminalSendInput(params, sessionManager2) {
     content: [
       {
         type: "text",
-        text: JSON.stringify({
-          status: "sent",
-          sessionId: input.sessionId,
-          inputLength: input.input.length,
-          pressedEnter: input.pressEnter ?? true
-        })
+        text: `Input sent to ${input.sessionId} (${input.input.length} chars${input.pressEnter ?? true ? " + Enter" : ""})`
       }
     ]
   };
@@ -6301,7 +6299,16 @@ var sessionManager;
 var statusBarItem;
 function getSocketPath() {
   const tmpDir = os.tmpdir();
-  return path.join(tmpDir, "vscode-terminal-mcp.sock");
+  const crypto3 = require("crypto");
+  const workspace4 = vscode4.workspace.workspaceFolders?.[0]?.uri.fsPath || "";
+  const hash = crypto3.createHash("md5").update(workspace4).digest("hex").slice(0, 8);
+  const socketPath = path.join(tmpDir, `vscode-terminal-mcp-${hash}.sock`);
+  const discoveryPath = path.join(tmpDir, "vscode-terminal-mcp.discovery");
+  try {
+    fs.writeFileSync(discoveryPath, socketPath);
+  } catch {
+  }
+  return socketPath;
 }
 function cleanupSocket(socketPath) {
   try {

package/dist/mcp-entry.js

@@ -27,7 +27,20 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 var net = __toESM(require("net"));
 var path = __toESM(require("path"));
 var os = __toESM(require("os"));
-var SOCKET_PATH = path.join(os.tmpdir(), "vscode-terminal-mcp.sock");
+var fs = __toESM(require("fs"));
+function getSocketPath() {
+  const tmpDir = os.tmpdir();
+  const discoveryPath = path.join(tmpDir, "vscode-terminal-mcp.discovery");
+  try {
+    const socketPath = fs.readFileSync(discoveryPath, "utf8").trim();
+    if (socketPath && fs.existsSync(socketPath)) {
+      return socketPath;
+    }
+  } catch {
+  }
+  return path.join(tmpDir, "vscode-terminal-mcp.sock");
+}
+var SOCKET_PATH = getSocketPath();
 var RECONNECT_DELAY_MS = 1e3;
 var MAX_RECONNECT_ATTEMPTS = 30;
 var StdioToIpcBridge = class {

package/package.json

@@ -2,7 +2,7 @@
   "name": "vscode-terminal-mcp",
   "displayName": "Terminal MCP Server",
   "description": "MCP server that provides visible terminal sessions in VSCode for Claude Code and subagents",
-  "version": "0.1.5",
+  "version": "0.1.6",
   "publisher": "sirlordt",
   "license": "MIT",
   "author": "sirlordt",