Skip to main content
Glama
bmahs-mcp-gateway-node

bmahs-mcp-gateway-node

by XJPeng12

bmahs-mcp-gateway-node

BMAHS(比马斯) 是一个开放的局域网硬件协议:每台设备上电即用自然语言「自我介绍」——我是谁、能做什么、安全边界在哪——让大模型智能体像接入 USB 设备一样,即插即用地发现、识别、按权限独占并安全地操作它们。

BMAHS(比马斯)设备协议 ↔ MCP 网关的 Node.js / TypeScript 实现:把局域网内按 bmahs/1.0 协议发布的硬件设备(解析侧兼容旧版 1–1.2 字段名)动态映射为 Model Context Protocol 工具,让大模型客户端可以直接发现、占用与操作这些设备。

与 Python 版(bmahs-mcp-gateway)功能全量对齐,两者可互换使用,也可与对方的参考设备跨语言互通(npm run smoke:py)。

特性

  • 零配置发现:UDP 组播(239.255.42.42:5354 / [ff02::4242]:5354,多网卡全 join + 自愈)+ Bonjour/mDNS 双通道;BMAHS_STATIC_DEVICES 静态设备表适配容器/跨网段。

  • 动态工具映射:设备 operations 自动映射为 MCP 工具(<设备id>__<动作>),含 JSON Schema、any_of 约束与自然语言说明,无需为每类设备写适配。

  • 协议级占用安全:控制前自动 occupy(有限租约)、token 按会话保管并自动携带、进程退出统一 release、token 递归遮蔽绝不回显。

  • 参数死循环防护(1.3.0,默认开启):参数净化器自动矫正畸形入参(device 传成 {id: 名称} 对象、数字加引号、id/动作名近似错),同参连续失败升级提示直至停止令;报错附可逐字照抄的 retry_with 模板。

  • 两种接入模式:stdio(单客户端)与 Streamable HTTP(多客户端共享,Bearer Token 常量时间鉴权,占用方可追溯到 -sN 会话)。

  • 实验性抓屏:声明了 ui 能力的设备可 bmahs_screenshot 抓帧(§4.9 二进制流解析)。

Related MCP server: MCP-Edge

安装

npm install -g bmahs-mcp-gateway-node       # 全局安装,得到命令 bmahs-mcp-node(与 pip 版的 bmahs-mcp 不冲突)
npx -y bmahs-mcp-gateway-node@latest serve  # 免安装直接运行

验证:bmahs-mcp-node --version 输出 bmahs-mcp-node 0.1.1。要求 Node.js ≥ 20。国内网络安装慢可临时走镜像 --registry=https://registry.npmmirror.com(同步可能有几分钟延迟)。

从源码构建开发:

npm install
npm run build        # tsc → dist/
node dist/bin.js --version

快速开始

# 扫描局域网内的 BMAHS 设备(全局安装后把 node dist/bin.js 换成 bmahs-mcp-node)
node dist/bin.js discover

# 联调:对设备执行一个动作(控制类动作自动 occupy → 执行 → release)
node dist/bin.js ctl 客厅灯 on
node dist/bin.js ctl 客厅灯 brightness --arg level=80
node dist/bin.js ctl 客厅灯 scene --arg name=cinema --ttl 600        # 指定占用租约 600 秒
node dist/bin.js ctl 客厅灯 on --no-release                          # 动作后保持占用(打印 token)
node dist/bin.js ctl 客厅灯 release --arg token=<占有时返回的 token>  # 手动释放保持的占用

# 启动 MCP 网关(stdio,默认子命令)
node dist/bin.js serve

# 以 Streamable HTTP 共享模式启动(多客户端同时连接)
node dist/bin.js http --host 0.0.0.0 --port 9530 --token 换成你的令牌

在 MCP 客户端中配置 stdio 接入:

{
  "mcpServers": {
    "bmahs-node": {
      "command": "node",
      "args": ["/绝对路径/bmahs-mcp-gateway-node/dist/bin.js", "serve"]
    }
  }
}

HTTP 模式端点为 http://<host>:9530/mcp;设置了 --token 后客户端须携带 Authorization: Bearer <token>。

重启客户端后,模型可见两类工具:7 个固定工具——bmahs_devices(列设备)、bmahs_refresh(重扫描)、bmahs_describe(读自述)、bmahs_occupy / bmahs_release(占用/释放)、bmahs_call(泛化调用)、bmahs_screenshot(ui 设备抓屏);以及每台设备的动态工具——<设备id>__<动作>(如 demo-light-001__brightness),参数说明来自设备自述。典型流程:bmahs_devices 选型 → 直接调动态工具(网关自动 occupy 并携带 token,默认 120 秒租约)→ 用完 bmahs_release;token 由网关代管并遮蔽,不进模型上下文。

常见问题

  • 扫不到设备? 确认设备已上电且同网段、Windows 防火墙放行 UDP 5354 入站;多网卡机器用 BMAHS_MCAST_IF_V4 指定网卡;跨网段/容器用 BMAHS_STATIC_DEVICES=tcp://IP:端口 静态表兜底。

  • 报「正被 xxx 占用」(occupied)? 设备独占中:bmahs_devices 看 holder/until,等租约到期或请占用方 bmahs_release;协议无强夺机制(防止两个模型打架)。

  • HTTP 模式 401? 请求头须带 Authorization: Bearer <--token 设置的值>。

  • stdio 模式没有输出? 正常:stdout 是 MCP 协议通道,日志全走 stderr(BMAHS_LOG_LEVEL=debug 调高)。

环境变量

与 Python 版同名同义:

变量

默认

说明

BMAHS_AGENT_ID

bmahs-mcp-<主机名>-<6位hex>

网关在协议中的智能体 id

BMAHS_STATIC_DEVICES

空

静态设备表,逗号/分号分隔 tcp://host:port

BMAHS_BONJOUR_BROWSE

1

0 关闭 mDNS 浏览通道

BMAHS_AUTO_OCCUPY / BMAHS_AUTO_OCCUPY_TTL / BMAHS_MAX_LEASE

1 / 120 / 3600

自动占用策略与租约上限

BMAHS_CALL_TIMEOUT / BMAHS_QUERY_INTERVAL / BMAHS_EXPIRE_SEC

30 / 300 / 1800

调用超时、query 周期与设备过期时限

BMAHS_TOOL_ALLOW / BMAHS_TOOL_DENY

空

动态工具黑白名单(fnmatch 通配符,deny 优先)

BMAHS_CAPTURE_DIR

<系统临时目录>/bmahs_captures

bmahs_screenshot 帧落盘目录

BMAHS_MCAST_IF_V4

自动枚举

手动指定组播网卡(逗号分隔本机 IPv4)

BMAHS_HTTP_HOST / BMAHS_HTTP_PORT / BMAHS_HTTP_PATH / BMAHS_HTTP_TOKEN

0.0.0.0 / 9530 / /mcp / 无

HTTP 模式默认参数

BMAHS_LOG_LEVEL

info

日志级别(一律走 stderr)

BMAHS_ARG_COERCE

1

参数净化器(防线②):device 传成对象自动解包、字符串数字转声明类型、id/动作名近似矫正;0 关闭

BMAHS_LOOP_GUARD / BMAHS_LOOP_GUARD_MAX

1 / 3

防循环守卫(防线③):同一工具同参连续失败第 2 次升级提示、第 N 次下达停止令

BMAHS_DESCRIBE_OPTIONAL

1

bmahs_describe 的 device 可选(唯一设备自动选中,多台返回选择清单)

BMAHS_DEVICE_TOOLS

0

备用:为每台设备生成零参数 <id>__describe 动态别名

开发与测试

npm test          # vitest 单元/集成测试(假设备,不需要真实硬件)
npm run smoke     # 端到端 17 项契约(假设备 + stdio 网关 + MCP 客户端)
npm run smoke:py  # 跨语言联调(拉起 ../examples/demo_light.py,需要上层 .venv)

测试拓扑:fake-device.ts 是只实现控制层与 UI 流的测试假设备(不绑组播、状态可注入),与 Python 版 tests/fake_device.py 行为对齐。

协议

完整协议文档见 Python 主仓库的 docs/BMAHS1.0.md:UDP 组播一报文一 JSON(≤1400 字节)负责发现,TCP 一行 JSON + \n 负责控制,连上先读 hello;网关在协议中承担「智能体」角色(§4.8)。

License

MIT

Available Tools

7 tools
bmahs_callA

对 BMAHS 设备执行任意其操作清单内(operations)的动作,参数按该动作的 args 传。适合调用尚未生成独立工具的动作,或临时查看新设备。

Inputs: action (required), device (required), args.

bmahs_describeA
Read-only

读取某台 BMAHS 设备的完整操作清单(operations)、安全边界(security)与自然语言自述。

Inputs: device (required).

bmahs_devicesA
Read-only

列出当前发现的全部 BMAHS 设备(id、显示名、自然语言自述、类型、状态、占用方与连接地址)。选设备、查占用状态时先用这个工具。

Inputs: type.

bmahs_occupyA

独占占用一台 BMAHS 设备(返回的 token 由网关保存并自动携带)。租约由网关强制为有限时长:不带 ttl 默认 120 秒(2 分钟),请求值超过上限(默认 3600 秒)会被截断,不支持无限期占用。租约到期设备自动收回占用权;任务结束也可调用 bmahs_release 提前释放。

Inputs: device (required), ttl.

bmahs_refreshA
Read-only

重新扫描 BMAHS 设备:发送组播 query 并刷新各设备的自述(hello)。当设备列表为空、新设备刚上电、或怀疑列表过期时调用。

Inputs: no named parameters.

bmahs_releaseA

释放对某台 BMAHS 设备的占用。任务结束、失败或取消后必须调用,否则其它智能体会一直收到「被占用」。

Inputs: device (required).

bmahs_screenshotA

(实验)对声明了 ui 能力的 BMAHS 设备抓取一帧当前画面:自动 ui.start → 二进制流取一帧 JPEG → ui.stop,返回图片与保存路径。

Inputs: device (required), max_width.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.1/5.0

    Scored across 7 tools

    Disambiguation4/5

    Each tool targets a distinct operation: listing, refreshing, describing, occupying, releasing, generic calling, and screenshotting. The only minor ambiguity is between bmahs_devices and bmahs_refresh (both concern device discovery), but their descriptions clearly separate current listing from force-rescanning.

    Naming Consistency4/5

    All tools share the uniform bmahs_ prefix and snake_case style, with simple verbs (refresh, describe, occupy, release, call). The slight inconsistency is that bmahs_devices uses a noun instead of a verb like list_devices, and bmahs_screenshot is a noun-verb hybrid, but the pattern remains predictable.

    Tool Count5/5

    Seven tools is a well-scoped size for a device gateway. Each tool covers a distinct phase of the device lifecycle: discovery, inspection, access control, and execution, without unnecessary redundancy or bloat.

    Completeness5/5

    The tool surface provides a full workflow: discover devices (devices/refresh), understand capabilities (describe), reserve access (occupy/release), execute actions (call), and capture UI (screenshot). The generic bmahs_call fills gaps for unmodeled actions, making the set effectively complete for the stated gateway purpose.

    Maintenance

    ActivitySlowing
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      C
      maintenance
      Enables AI agents to discover and interact with iOS apps through a local MCP gateway, converting remote Streamable HTTP MCP endpoints into stdio tools. Provides dynamic device discovery, tool schema introspection, and deterministic tool calling for app analysis.
      -
    • A
      license
      A
      quality
      B
      maintenance
      Enables AI clients to discover, occupy, and operate LAN hardware devices that speak the BMAHS protocol by mapping their actions to MCP tools.
      7
      67 PyPI
      MIT