87 个工具会把小模型淹掉:ha-mcp 用检索加读写删三档代理收窄入口

87 个工具会把小模型淹掉:ha-mcp 用检索加读写删三档代理收窄入口

1周前
duguying
4 阅读
来源:GitHub

让 Claude、ChatGPT 直接改 Home Assistant 的 MCP 服务器:工具目录藏到 BM25 检索后面,读、写、删拆成三条执行通道,权限策略按类别设置,YAML 直改还被降级进了 beta。

相关标签

#GitHub#Trending#HomeAssistant#MCP#智能家居

把 87 个工具的名字、参数和说明一次性写进上下文,会发生什么?不是模型变强,而是它开始乱点。ha-mcp 这一版给出的解法有点反常:把工具目录藏起来,只留一个检索入口。

ha-mcp 是一台让 Claude、ChatGPT 等 AI 助手直接管 Home Assistant 的 MCP 服务器,用 FastMCP 构建,目前挂着 87 个工具。它和 Home Assistant 自带的 MCP Server 不是一回事:内置那套走 Assist 管道,只能读和控制”已经暴露给 Assist”的实体、跑 Assist 理解的意图,属于语音式控制;ha-mcp 的范围是整个实例——任意服务调用、批量设备控制、实时状态;建和改自动化、脚本、场景、仪表盘;按执行轨迹调试自动化、读历史与日志;管理 helper、区域、标签、分组、日历、蓝图;备份、应用(旧称 add-on)、HACS、设备与实体注册表。

安装路径已经收敛

推荐方式是 HA-MCP 集成:从 HACS 装,或者 Home Assistant 2026.11 之后直接在设置里的 Marketplace 搜 HA-MCP。它把完整服务器跑在 HA 进程内,OS、Supervised、Container、Core 四种安装类型全支持,功能一致,要求 HA 2026.8.0 以上。9.0.0(10 月 28 日)起,设置流程会先要一个管理员令牌,再问客户端怎么连。

有一个破坏性变更得注意:v7.3.0 把 ha_config_set_yaml 移进了 beta。换句话说,让 AI 直接改 YAML 配置这件事被主动降级了——这恰好是风险最高的一类操作。

权限拆成三条通道

默认情况下,客户端拿到的是全量目录。对支持延迟加载工具的客户端(claude.ai、Claude Desktop、Claude Code)这没什么成本,工具用到才拉进上下文。但对没有这个能力的模型——Claude Haiku、Gemini、兼容 OpenAI 的本地模型、各种小参数开源模型,以及不看模型一律内联全部 schema 的客户端——全量目录会占掉大量闲置上下文,还会把小模型压垮。

设 ENABLE_TOOL_SEARCH=true 后,目录被 BM25 检索接口取代,只留少量 pinned 工具(ha_search、ha_get_overview、ha_report_issue 等)。ha_search_tools 分两跳:先返回紧凑结果(名字、一行描述、一行参数清单、可执行它的代理),再按名字拿完整定义。单次最多返回 5 条,可调 2 到 10。

真正的设计巧思在三个执行代理:ha_call_read_tool 只能跑带 readOnlyHint 的工具,客户端可以放心自动批准;ha_call_write_tool 负责创建和更新;ha_call_delete_tool 负责删除。这样客户端不必解析工具说明,就能按类别设策略——自动放行读、写要确认、删要二次确认。只读模式下目录里只剩读代理,写调用会拿到只读模式错误,而不是”工具不存在”。

多客户端共用一个服务器时还能按 URL 分目录:/catalog/full 永远给全量、/catalog/search 永远给检索入口、/readonly/catalog/search 是只读加检索。改完任何设置都要让客户端刷新工具列表——客户端缓存着旧目录时,新开的工具根本不会出现,已下线的工具点了才报错。

安全上还做了哪些

Read Only Mode 是一个开关;每个工具可以单独启停;工具安全策略要求逐次用户审批;编辑前自动备份,helper 编辑会把持久化的 options 一起抓下来,恢复前必须先有一份新的安全备份,密钥脱敏不达标就拒绝抓取。配置层面还支持 OIDC 鉴权,把远程访问挡在 Authentik、Keycloak、Auth0 之类的身份提供商后面。

技能层补的是”该怎么建”

MCP 能给 agent 一堆工具,但对”该怎么组织”没有意见,于是常见的后果是到处堆 Jinja2 模板、helper 类型选错、自动化难维护。ha-mcp 把 homeassistant-ai/skills 打包成 MCP resources,用 skill:// URI 暴露;不支持 resources 的客户端可以调 ha_get_skill_guide 读 SKILL.md,这个工具被设成不可禁用,避免技能面静默消失。

一个服务器、87 个工具、三条权限通道,最后落到的还是老问题:给模型的选择越多,越需要有人替它把选项收窄。

仓库地址:https://github.com/homeassistant-ai/ha-mcp

返回列表

更多资讯

想看更多优质内容?

浏览所有资讯