AI导哈

伪终端会话服务

PTY-MCP是一个通过模型上下文协议（MCP）暴露伪终端（PTY）会话的服务，支持通过编程方式控制shell会话和REPL，适用于自动化脚本执行和交互式应用开发。

  • by brkhrdt
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 brkhrdt/pty-mcp

使用说明

PTY-MCP

MCP服务器为AI代理公开PTY（伪终端）会话。通过模型上下文协议启用对shell会话和REPL的编程控制。

特性

  • 启动和管理多个PTY会话
  • 使用基于哨兵的完成检测运行命令
  • 适用于任何shell（bash、zsh、tcsh、fish等）
  • 适用于嵌套的REPL（Python、Node、Tcl等）
  • 可配置的会话超时和缓冲区大小
  • 交互式应用程序的原始输入支持

安装

uv add pty-mcp

用法

作为MCP服务器

添加到MCP客户端配置中：

{
  "mcpServers": {
    "pty": {
      "command": "uv",
      "args": ["run", "pty-mcp"]
    }
  }
}

或者直接运行：

uv run pty-mcp --max-sessions 10 --log-dir /path/to/logs

这 --log-dir 选项启用实时会话日志记录。指定后，每个会话的输出将立即写入名为的日志文件 pty_<command_name>_<session_id>.log （例如。， pty_bash_3a4b5c6d7e8f.log).目录必须存在；如果没有，服务器将出错。您可以使用实时监视日志 tail -f /path/to/logs/*.log.

MCP工具

start_session

使用任何命令或shell启动新的PTY会话。

参数：

  • command （可选）：要执行的命令/二进制文件（默认值： $SHELL 或 /bin/bash).可以是任何可执行文件，如 bash, python3, tcl, somebinary -a -b等等。如果 args 如果未提供，将自动解析命令字符串以提取参数。
  • args （可选）：传递给命令的参数列表。如果省略，参数将从 command 弦。当参数包含空格或特殊字符时，明确提供此选项。
  • cwd （可选）：工作目录
  • timeout_session （可选）：空闲超时（默认值：86400）
  • buffer_size （可选）：回滚缓冲行（默认值：1000）
  • sentinel_command （可选）：回声哨兵的命令（默认值： echo {sentinel})

退货： 会话ID

示例：

# Start default shell (bash)
start_session()

# Start Python REPL
start_session(command="python3")

# Start custom binary with arguments (auto-parsed)
start_session(command="somebinary -a -b --args")

# Start with explicit args (for complex arguments)
start_session(command="somebinary", args=["-a", "-b", "--args"])

# Start Tcl shell in specific directory
start_session(command="tclsh", cwd="/path/to/project")

run_command

运行命令并等待完成。

参数：

  • session_id （必填）：会话ID来自 start_session
  • command （必填）：运行命令
  • timeout （可选）：超时秒数（默认值：1800）

退货： 命令输出

send_keys

发送原始输入，无需等待完成。

参数：

  • session_id （必填）：会话ID
  • keys （必填）：原始输入（使用 \n 对于Enter， \x03 对于Ctrl+C）

get_buffer

获取回滚缓冲区内容。

参数：

  • session_id （必填）：会话ID
  • lines （可选）：从末尾开始的行数

退货： 缓冲区内容

stop_session

停下来清理会话。

参数：

  • session_id （必填）：要停止的会话ID

set_sentinel

更改会话的哨兵命令。在shell和REPL之间切换时使用。

参数：

  • session_id （必填）：会话ID
  • sentinel_command （必填）：新的哨兵指挥模板 {sentinel} 占位符

list_sessions

列出所有具有元数据的活动会话。

使用REPL

从shell切换到REPL（或在REPL之间切换）时，请使用 set_sentinel 要更新哨兵命令，请执行以下操作：

# Start with bash (default sentinel: echo {sentinel})
session_id = start_session()

# Run some bash commands
run_command(session_id, "ls -la")

# Switch to Python REPL
send_keys(session_id, "python3\n")
set_sentinel(session_id, "print('{sentinel}')")

# Now run Python commands
run_command(session_id, "print('hello from python')")
run_command(session_id, "2 + 2")

# Exit Python and switch back to bash
send_keys(session_id, "exit()\n")
set_sentinel(session_id, "echo {sentinel}")

常见哨兵命令：

  • Bash/sh/zsh： echo {sentinel}
  • python print('{sentinel}')
  • Node.js： console.log('{sentinel}')
  • Tcl： puts {sentinel}
  • 鲁比（irb）： puts '{sentinel}'

发展

# Install dependencies
uv sync

# Run tests
uv run pytest tests/ -v

许可证

麻省理工学院

相关 MCP