bmahs-mcp-gateway

# bmahs-mcp-gateway > **BMAHS（比马斯）** 是一个开放的局域网硬件协议：每台设备上电即用自然语言「自我介绍」——我是谁、能做什么、安全边界在哪——让大模型智能体像接入 USB 设备一样，即插即用地发现、识别、按权限独占并安全地操作它们。 BMAHS（比马斯）设备协议 ↔ MCP 网关：把局域网内按 `bmahs/1.0` 协议发布的硬件设备（解析侧兼容旧版 1–1.2 字段名）动态映射为 [Model Context Protocol](https://modelcontextprotocol.io) 工具，让大模型客户端可以直接发现、占用与操作这些设备。 ## 特性 - **零配置发现**：UDP 组播（`239.255.42.42:5354` / `[ff02::4242]:5354`）+ Bonjour/mDNS 双通道，设备上线即被识别；也支持 `BMAHS_STATIC_DEVICES` 静态设备表（适配不支持组播的环境）。 - **动态工具映射**：设备的动作清单（`ops`）自动映射为 MCP 工具，含参数 Schema 与 `any_of` 预检，无需为每类设备写适配代码。 - **协议级占用安全**：控制前自动 `occupy`、自动携带 token、任务结束/进程退出自动 `release`，token 不写入 UDP/TXT/日志。 - **标准错误信封**：设备错误按 §4.7 信封（`ok/action/code/error/retryable`）透传给模型，`error` 为自然语言中文。 - **参数死循环防护**（1.3.0，默认开启）：参数净化器自动矫正畸形入参（device 传成 `{id: 名称}` 对象、数字加引号、id/动作名近似错），同参连续失败升级提示直至停止令；报错附可逐字照抄的 `retry_with` 模板。 - **设备侧 SDK**：单文件 `sdk/bmahs_device.py`（仅标准库、拷走即用）——厂商声明「我是谁、有哪些动作」，发现/hello/信封/校验/占用全托管，声明即校验。 - **两种接入模式**：stdio（单客户端，MCP 客户端直接拉起）与 Streamable HTTP（多客户端共享一个网关进程，可选 Bearer Token 鉴权）。 ## 安装 推荐隔离安装（uv tool 或 pipx）：包与依赖装在独立环境，不污染系统/conda Python，任何终端可直接用 `bmahs-mcp`： ```bash uv tool install "bmahs-mcp-gateway[http]" # 首选；只用 stdio 模式可去掉 [http] pipx install "bmahs-mcp-gateway[http]" # 等效的 pipx 写法 ``` 也可直接 pip 装（装进当前 Python 环境，依赖与其它包共享、可能冲突，换环境后命令不可用）： ```bash pip install bmahs-mcp-gateway # stdio 模式，最小依赖 pip install "bmahs-mcp-gateway[http]" # 需要 Streamable HTTP 共享模式时 ``` 作为库集成时用 [uv](https://docs.astral.sh/uv/)：`uv add bmahs-mcp-gateway`。要求 Python ≥ 3.10。 验证：`bmahs-mcp --version` 输出 `bmahs-mcp 1.4.0`。 ## 快速开始 ```bash # 扫描局域网内的 BMAHS 设备 bmahs-mcp discover # 联调：对设备执行一个动作（控制类动作自动 occupy → 执行 → release） bmahs-mcp ctl 客厅灯 on bmahs-mcp ctl 客厅灯 brightness --arg level=80 bmahs-mcp ctl 客厅灯 scene --arg name=cinema --ttl 600 # 指定占用租约 600 秒 bmahs-mcp ctl 客厅灯 on --no-release # 动作后保持占用（打印 token） bmahs-mcp ctl 客厅灯 release --arg token=<占有时返回的 token> # 手动释放保持的占用 # 启动 MCP 网关（stdio，供 MCP 客户端连接；默认子命令） bmahs-mcp serve # 以 Stream…