smart-terminal-mcp

使用说明（简要、易上手）

• 项目简介 本仓库实现了一个基于 MCP（Model Context Protocol）的服务器端后端，核心功能包括：持久化的 PTY/伪终端会话、执行命令并保持会话状态、支持交互式输入输出、提供多种工具接口用于与 AI 客户端协作，以及对输出进行分页、裁剪与解析，便于模型在对话中获取可控的上下文信息。

• 主要功能点

  • 持久化终端会话：通过 PTY 实现持续的 shell 会话，跨步骤保持目录、环境与进程状态。
  • 命令执行工具：提供 terminal_start、terminal_exec、terminal_run 等命令；支持交互式执行、单-shot 执行、输出分页与摘要。
  • 输出解析与摘要：对特定命令输出进行结构化解析（如 git 状态、进度摘要等），并提供摘要信息，减少模型消耗的 token 数量。
  • 历史与会话管理：记录会话输出历史、可分页读取，支持多会话并发管理。
  • 兼容多种传输：主实现使用 stdio 传输（MCP 客户端可通过 stdin/stdout 连接），并设计为可扩展为 SSE/WebSocket 等传输。
  • 安全与健壮性：对错误、超时、输出字节上限进行保护，提供进度通知（可选）。

• 安装步骤

  • 安装 Node.js 环境（建议 LTS 版本）。
  • 下载或克隆仓库代码。
  • 安装依赖并启动服务（示例方式请参考 README，推荐通过 npx 启动稳定版本的 MCP 服务）。注意实际部署会根据你的运行环境选择合适的启动方式。

• 服务器配置（MCP 客户端使用的配置信息，供连接服务器使用的启动参数） 说明：MCP 客户端需要配置启动命令来连接 MCP 服务器。以下配置用于 Claude/Code 等环境的集成，表示如何启动该 MCP 服务器。 { "serverName": "smart-terminal", "command": "npx", "args": ["-y", "smart-terminal-mcp@stable"] } 参数说明：

  • serverName：在客户端侧用于标识此 MCP 服务器的名称，便于管理和切换。
  • command：启动 MCP 服务器的命令，这里使用 npx 直接执行稳定版本的 smart-terminal-mcp。
  • args：传递给命令的参数，-y 表示自动确认，确保无人工干预地拉取最新的稳定版本。 备注：MCP 客户端不需要了解服务器端的实现细节，只需知道如何启动并与服务器建立稳定的 JSON-RPC 通道即可。

• 基本使用方法

  • 启动服务后，客户端可以通过 MCP 协议向服务器请求读取资源、调用工具、获取提示模板等能力。
  • 使用 terminal_start 创建一个持久化的交互式终端会话，之后通过 terminal_write/terminal_read 进行交互。
  • 如需一次性执行命令，使用 terminal_run；如需交互式会话、分页输出、等待特定文本等，可结合 terminal_exec、terminal_wait、terminal_get_history 等工具使用。
  • 管理会话时可以查看 terminal_list，获取当前活动会话及其元信息。
  • 服务器对输出进行截断、分页、摘要等处理，默认行为是帮助模型在对话中更高效地获取上下文信息。

• 其他注意

  • 该实现包含了完整的服务端逻辑、命令解析、输出格式化、diff 生成等能力，代码结构清晰且带有完整测试用例，便于本地开发和扩展。
  • 根据部署环境，可能需要对 shell、路径、权限等做适配，以确保在目标系统上的稳定性。