内容
# PuTTY MCP 服务器
适用于与已打开的 PuTTY 窗口交互的最小 [模型上下文协议](https://modelcontextprotocol.io/) 服务器。
服务器暴露 4 种工具：列出窗口、读取终端输出、发送命令和清除滚动缓冲区。
## 工具
| 工具 | 描述 |
|------|-------------|
| `putty_list_windows` | 列出可见的 PuTTY 窗口，包含标题和 PID |
| `putty_read_window` | 从选定的 PuTTY 窗口读取完整文本（屏幕 + 滚动缓冲区） |
| `putty_send_command` | 向选定的 PuTTY 窗口发送文本（可选地带有 Enter） |
| `putty_clear_window` | 清除选定 PuTTY 窗口的滚动缓冲区/历史记录 |
### 窗口选择
当多个 PuTTY 窗口打开时，请将以下选择器之一传递给 `putty_read_window`、`putty_send_command` 和 `putty_clear_window`：
| 参数 | 描述 |
|-----------|-------------|
| `process_id` | 来自 `putty_list_windows` 的 PID（最可靠） |
| `host` | 窗口标题的子字符串匹配（不区分大小写） |
| `title_substring` | 与 `host` 相同；标题匹配的替代名称 |
如果只有一个 PuTTY 窗口打开，则选择器是可选的。
### 工具参数
**`putty_send_command`**
- `command`（必需）— 要发送的文本
- `append_newline`（默认值：`true`）— 在命令后追加 Enter
**`putty_read_window`**，**`putty_clear_window`**，**`putty_send_command`**
- `process_id`，`host` 或 `title_substring` — 参见 [窗口选择](#窗口选择)
## 典型工作流程
1. 调用 `putty_list_windows`。
2. 通过 `process_id`（首选）或 `title_substring` 选择窗口。
3. 可选地调用 `putty_clear_window` 以在读取之前清除旧的滚动缓冲区。
4. 调用 `putty_send_command`。
5. 等待 1-2 秒。
6. 调用 `putty_read_window` 以获取命令输出。
有关 AI 代理，请参见 [AGENTS.md](AGENTS.md) 中的选择规则、诊断标记和上下文缩减提示。
## 要求
- Python 3.10+
- Windows
- `pywin32` 和 `mcp[cli]`（参见 [安装](#安装)）
- 一个或多个已打开的 PuTTY GUI 窗口（`putty.exe`）
## 安装
```bash
git clone https://github.com/pekishev/putty-mcp.git
cd putty-mcp
pip install -r requirements.txt
```
或从 `pyproject.toml` 安装：
```bash
pip install .
```
## MCP 配置
适用于 Cursor 或其他 MCP 客户端的示例 MCP 服务器条目：
```json
{
"mcpServers": {
"putty": {
"command": "python",
"args": ["C:/path/to/putty-mcp/putty_mcp.py"]
}
}
}
```
使用您机器上的 `putty_mcp.py` 的绝对路径。
## 工作原理
- **读取** — 通过 `PostMessage` 发送 PuTTY 系统命令 *复制所有到剪贴板*（`IDM_COPYALL`），读取剪贴板，然后恢复以前的剪贴板内容。
- **发送** — 解析目标窗口，尽力激活/聚焦，然后使用 `WM_CHAR` 直接向 PuTTY 窗口发送字符。交付不严格依赖于窃取 OS 前台焦点。
- **清除** — 通过系统菜单命令 ID 发送 PuTTY *清除滚动缓冲区*（`IDM_CLRSB`）；无论 UI 本地化如何，都有效。
PuTTY 窗口通过进程名称（`putty.exe`）检测，而不是仅通过窗口标题。
## 响应格式
所有工具都返回带有 `success` 字段的 JSON 对象。
示例：
- `putty_list_windows` → `{ "success": true, "windows": [{ "title": "...", "pid": 1234 }], "count": 1 }`
- `putty_read_window` → `{ "success": true, "content": "...", "window_title": "..." }`
- `putty_send_command` → `{ "success": true, "window_title": "...", "command_sent": "...\n", "activated": true }`
- `putty_clear_window` → `{ "success": true, "window_title": "...", "message": "PuTTY 滚动缓冲区已清除。" }`
在发生错误时，响应包括 `error` 和相关时包含 `windows` 列表，以帮助选择正确的目标。
## 使用说明
- `putty_send_command` 确认文本已发送；它 **不** 返回命令的标准输出。使用 `putty_read_window` 读取输出。
- 当打开多个会话时，优先使用 `process_id` 而不是标题匹配。
- 如果激活被 Windows 焦点规则阻止，则发送可能仍成功（`activated: false`）；如有需要，手动将 PuTTY 带到前台。
- 在诊断之前，使用 `putty_clear_window` 或标记命令（`echo DIAG_START` / `echo DIAG_END`）减少长滚动缓冲区中的噪音。
## 项目布局
```
putty_mcp.py # MCP 服务器入口点（FastMCP，stdio 传输）
putty_lib/
window_reader.py # 列出/读取 PuTTY 窗口
window_send.py # 发送命令和清除滚动缓冲区
```
## 限制
- 仅限 Windows（需要 `pywin32`）。
- 与现有的 PuTTY GUI 窗口配合使用；服务器不会创建 SSH 会话。
- 仅支持 `putty.exe` 窗口（不支持 KiTTY、PuTTYtel 或其他分支，除非它们使用相同的可执行文件名）。
- 读取依赖于 PuTTY 响应 *复制所有到剪贴板*。
## License
MIT
