pty-mcp-server

pty-mcp-server

---

⚠️ 注意

不要授予 AI 不受限制的控制权。
无人监督地使用或滥用可能导致意外后果。
所有 AI 系统都必须始终处于人类的严格监督和控制之下。
请谨慎使用，充分了解相关风险，并自行承担责任。

---

📢 提示

升级服务时，请务必确保 pty-mcp-server.yaml 已更新到最新版本。使用过时的配置文件可能导致兼容性问题或执行错误。

---

📘 概述

pty-mcp-server 是一个采用 Haskell 实现的 MCP（Model Context Protocol）服务，可让 AI Agent 动态控制 PTY（伪终端）会话，以及面向 Agent 的进程、文件系统、套接字和串行接口，从而通过基于终端和直接 I/O 的接口与真实系统环境交互。

该服务仅通过**标准输入/输出（stdio）**进行通信，确保与 MCP 客户端的集成简单且安全。借助此接口，AI Agent 可以在人工监督下执行命令、与外部端点交换数据、检索系统状态并应用配置。

---

🎯 目的

• 为 AI Agent 提供基于 TTY 和直接 I/O 的控制能力
• 使用 CLI 工具实现自动化配置、检查和操作
• 支持用于系统开发、诊断和远程交互的 AI 驱动工作流
• 允许 AI Agent 访问并操作静态脚本或 API 无法触及的系统
• 支持需要交互式或有状态终端工作流的 基础设施即代码（IaC） 场景
• 协助在异构环境和遗留系统之间进行系统集成
• 通过操作需要类似人类终端交互的工具，赋能 AI Agent 支持 DevOps、IaC 和集成流水线

---

🔧 示例用例

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

---

用户指南（使用和设置）

功能

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

可用工具

• agent-proc-run
  使用指定的命令和选项启动外部进程。该进程的 stdin/stdout 将连接起来，以供后续的 agent-proc-read 和 agent-proc-write 操作使用。同一时间只能有一个进程处于活动状态。

• agent-proc-read
  从正在运行的进程的 stdout 中读取指定字节数以内的数据。此操作会立即返回当前可用的数据（非阻塞）。如果没有可用数据，则返回空字符串。

• agent-proc-write
  将指定字符串写入正在运行的进程的 stdin。

• agent-proc-terminate
  强制终止当前运行的进程。此操作会重置内部状态，以便再次调用 agent-proc-run。

• agent-socket-open 打开套接字连接，以供后续的 agent-socket-read、agent-socket-write、agent-socket-read-byte 和 agent-socket-write-byte 操作使用。Unix 域套接字请指定 file；TCP 套接字请指定 host 和 port。

• agent-socket-close 关闭当前活动的 Agent 套接字连接。

• agent-socket-read 从当前活动的 Agent 套接字连接读取指定字节数以内的数据，并以 UTF-8 字符串形式返回。如果超时前没有可用数据，则返回空字符串。

• agent-socket-read-byte 从当前活动的 Agent 套接字连接读取指定字节数以内的数据，并以大写十六进制字符串形式返回。

• agent-socket-write 将指定的 UTF-8 字符串写入当前活动的 Agent 套接字连接。

• agent-socket-write-byte 解码指定的十六进制字符串，并将解码得到的字节写入当前活动的 Agent 套接字连接。

• agent-server-listen 绑定到指定的 host 和 port，开始侦听传入的 TCP 连接，并启动后台接受线程。侦听器就绪后立即返回。一次只能有一个侦听器处于活动状态。

• agent-server-close 关闭当前已接受的连接（如果有）。如果没有活动连接，也会关闭侦听器。调用两次即可同时关闭连接和侦听器。

• agent-server-status 以 JSON 对象形式返回当前服务器状态，其中包含布尔字段 isListening 和 isConnected。

• agent-server-events 从队列中取出并返回自上次调用以来累积的所有服务器端事件（例如 ClientConnected、BytesReceived、ClientDisconnected）。如果没有待处理事件，则返回空数组。

• agent-server-read 从当前已接受的连接读取数据，并以 UTF-8 字符串形式返回。如果超时前没有可用数据，则返回空字符串。

• agent-server-read-byte 从当前已接受的连接读取数据，并以大写十六进制字符串形式返回。

• agent-server-write 将指定的 UTF-8 字符串写入当前已接受的连接。注意：\r\n 会作为字面字符发送；要正确发送 CRLF，请使用 agent-server-write-byte。

• agent-server-write-byte 解码指定的十六进制字符串，并将解码得到的字节写入当前已接受的连接。十六进制字符串不得包含空格或换行符。

• agent-serial-open 打开串口连接，以供后续的 agent-serial-read、agent-serial-write、agent-serial-read-byte 和 agent-serial-write-byte 操作使用。一次只能有一个端口处于活动状态。

• agent-serial-close 关闭当前活动的串口连接。

• agent-serial-read 从当前活动的串口读取指定字节数以内的数据，并以 UTF-8 字符串形式返回。如果超时前没有可用数据，则返回空字符串。

• agent-serial-read-byte 从当前活动的串口读取指定字节数以内的数据，并以大写十六进制字符串形式返回（例如 FF0A1B41）。

• agent-serial-write 将指定的 UTF-8 字符串写入当前活动的串口。

• agent-serial-write-byte 解码指定的十六进制字符串，并将解码得到的字节写入当前活动的串口。接受大写或小写十六进制字符，例如 FF0A1BFF 或 000a1bff。

• pms-list-dir
  列出指定路径下的目录内容。

• pms-make-dir
  在指定路径创建目录。缺失的父目录也会一并创建。

• pms-read-file
  读取指定路径下文件的内容。可选指定 startLine/endLine（从 1 开始，包含边界），仅读取部分行范围。

• pms-write-file
  将内容写入指定路径下的文件。

• pms-file-info
  返回文件的基本元数据：总行数和字节大小。可在使用 pms-read-file 前调用此工具了解文件规模，并结合行数使用 pms-read-file 的 partial-read 功能，避免加载超出所需的内容。

• pms-grep-file
  使用 POSIX 扩展正则表达式搜索文件中匹配的行。返回一个 JSON 命中对象数组，每个对象包含：'line'（从 1 开始的行号）、'text'（匹配行的完整内容）和 'cols'（模式在该行中匹配位置的列偏移量数组，列号从 1 开始）。没有匹配行时返回空数组。可使用返回的行号调用 pms-read-file 的 partial-read 功能，高效获取周边上下文。

• pms-replace-file
  替换文件中的字面文本。每次替换按顺序应用，并将该步骤中找到的每个 oldText 都替换为 newText。这不是正则表达式替换。

• pms-patch-file
  将统一差异补丁应用到指定路径的文件。补丁必须采用统一差异格式（例如 @@ -1,3 +1,3 @@）。成功时返回已修补文件的路径。失败时返回错误消息，例如 HunkMismatch。注意：使用多个区块时，每个区块的行号（- 和 + 两侧）都必须计入所有前序区块累计的行数变化（新增行数减去删除行数）。

• socket-open
  此工具会与指定的主机和端口建立套接字连接。（已弃用：此工具与 agent-socket-open 功能重复，后者提供了对 Agent 更友好的等效接口。）

• socket-close
  此工具会关闭此前使用 'socket-open' 工具建立的活动套接字连接。（已弃用：此工具与 agent-socket-close 功能重复，后者提供了对 Agent 更友好的等效接口。）

• socket-read
  从套接字读取指定数量的字节。'size' 参数表示要读取的字节数。（已弃用：此工具与 agent-socket-read-byte 功能重复，后者提供了对 Agent 更友好的等效接口。）

• socket-write
  向套接字写入一串字节。（已弃用：此工具与 agent-socket-write-byte 功能重复，后者提供了对 Agent 更友好的等效接口。）

• socket-message
  此工具会通过活动套接字连接发送消息。（已弃用：此工具与 agent-socket-write 功能重复，后者提供了对 Agent 更友好的等效接口。）

• socket-telnet
  一种通过原始 TCP 套接字进行类 Telnet 通信的简单工具。此工具会连接到指定的主机和端口，发送和接收数据，并从通信流中移除任何 Telnet IAC（Interpret As Command，解释为命令）序列。注意：这是简化版 Telnet 实现，不支持完整的 Telnet 协议功能。（已弃用：此工具与 agent-socket-open、agent-socket-read-byte 和 agent-socket-write-byte 功能重复，后者提供了对 Agent 更友好的等效接口。）

• serial-open
  以指定波特率打开与指定设备的串口连接。通常用于通过控制台访问本地硬件或网络设备。（已弃用：此工具与 agent-serial-open 功能重复，后者提供了对 Agent 更友好的等效接口。）

• serial-close
  此工具会关闭此前使用 'serial-open' 工具建立的活动串口连接。（已弃用：此工具与 agent-serial-close 功能重复，后者提供了对 Agent 更友好的等效接口。）

• serial-read
  从串口读取指定数量的字节。'size' 参数表示要读取的字节数。（已弃用：此工具与 agent-serial-read-byte 功能重复，后者提供了对 Agent 更友好的等效接口。）

• serial-write
  向串口写入一系列字节。（已弃用：此工具与 agent-serial-write-byte 重复，后者提供了功能等同且更适合 Agent 使用的接口。）

• serial-message
  此工具会向活动串口连接发送指定字符串，然后等待远程端出现可识别的提示符。检测到提示符后，它会捕获并返回此前收到的所有输出。（已弃用：此工具与 agent-serial-write 和 agent-serial-read 重复，后两者提供了功能等同且更适合 Agent 使用的接口。）

• pty-bash
  pty-bash 是一种在伪终端（PTY）中启动 bash shell 的工具。它允许大模型（MCP 客户端）通过交互式终端（PTY）与真实的 Linux shell 交互。这样，AI 就能像人类一样运行系统命令、收集信息，并处理提示或基于 TUI 的工具，因此适用于动态的 Linux 自动化和诊断。（注意：此工具与 agent-proc-run 重复，后者提供了功能等同且更适合 Agent 使用的接口。）

• pty-ssh
  使用指定参数在伪终端中建立 SSH 会话，以便与远程系统交互。（注意：此工具与 agent-proc-run 重复，后者提供了功能等同且更适合 Agent 使用的接口。）

• pty-telnet
  在伪终端（PTY）会话中启动 telnet 命令。这样便可与远程 Telnet 服务进行交互式通信，使 AI 能像人类用户一样响应 login: 或 Password: 等提示。PTY 环境可确保终端表现得像真实的 TTY 设备，这对许多 Telnet 服务来说是必需的。（注意：此工具与 agent-proc-run 重复，后者提供了功能等同且更适合 Agent 使用的接口。）

• pty-cabal
  使用指定的项目目录、主源文件和参数，在伪终端中启动 cabal repl 会话。（注意：此工具与 agent-proc-run 重复，后者提供了功能等同且更适合 Agent 使用的接口。）

• pty-stack
  使用指定的项目目录、主源文件和参数，在伪终端中启动 stack repl 会话。（注意：此工具与 agent-proc-run 重复，后者提供了功能等同且更适合 Agent 使用的接口。）

• pty-ghci
  使用指定的项目目录、主源文件和参数，在伪终端中启动 GHCi 会话。（注意：此工具与 agent-proc-run 重复，后者提供了功能等同且更适合 Agent 使用的接口。）

• pty-connect
  通过伪终端（pty）运行命令，以便与外部工具或服务交互，并可选择提供参数。（注意：此工具与 agent-proc-run 重复，后者提供了功能等同且更适合 Agent 使用的接口。）

• pty-message
  pms-messages 是一种向正在运行的 PTY 会话发送结构化指令或命令的工具。它对直接终端输入进行了封装，使大模型（MCP 客户端）能够以受控且可编程的方式与 PTY 进程交互。（注意：此工具与 agent-proc-write 重复，后者提供了功能等同且更适合 Agent 使用的接口。）

• pty-terminate
  强制终止活动的伪终端（PTY）连接。（注意：此工具与 agent-proc-terminate 重复，后者提供了功能等同且更适合 Agent 使用的接口。）

• proc-cmd
proc-cmd 工具会将 Windows 命令提示符（cmd.exe）作为子进程启动。它允许 AI 与标准 Windows shell 环境交互，从而在熟悉的终端界面中执行批处理命令、文件操作和系统配置任务。（注意：此工具与 agent-proc-run 重复，后者提供功能相同且更适合 Agent 使用的界面。）

• proc-ps
proc-ps 会将 Windows PowerShell（powershell.exe）作为子进程启动。它提供交互式命令行环境，AI 可在其中执行 PowerShell 命令、脚本和系统管理任务。shell 会使用默认选项启动，以保持打开状态并等待后续输入。（注意：此工具与 agent-proc-run 重复，后者提供功能相同且更适合 Agent 使用的界面。）

• proc-ssh
proc-ssh 使用 runProcess 将 SSH 客户端（ssh）作为子进程启动。它使 AI 能够通过 Secure Shell 协议与其他系统建立远程连接。此工具可用于执行远程命令、访问远程 shell，或通过 SSH 隧道传输服务。必需的 arguments 字段用于指定目标用户、主机和任何 SSH 选项（例如 -p、-i、-L）。（注意：此工具与 agent-proc-run 重复，后者提供功能相同且更适合 Agent 使用的界面。）

• proc-telnet
  此工具在内部使用 PuTTY 的 plink 可执行文件运行 Telnet 会话。无需外部伪终端模拟器（如 winpty），即可在 Windows 上建立交互式 Telnet 连接。用户提供 Telnet 命令参数，这些参数会直接传递给 plink 以建立会话。（注意：plink.exe 必须位于系统 PATH 中。）（注意：此工具与 agent-proc-run 重复，后者提供功能相同且更适合 Agent 使用的界面。）

• proc-plink
  此 Windows 工具通过 plink 启动交互式控制台应用。plink 是一款命令行 SSH 和 Telnet 客户端。适合直接运行 SSH 或 Telnet 会话，无需外部 PTY 模拟器。（注意：plink.exe 必须位于系统 PATH 中。）（注意：此工具与 agent-proc-run 重复，后者提供功能相同且更适合 Agent 使用的界面。）

• proc-spawn
  使用指定参数启动外部进程，并支持通过标准输入和输出进行交互式通信。与基于 PTY 的执行不同，此工具不分配伪终端，而是使用 runProcess 函数直接与进程通信。适用于基于 stdin/stdout 的非 TUI 交互式程序。（注意：此工具与 agent-proc-run 重复，后者提供功能相同且更适合 Agent 使用的界面。）

• proc-message
  向使用 runProcess 启动的子进程发送结构化的文本指令或命令。它提供可编程接口，以便通过标准输入与进程交互。（注意：此工具与 agent-proc-write 重复，后者提供功能相同且更适合 Agent 使用的界面。）

• proc-read
  从活动 PTY 会话中读取可用输出，不会阻塞。如果没有可用数据，则返回空字符串。（注意：此工具与 agent-proc-read 重复，后者提供功能相同且更适合 Agent 使用的界面。）

• proc-write
  向活动 PTY 会话写入输入数据后立即返回，不会等待操作完成。（注意：此工具与 agent-proc-write 重复，后者提供功能相同且更适合 Agent 使用的界面。）

• proc-terminate
  强制终止通过 runProcess 创建的运行中进程。（注意：此工具与 agent-proc-terminate 重复，后者提供功能相同且更适合 Agent 使用的界面。）

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

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

  1. 在 tools/ 目录中创建名为 your-tool.sh 的 Shell 脚本。
  2. 在 tools-list.json 中添加一个名称为 "your-tool" 且包含适当元数据的条目。
  3. 无需重新编译或修改服务器——工具会按名称动态解析。

  将工具定义（tools-list.json）与实现（tools/your-tool.sh）分离，可确保清晰解耦并简化扩展。

注意：
Windows 不支持以 pty- 开头的命令。这些工具依赖 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 配置（ref）

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

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

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

• prompts：
  用于检测交互式命令提示符的提示词字符串列表。这样 AI 就能识别命令是否正在等待输入。示例包括 "ghci>"、"]$"、"password:" 等。

• allowedAgentCmds：
  允许与 agent-proc-run 配合使用的命令白名单。如果此列表为空（默认情况），则拒绝所有命令。只有此处明确列出的命令才允许执行。

---

演示

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

参考：socket-telnet-prompt

此视频演示了由 socket-telnet-prompt.md 中定义的 MCP 提示词驱动的 Telnet 登录流程。AI 使用 socket-open、socket-read、socket-write 和 socket-message 等工具执行 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 服务构建 Agent 提示词

1. [场景 1：概览与 MCP 配置]
   在本演示中，我们将展示 AI Agent 如何使用 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 Agent]
   我们打开聊天界面，并发送一条专为 Web 服务构建 Agent 设计的提示词。
   AI 通过 PTY 连接到容器的 Bash 会话，并开始准备工作。

5. [场景 5：初始设置命令]
   按照提示词，AI 首先会：

   • 创建项目文件夹
   • 进入工作目录

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

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

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

8. [场景 8：从容器外部进行验证]
   为确认外部可访问性，我们通过 端口 8080 从主机访问该服务。正如预期，响应为：“Hello, world”

9. [场景 9：查看执行历史]
   最后，我们逐步查看 AI 的操作：

   • 初始化 Bash 会话并创建工作目录
   • 设置 Python 环境
   • 生成基于 Flask 的 app.py
   • 启动 Web 服务并验证其运行情况

10. [场景 10：结论]
    这展示了 AI 如何结合 PTY-MCP-Server 和 Docker，
    以交互式、智能化且可复现的方式自动执行实际开发任务。

演示：Docker 执行和主机 SSH 访问

1. 使用 Docker 配置 MCP
   这是 mcp.json 文件，用于定义 MCP 服务的启动配置。本例中，pty-mcp-server 将通过 shell 脚本 run.sh 启动。该脚本使用 Podman 启动容器。
2. 启动 MCP 服务
   这是 run.sh 脚本。它使用 podman run 启动 Docker 容器，并设置正确的卷挂载、主机名和镜像标签。执行后，MCP 服务将在容器内启动。
3. 工具列表
   接下来，在 tools-list.json 中定义向客户端公开的工具列表。 其中包含三个工具：pty-message、pty-ssh，以及名为 hostname.sh 的 shell 脚本
4. 工具脚本目录
   在 config.yaml 中定义脚本目录的路径。 hostname.sh 等工具脚本应放置在此处
5. 主机名脚本
   hostname.sh 脚本只会运行 hostname 命令。 它会作为工具在容器内执行。
6. 在聊天中执行 hostname
   现在，让我们在聊天中运行 hostname 工具。 这会显示当前主机的名称，也就是容器的名称。
   正如预期，输出为：pms-docker-container 这确认了命令是在 Docker 容器内执行的。
7. 使用 pty-ssh 访问主机
   接下来，我们使用 pty-ssh 与主机操作系统建立 pty 会话。 SSH 连接会尝试通过 host.docker.internal 建立，该地址会解析为 Docker 主机。
   确认主机身份并输入密码后，即可成功登录。
8. 确认主机环境
   连接到主机后，我们运行：cat /etc/redhat-release
   这确认了我们现在处于主机操作系统中，系统为 CentOS 9。
   相比之下，Docker 容器运行的是 AlmaLinux 9。

演示：通过 PTY 交互式使用 Bash

1. 在 mcp.json 中配置 bash-mcp-server
   在此文件中，将 bash-mcp-server 注册为 MCP 服务。
   将命令指定为 pty-mcp-server，并将配置文件 config.yaml 作为参数传入。
2. config.yaml 中的设置
   config.yaml 文件定义日志目录、工具目录和提示词检测模式。
   这些设置为 AI 通过 PTY 与 bash 交互建立运行环境。
3. 将 tools-list.json 放入 toolsDir
   需要将 tools-list.json 放在 toolsDir 指定的目录中。
   此文件声明了 AI 可用的工具，包括 pty-bash 和 pty-message。
4. AI 连接 Bash 并自主选择命令
   AI 通过伪终端连接到 bash，并根据上下文决定要执行哪些命令。
5. 确认命令执行结果
   getenforce 命令的输出会显示 SELinux 是否处于 Enforcing 模式。
   该结果会显示在终端或日志中，用户可据此确认系统状态。

演示：执行 Shell 脚本

1. mcp.json 配置
   以 stdio 模式启动 pty-mcp-server，并将 config.yaml 作为参数传入。
2. config.yaml 概览
   指定日志目录、工具目录和提示词字符串。
   toolsDir 中的 tools-list.json 定义了要公开的工具。
3. tools-list.json 的作用
   列出可用的脚本工具，此处只注册了 script_add 工具。
4. tools 文件夹的作用和命名约定
   存放通过 MCP 服务调用的可执行 shell 脚本。
   tools-list.json 中的工具名称与此文件夹中的 shell 脚本文件名相对应。
5. 通过 VSCode GitHub Copilot 执行
   使用命令 #script_add 2 3 运行 script_add.sh，执行加法运算。
6. 确认结果
   返回“5”，表示运算成功。

演示：使用 cabal repl 调试 Haskell

参考：Haskell cabal 调试提示词

1. 目标代码概览
   选中 MyLib.hs 中的一个函数，通过 cabal repl 和 AI 驱动的调试界面检查其运行时状态。
2. MCP 服务初始化
   启动 MCP 服务，以支持 AI 与调试命令之间的结构化交互。
3. 调试提示词与环境设置
   AI 接收提示词，启动 cabal repl 并加载模块，为运行时检查做好准备。
4. 开始执行调试
   执行目标函数，并在预先设定的位置暂停，以便观察运行时状态。
5. 状态检查与输出
   显示运行时值和控制流，帮助验证逻辑并观察内部行为。
6. 总结
   与 pty-msp-server 集成后，可为 Haskell 应用实现自动化运行时检查。

---

架构指南（软件架构与技术细节）

架构策略

pty-mcp-server 项目的架构面向中大型系统设计，着重强调模块化、可维护性和可扩展性，尤其适用于涉及多个团队或组织的环境。

为实现这些目标，系统采用由职责划分清晰的多个软件包构成的结构，每个软件包负责特定的关注点或领域。这种以软件包为核心的设计具有多项战略优势。

整体软件包结构遵循洋葱架构原则，体现了以领域模型为核心的分层设计。此外，每个软件包内部的模块结构也遵循分层设计，使纯数据定义、领域服务和基础设施关注点之间保持清晰分离。

pty-mcp-server 作为依赖注入器的角色

除了管理 REPL 通信外，pty-mcp-server 不仅仅是一个可执行模块，它还充当整个系统的依赖注入器。

• 它能够引用所有相关的 PMS 软件包，包括其所依赖的软件包。
• 这使它能够以统一的方式构建并连接多个软件包和模块中的应用组件。
• 通过集中处理依赖解析，pty-mcp-server 为横切依赖提供了单一控制点，从而提高对系统架构的可见性和控制力。

因此，可以集中协调和管理软件包之间以及模块之间的依赖关系，从而提升整个系统的封装性、可复用性和可测试性。

依赖项

此软件包依赖于以下软件包：

• pms-ui-request
• pms-ui-response
• pms-ui-notification
• pms-infrastructure
• pms-infra-cmdrun
• pms-infra-procspawn
• pms-infra-agent-process
• pms-infra-agent-socket
• pms-infra-agent-server
• pms-infra-agent-serial
• pms-infra-serial
• pms-infra-socket
• pms-infra-watch
• pms-infra-filesystem
• pms-application-service
• pms-domain-service
• pms-domain-model

软件包拆分的原因

• 清晰的接口定义
  每个软件包仅公开最精简、定义明确的公共 API。这有助于建立清晰的模块边界，并减少组件之间意外产生的依赖。

• 团队和供应商所有权
  在大型项目中，不同团队或外部供应商可以负责特定的软件包。清晰的拆分确保职责明确，并支持跨组织边界的协作开发。

• 仓库和发布独立性
  软件包可以拆分到不同的仓库中，并独立进行版本管理。这有助于实现模块化开发和灵活的发布工作流，同时缩短构建时间并简化集成。

• 提升可维护性和可扩展性
  通过隔离各项关注点，代码变更的影响仅限于相关模块。这能最大限度地减少回归问题，并便于随着时间推移安全、渐进地改进。

预期使用场景

• 涉及多位开发者或多个团队的中大型企业系统
• 组件需要独立开发和发布周期的模块化系统
• 需要长期可维护性、可扩展性和关注点隔离的项目

此架构采用分层和模块化方法。领域模型、领域服务、应用逻辑和基础设施关注点分别封装在各自的软件包中，从而实现清晰的组合，同时保持职责分离。

部署图

软件包结构

线程结构

背景

pty-mcp-server 的分层和模块化架构是最初的案例研究，核心投影架构（CPA）正是由此衍生而来。

---