使用说明（Markdown 格式）

使用说明

• 项目简介

  • 这是一个基于 MCP（Model Context Protocol）的服务端实现，用于在本地 UNIX 环境中创建终端会话、执行命令、读取输出，并通过 JSON-RPC 与客户端进行通信。它提供会话管理、命令执行、流式输出、控制字符等能力，面向需要与本地系统交互的 LLM 模型或自动化系统。

• 主要功能点

  • 会话管理：创建、列举、销毁终端会话（create_session、list_sessions、destroy_session）
  • 命令执行：同步执行并获取输出（execute_command）、异步执行及输出读取（execute_command_async、read_streaming_output）
  • 流式输出：即时读取和持续读取命令输出
  • 终端输入控制：发送控制字符（send_control_character）
  • 运行时状态与调试支持：调试模式、等待就绪、状态读取等
  • 使用 PTY 实现真实的伪终端环境，确保与常见 CLI 的交互行为匹配

• 安装步骤

  • 安装前提：需要 rust 和 cargo 环境
  • 构建与运行
    1. 获取代码并进入项目目录
    2. 运行构建与运行（开发模式）：cargo run
    3. 运行时，通过标准输入输出（stdio）与 MCP 客户端进行通信
  • 备注：该实现默认通过 stdio 传输进行 MCP 通信，适用于需要将 JSON-RPC 请求/响应通过管道方式对接的场景。

• 服务器配置（MCP 客户端对接所需信息）

  • MCP 服务器用于客户端对接，客户端需要知道服务器的启动命令与参数，以便通过 MCP 客户端与服务器建立连接。以下信息仅用于说明配置，不需要在客户端代码中执行。
  • 服务器名称（server_name）：terminal-mcp
  • 启动命令（command）：/path/to/terminal-mcp
  • 启动参数（args）：[]
  • 备注：由于本实现通过标准输入输出（stdio）进行 MCP 通信，客户端配置应指向能够将 JSON-RPC 请求注入到服务器进程的入口，实际参数可根据运行环境调整。

• 基本使用方法

  • 启动服务器后，将 MCP 客户端的请求写入服务器的标准输入，服务器将输出 JSON-RPC 响应到标准输出。
  • 最常用的工具调用示例（要点说明，实际请求请按 MCP 协议格式封装为 JSON-RPC 请求）：
    • 创建会话：name 为会话名，command 为要在会话中执行的起始命令，例如 bash、ssh user@host、python 等。
    • 列出会话：查看当前创建的会话及其状态
    • 执行命令：在指定会话中执行命令，获取输出
    • 异步执行与读取：启动异步命令后可通过 read_streaming_output 获取新输出及完成状态
    • 发送控制字符：向会话发送 Ctrl+C 等控制信号