persistent-terminal-mcp 1.0.2

package/CHANGELOG.md

@@ -0,0 +1,278 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+- _Nothing yet._
+
+## [1.0.2] - 2025-10-18
+
+### Added
+- **🌐 Web UI 管理界面**: 基于浏览器的可视化终端管理界面
+  - 使用 xterm.js 渲染终端输出，支持完整 ANSI 颜色
+  - WebSocket 实时推送，终端输出实时显示
+  - 直接在浏览器中发送命令、查看输出
+  - 自动端口分配，支持多实例运行
+  - VS Code 风格的暗色主题界面
+  - 新增 `open_terminal_ui` MCP 工具
+  - 新增 `WebUIManager` 和 `WebUIServer` 模块
+  - 新增 Web UI 静态文件（public/）
+  - 新增 Web UI 使用指南文档
+- **📚 文档更新**: 全面更新中文 README，包含所有新功能说明
+
+### Changed
+- 更新 README.zh-CN.md，采用更清晰的结构和更详细的功能说明
+- 优化文档导航，添加更多 emoji 图标提升可读性
+- npm 包装清理：新增二进制入口（`persistent-terminal-mcp`、`persistent-terminal-mcp-rest`），
+  导出完整类型定义，限制发布文件为 `dist/` 与核心静态资源，并更新文档以推荐 `npx`
+  启动方式
+
+### Fixed
+
+#### 🔴 Critical: Terminal command execution and interaction issues
+- **Problem 1: Commands not executing properly**
+  - Commands sent to terminal were not being executed
+  - No command echo visible in output
+  - Terminal line count increased but content was invisible
+- **Problem 2: Interactive input handling unstable**
+  - Control characters (arrow keys, enter) not working reliably
+  - Interface not updating in interactive applications
+  - Required multiple key presses for single action
+- **Problem 3: Output reading not real-time**
+  - Reading stale output instead of latest
+  - Required multiple reads to get current state
+  - No way to detect if command is still running
+- **Solution**:
+  - Fixed PTY configuration: Changed from `xterm-color` to `xterm-256color`
+  - Added proper environment variables: `TERM`, `LANG`, `PAGER`
+  - Improved write logic with drain event handling
+  - Added `setImmediate` for immediate data processing
+  - Added `waitForOutputStable()` method to detect output completion
+  - Added `wait_for_output` MCP tool for waiting until output stabilizes
+- **Impact**: Full support for interactive applications (vim, npm create, etc.)
+- **Testing**: All 6 tests pass in `test-terminal-fixes.mjs`
+- **Documentation**: See [TERMINAL_FIXES.md](TERMINAL_FIXES.md) for detailed analysis
+
+#### 🔴 Critical: Stdio channel pollution causing Cursor compatibility issues
+- **Problem**: Console logging was polluting stdout, causing JSON parsing errors in Cursor and other strict MCP clients
+  - Error: `Unexpected token 'T', "Terminal c"... is not valid JSON`
+  - Cursor would freeze after a few commands
+  - MCP protocol requires stdout to contain only JSON-RPC messages
+- **Solution**: All logging now uses `process.stderr.write()` instead of `console.log/error`
+  - Debug logs controlled by `MCP_DEBUG` environment variable
+  - All logs output to stderr, keeping stdout pure for JSON-RPC
+- **Impact**: Full compatibility with Cursor and other strict MCP clients
+- **Backward Compatible**: Yes - no API changes, only logging behavior
+- **Files Modified**:
+  - `src/index.ts` - Fixed log function and error handlers
+  - `src/mcp-server.ts` - Fixed event handlers and shutdown logging
+  - `src/terminal-manager.ts` - Fixed cleanup and shutdown logging
+- **Testing**: Added comprehensive stdio purity tests
+  - `test-mcp-stdio.mjs` - Validates stdout contains only JSON-RPC
+  - `test-cursor-scenario.mjs` - Simulates real Cursor usage scenarios
+- **Documentation**: See [STDIO_FIX.md](STDIO_FIX.md) for detailed analysis
+
+### Added
+- **Spinner Animation Compaction**: Automatically detects and throttles progress animations
+  - Identifies common spinner characters (⠋⠙⠹⠸⠼⠴⠦⠧⠇⠏, ◐◓◑◒, etc.)
+  - Reduces noise from `npm install`, `yarn`, `pnpm` and similar commands
+  - Configurable via `COMPACT_ANIMATIONS` and `ANIMATION_THROTTLE_MS` environment variables
+  - Enabled by default with 100ms throttle
+  - Can be toggled per-read via `stripSpinner` parameter
+  - See [Spinner Compaction Guide](docs/guides/spinner-compaction.md) for details
+- **`wait_for_output` MCP tool**: Wait for terminal output to stabilize before reading
+  - Parameters: `terminalId`, `timeout` (default: 5000ms), `stableTime` (default: 500ms)
+  - Useful for ensuring complete output capture after running commands
+  - Helps with interactive applications and long-running commands
+- **`waitForOutputStable()` method**: Programmatic API for waiting for output stability
+- **`isTerminalBusy()` method**: Check if terminal is currently processing output
+- `create_terminal_basic` MCP tool to support clients that can only send simple
+  string arguments
+- Open-source collateral: MIT `LICENSE` and `CONTRIBUTING.md`
+- Comprehensive test suite for spinner detection (12 new tests)
+- Comprehensive test suite for terminal fixes (6 new tests)
+- Example script: `npm run example:spinner`
+- Test script: `test-terminal-fixes.mjs`
+- `MCP_DEBUG` environment variable for controlling debug output
+
+### Changed
+- **PTY Configuration**: Changed terminal type from `xterm-color` to `xterm-256color`
+- **Environment Variables**: Now sets `TERM`, `LANG`, and `PAGER` for better compatibility
+- **Write Logic**: Improved with drain event handling and immediate processing
+- **Read Logic**: Added `setImmediate` to ensure latest data is captured
+- **Output Capture**: Using `setImmediate` in `onData` handler for immediate processing
+- `OutputBuffer` constructor now accepts `compactAnimations` and `animationThrottleMs` options
+- `TerminalManagerConfig` extended with animation compaction settings
+- `read_terminal` MCP tool now supports optional `stripSpinner` parameter
+- Consolidated documentation under [`docs/`](docs/README.md) with clearer
+  filenames and an index
+- Refreshed `README.md` with quick-start instructions and the expanded tool set
+- All logging now uses stderr to comply with MCP stdio protocol requirements
+
+## [1.0.1] - 2025-10-03
+
+### Fixed
+
+#### 🔴 Critical: Commands not executing automatically
+- **Problem**: Commands sent to terminal were displayed but not executed
+- **Solution**: `write_terminal` now automatically adds newline character if not present
+- **Impact**: Users can now send `"pwd"` instead of `"pwd\n"`
+- **Backward Compatible**: Yes - existing code with `\n` still works
+
+#### 🟡 Medium: Terminated terminals still in list
+- **Problem**: After `kill_terminal`, terminals remained in `list_terminals` with status "terminated"
+- **Solution**: Terminals are now completely removed from all internal maps after termination
+- **Impact**: Better memory management and cleaner terminal list
+- **Backward Compatible**: Yes - no API changes
+
+### Changed
+
+- Updated `write_terminal` tool description to mention automatic newline addition
+- Updated parameter descriptions to clarify newline behavior
+
+### Added
+
+- New test script: `npm run test:fixes` to verify bug fixes
+- Comprehensive test coverage for command execution and terminal cleanup
+
+### Documentation
+
+- Added `docs/reference/bug-fixes.md` - Detailed technical report of fixes
+- Added `docs/reference/test-response.md` - Response to AI testing teams
+- Updated `docs/guides/usage.md` - Simplified command sending examples
+
+---
+
+## [1.0.0] - 2025-10-03
+
+### Added
+
+#### Core Features
+- **Persistent Terminal Sessions**: Create and manage long-running terminal sessions
+- **Output Buffering**: Circular buffer with configurable size (default 10,000 lines)
+- **Smart Output Reading**: Multiple modes (full, head, tail, head-tail)
+- **Incremental Reading**: Read only new output using `since` parameter
+- **Session Management**: Automatic cleanup of timed-out sessions
+
+#### MCP Tools (6 total)
+1. `create_terminal` - Create new persistent terminal sessions
+2. `write_terminal` - Send input to terminal sessions
+3. `read_terminal` - Read output with smart truncation
+4. `get_terminal_stats` - Get detailed statistics (lines, bytes, tokens)
+5. `list_terminals` - List all active terminal sessions
+6. `kill_terminal` - Terminate terminal sessions
+
+#### MCP Resources (3 total)
+1. `terminal://list` - List of all terminals
+2. `terminal://{id}/output` - Terminal output
+3. `terminal://{id}/info` - Terminal information
+
+#### MCP Prompts (2 total)
+1. `debug-terminal` - Debug terminal issues
+2. `monitor-terminal` - Monitor terminal output
+
+#### REST API
+- Alternative HTTP interface for non-MCP clients
+- All MCP tools available as REST endpoints
+- CORS enabled for web clients
+
+#### Examples
+- `basic-usage.ts` - Basic terminal operations
+- `rest-api-demo.ts` - REST API usage
+- `interactive-demo.ts` - Interactive terminal demo
+- `smart-reading-demo.ts` - Smart reading features
+- `test-all-tools.ts` - Comprehensive tool testing
+
+#### Documentation
+- `README.md` - Project overview and quick start
+- `docs/meta/project-status.md` - Project status and roadmap
+- `docs/guides/usage.md` - Guide for AI assistants
+- `docs/guides/troubleshooting.md` - Troubleshooting guide
+- `docs/clients/claude-code-setup.md` - Claude Code configuration
+- `docs/guides/mcp-config.md` - MCP configuration guide
+- `docs/reference/tools-summary.md` - Quick reference for all tools
+
+#### Configuration
+- Environment variables support (`MAX_BUFFER_SIZE`, `SESSION_TIMEOUT`)
+- Example configuration files for Claude Desktop and Claude Code
+- TOML configuration format support
+
+### Technical Details
+
+#### Architecture
+- TypeScript with strict mode
+- ES Modules (ESM)
+- Event-driven design using EventEmitter
+- Zod schema validation
+- node-pty for PTY management
+
+#### Testing
+- Jest test framework
+- Unit tests for core functionality
+- Integration tests for MCP tools
+- Example scripts for manual testing
+
+#### Build System
+- TypeScript compiler (tsc)
+- tsx for development
+- npm scripts for common tasks
+
+---
+
+## Version History
+
+- **1.0.1** (2025-10-03) - Bug fixes for command execution and terminal cleanup
+- **1.0.0** (2025-10-03) - Initial release with full MCP support
+
+---
+
+## Upgrade Guide
+
+### From 1.0.0 to 1.0.1
+
+No breaking changes. Simply update and rebuild:
+
+```bash
+git pull
+npm run build
+```
+
+If using Claude Code or Claude Desktop, restart the application after rebuilding.
+
+### Benefits of Upgrading
+
+1. **Better UX**: No need to manually add `\n` to commands
+2. **Memory Efficiency**: Terminated terminals are properly cleaned up
+3. **Cleaner API**: Terminal list only shows active terminals
+
+---
+
+## Future Plans
+
+See `docs/meta/project-status.md` for detailed roadmap.
+
+### Planned Features
+
+- [ ] Terminal session persistence across restarts
+- [ ] Terminal multiplexing (tmux/screen integration)
+- [ ] File upload/download support
+- [ ] Terminal recording and playback
+- [ ] WebSocket support for real-time updates
+- [ ] Terminal sharing between users
+- [ ] Custom shell profiles
+- [ ] Environment variable management
+- [ ] Command history and search
+
+---
+
+## Contributing
+
+Contributions are welcome! Please see `CONTRIBUTING.md` for guidelines.
+
+## License
+
+MIT License - see `LICENSE` file for details.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Persistent Terminal Contributors
+
+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.en.md

@@ -0,0 +1,259 @@
+# Persistent Terminal MCP Server
+
+[简体中文](README.md)
+
+Persistent Terminal MCP Server is a TypeScript implementation of a Model Context
+Protocol (MCP) server that keeps terminal sessions alive for AI assistants and
+automation flows. It is built on top of [`node-pty`](https://github.com/microsoft/node-pty)
+so commands continue running even when the requesting client disconnects.
+
+## Highlights
+- **Persistent PTY sessions** – create, reuse, and terminate long-running shells
+- **Smart output buffering** – incremental reads plus head, tail, or head-tail
+  views with token estimates for large logs
+- **Spinner animation compaction** – automatically detects and throttles progress
+  animations (like npm install spinners) to reduce noise and preserve real logs
+- **Full session management** – statistics, listing, kill signals, and automatic
+  cleanup for inactive sessions
+- **MCP-ready** – ships with tools, resources, and prompts compatible with
+  Claude Desktop, Claude Code, and other MCP clients
+- **REST API option** – optional Express server mirrors the MCP functionality
+  for non-MCP integrations
+
+## Installation
+
+### One-off run (recommended for MCP clients)
+Use `npx` to launch the server without a global install:
+```bash
+npx persistent-terminal-mcp
+```
+
+The REST flavor is available the same way:
+```bash
+npx persistent-terminal-mcp-rest
+```
+
+### Project dependency
+Add the package to an existing project (CLI + TypeScript APIs):
+```bash
+npm install persistent-terminal-mcp
+```
+
+Now you can reference both the CLI binaries in `node_modules/.bin/` and the
+TypeScript exports:
+```ts
+import { PersistentTerminalMcpServer } from 'persistent-terminal-mcp';
+```
+
+### Global install (optional)
+```bash
+npm install --global persistent-terminal-mcp
+persistent-terminal-mcp
+```
+
+## Local Development
+Clone the repo if you want to work on the source:
+```bash
+npm install          # install dependencies
+npm run build        # compile TypeScript → dist/
+npm start            # launch the MCP server over stdio
+```
+
+During development you can run the TypeScript sources directly:
+```bash
+npm run dev          # MCP server (tsx)
+npm run dev:rest     # REST server (tsx)
+```
+
+### Debugging Mode
+To enable debug logging (output to stderr, won't interfere with MCP communication):
+```bash
+MCP_DEBUG=true persistent-terminal-mcp
+```
+
+### Example Scripts
+```bash
+npm run example:basic        # basic lifecycle (create → write → read → kill)
+npm run example:smart        # demonstrates head/tail/head-tail reading
+npm run test:tools           # exercises every MCP tool end-to-end
+npm run test:fixes           # regression tests for recent bug fixes
+```
+
+## MCP Client Configuration
+
+### Claude Desktop (macOS / Linux)
+Add the following configuration to your MCP settings file:
+
+**Configuration file location**: `~/Library/Application Support/Claude/claude_desktop_config.json`
+
+```json
+{
+  "mcpServers": {
+    "persistent-terminal": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "persistent-terminal-mcp"
+      ],
+      "env": {
+        "MAX_BUFFER_SIZE": "10000",
+        "SESSION_TIMEOUT": "86400000",
+        "COMPACT_ANIMATIONS": "true",
+        "ANIMATION_THROTTLE_MS": "100"
+      }
+    }
+  }
+}
+```
+
+**Already installed?** If you installed the package globally, change `command` to
+`"persistent-terminal-mcp"` and remove the `-y` argument.
+
+### Claude Code (CLI Method)
+Use the command line to quickly add the MCP server:
+
+```bash
+claude mcp add persistent-terminal \
+  --env MAX_BUFFER_SIZE=10000 \
+  --env SESSION_TIMEOUT=86400000 \
+  --env COMPACT_ANIMATIONS=true \
+  --env ANIMATION_THROTTLE_MS=100 \
+  -- npx -y persistent-terminal-mcp
+```
+
+**Tip**: The `-y` flag answers "yes" to the download prompt so the command can run non-interactively.
+
+**Example** (global install):
+```bash
+claude mcp add persistent-terminal \
+  --env MAX_BUFFER_SIZE=10000 \
+  --env SESSION_TIMEOUT=86400000 \
+  --env COMPACT_ANIMATIONS=true \
+  --env ANIMATION_THROTTLE_MS=100 \
+  -- persistent-terminal-mcp
+```
+
+### Cursor / Cline Configuration
+Configuration is similar to Claude Desktop. Please refer to the MCP configuration documentation for each client.
+
+### Codex Configuration
+For Codex, add the following to `.codex/config.toml`:
+
+```toml
+# MCP Server Configuration (TOML Format)
+# For configuring persistent-terminal MCP server
+
+[mcp_servers.persistent-terminal]
+command = "npx"
+args = ["-y", "persistent-terminal-mcp"]
+
+[mcp_servers.persistent-terminal.env]
+MAX_BUFFER_SIZE = "10000"
+SESSION_TIMEOUT = "86400000"
+COMPACT_ANIMATIONS = "true"
+ANIMATION_THROTTLE_MS = "100"
+```
+
+**Note**: Ensure the environment running `npx` has network access the first time so it can download the package if necessary.
+
+### Environment Variables
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `MAX_BUFFER_SIZE` | Maximum number of lines to keep in buffer | 10000 |
+| `SESSION_TIMEOUT` | Session timeout in milliseconds | 86400000 (24 hours) |
+| `COMPACT_ANIMATIONS` | Enable spinner animation compaction | true |
+| `ANIMATION_THROTTLE_MS` | Animation throttle time in milliseconds | 100 |
+| `MCP_DEBUG` | Enable debug logging | false |
+
+## Programmatic Usage (TypeScript)
+
+```ts
+import {
+  PersistentTerminalMcpServer,
+  TerminalManager,
+  RestApiServer
+} from 'persistent-terminal-mcp';
+
+const manager = new TerminalManager();
+const rest = new RestApiServer(manager);
+
+await rest.start(3001);
+
+const mcpServer = new PersistentTerminalMcpServer();
+const server = mcpServer.getServer();
+await server.connect(/* transport of your choice */);
+```
+
+All core classes and type definitions are available directly from the root
+module. Refer to [`src/index.ts`](src/index.ts) for the complete export list.
+
+## MCP Tools
+| Tool | Purpose |
+|------|---------|
+| `create_terminal` | Create a persistent terminal session (supports `env`, `shell`, and `cwd`) |
+| `create_terminal_basic` | Convenience alias for clients that can only send simple strings |
+| `write_terminal` | Send input to a terminal; newline is added automatically if needed |
+| `read_terminal` | Retrieve buffered output with smart truncation options |
+| `wait_for_output` | Wait for terminal output to stabilize (useful after running commands) |
+| `get_terminal_stats` | Inspect buffer size, line counts, estimated tokens, and activity |
+| `list_terminals` | Enumerate active sessions and their metadata |
+| `kill_terminal` | Terminate a session with an optional signal |
+
+Additional MCP resources and prompts are exposed for listing sessions, viewing
+output, and surfacing troubleshooting tips inside compatible clients.
+
+## REST API (Optional)
+If you prefer HTTP, start the REST variant:
+```bash
+npx persistent-terminal-mcp-rest
+```
+The server listens on port `3001` (configurable) and mirrors the MCP toolset.
+Endpoints include `/api/terminals`, `/api/terminals/:id/input`, `/api/terminals/:id/output`,
+`/api/terminals/:id/stats`, `/api/terminals`, and `/api/terminals/:id`.
+
+## Project Layout
+```
+docs/                → Consolidated documentation index
+  ├── guides/        → Usage guides and tutorials
+  ├── reference/     → Technical references and fixes
+  │   └── fixes/     → All fix documentation
+  ├── clients/       → Client-specific setup
+  └── zh/            → Chinese documentation
+scripts/             → Helper scripts for local debugging
+src/                 → TypeScript source code
+  ├── __tests__/     → Unit tests
+  └── examples/      → Example scripts
+tests/               → Test suites
+  └── integration/   → Integration tests
+dist/                → Compiled JavaScript output
+```
+
+### Documentation Map
+All documentation is organized under [`docs/`](docs/README.md):
+
+**Quick Access:**
+- 📖 [Documentation Index](docs/README.md) – Complete documentation map
+- 🚨 [Fixes Index](docs/reference/fixes/README.md) – All fixes and solutions
+- 🧪 [Integration Tests](tests/integration/README.md) – Test suite
+
+**By Category:**
+- **Guides**: Usage, troubleshooting, MCP configuration
+- **Reference**: Technical details, tools summary, bug fixes
+- **Fixes**: Stdio fix, Cursor fix, terminal fixes
+- **Clients**: Claude Desktop / Claude Code setup
+- **中文**: Chinese-language documentation
+
+### Important Notes
+- **Stdio Purity**: This MCP server follows the MCP protocol strictly by ensuring stdout only contains JSON-RPC messages. All logging goes to stderr. See [docs/reference/fixes/STDIO_FIX.md](docs/reference/fixes/STDIO_FIX.md) for details.
+- **Cursor Compatibility**: Fully compatible with Cursor and other strict MCP clients that require clean JSON-RPC communication. See [docs/reference/fixes/QUICK_FIX_GUIDE.md](docs/reference/fixes/QUICK_FIX_GUIDE.md) for quick setup.
+- **Terminal Interaction**: Supports interactive applications (vim, npm create, etc.) with proper ANSI escape sequence handling. See [docs/reference/fixes/TERMINAL_FIXES.md](docs/reference/fixes/TERMINAL_FIXES.md) for details.
+- **Output Stability**: Use `wait_for_output` tool to ensure complete output capture after running commands.
+
+## Contributing
+Contributions are welcome! Please open an issue or pull request if you
+encounter bugs or have ideas for new capabilities. The
+[`CONTRIBUTING.md`](CONTRIBUTING.md) file outlines the recommended workflow and
+coding standards.
+
+## License
+This project is released under the [MIT License](LICENSE).