feat: Add terminal management tools with output capture to mcp-server-vscode

[psh4607]

Summary

Add five terminal management tools to the VSCode MCP Server extension, enabling AI assistants to create, control, and read output from VS Code integrated terminals via MCP.

This builds on the existing tool patterns (debug_tools, focus_editor) and adds a frequently requested capability: programmatic terminal access for AI-powered development workflows.

New Tools

Tool	Description
create_terminal	Create a new terminal with optional name, working directory, and initial command
list_terminals	List all active terminals in the workspace
send_terminal_text	Send text/commands to an existing terminal by name
close_terminal	Close a terminal by name
get_terminal_output	Read captured per-command output with pagination support

Design Decisions & Trade-offs

Output Capture: Why Shell Execution Events (not file-based)

We explored three approaches for reading terminal output before settling on the current design:

Approach A: Passive capture via onDidWriteTerminalData (rejected)

• Captures raw terminal data stream to temp files on disk
• Pros: Captures everything, works without shell integration
• Cons: onDidWriteTerminalData is a proposed API, not available in stable @types/vscode. Also raises security concerns — terminal output (which may contain environment variables, API keys, passwords) would be persisted to disk files, creating a larger attack surface than xterm.js's in-memory scrollback buffer.

Approach B: File-based storage (rejected)

• Append-only files in os.tmpdir() with get_terminal_output(name, offset, limit, stripAnsi) pagination
• While this is memory-efficient (OS page cache handles caching) and suits the write-heavy/read-occasional pattern, the security concern remains: sensitive terminal data on disk survives terminal closure and VS Code restarts, is readable by other processes, and could be forensically recovered after deletion.
• Note: We considered that xterm.js already holds the same data in memory, and ~/.zsh_history persists commands to disk — so the threat model isn't dramatically different. Still, adding a new persistence vector seemed unnecessary when a better stable API exists.

Approach C: Shell execution events (chosen) ✅

• Uses onDidStartTerminalShellExecution + TerminalShellExecution.read() (stable since VS Code 1.93)
• Per-command structured output, already stripped of ANSI escape codes
• In-memory only (max 50 commands per terminal), auto-cleaned on terminal close
• Zero disk persistence = zero security concern
• Requires shell integration (enabled by default in VS Code 1.93+)

Architecture

terminal_output_capture.ts (utils)
  └─ onDidStartTerminalShellExecution listener
  └─ Per-command output stored in Map<terminalName, CommandRecord[]>
  └─ Auto-cleanup on terminal close + extension deactivation

terminal_tools.ts (tools)
  └─ create_terminal, list_terminals, send_terminal_text, close_terminal
  └─ get_terminal_output (reads from capture module)

extension.ts
  └─ Tool registration + capture initialization

Expected Impact

• AI-assisted terminal workflows: AI assistants can create terminals, run commands, and read results — enabling automated build/test/deploy cycles
• Debugging support: Read command output to diagnose build failures, test results, or runtime errors without manual copy-paste
• Multi-terminal orchestration: Manage multiple terminals programmatically (e.g., start a dev server in one, run tests in another, read both outputs)

Files Changed

File	Description
src/tools/terminal_tools.ts	5 tool implementations with Zod schema validation
src/utils/terminal_output_capture.ts	Shell execution event listener + in-memory command history
src/test/terminal_tools.test.ts	Schema validation unit tests for all 5 tools
src/extension.ts	Tool registrations + capture initialization

Testing

• TypeScript compilation (tsc): passing
• Webpack build: passing
• Schema validation tests: passing
• Runtime testing requires VS Code Extension Development Host (F5)

[psh4607]

Note: This PR (#659) includes all 5 terminal tools — the 4 management tools from #658 plus get_terminal_output with shell execution-based output capture.

If the output capture approach (onDidStartTerminalShellExecution + in-memory command history) needs further discussion or review, #658 is a standalone subset containing only the 4 terminal management tools (create_terminal, list_terminals, send_terminal_text, close_terminal) that can be reviewed and merged independently.

Happy to iterate on either PR based on your feedback!

[psh4607]

@microsoft-github-policy-service agree