remote-debug-mcp 0.2.0__py3-none-any.whl

remote_debug_mcp-0.2.0.dist-info/METADATA

@@ -0,0 +1,315 @@
+Metadata-Version: 2.4
+Name: remote-debug-mcp
+Version: 0.2.0
+Summary: MCP server for remote debugging via SSH and Telnet with persistent background connections
+Project-URL: Homepage, https://github.com/user/remote-debug-mcp
+Project-URL: Repository, https://github.com/user/remote-debug-mcp
+Project-URL: Issues, https://github.com/user/remote-debug-mcp/issues
+License: MIT License
+        
+        Copyright (c) 2025
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Keywords: android,debugging,mcp,remote-debug,serial,ssh,telnet
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Topic :: Software Development :: Debuggers
+Classifier: Topic :: System :: Networking
+Requires-Python: >=3.10
+Requires-Dist: mcp>=1.0.0
+Requires-Dist: pexpect>=4.8
+Description-Content-Type: text/markdown
+
+# Remote Debug MCP
+
+基于 MCP (Model Context Protocol) 的远程调试服务器，支持 **SSH** 和 **Telnet** 后台持久化连接，专为远程串口调试和 Android/Linux 设备管理设计。
+
+## 功能
+
+- **SSH** — 持续后台连接远程服务器/Windows PC，支持命令执行、SCP/SFTP 文件传输、MD5 完整性校验、自动重连
+- **Telnet** — 持续后台连接，支持数据收发、串口数据监听、后台监控保存
+- **com2tcp** — 一键桥接 Windows COM 串口到 TCP Telnet，远程调试串口设备
+- **配置文件** — YAML 文件预设连接参数，`ssh_connect(config_name="xxx")` 一键连接
+
+## 安装
+
+```bash
+# 克隆到 ~/.config 目录（推荐，与配置文件路径一致）
+mkdir -p ~/.config
+git clone https://github.com/zxyyzwd/remote_debug_mcp.git ~/.config/remote_debug_mcp
+cd ~/.config/remote_debug_mcp
+
+# 虚拟环境安装
+python3 -m venv .venv && source .venv/bin/activate && pip install -e .
+
+# 或直接安装
+pip install -e .
+```
+
+依赖：Python ≥ 3.10 · pexpect · mcp
+
+## 配置客户端
+
+### OpenCode
+
+`~/.config/opencode/opencode.jsonc`：
+
+```jsonc
+{
+  "mcp": {
+    "remote-debug": {
+      "type": "local",
+      "command": ["python3", "-m", "remote_debug_mcp"],
+      "enabled": true,
+      "timeout": 60000
+    }
+  }
+}
+```
+
+### Claude Code
+
+`~/.claude.json`：
+
+```json
+{
+  "mcp": {
+    "remote-debug": {
+      "command": "python3",
+      "args": ["-m", "remote_debug_mcp"],
+      "enabled": true,
+      "timeout": 60000
+    }
+  }
+}
+```
+
+也可用命令行添加：
+
+```bash
+claude mcp add remote-debug python3 -- -m remote_debug_mcp
+```
+
+> 使用虚拟环境时，将 `python3` 替换为虚拟机环境中的 Python 路径。
+
+配置后重启客户端即可使用。
+
+## 连接配置
+
+### YAML 配置文件
+
+`config.yaml` 放在工作目录或仓库根目录，首次调用 `ssh_connect(config_name=...)` 时自动加载并缓存。
+
+`config.yaml` 默认搜索路径：
+- `./config.yaml`（当前工作目录）
+- `<source_dir>/config.yaml`（源码目录）
+- `<source_dir>/../config.yaml`（`src/` 父目录）
+- `<repo_root>/config.yaml`（仓库根目录）
+- `<repo_root>/src/remote_debug_mcp/config.yaml`（源码包目录）
+- `~/.config/remote-debug-mcp/config.yaml`（用户全局配置）
+
+```yaml
+connections:
+  # ── SSH 连接 ──────────────────────
+  - name: "office-pc"          # 连接名称，后续引用用
+    type: ssh
+    host: "192.168.1.16"       # 远程 IP
+    port: 22                   # SSH 端口
+    username: "zxyyz"          # 用户名
+    password: "kaixin123"      # 密码（明文，仅本地使用）
+
+  - name: "office-pc-key"      # 密钥认证
+    type: ssh
+    host: "192.168.1.16"
+    username: "admin"
+    key_file: "/home/me/.ssh/id_rsa"
+
+  # ── 串口映射 ──────────────────────
+  - name: "serial-com4"        # com2tcp 桥接配置
+    type: com2tcp
+    ssh: "office-pc"           # 引用上面的 SSH 连接名（用于解析 host）
+    com_port: "COM4"           # Windows COM 口
+    telnet_port: 5200          # 暴露的 Telnet 端口
+    baud: 115200               # 波特率（默认 115200）
+    # 以下为可选参数（均有默认值）
+    # username: ""             # Telnet 登录用户名
+    # password: ""             # Telnet 登录密码
+    # connect_timeout: 15      # 连接超时（秒）
+    # buffer_max_size: 65536   # 缓冲区大小（字节，默认 64KB）
+    # max_retries: 3           # 自动重连次数
+```
+
+使用：
+
+```
+ssh_connect → config_name: "office-pc"            # 自动从 config.yaml 读参数连接
+list_connections                                   # 查看已加载的配置
+save_config                                        # 保存当前内存配置
+save_config → connections: [{...}]                 # 创建/更新配置条目（无配置文件时的唯一入库入口）
+```
+
+## com2tcp 串口调试工作流
+
+### 远程环境要求
+
+远程 Windows PC 需满足以下条件，否则 `setup_com2tcp` 将失败：
+
+| 依赖 | 说明 | 安装方式 |
+|------|------|----------|
+| **Python >= 3.8** | 运行 com2telnet.py 串口转 TCP 服务 | [python.org](https://www.python.org/downloads/) 下载，**勾选 "Add Python to PATH"** |
+| **pip** | 安装 pyserial 依赖 | 随 Python 一同安装 |
+| **pyserial** | 串口通信库 | `setup_com2tcp` 自动 `pip install` |
+| **防火墙放行** | Telnet 端口（如 5200）需入站放行 TCP | `setup_com2tcp` 执行时自动通过 SSH 放行，或手动配置 |
+
+安装 Python 后验证：
+
+```powershell
+python --version
+pip --version
+```
+
+`setup_com2tcp` 会自动上传 `com2telnet.py` + `pyproject.toml` 到 `D:\remote-debug\com2telnet\` 并安装依赖，无需手动操作。
+
+如果远程机器无 Python，可通过 SSH 自动下载安装：
+
+```powershell
+Invoke-WebRequest -Uri "https://www.python.org/ftp/python/3.11.9/python-3.11.9-amd64.exe" -OutFile "$env:TEMP\python-installer.exe"
+Start-Process -Wait -FilePath "$env:TEMP\python-installer.exe" -ArgumentList "/quiet", "InstallAllUsers=1", "PrependPath=1"
+```
+
+### 架构
+
+```
+┌──────────┐  SSH (PowerShell)   ┌──────────────────┐
+│  MCP     │ ──────────────────▶ │  Windows PC       │
+│  Server  │                     │  COM4 → :5200     │
+│          │  Telnet :5200       │       ↑           │
+│          │ ◀────────────────── │  串口设备          │
+└──────────┘                     └──────────────────┘
+```
+
+```
+1. ssh_connect → config_name: "office-pc"    # SSH 到 Windows PC
+2. setup_com2tcp → ssh_session_id: "...", com_port: "COM4", telnet_port: 5200
+3. save_config → connections: [{name: "serial-com4", type: "com2tcp", ...}]  # 持久化配置
+4. telnet_connect → session_id: "serial", config_name: "serial-com4"         # 所有参数从配置解析
+5. telnet_send → data: "ls", timeout: 3
+6. telnet_listen → duration: 10
+7. telnet_start_monitor → output_file: "serial.log"  # 后台持续记录
+```
+
+## 工具参考
+
+### SSH（6 个）
+
+| 工具 | 说明 |
+|------|------|
+| `ssh_connect` | 通过 config_name 从 config.yaml 读取参数连接（密码/密钥自适应） |
+| `ssh_execute` | 执行命令（自动适配 bash/PowerShell，中文编码正确） |
+| `ssh_upload` | 上传文件（SCP → SFTP 降级，自动 MD5 校验） |
+| `ssh_download` | 下载文件（SCP → SFTP 降级，自动 MD5 校验） |
+| `ssh_disconnect` | 关闭会话 |
+| `ssh_list` | 列出所有 SSH 会话 |
+
+### Telnet（5 个）
+
+| 工具 | 说明 |
+|------|------|
+| `telnet_connect` | 通过 config_name 连接（host/port/login/buffer/retries 全从配置解析） |
+| `telnet_send` | 发送数据（timeout=0 发后即返，timeout>0 等响应；`__CTRL_C__`/`__CTRL_D__`/`__CTRL_Z__`；普通数据自动追加 `\r`） |
+| `telnet_listen` | 监听指定秒数，返回新数据（支持 utf-8/base64/hex 编码） |
+| `telnet_disconnect` | 关闭会话 |
+| `telnet_list` | 列出所有 Telnet 会话 |
+
+### Telnet 监控（2 个）
+
+| 工具 | 说明 |
+|------|------|
+| `telnet_start_monitor` | 启动后台持续监听（可选持续写入文件） |
+| `telnet_stop_monitor` | 停止后台监听，返回累计行数 |
+
+### 配置（2 个）
+
+| 工具 | 说明 |
+|------|------|
+| `list_connections` | 列出已加载配置中的所有 SSH 和 com2tcp 连接 |
+| `save_config` | **配置唯一入库入口**：无参保存内存配置；带 `connections` 参数创建/更新条目后写入文件 |
+
+### 工作流（1 个）
+
+| 工具 | 说明 |
+|------|------|
+| `setup_com2tcp` | 完整 com2tcp 工作流（上传 + 启动 + 验证），完成后提示调 `save_config` 持久化 |
+
+### 通用（1 个）
+
+| 工具 | 说明 |
+|------|------|
+| `list_sessions` | 列出所有 SSH + Telnet 会话 |
+
+## 架构
+
+```
+src/
+├── remote_debug_mcp/
+│   ├── server.py         # MCP 服务端：17 个工具定义 + 分发
+│   ├── sessions.py       # SSH/Telnet 会话生命周期管理
+│   ├── config_loader.py  # YAML 配置文件加载/保存
+│   ├── config.example.yaml
+│   ├── __init__.py
+│   └── __main__.py
+└── remote/               # 上传远程服务器的 Python 脚本
+    ├── pyproject.toml    # 远程工具安装配置
+    └── com2telnet.py     # 串口转 Telnet 服务端
+```
+
+## 技术要点
+
+- SSH 使用 `pexpect.spawn('ssh', ...)` 直连，**不使用 pxssh**（避免 Windows 提示符兼容问题）
+- SSH pexpect `encoding=None` 原始字节模式
+- **Windows 双路径编码**：`-T` 无 PTY 模式用 **GBK** 编码，`-t` PTY 回退模式建立后执行 `chcp 65001` 切换 **UTF-8** 编码
+- Linux 统一 UTF-8 编解码
+- Windows 连接后尝试切 PowerShell，成功后走交互式命令执行；失败则回退 CMD + one-shot 模式（每次命令新起 SSH），适配不同 SSH 服务端配置
+- 命令输出通过 `echo` 唯一标记分隔，不依赖 shell 提示符
+- Windows 自动切换到 PowerShell，工作目录 `D:\remote_debug`
+- 文件传输 SCP 优先 → SFTP 兜底，传输后自动 MD5 校验
+- Telnet `telnet_send` 使用 echo-marker 策略（`command; echo __MCP_{ts}__`），命令执行完即刻返回，不再盲等 timeout 秒
+- Telnet `telnet_stop_monitor` 移除阻塞 `join()`，不再阻塞事件循环
+- Telnet 缓冲区 64KB（可配），支持 utf-8/base64/hex 编码
+- Telnet 后台监听：deque 行缓存 90 万行（FIFO），可选持续写入文件
+- 自动重连：指数退避，默认最多 3 次
+- 配置自动缓存内存，`save_config` 持久化到 YAML
+
+详细设计参见 [DESIGN.md](DESIGN.md)
+
+## 变更日志
+
+### v0.2.0
+
+- **Windows 双路径编码**：`-T` 无 PTY 模式仍用 GBK，`-t` PTY 回退模式切换为 UTF-8（建立后执行 `chcp 65001`），解决 server12 等 PTY 机器中文乱码
+- **Telnet 命令 latency 优化**：`telnet_send` 采用 echo-marker 策略（与 SSH 统一），命令执行完即刻返回，不再盲等 timeout 秒
+- **Telnet 监控无阻塞**：`telnet_stop_monitor` 移除 `join()` 调用，不再阻塞事件循环 3 秒
+- **com2telnet 广播优化**：`_broadcast()` 改用 `asyncio.gather()` 并发 drain，慢客户端不再阻塞其他客户端
+- **SSH 命令轮询**：输出轮询间隔 300ms → 100ms，命令响应延迟降低 3 倍
+- 连接日志新增 `[pty/no-pty]` `[powershell/cmd]` `[gbk/utf-8]` 诊断信息

remote_debug_mcp-0.2.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+remote_debug_mcp/__init__.py,sha256=ye8y97-PQyT20seg8IIgbZzH-4lrXTTYIomuu9LMrRQ,61
+remote_debug_mcp/__main__.py,sha256=oNhY2z-YMhS3zUJSgbKqSPcbEV0oqqHpYitXGW_zzMY,108
+remote_debug_mcp/config_loader.py,sha256=L_PQP-dmtDV7pgznC2bgvJrnigCGbc1ZQA2TGQS30aw,7111
+remote_debug_mcp/server.py,sha256=UD8J0J0RD0SGBoK9-SwnUUaBGWo-sxw1XDglayo_Tuw,29284
+remote_debug_mcp/sessions.py,sha256=PF0TW583lyWo6qxblyQQiqBxUwzMTCwlBhsDACoQlmU,46122
+remote_debug_mcp/config.example.yaml,sha256=iv3mGvxdDS_IqlpJhLBsev_mfjc2dLrSe0XzHxJgH4A,1129
+remote_debug_mcp-0.2.0.dist-info/METADATA,sha256=4uTI42JAgaWWtB4eBapN4htgtnoqGUJCMsTn_eXxWlI,12861
+remote_debug_mcp-0.2.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+remote_debug_mcp-0.2.0.dist-info/entry_points.txt,sha256=hx4G_KPgAKAkpA92pJ2eMAfsLu6W8f02OGLv7nupR5g,59
+remote_debug_mcp-0.2.0.dist-info/licenses/LICENSE,sha256=Btzdu2kIoMbdSp6OyCLupB1aRgpTCJ_szMimgEnpkkE,1056
+remote_debug_mcp-0.2.0.dist-info/RECORD,,

remote_debug_mcp-0.2.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

remote_debug_mcp-0.2.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+remote-debug-mcp = remote_debug_mcp:main

remote_debug_mcp-0.2.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.