pty-mcp-server

---

⚠️ 警告

不要授予AI不受限制的控制权。
未经监督使用或误用可能导致意外后果。
所有AI系统必须严格在人类监督和控制下运行。
请负责任地使用，充分了解风险并自行承担后果。

---

📘 概述

pty-mcp-server 是一个用Haskell实现的MCP（模型上下文协议）服务器，它使AI代理能够动态获取和控制PTY（伪终端）会话，从而通过基于终端的接口与真实系统环境进行交互。

该服务器仅通过**标准输入/输出（stdio）**进行通信，确保与MCP客户端简单且安全的集成。通过此接口，AI代理可以执行命令、检索系统状态并应用配置——就像人类操作员通过终端一样。

---

🎯 目的

• 向AI代理提供基于TTY的控制能力
• 使用CLI工具实现自动化配置、检查和操作
• 支持由AI驱动的工作流，用于系统开发、诊断和远程交互
• 允许AI代理访问和操作超出静态脚本或API范围的系统
• 支持需要交互式或有状态终端工作流的**基础设施即代码（IaC）**场景
• 在异构环境和遗留系统中协助系统集成
• 通过操作需要类似人类终端交互的工具，支持AI代理在DevOps、IaC和集成流水线中的作用

---

🔧 示例用例

• 动态执行需要PTY环境的CLI工具
  （例如，通过串行或基于SSH的终端连接嵌入式系统）
• REPL自动化：驱动GHCi或其他基于CLI的交互解释器
• 交互式调试：调试Haskell应用程序或基于shell的工作流
• 系统诊断：通过脚本化或交互式的bash会话
• 远程服务器管理：使用SSH
• 手动系统操作：当CLI行为不能通过非交互式脚本模拟时
• 网络设备交互：通过控制台配置路由器、交换机或设备
• AI辅助IaC工作流：执行涉及提示、状态协调或实时输入的Terraform、Ansible或基于shell的部署脚本
• AI驱动的跨多个环境和CLI工具的系统集成测试
• 遗留系统自动化：在没有GUI/API的情况下，仅支持终端交互

---

用户指南（使用和设置）

功能

pty-mcp-server 提供以下内置工具以实现强大而灵活的自动化：

可用工具

• pty-connect
  通过伪终端（pty）运行命令以与外部工具或服务交互，可选参数。

• pty-terminate
  强制终止活动的伪终端（PTY）连接。

• pty-message
  pms-messages 是一种向正在运行的PTY会话发送结构化指令或命令的工具。它抽象了直接终端输入，允许LLM（MCP客户端）以受控和可编程的方式与PTY进程交互。

• pty-bash
  pty-bash 是一个在伪终端（PTY）中启动bash shell的工具。它允许LLM（MCP客户端）与真实的Linux shell进行交互式终端（PTY）交互。这使得AI能够运行系统命令、收集信息并处理提示或基于TUI的工具，就像由人类操作一样，使其适用于动态的Linux自动化和诊断。

• pty-ssh
  在指定参数的伪终端中建立SSH会话，允许与远程系统交互。

• pty-telnet
  在伪终端（PTY）会话中启动telnet命令。这允许与远程Telnet服务器进行交互式通信，使AI能够像人类用户一样响应诸如“登录：”或“密码：”等提示。PTY环境确保终端行为类似于真正的TTY设备，这是许多Telnet服务器所必需的。

• pty-cabal
  在指定项目目录中启动cabal repl会话，加载目标Haskell文件。
  支持参数传递和实时代码交互。

• pty-stack
  在伪终端中使用指定项目目录、主源文件和参数启动stack repl会话。

• pty-ghci
  使用指定项目目录、主源文件和参数在伪终端中启动GHCi会话。

• proc-spawn
  使用指定参数启动外部进程，并通过标准输入和输出进行交互式通信。与基于PTY的执行不同，这通过runProcess函数直接与进程通信而不分配伪终端。适合非TUI、基于stdin/stdout的交互程序。

• proc-terminate
  强制终止通过runProcess创建的运行进程。

• proc-message
  向通过runProcess启动的子进程发送结构化的文本指令或命令。它提供了通过标准输入与进程交互的可编程接口。

• proc-cmd
proc-cmd 工具启动Windows命令提示符（cmd.exe）作为子进程。它允许AI与标准Windows shell环境交互，执行批处理命令、文件操作和系统配置任务，提供熟悉的终端界面。

• proc-ps
proc-ps 启动Windows PowerShell（powershell.exe）作为子进程。它提供了一个交互式命令行环境，其中AI可以执行PowerShell命令、脚本和系统管理任务。shell以默认选项启动，保持打开并准备进一步输入。

• proc-ssh
proc-ssh 使用runProcess启动SSH客户端（ssh）作为子进程。它使AI能够通过Secure Shell协议发起对其他系统的远程连接。该工具可用于执行远程命令、访问远程shell或通过SSH隧道服务。所需的arguments字段允许指定目标用户、主机和任何SSH选项（如-p、-i、-L）。

• proc-telnet
  一个工具，通过内部使用PuTTY的plink可执行文件来运行Telnet会话。这使得在Windows上无需外部伪终端模拟器（如winpty）即可进行交互式Telnet连接。用户提供的Telnet命令参数直接传递给plink以建立会话。（注意：plink.exe必须在系统PATH中可用。）

• proc-plink
  一个Windows工具，通过plink启动交互式控制台应用程序。适合直接执行SSH或Telnet会话，无需外部PTY模拟器。（注意：plink.exe必须在系统PATH中可用。）

• socket-open
  此工具初始化到指定主机和端口的套接字连接。

• socket-close
  此工具关闭之前使用socket-open工具建立的活动套接字连接。

• socket-read
  从套接字读取指定数量的字节。size 参数指示要读取的字节数。

• socket-write
  将一系列字节写入套接字。

• socket-message
  此工具将指定字符串发送到活动套接字连接，然后等待来自远程方的可识别提示。检测到提示后，它捕获并返回在此之前收到的所有输出。

• socket-telnet
  一个简单的类似Telnet的通信工具，通过原始TCP套接字。此工具连接到指定的主机和端口，发送和接收数据，并从通信流中删除任何Telnet IAC（按命令解释）序列。注意：这是一个简化的Telnet实现，不支持完整的Telnet协议功能。

• serial-open
  打开到指定设备的串行端口连接，具有给定的波特率。通常用于通过控制台访问本地硬件或网络设备。

• serial-close
  此工具关闭之前使用serial-open工具建立的活动串行连接。

• serial-read
  从串行端口读取指定数量的字节。size 参数指示要读取的字节数。

• serial-write
  将一系列字节写入串行端口。

• serial-message
  此工具将指定字符串发送到活动套接字连接，然后等待来自远程方的可识别提示。检测到提示后，它捕获并返回在此之前收到的所有输出。

• Scriptable CLI Integration
pty-mcp-server 支持执行注册工具定义在tools-list.json中的相关shell脚本。每个工具必须按名称注册，并且相应的shell脚本（.sh）应在配置的tools/目录中存在。

  这种设计通过可预测的脚本机制暴露工具接口，支持AI驱动的工作流。AI可以通过名称发出工具调用，而服务器透明地管理执行和交互。
  添加新工具的方法：

  1. 在tools/目录中创建名为your-tool.sh的shell脚本。
  2. 在tools-list.json中添加一个条目，名称为"your-tool"，并附带适当的元数据。 [3. 不需要重新编译或修改服务器——工具是通过名称动态解析的。]

  工具定义（tools-list.json）和实现（tools/your-tool.sh）之间的这种分离确保了清晰的解耦和简化了扩展性。

注意：
以pty-开头的命令在Windows上不受支持。这些工具依赖于POSIX风格的伪终端（PTY），而在Windows环境中并不原生可用。

使用Podman或Docker运行

您可以使用Podman或Docker构建和运行pty-mcp-server。

注意： 当在Docker容器内运行pty-mcp-server时，建立pty连接后，您将在容器环境中操作。这一点在与服务器交互时应予以考虑。

1. 构建镜像

克隆仓库并导航到docker目录：

$ git clone https://github.com/phoityne/pty-mcp-server.git
$ cd pty-mcp-server/docker
$ podman build . -t pty-mcp-server-image
$

参考：build.sh

2. 运行容器

在容器内运行服务器：

$ podman run --rm -i \
--name pty-mcp-server-container \
-v /path/to/dir:/path/to/dir \
--hostname pms-docker-container \
pty-mcp-server-image \
-y /path/to/dir/config.yaml
$

参考：run.sh

下面是如何配置mcp.json以在VSCode中运行MCP服务器的一个示例：

{
  "servers": {
    "pty-mcp-server": {
      "type": "stdio",
      "command": "/path/to/run.sh",
      "args": []
      /*
      "command": "podman",
      "args": [
        "run", "--rm", "-i",
        "--name", "pty-mcp-server-container",
        "-v", "/path/to/dir:/path/to/dir",
        "--hostname", "pms-docker-container",
        "pty-mcp-server-image",
        "-y", "/path/to/dir/config.yaml"
      ]
      */
    }
  }
}

二进制安装

如果您希望自行构建，请确保满足以下要求：

• GHC >= 9.6

您可以使用cabal安装pty-mcp-server：

$ cabal install pty-mcp-server

通过.dxt包安装

您还可以使用预打包的.dxt文件设置工具。
这种方法适用于快速安装到Claude Code，或者通过提取进行手动设置。

🛠️ .dxt 包分发目前正处于准备阶段，
您可以在以下链接查看最新状态和下载链接：
https://github.com/phoityne/pms-dxt

二进制执行

pty-mcp-server 应用程序从命令行执行。

使用方法

$ pty-mcp-server -y config.yaml

虽然可以直接从命令行启动服务器，但通常是由集成了MCP客户端的开发工具（如Visual Studio Code）启动和管理。这些工具利用服务器通过PTY会话实现交互和自动命令执行。

VSCode 集成：.vscode/mcp.json

为了简化开发和从Visual Studio Code中调用服务器，该项目支持.vscode/mcp.json配置文件。

此文件定义了pty-mcp-server在开发环境中的启动方式。示例配置：

{
  "servers": {
    "pty-mcp-server": {
      "type": "stdio",
      "command": "pty-mcp-server",
      "args": ["-y", "/path/to/your/config.yaml"]
    }
  }
}

config.yaml 配置（参考）

• logDir：
  日志文件保存的目录路径。包括标准输出/错误日志和脚本执行的日志。

• logLevel：
  设置日志级别。示例包括"Debug"、"Info"和"Error"。

• toolsDir：
  包含脚本文件（以工具名称命名的shell脚本，例如ping.sh）的目录。如果在此目录中存在与工具名称匹配的脚本，则在调用工具时将执行该脚本。
  此目录还必须包含定义可用公共工具及其元数据的tools-list.json文件。

• prompts：
  用于检测交互命令提示的一系列提示字符串。这允许AI识别何时命令等待输入。示例包括"ghci>"、"]$"、"password:"等。

---

演示

AI 通过 pty-mcp-server 处理二进制协议对话

参考：socket-telnet-prompt

此视频演示了由在socket-telnet-prompt.md中定义的MCP提示驱动的Telnet登录序列。使用socket-open、socket-read、socket-write和socket-message等工具，AI执行Telnet协商，处理提示并提交凭据。二进制响应被解析并以人类可读的形式显示。

通过串行连接检查网络设备版本 —— 由 pty-mcp-server 驱动

参考：serial-nw-setting-prompt

此视频演示了如何使用pty-mcp-server通过串行连接实现AI辅助的网络设备自动化。

1. 设备设置
   用户指定了通信端口和波特率。
   示例： Windows上的COM3，9600波特率。

2. 登录交互
   AI提示输入用户名和密码，
   并使用它们登录到网络设备。

3. 设备版本检索
   登录后，AI发送命令
   以检索已安装的操作系统或固件版本。

4. 在线版本检查
   AI访问官方网站以检查最新可用版本，
   并与已安装版本进行比较。

5. 会话终止
   检查完成后，AI注销并干净地关闭串行连接。

演示：观看AI从零开始创建并启动Web应用程序

参考：Web服务构建代理提示

1. [场景1：概述及MCP配置]
   在这个演示中，我们将展示AI代理如何使用pty-mcp-server在Docker容器内构建和运行Web服务。
   首先，我们配置mcp.json以使用shell脚本启动MCP服务器。
   此脚本启动Docker容器，在其中我们的基于PTY的交互将发生。

2. [场景2：Docker启动配置]
   run.sh脚本包括卷挂载、主机名设置，并打开端口8080。
   这允许容器向主机系统公开Web服务。

3. [场景3：启动MCP服务器]
   现在，容器已启动，pty-mcp-server在其内部运行，
   准备通过伪终端处理AI驱动的请求。

4. [场景4：连接AI代理]
   我们打开聊天界面并发送一个设计用于Web服务构建代理的提示。
   AI通过PTY连接到容器的Bash会话并开始其准备工作。

5. [场景5：初始设置命令]
   根据提示，AI开始：

   • 创建项目文件夹
   • 移动到工作目录

6. [场景6：AI准备好接收指令]
   一旦环境就绪，我们指示AI构建一个“Hello, world”Web服务。
   从这里开始，AI开始其自主构建过程。

7. [场景7：AI执行Web设置命令]
   AI提出了一系列终端命令。
   作为用户，我们逐个审查并批准它们。
   步骤包括：

   • 检查Python
   • 安装Flask
   • 编写源代码（app.py）以提供“Hello, world”
   • 运行Flask服务器
   • 通过curl http://localhost:8080在容器内测试

8. [