ESP32 NAT Router MCP Bridge

使用说明

• 项目简介
  • 该仓库包含一个 MCP 服务器实现（Esp32 NAT Router MCP Bridge），通过 Python 编写，使用 FastMCP 库提供 JSON-RPC 风格的接口。服务器端与 ESP32 NAT Router 的远程控制台（Telnet/TCP）进行通信，汇总路由器状态、网络配置、端口映射、ACL、PCAP 等功能，并对外提供工具方法供 LLM 客户端调用。
• 主要功能点
  • MCP 服务器核心
    • 提供基于 MCP 的工具集，能够查询路由器状态、配置、DHCP 映射、ACL、端口映射等信息，并将结果以文本化的形式返回。
    • 支持会话生命周期管理，具备基本认证、传输适配（stdio、SSE、HTTP 传输）等 MCP 服务器特性。
  • 远程控制桥接
    • 通过 Telnet/ TCP 连接 ESP32 的远程控制台，执行路由器上的实际命令（如 show status、set_sta、portmap、acl、pcap 等）。
  • 资源与工具暴露
    • 将路由器上的资源、工具、以及可用的提示模板以 MCP 的规范暴露给 LLM，便于统一的上下文管理和功能调用。
  • 拓展能力
    • 与 ESP32 固件中的流控、PCAP、WIFi/VPN、远程控制台等模块协同工作，提供综合性的网络管理能力。
• 安装步骤
  • 需要的环境
    • Python 3.x 环境
    • 安装依赖：pip install fastmcp telnetlib3
  • 安装与运行
    • 将仓库克隆到本地
    • 进入 esp32_nat_router 目录，执行以下任一启动命令之一
      • python esp_nat_bridge.py
        • 默认标准输入/输出（stdio）传输，适合直接在终端或同一主机内接入 MCP 客户端。
      • python esp_nat_bridge.py --transport streamable-http --port 8000
        • 使用可流式传输的 HTTP 传输，监听 8000 端口，便于远程浏览器或工具接入。
• 服务器配置（MCP 客户端需要的最小信息，JSON 配置示例，描述区分客户端需求）
  • 服务器名称: ESP32 NAT Router MCP Bridge
  • 启动命令: python esp_nat_bridge.py
  • 参数示例（JSON，客户端需要提供 server、command、args 字段）
    • 示例 A（stdio 传输，默认）
      • server_name: "ESP32 NAT Router MCP Bridge"
      • command: "python3 esp_nat_bridge.py"
      • args: ["--transport","stdio"]
      • 注释: 使用 stdio 传输，直接通过命令行的标准输入/输出与 MCP 客户端通信。
    • 示例 B（HTTP 传输，端口 8000）
      • server_name: "ESP32 NAT Router MCP Bridge"
      • command: "python3 esp_nat_bridge.py"
      • args: ["--transport","streamable-http","--port","8000"]
      • 注释: 通过 HTTP 流式传输的 MCP 连接，适合远端浏览器或远程工具接入。
• 基本使用方法
  • 启动后，MC 客户端通过规范的 MCP 接口调用工具，例如 show_status、show_config、get_heap_info、restart 等。
  • 客户端可以组合调用，获取文本结果，用于将路由器状态嵌入到工作流或对话式 AI 中进行决策与操作。
  • 如需变更连接方式，可调整启动参数，将传输改为 stdio、SSE 或 streamable-http，并在需要时指定端口。
• 运行与维护要点
  • 该桥接实现需要 ESP32 端启用 Telnet remote console，并正确配置 ESP-NET、AP/STA/Uplink 等网络场景。
  • MCP 服务端依赖远端设备的稳定性（ESP32 NAT Router）和网络连通性，确保远程控制台可用。
  • 如遇认证/连接问题，请检查 ESP32_NAT_ROUTER 的 telnet 控制台权限与密码设置。