router-ssh-mcp/
├── pyproject.toml               # 依赖与 console script 入口
├── config.example.json          # 配置文件示例（不含真实口令）
├── .env.example                 # 环境变量示例
├── src/router_mcp/
│   ├── config.py                # 配置加载（默认值 < 配置文件 < 环境变量）
│   ├── errors.py                # 错误码与结构化异常
│   ├── commands.py              # 命令白名单与 argv 模板（安全核心）
│   ├── ssh_pool.py              # SSH 连接复用 / 保活 / 超时重连 / 错误归类
│   ├── controller.py            # 编排层：安全策略、二次确认、工具语义
│   ├── models.py                # pydantic 返回模型
│   ├── server.py                # MCP 服务器与工具注册
│   ├── _compat.py               # mcp 1.x / 2.x 兼容层
│   └── backends/
│       ├── base.py              # 后端抽象与公共能力（启动时间推算）
│       ├── initd.py             # /etc/init.d 通用实现（sysvinit）
│       ├── procd.py             # OpenWrt ubus + procd
│       └── systemd.py           # systemctl + journalctl
├── scripts/
│   ├── selftest.py              # 真实设备自测（只读 + 可选写入演练）
│   └── mcp_smoke.py             # stdio 协议级冒烟测试
└── tests/                       # 离线单元测试 + MCP 层端到端测试

python3 -m venv .venv
source .venv/bin/activate
pip install -e .          # 开发模式
# 或：pip install .

python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -e .

{
  "host": "192.168.1.1",
  "username": "root",
  "password": "",
  "init_system": "auto",
  "security": {
    "require_confirmation": true,
    "allowed_services": [],
    "denied_services": ["network", "firewall"]
  }
}

# stdio（默认，供 MCP 客户端拉起）
ROUTER_MCP_HOST=192.168.1.1 ROUTER_MCP_PASSWORD=xxx python -m router_mcp

# 等价的 console script
ROUTER_MCP_HOST=192.168.1.1 ROUTER_MCP_PASSWORD=xxx router-ssh-mcp

# 命令行覆盖参数
router-ssh-mcp --host 192.168.1.1 --user root --key-path ~/.ssh/id_ed25519

# SSE / Streamable HTTP（远程部署时使用）
router-ssh-mcp --transport streamable-http

{
  "mcpServers": {
    "router-ssh": {
      "description": "通过 SSH 管理路由器（OpenWrt/ImmortalWrt/systemd）服务的 MCP 连接器；只读工具可直接调用，写入操作需二次确认，run_shell 高危能力默认关闭。",
      "command": "python",
      "args": ["-m", "router_mcp"],
      "env": {
        "ROUTER_MCP_HOST": "192.168.1.1",
        "ROUTER_MCP_USER": "root",
        "ROUTER_MCP_PASSWORD": "你的密码"
      }
    }
  }
}

{
  "ok": true,
  "tool": "service_status",
  "host": "192.168.1.1",
  "duration_ms": 412,
  "data": {
    "service": {
      "name": "dnsmasq",
      "running": true,
      "enabled": true,
      "pid": 2814,
      "started_at": "2026-09-10 09:00:12",
      "description": "/usr/sbin/dnsmasq -C /var/etc/dnsmasq.conf",
      "source": "procd"
    },
    "checked_at": "2026-09-10T09:21:03+08:00"
  },
  "error": null
}

{
  "ok": false,
  "tool": "service_restart",
  "host": "192.168.1.1",
  "error": {
    "code": "CONFIRMATION_REQUIRED",
    "message": "写入操作 restart 需要二次确认",
    "hint": "确认无误后再次调用，并传入 confirm=\"dnsmasq\"",
    "details": {"service": "dnsmasq", "expected_confirm": "dnsmasq"}
  }
}

{
  "ok": true,
  "tool": "router_info",
  "data": {
    "capability": "ssh-router-management",
    "init_system": "procd",
    "host": "192.168.1.1",
    "security": {
      "require_confirmation": true,
      "allow_shell": false,
      "denied_services": ["network", "firewall", "system", "boot", "done"]
    }
  }
}

# 1) 刷新软件源并安装插件（OpenWrt 包管理器 opkg）
run_shell(
  command="opkg update && opkg install luci-app-sqm",
  confirm="opkg update && opkg install luci-app-sqm"
)

# 2) 安装后启用并随系统自启
run_shell(
  command="/etc/init.d/sqm enable && /etc/init.d/sqm start",
  confirm="/etc/init.d/sqm enable && /etc/init.d/sqm start"
)

{
  "ok": true,
  "tool": "run_shell",
  "data": {
    "raw_command": "opkg update && opkg install luci-app-sqm",
    "exit_status": 0,
    "stdout": "Installing luci-app-sqm (...)",
    "stderr": "",
    "host": "192.168.1.1",
    "reused_connection": true,
    "confirmed": true,
    "warning": "命令以 root 身份在路由器上执行，已绕过服务白名单；请确认输出不含敏感信息"
  }
}

pip install -e ".[dev]"
python -m pytest -q

# 仅握手 + 列工具，不需要设备
python scripts/mcp_smoke.py

# 真实调用一次只读工具
ROUTER_MCP_HOST=192.168.1.1 ROUTER_MCP_USER=root ROUTER_MCP_PASSWORD=xxx \
  python scripts/mcp_smoke.py --call router_info

# 带参数调用
python scripts/mcp_smoke.py --call service_status --args '{"name": "dnsmasq"}'

ROUTER_MCP_HOST=192.168.1.1 ROUTER_MCP_USER=root ROUTER_MCP_PASSWORD=xxx \
  python scripts/selftest.py

python scripts/selftest.py --host 192.168.1.1 --password xxx \
  --service dnsmasq --do-write