v2.8.0

v2.8.0

This release makes the browser viewer much more practical for day-to-day use, especially when you are working with
more than one session at once.

What's new

• Safe / Full is now per session
  You can switch one session to full without affecting every other session in the same server.
  This is much safer when you are multitasking across devices or terminals.

• A real browser control panel
  The viewer home page can now do more than just list sessions.
  You can now manage:

  • viewer access policy
  • per-session custom command rules
  • rule order, enable/disable state, and severity

• Custom rules are much more flexible
  Rules now support three levels:

  • error: block the command
  • warning: allow it but show a warning
  • log: allow it and record the match

• Rule ordering is now controllable
  You can reorder rules in the UI, and that order now actually matters.
  Within the same severity level, rules higher in the list win.

• Viewer access policy management
  You can configure browser access with:

  • allow_all
  • allowlist
  • denylist

  This is especially useful when the viewer is exposed outside plain localhost.

• Debug / local workflow is back and improved
  In --local --debug mode, the browser home page again lets you:

  • run commands as the simulated agent
  • send control keys like Ctrl-C, arrows, Tab, and Esc
  • set the active session directly

What's better now

• Less interference between sessions
  Session state is more isolated, so one session's mode or policy changes are less likely to surprise you somewhere
  else.

• Smoother browser viewer behavior
  The session list no longer flashes or fades in again on every auto-refresh.

• Details panels stay open
  If you open a session's Details, it now stays open during refresh instead of collapsing unexpectedly.

• Editing rules is safer
  If you are in the middle of editing a rule, auto-refresh will avoid overwriting that work.

• Dragging rules feels more natural
  Only the drag handle starts a drag now, so editing text fields no longer accidentally drags the whole rule row.

• Debug testing now respects saved rules
  When you test commands from the browser's debug controls, they now follow the same session rules and safety mode you
  configured.

Typical things you can do now

• Keep one session in safe and another in full
• Use the browser viewer to tune command rules per session
• Test blocked and warned commands directly from the debug UI
• Expose the viewer more carefully with allow/deny policies
• Edit rules in the UI without losing your work every second

Compatibility note

Older rule actions such as block and warn are still accepted and mapped automatically, so existing configs do not
need to be rewritten immediately.

v2.7.3

v2.7.3

Automated release for v2.7.3.

v2.7.1

v2.7.1

Automated release for v2.7.1.

ssh-session-mcp v2.7.0

v2.7.0 — Local Debug Mode & Viewer Dashboard Overhaul

✨ Highlights

• 🖥️ Local Debug Mode
  --local spawns a local shell, no SSH host needed. Works on Windows, Linux, and macOS. Perfect for development, testing, and demos.

• 🎮 Debug Mode
  --debug unlocks in-browser agent command input, control keys (Ctrl+C, arrows, etc.), and session management directly from the home page.

• 🏠 Viewer Dashboard Redesign
  AJAX-powered soft-refresh home page with:

  • Status badges (active, idle, stale, locked) with live updates
  • One-click per-session details panel (diagnostics + history)
  • Close / Set Active / Agent command input right from the dashboard
  • "New Local Session" button when running in local mode

• ✨ Full UI Animation System
  fadeIn, pulse, shakeIn, hover/active transitions, and focus-visible outlines applied across all pages.

• 🔌 WebSocket Resilience
  Exponential backoff reconnection (10 attempts max), clear status messages, and session-scoped broadcasts.

🆕 New in v2.7.0

• 🆕 Local debug mode (--local / SSH_MCP_LOCAL=true)
• 🆕 Debug mode (--debug / SSH_MCP_DEBUG=true)
• 🆕 Viewer dashboard with soft refresh and session management
• 🆕 Session API: /close, /diagnostics, /history, /agent-input, /control, /set-active
• 🎨 CSS animations and interactive polish on all viewer pages
• 🔧 WebSocket reconnect with exponential backoff
• 🔧 Xterm CDN failure handling and lock-aware cursor behavior

📊 Cumulative Changes Since v2.6.4 (6 versions)

Version	Key Changes
v2.7.0	Local mode, dashboard, UI animations, WebSocket reconnect
v2.6.9	ssh-retry validation, background timeout cap, regex fixes
v2.6.8	Multi-line sentinel handling (heredoc, CR/LF/CRLF)
v2.6.7	Test suite stability
v2.6.6	License copyright fix
v2.6.5	Viewer architecture refactoring, MIT → Apache-2.0

📦 Install

npm install -g ssh-session-mcp@2.7.0

ssh-session-mcp@2.6.4

概述

自 2.2.0 版本以来，ssh-session-mcp 经历了重大演进，从基础的 SSH 会话管理发展为完整的多设备、多实例企业级 SSH 会话管理平台。本版本在稳定性、可观测性、配置管理和用户体验方面进行了全面增强。
主要新特性（2.3.0 → 2.6.4）

会话诊断与可观测性 (2.4.0)

• 会话诊断工具: ssh-session-diagnostics 检查终端模式、输入锁定状态、查看器状态和运行命令元数据
• 带行号的历史记录: ssh-session-history 以行号形式召回混合 SSH 输出、用户输入和AI输入
• 本地 JSONL 元数据日志: 支持 SSH_MCP_LOG_MODE=meta 和 SSH_MCP_LOG_DIR 进行文件级本地日志记录
• CLI 日志查看器: npm run logs 检查本地服务器或会话日志，不污染 MCP stdio

多设备与配置管理 (2.5.0)

• 多设备配置文件: 使用 ssh-session-mcp.config.json 管理多个 SSH 设备配置
• 设备配置文件: 支持 defaults、defaultDevice 和 devices 字段的JSON配置文件
• 配置治理 CLI: 新增 ssh-session-mcp-config 命令用于配置检查、设备编辑和默认设备管理
• 配置发现规则: 明确了配置文件的自动发现机制和显式配置路径支持
• 认证模式: 支持 auth.passwordEnv 和 auth.keyPath，不再支持明文密码

仓库验证与文档标准化 (2.6.0)

• 仓库验证工具: ssh-session-mcp-validate-repo 检查必需的文档、示例配置有效性、验收场景ID等
• 跨工具响应契约: 标准化的工具响应字段 (resultStatus / summary / nextAction)
• 失败分类文档: 一致的错误分类和故障排除指南
• 验收场景基线: 定义了预期用户工作流和测试场景
• 平台兼容性文档: 部署指南和运行时兼容性说明

代码架构改进 (2.6.1)

• 模块化重构: 将庞大的 src/index.ts 重构为专注的模块：
  • src/server-state.ts - 服务器状态管理
  • src/tools.ts - 工具函数模块
  • src/viewer-html.ts - 查看器HTML生成
  • src/viewer-server.ts - 查看器服务器逻辑

查看器UI增强 (2.6.4)

• 响应式设计: 移动端友好的布局，窄屏适配（<900px）
• 锁定模式改进: 正确处理"common"模式为未锁定状态
• UI合约测试: 新增测试确保查看器UI行为一致性

关键改进

命令执行可靠性 (2.2.x → 2.3.2)

• 确定性的完成标记: 使用唯一哨兵标记 (MCP_DONE__) 进行可靠的完成检测
• 退出代码捕获: 命令执行后准确捕获并返回退出代码
• 哨兵回显检测: 区分命令回显和实际哨兵输出，防止误匹配
• ANSI感知匹配: 提示检测和哨兵匹配在模式匹配前去除ANSI转义序列
• CR-only PTY 完成检测: 标准化 \r\n / \r 处理，兼容不同板卡的换行约定

输入锁定与协作 (2.0.x → 2.6.4)

• 三种锁定模式: user（用户锁定）、agent（AI锁定）、common（无锁定共享）
• 浏览器终端锁定: 可通过浏览器UI实时切换锁定模式
• AI工具自动锁定: ssh-run 自动获取和释放agent锁
• 用户输入保护: 当AI活跃时阻止用户输入，提供视觉反馈

查看器体验 (2.0.0 → 2.6.4)

• xterm.js 浏览器终端: 真实的终端仿真，替代文本仪表板
• WebSocket 通信: 二进制PTY输出流，替代HTTP轮询
• 自动打开终端: --autoOpenTerminal 或 AUTO_OPEN_TERMINAL 环境变量
• 查看器端口自动分配: VIEWER_PORT=auto 选择随机空闲端口
• 多实例隔离: 通过 SSH_MCP_INSTANCE 值防止AI代理间的干扰

安全与配置增强

密码提示保护

• 全模式保护: 在所有操作模式下检测密码提示并阻止命令执行
• 执行后检测: 命令完成后检查终端是否停留在密码提示
• 明确的错误消息: 指导用户手动处理密码提示

配置发现与优先级

1. 显式配置路径 (--config=/path/to/config.json 或 SSH_MCP_CONFIG)
2. 工作空间配置 (<cwd>/ssh-session-mcp.config.json)
3. 用户全局配置 (平台默认位置)
4. 遗留 .env 单设备回退

认证模式

• 推荐: auth.passwordEnv (环境变量引用) 和 auth.keyPath (密钥文件路径)
• 不支持: 明文 auth.password (配置验证时会失败)
• 示例: { "auth": { "passwordEnv": "BOARD_A_PASSWORD" } }

向后兼容性

保持兼容

• 遗留 .env 单设备模式仍然支持
• 原有的MCP工具接口保持不变
• 浏览器终端回退页面仍然可用

默认值变更

• AUTO_OPEN_TERMINAL 默认改为 false
• VIEWER_PORT 默认改为 0 (禁用)
• 浏览器终端下拉菜单默认模式改为 "common"

v2.2.0 - Deterministic Completion Markers & Structured Parsers

v2.2.0 - Intelligent Command Completion & Safety Modes

A major reliability and safety upgrade. Commands now complete deterministically, dangerous operations are blocked by default, and long-running commands are handled gracefully.

Highlights

Deterministic Command Completion

• Sentinel markers: Each command gets a unique completion marker (___MCP_DONE_<id>_<exitcode>___). No more guessing when a command finishes.
• Exit code capture: ssh-run now returns the actua...

v2.0.0 - Shared SSH Terminal

v2.0.0 - Shared SSH Terminal with xterm.js

The first major release of ssh-session-mcp v2, introducing a shared browser terminal where users and AI agents collaborate on the same SSH session in real-time.

Highlights

• xterm.js Browser Terminal: Real terminal emulator replaces the text dashboard. Full color, cursor movement, and interactive program support.
• WebSocket Streaming: Binary PTY output streamed in real-time via WebSocket — no more HTTP polling.
• Input Lock Mechanism: User/AI mode switch prevents simultaneous input conflicts. The browser dropdown controls who can type.
• Simplified AI Tools: Just two tools cover most use cases:
  • ssh-quick-connect — one-step connect + open terminal
  • ssh-run — execute command and return output
• .env Configuration: SSH credentials loaded from .env file automatically. No command-line secrets.
• One-Command Launch: npm run launch starts MCP server, connects SSH, and opens the browser termin...