{"$schema":"https://wellknown.network/schemas/agent-record-v1.json","schemaVersion":"1","id":"ag_h3vnxd3cgdde","handle":"bmahs-mcp-gateway","url":"https://wellknown.network/agents/bmahs-mcp-gateway","links":{"self":"https://wellknown.network/agents/bmahs-mcp-gateway/record.json","html":"https://wellknown.network/agents/bmahs-mcp-gateway","markdown":"https://wellknown.network/agents/bmahs-mcp-gateway/record.md","api":"https://wellknown.network/api/v1/agents/bmahs-mcp-gateway","status":"https://wellknown.network/api/v1/agents/bmahs-mcp-gateway/status","claim":"https://wellknown.network/agents/bmahs-mcp-gateway/claim","claimApi":"https://wellknown.network/api/v1/claims","claimDescriptor":"https://wellknown.network/agents/bmahs-mcp-gateway/claim.json","badge":"https://wellknown.network/agents/bmahs-mcp-gateway/badge.svg","openapi":"https://wellknown.network/openapi.json","history":"https://wellknown.network/api/v1/agents/bmahs-mcp-gateway/history","tools":"https://wellknown.network/api/v1/agents/bmahs-mcp-gateway/tools"},"ard":{"identifier":"urn:air::server:bmahs-mcp-gateway","type":"application/mcp-server-card+json"},"kind":"mcp_server","declared":{"name":"bmahs-mcp-gateway","summary":"BMAHS（比马斯）设备协议 ↔ MCP 网关：发现并操作局域网内的 BMAHS 硬件设备","description":"# bmahs-mcp-gateway\n\n> **BMAHS（比马斯）** 是一个开放的局域网硬件协议：每台设备上电即用自然语言「自我介绍」——我是谁、能做什么、安全边界在哪——让大模型智能体像接入 USB 设备一样，即插即用地发现、识别、按权限独占并安全地操作它们。\n\nBMAHS（比马斯）设备协议 ↔ MCP 网关：把局域网内按 `bmahs/1.0` 协议发布的硬件设备（解析侧兼容旧版 1–1.2 字段名）动态映射为 [Model Context Protocol](https://modelcontextprotocol.io) 工具，让大模型客户端可以直接发现、占用与操作这些设备。\n\n## 特性\n\n- **零配置发现**：UDP 组播（`239.255.42.42:5354` / `[ff02::4242]:5354`）+ Bonjour/mDNS 双通道，设备上线即被识别；也支持 `BMAHS_STATIC_DEVICES` 静态设备表（适配不支持组播的环境）。\n- **动态工具映射**：设备的动作清单（`ops`）自动映射为 MCP 工具，含参数 Schema 与 `any_of` 预检，无需为每类设备写适配代码。\n- **协议级占用安全**：控制前自动 `occupy`、自动携带 token、任务结束/进程退出自动 `release`，token 不写入 UDP/TXT/日志。\n- **标准错误信封**：设备错误按 §4.7 信封（`ok/action/code/error/retryable`）透传给模型，`error` 为自然语言中文。\n- **参数死循环防护**（1.3.0，默认开启）：参数净化器自动矫正畸形入参（device 传成 `{id: 名称}` 对象、数字加引号、id/动作名近似错），同参连续失败升级提示直至停止令；报错附可逐字照抄的 `retry_with` 模板。\n- **设备侧 SDK**：单文件 `sdk/bmahs_device.py`（仅标准库、拷走即用）——厂商声明「我是谁、有哪些动作」，发现/hello/信封/校验/占用全托管，声明即校验。\n- **两种接入模式**：stdio（单客户端，MCP 客户端直接拉起）与 Streamable HTTP（多客户端共享一个网关进程，可选 Bearer Token 鉴权）。\n\n## 安装\n\n推荐隔离安装（uv tool 或 pipx）：包与依赖装在独立环境，不污染系统/conda Python，任何终端可直接用 `bmahs-mcp`：\n\n```bash\nuv tool install \"bmahs-mcp-gateway[http]\"   # 首选；只用 stdio 模式可去掉 [http]\npipx install \"bmahs-mcp-gateway[http]\"     # 等效的 pipx 写法\n```\n\n也可直接 pip 装（装进当前 Python 环境，依赖与其它包共享、可能冲突，换环境后命令不可用）：\n\n```bash\npip install bmahs-mcp-gateway            # stdio 模式，最小依赖\npip install \"bmahs-mcp-gateway[http]\"    # 需要 Streamable HTTP 共享模式时\n```\n\n作为库集成时用 [uv](https://docs.astral.sh/uv/)：`uv add bmahs-mcp-gateway`。要求 Python ≥ 3.10。\n\n验证：`bmahs-mcp --version` 输出 `bmahs-mcp 1.4.0`。\n\n## 快速开始\n\n```bash\n# 扫描局域网内的 BMAHS 设备\nbmahs-mcp discover\n\n# 联调：对设备执行一个动作（控制类动作自动 occupy → 执行 → release）\nbmahs-mcp ctl 客厅灯 on\nbmahs-mcp ctl 客厅灯 brightness --arg level=80\nbmahs-mcp ctl 客厅灯 scene --arg name=cinema --ttl 600        # 指定占用租约 600 秒\nbmahs-mcp ctl 客厅灯 on --no-release                          # 动作后保持占用（打印 token）\nbmahs-mcp ctl 客厅灯 release --arg token=<占有时返回的 token>  # 手动释放保持的占用\n\n# 启动 MCP 网关（stdio，供 MCP 客户端连接；默认子命令）\nbmahs-mcp serve\n\n# 以 Stream…","publisher":{"name":"pengxingjie","url":null},"homepage":"https://github.com/XJPeng12/bmahs-mcp-gateway","repository":"https://github.com/XJPeng12/bmahs-mcp-gateway","version":"1.4.0","license":"MIT","protocols":["mcp"],"tags":["agent","bmahs","iot","llm","mcp","smart-home","zeroconf"],"pricing":null,"endpoints":[{"url":"pypi:bmahs-mcp-gateway","type":"package_pypi","auth":null,"probeable":false}],"skills":null,"tools":null,"extra":null,"attribution":{"kind":"pypi","name":"pypi","license":"pypi","repoUrl":"pypi","summary":"pypi","version":"pypi","description":"pypi","homepageUrl":"pypi","publisherName":"pypi"}},"derived":{"capabilities":[{"slug":"infra.devices","name":"Devices & IoT","confidence":1,"provenance":"declared"}],"categories":["infra"],"language":"en"},"observed":{"status":"unknown","statusReason":"Distributed as a package to run locally; no network endpoint to check.","lastOkAt":null,"lastProbedAt":null,"statusComputedAt":null,"reliability30d":null,"latestObservations":[],"tools":null,"package":{"name":"bmahs-mcp-gateway","registry":"pypi","observedAt":"2026-10-24T17:28:44.907Z","publishedAt":"2026-09-30T03:13:52.129263Z","latestVersion":"1.4.0"},"toolSurface":null,"endpointFacts":[]},"verification":{"claimed":false,"claimedAt":null,"proofs":[]},"provenance":{"sources":[{"source":"pypi","key":"bmahs-mcp-gateway","url":"https://pypi.org/project/bmahs-mcp-gateway/","firstSeenAt":"2026-09-18T08:26:20.022Z","fetchedAt":"2026-10-24T17:26:53.682Z","normalizedAt":"2026-10-24T17:26:53.682Z"}]},"firstSeenAt":"2026-09-18T08:26:20.022Z","updatedAt":"2026-10-24T17:28:44.907Z"}