ha-mcp-dev 7.14.2.dev2167__tar.gz → 7.14.2.dev2169__tar.gz

{ha_mcp_dev-7.14.2.dev2167/src/ha_mcp_dev.egg-info → ha_mcp_dev-7.14.2.dev2169}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ha-mcp-dev
-Version: 7.14.2.dev2167
+Version: 7.14.2.dev2169
 Summary: Home Assistant MCP Server - Complete control of Home Assistant through MCP
 Author-email: Julien <github@qc-h.net>
 License: MIT
@@ -357,9 +357,9 @@ Skills can still be installed manually for clients that prefer local skill files
 
 ## 🔍 Tool Discovery for AI Agents
 
-By default, the full tool catalog (~84 tools) is listed to the client through the standard MCP `tools/list` response. Clients with deferred / on-demand tool loading (Claude Sonnet, Claude Opus) handle that fine — tools are pulled into context only when needed, so idle context cost is near-zero.
+By default, the full tool catalog (~84 tools) is listed to the client through the standard MCP `tools/list` response. Clients with deferred / on-demand tool loading (claude.ai, Claude Desktop, Claude Code) handle that fine — tools are pulled into context only when needed, so idle context cost is near-zero.
 
-For models *without* deferred tool support — Claude Haiku, Gemini, ChatGPT OpenAI-compatible local models, smaller open-weights models — listing the full tool catalog up front adds a lot of idle context and can overwhelm smaller models. To address that, the server ships with a **search-based discovery mode** built on top of FastMCP's BM25 search transform.
+For setups *without* deferred tool support — models like Claude Haiku, Gemini, OpenAI-compatible local models and smaller open-weights models, or clients that inline all tool schemas regardless of model (e.g. GitHub Copilot CLI) — listing the full tool catalog up front adds a lot of idle context and can overwhelm smaller models. To address that, the server ships with a **search-based discovery mode** built on top of FastMCP's BM25 search transform.
 
 ### Smaller or local LLMs (Ollama, etc.)
 
@@ -389,11 +389,11 @@ The proxy split lets MCP clients apply different permission policies per categor
 
 ### When to enable
 
-- **Claude Haiku, OpenAI-compatible local models, Gemini, ChatGPT or any model without native deferred tool support** — large idle-context savings.
+- **Claude Haiku, OpenAI-compatible local models, Gemini, or any model without native deferred tool support** — large idle-context savings. The same applies to clients that inline all tool schemas regardless of model (e.g. GitHub Copilot CLI, even when running Claude Sonnet/Opus).
 - MCP clients that cap total tool count (some cap at 100) — surfaces a minimal set (~10 tools) instead of 84.
 - **Cost-sensitive deployments** — fewer idle tokens per turn.
 
-Leave it off when using Claude Sonnet/Opus or any client with deferred tool loading; the full catalog has no idle cost there and direct calls skip the search step. If you choose to use our toolsearch then you should disable the native Claude Opus/Sonnet toolsearch, which is called deferred tools in the settings.
+Leave it off in clients with deferred tool loading (claude.ai, Claude Desktop, Claude Code); the full catalog has no idle cost there, direct calls skip the search step, and the client's built-in tool search is the better choice — there is no benefit to running ha-mcp's on top of it. Whether tools are deferred depends on the client and model combination: the same model can behave differently per client — GitHub Copilot CLI running Claude Sonnet/Opus inlines the full catalog and still benefits from tool search here. Some Codex models and ChatGPT include deferred tools too — check your client/model directly to confirm its features so you don't leave this enabled unnecessarily.
 
 > 🔄 **Refresh your client's tool list after changing this (or any) setting.** Toggling `ENABLE_TOOL_SEARCH` (or changing pinned/disabled tools, Read Only Mode, etc.) changes the tools the server exposes, but your AI client keeps serving its **cached** tool list until it re-fetches. Restarting the add-on or Home Assistant does **not** refresh the client — reconnect or refresh the MCP server in your client (e.g. re-add/refresh the connector in ChatGPT, or close and reopen Claude Desktop). If you skip this, newly enabled tools won't appear in the client at all, and tools the server no longer exposes still show as available but return `Unknown tool` when called. ChatGPT sometimes keeps serving the stale list even after the connector is removed and re-added under the same name — if tools are still missing after re-adding, delete the connector and create a new one with a **different name**.
 

{ha_mcp_dev-7.14.2.dev2167 → ha_mcp_dev-7.14.2.dev2169}/README.md

@@ -324,9 +324,9 @@ Skills can still be installed manually for clients that prefer local skill files
 
 ## 🔍 Tool Discovery for AI Agents
 
-By default, the full tool catalog (~84 tools) is listed to the client through the standard MCP `tools/list` response. Clients with deferred / on-demand tool loading (Claude Sonnet, Claude Opus) handle that fine — tools are pulled into context only when needed, so idle context cost is near-zero.
+By default, the full tool catalog (~84 tools) is listed to the client through the standard MCP `tools/list` response. Clients with deferred / on-demand tool loading (claude.ai, Claude Desktop, Claude Code) handle that fine — tools are pulled into context only when needed, so idle context cost is near-zero.
 
-For models *without* deferred tool support — Claude Haiku, Gemini, ChatGPT OpenAI-compatible local models, smaller open-weights models — listing the full tool catalog up front adds a lot of idle context and can overwhelm smaller models. To address that, the server ships with a **search-based discovery mode** built on top of FastMCP's BM25 search transform.
+For setups *without* deferred tool support — models like Claude Haiku, Gemini, OpenAI-compatible local models and smaller open-weights models, or clients that inline all tool schemas regardless of model (e.g. GitHub Copilot CLI) — listing the full tool catalog up front adds a lot of idle context and can overwhelm smaller models. To address that, the server ships with a **search-based discovery mode** built on top of FastMCP's BM25 search transform.
 
 ### Smaller or local LLMs (Ollama, etc.)
 
@@ -356,11 +356,11 @@ The proxy split lets MCP clients apply different permission policies per categor
 
 ### When to enable
 
-- **Claude Haiku, OpenAI-compatible local models, Gemini, ChatGPT or any model without native deferred tool support** — large idle-context savings.
+- **Claude Haiku, OpenAI-compatible local models, Gemini, or any model without native deferred tool support** — large idle-context savings. The same applies to clients that inline all tool schemas regardless of model (e.g. GitHub Copilot CLI, even when running Claude Sonnet/Opus).
 - MCP clients that cap total tool count (some cap at 100) — surfaces a minimal set (~10 tools) instead of 84.
 - **Cost-sensitive deployments** — fewer idle tokens per turn.
 
-Leave it off when using Claude Sonnet/Opus or any client with deferred tool loading; the full catalog has no idle cost there and direct calls skip the search step. If you choose to use our toolsearch then you should disable the native Claude Opus/Sonnet toolsearch, which is called deferred tools in the settings.
+Leave it off in clients with deferred tool loading (claude.ai, Claude Desktop, Claude Code); the full catalog has no idle cost there, direct calls skip the search step, and the client's built-in tool search is the better choice — there is no benefit to running ha-mcp's on top of it. Whether tools are deferred depends on the client and model combination: the same model can behave differently per client — GitHub Copilot CLI running Claude Sonnet/Opus inlines the full catalog and still benefits from tool search here. Some Codex models and ChatGPT include deferred tools too — check your client/model directly to confirm its features so you don't leave this enabled unnecessarily.
 
 > 🔄 **Refresh your client's tool list after changing this (or any) setting.** Toggling `ENABLE_TOOL_SEARCH` (or changing pinned/disabled tools, Read Only Mode, etc.) changes the tools the server exposes, but your AI client keeps serving its **cached** tool list until it re-fetches. Restarting the add-on or Home Assistant does **not** refresh the client — reconnect or refresh the MCP server in your client (e.g. re-add/refresh the connector in ChatGPT, or close and reopen Claude Desktop). If you skip this, newly enabled tools won't appear in the client at all, and tools the server no longer exposes still show as available but return `Unknown tool` when called. ChatGPT sometimes keeps serving the stale list even after the connector is removed and re-added under the same name — if tools are still missing after re-adding, delete the connector and create a new one with a **different name**.
 

{ha_mcp_dev-7.14.2.dev2167 → ha_mcp_dev-7.14.2.dev2169}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "ha-mcp-dev"
-version = "7.14.2.dev2167"
+version = "7.14.2.dev2169"
 description = "Home Assistant MCP Server - Complete control of Home Assistant through MCP"
 readme = "README.md"
 # Upper bound widened to <3.15 so the package installs on Home Assistant's

{ha_mcp_dev-7.14.2.dev2167 → ha_mcp_dev-7.14.2.dev2169}/src/ha_mcp/settings_ui/locales/de.json

@@ -110,7 +110,7 @@
     "visibility.assist.help": "Verstecke Entitäten, die nicht für den Assist-Sprachassistenten (Konversation) von Home Assistant freigegeben sind – entsprechend der Liste Einstellungen > Sprachassistenten > Freigeben. Fügt zwei WebSocket-Lesevorgänge pro Suche hinzu, während es aktiviert ist.",
     "visibility.assist.only_exposed": "Nur für Assist freigegebene Entitäten anzeigen",
     "features.enable_tool_search.label": "Tool-Suche aktivieren",
-    "features.enable_tool_search.help": "Ersetzt den vollständigen Tool-Katalog durch suchbasierte Entdeckung. Reduziert den Leerlauf-Kontext von ~46K auf ~5K Tokens. ⚠️ Aktiviere dies NICHT, wenn du Claude im Sonnet- oder Opus-Modus verwendest – diese Modelle haben ihre eigene integrierte Tool-Suche / aufgeschobene Tools, die mit unserer kollidiert. Um die Tool-Suche von ha-mcp mit Claude zu verwenden, deaktiviere zuerst Claudes integrierte Tool-Suche; lasse dies andernfalls ausgeschaltet. Verwende dies nur mit LLMs, denen native aufgeschobene Tools fehlen (z. B. Claude Haiku, lokale OpenAI-kompatible Modelle) oder mit kleineren Kontextfenstern. Tools werden über ha_search_tools gefunden und über kategorisierte Proxys (read/write/delete) ausgeführt. Erfordert Neustart, um wirksam zu werden.",
+    "features.enable_tool_search.help": "Ersetzt den vollständigen Tool-Katalog durch suchbasierte Entdeckung. Reduziert den Leerlauf-Kontext um rund 90 % auf etwa 5K Tokens. ⚠️ Aktiviere dies NICHT in Clients mit eigener integrierter Tool-Suche / aufgeschobenen Tools (claude.ai, Claude Desktop, Claude Code) – die beiden Suchebenen kollidieren, und die integrierte Tool-Suche des Clients ist dort die bessere Wahl; lasse dies ausgeschaltet. Ob Tools aufgeschoben werden, hängt von der Kombination aus Client und Modell ab: Verwende dies, wenn dein Setup den vollständigen Katalog von Anfang an lädt – Modelle ohne native aufgeschobene Tools (z. B. Gemini, lokale OpenAI-kompatible Modelle, Claude Haiku), Clients, die alle Tool-Schemata unabhängig vom Modell direkt einbetten (z. B. GitHub Copilot CLI), oder kleinere Kontextfenster. Auch einige Codex-Modelle und ChatGPT haben aufgeschobene Tools – prüfe direkt bei deinem Client/Modell, welche Features er hat, damit du dies nicht unnötig aktiviert lässt. Tools werden über ha_search_tools gefunden und über kategorisierte Proxys (read/write/delete) ausgeführt. Erfordert Neustart, um wirksam zu werden.",
     "features.tool_search_max_results.label": "Max. Tool-Suchergebnisse",
     "features.tool_search_max_results.help": "Maximale Anzahl von Tools, die von ha_search_tools zurückgegeben werden, wenn die Tool-Suche aktiviert ist. Niedrigere Werte (2-3) sparen Kontext-Tokens, können aber relevante Tools übersehen. Bereich: 2-10. Erfordert Neustart.",
     "features.enable_tool_security_policies.label": "Tool-Sicherheitsrichtlinien aktivieren (erweitert)",

{ha_mcp_dev-7.14.2.dev2167 → ha_mcp_dev-7.14.2.dev2169}/src/ha_mcp/settings_ui/locales/en.json

@@ -110,7 +110,7 @@
     "visibility.assist.help": "Hide entities not exposed to Home Assistant's Assist (“conversation”) voice assistant, mirroring the Settings > Voice assistants > Expose list. Adds two websocket reads per search while enabled.",
     "visibility.assist.only_exposed": "Only show entities exposed to Assist",
     "features.enable_tool_search.label": "Enable tool search",
-    "features.enable_tool_search.help": "Replace the full tool catalog with search-based discovery. Reduces idle context from ~46K to ~5K tokens. ⚠️ Do NOT enable this if you use Claude in Sonnet or Opus modes — those models have their own built-in tool search / deferred tools, which conflicts with ours. To use ha-mcp's tool search with Claude, disable Claude's built-in tool search first; otherwise leave this off. Use this only with LLMs that lack native deferred tools (e.g. Claude Haiku, local OpenAI-compatible models) or with smaller context windows. Tools are found via ha_search_tools and executed via categorized proxies (read/write/delete). Requires restart to take effect.",
+    "features.enable_tool_search.help": "Replace the full tool catalog with search-based discovery. Reduces idle context by roughly 90%, to about 5K tokens. ⚠️ Do NOT enable this in clients with their own built-in tool search / deferred tools (claude.ai, Claude Desktop, Claude Code) — the two search layers conflict, and the client's built-in tool search is the better choice there; leave this off. Whether tools are deferred depends on your client and model combination: use this when your setup loads the full catalog up front — models without native deferred tools (e.g. Gemini, OpenAI-compatible local models, Claude Haiku), clients that inline all tool schemas regardless of model (e.g. GitHub Copilot CLI), or smaller context windows. Some Codex models and ChatGPT include deferred tools too — check your client/model directly to confirm its features so you don't leave this enabled unnecessarily. Tools are found via ha_search_tools and executed via categorized proxies (read/write/delete). Requires restart to take effect.",
     "features.tool_search_max_results.label": "Tool search max results",
     "features.tool_search_max_results.help": "Maximum number of tools returned by ha_search_tools when tool search is enabled. Lower values (2-3) save context tokens but may miss relevant tools. Range: 2-10. Requires restart.",
     "features.enable_tool_security_policies.label": "Enable Tool Security Policies (advanced)",

{ha_mcp_dev-7.14.2.dev2167 → ha_mcp_dev-7.14.2.dev2169}/src/ha_mcp/settings_ui/locales/es.json

@@ -110,7 +110,7 @@
     "visibility.assist.help": "Oculta las entidades no expuestas al asistente de voz Assist («conversation») de Home Assistant, replicando la lista de Ajustes > Asistentes de voz > Exponer. Añade dos lecturas por websocket en cada búsqueda mientras está activado.",
     "visibility.assist.only_exposed": "Mostrar solo las entidades expuestas a Assist",
     "features.enable_tool_search.label": "Activar la búsqueda de herramientas",
-    "features.enable_tool_search.help": "Sustituye el catálogo completo de herramientas por un descubrimiento basado en búsqueda. Reduce el contexto en reposo de unos 46K a unos 5K tokens. ⚠️ NO actives esto si usas Claude en modo Sonnet u Opus: esos modelos tienen su propia búsqueda de herramientas / herramientas diferidas integrada, que entra en conflicto con la nuestra. Para usar la búsqueda de herramientas de ha-mcp con Claude, desactiva primero la búsqueda integrada de Claude; si no, deja esto desactivado. Úsalo solo con LLM que carezcan de herramientas diferidas nativas (p. ej. Claude Haiku, modelos locales compatibles con OpenAI) o con ventanas de contexto más pequeñas. Las herramientas se localizan mediante ha_search_tools y se ejecutan a través de proxies por categoría (lectura/escritura/borrado). Requiere reiniciar para que surta efecto.",
+    "features.enable_tool_search.help": "Sustituye el catálogo completo de herramientas por un descubrimiento basado en búsqueda. Reduce el contexto en reposo en torno a un 90 %, hasta unos 5K tokens. ⚠️ NO actives esto en clientes con su propia búsqueda de herramientas / herramientas diferidas integrada (claude.ai, Claude Desktop, Claude Code): las dos capas de búsqueda entran en conflicto y la búsqueda integrada del cliente es allí la mejor opción; deja esto desactivado. Que las herramientas se difieran depende de la combinación de cliente y modelo: usa esto cuando tu configuración carga el catálogo completo de entrada — modelos sin herramientas diferidas nativas (p. ej. Gemini, modelos locales compatibles con OpenAI, Claude Haiku), clientes que insertan todos los esquemas de herramientas sea cual sea el modelo (p. ej. GitHub Copilot CLI) o ventanas de contexto más pequeñas. Algunos modelos Codex y ChatGPT también incluyen herramientas diferidas: comprueba directamente con tu cliente/modelo qué características tiene para no dejar esto activado innecesariamente. Las herramientas se localizan mediante ha_search_tools y se ejecutan a través de proxies por categoría (lectura/escritura/borrado). Requiere reiniciar para que surta efecto.",
     "features.tool_search_max_results.label": "Máximo de resultados de la búsqueda de herramientas",
     "features.tool_search_max_results.help": "Número máximo de herramientas que devuelve ha_search_tools cuando la búsqueda de herramientas está activada. Los valores bajos (2-3) ahorran tokens de contexto pero pueden dejar fuera herramientas relevantes. Rango: 2-10. Requiere reiniciar.",
     "features.enable_tool_security_policies.label": "Activar las políticas de seguridad de herramientas (avanzado)",

{ha_mcp_dev-7.14.2.dev2167 → ha_mcp_dev-7.14.2.dev2169}/src/ha_mcp/settings_ui/locales/fr.json

@@ -110,7 +110,7 @@
     "visibility.assist.help": "Masque les entités non exposées à l'assistant vocal Assist (« conversation ») de Home Assistant, en miroir de la liste Paramètres > Assistants vocaux > Exposer. Ajoute deux lectures websocket par recherche lorsqu'il est activé.",
     "visibility.assist.only_exposed": "Afficher uniquement les entités exposées à Assist",
     "features.enable_tool_search.label": "Activer la recherche d'outils",
-    "features.enable_tool_search.help": "Remplace le catalogue complet d'outils par une découverte basée sur la recherche. Réduit le contexte inactif d'environ 46K à 5K tokens. ⚠️ N'active PAS ceci si tu utilises Claude en modes Sonnet ou Opus — ces modèles ont leur propre recherche d'outils intégrée / outils différés, qui entre en conflit avec la nôtre. Pour utiliser la recherche d'outils de ha-mcp avec Claude, désactive d'abord la recherche d'outils intégrée de Claude ; sinon, laisse ceci désactivé. Utilise ceci uniquement avec des LLM qui n'ont pas d'outils différés natifs (p. ex. Claude Haiku, modèles locaux compatibles OpenAI) ou avec des fenêtres de contexte plus petites. Les outils sont trouvés via ha_search_tools et exécutés via des proxys catégorisés (lecture/écriture/suppression). Nécessite un redémarrage pour prendre effet.",
+    "features.enable_tool_search.help": "Remplace le catalogue complet d'outils par une découverte basée sur la recherche. Réduit le contexte inactif d'environ 90 %, à près de 5K tokens. ⚠️ N'active PAS ceci dans les clients qui ont leur propre recherche d'outils intégrée / outils différés (claude.ai, Claude Desktop, Claude Code) — les deux couches de recherche entrent en conflit, et la recherche d'outils intégrée du client y est le meilleur choix ; laisse ceci désactivé. Le report des outils dépend de la combinaison client/modèle : utilise ceci lorsque ta configuration charge le catalogue complet d'emblée — modèles sans outils différés natifs (p. ex. Gemini, modèles locaux compatibles OpenAI, Claude Haiku), clients qui intègrent tous les schémas d'outils quel que soit le modèle (p. ex. GitHub Copilot CLI), ou fenêtres de contexte plus petites. Certains modèles Codex et ChatGPT incluent aussi des outils différés — vérifie directement auprès de ton client/modèle quelles fonctionnalités il possède pour ne pas laisser ceci activé inutilement. Les outils sont trouvés via ha_search_tools et exécutés via des proxys catégorisés (lecture/écriture/suppression). Nécessite un redémarrage pour prendre effet.",
     "features.tool_search_max_results.label": "Résultats max. de la recherche d'outils",
     "features.tool_search_max_results.help": "Nombre maximum d'outils renvoyés par ha_search_tools lorsque la recherche d'outils est activée. Des valeurs plus basses (2-3) économisent des tokens de contexte mais peuvent manquer des outils pertinents. Plage : 2-10. Nécessite un redémarrage.",
     "features.enable_tool_security_policies.label": "Activer les politiques de sécurité des outils (avancé)",

{ha_mcp_dev-7.14.2.dev2167 → ha_mcp_dev-7.14.2.dev2169}/src/ha_mcp/settings_ui/locales/ru.json

@@ -110,7 +110,7 @@
     "visibility.assist.help": "Скрывает сущности, не предоставленные голосовому помощнику Assist («conversation»), в соответствии со списком «Настройки → Голосовые помощники → Предоставить доступ». При каждом поиске выполняются два дополнительных WebSocket-запроса.",
     "visibility.assist.only_exposed": "Показывать только сущности, доступные Assist",
     "features.enable_tool_search.label": "Включить поиск инструментов",
-    "features.enable_tool_search.help": "Заменяет полный каталог инструментов поиском по запросу. Уменьшает неиспользуемый контекст примерно с 46 тыс. до 5 тыс. токенов. ⚠️ НЕ включайте этот параметр, если используете Claude в режимах Sonnet или Opus: у этих моделей есть собственный встроенный поиск инструментов и отложенные инструменты, которые конфликтуют с нашими. Чтобы использовать поиск инструментов ha-mcp с Claude, сначала отключите встроенный поиск инструментов Claude; в противном случае оставьте этот параметр выключенным. Используйте его только с LLM без собственных отложенных инструментов (например, Claude Haiku или локальными OpenAI-совместимыми моделями) либо с небольшими контекстными окнами. Инструменты находятся через ha_search_tools и выполняются через распределённые по категориям прокси (чтение, запись, удаление). Для применения требуется перезапуск.",
+    "features.enable_tool_search.help": "Заменяет полный каталог инструментов поиском по запросу. Уменьшает неиспользуемый контекст примерно на 90 % — до порядка 5 тыс. токенов. ⚠️ НЕ включайте этот параметр в клиентах с собственным встроенным поиском инструментов и отложенными инструментами (claude.ai, Claude Desktop, Claude Code): два слоя поиска конфликтуют, а встроенный поиск инструментов клиента там — лучший выбор; оставьте этот параметр выключенным. Будут ли инструменты отложенными, зависит от сочетания клиента и модели: используйте этот параметр, когда ваша конфигурация загружает полный каталог сразу — модели без собственных отложенных инструментов (например, Gemini, локальные OpenAI-совместимые модели, Claude Haiku), клиенты, которые встраивают все схемы инструментов независимо от модели (например, GitHub Copilot CLI), или небольшие контекстные окна. Некоторые модели Codex и ChatGPT тоже включают отложенные инструменты — уточните непосредственно у своего клиента/модели, какие функции он поддерживает, чтобы не оставлять этот параметр включённым без необходимости. Инструменты находятся через ha_search_tools и выполняются через распределённые по категориям прокси (чтение, запись, удаление). Для применения требуется перезапуск.",
     "features.tool_search_max_results.label": "Максимальное количество результатов поиска инструментов",
     "features.tool_search_max_results.help": "Максимальное количество инструментов, возвращаемых ha_search_tools при включённом поиске инструментов. Меньшие значения (2–3) экономят токены контекста, но могут пропустить подходящие инструменты. Диапазон: 2–10. Требуется перезапуск.",
     "features.enable_tool_security_policies.label": "Включить политики безопасности инструментов (расширенная настройка)",

{ha_mcp_dev-7.14.2.dev2167 → ha_mcp_dev-7.14.2.dev2169}/src/ha_mcp/settings_ui/locales/zh-Hans.json

@@ -110,7 +110,7 @@
     "visibility.assist.help": "隐藏未暴露给 Home Assistant 的 Assist（“对话”）语音助手的实体，对应设置 > 语音助手 > 暴露列表。启用时每次搜索额外增加两次 websocket 读取。",
     "visibility.assist.only_exposed": "仅显示暴露给 Assist 的实体",
     "features.enable_tool_search.label": "启用工具搜索",
-    "features.enable_tool_search.help": "用基于搜索的发现取代完整工具目录。将空闲上下文从约 46K 降至约 5K token。⚠️ 如果你在 Sonnet 或 Opus 模式下使用 Claude，请勿启用此功能——这些模型自带内置工具搜索/延迟工具，会与我们的功能冲突。要在 Claude 中使用 ha-mcp 的工具搜索，请先禁用 Claude 的内置工具搜索；否则请保持关闭。仅在与缺乏原生延迟工具的 LLM 一起使用（例如 Claude Haiku、本地 OpenAI 兼容模型）或上下文窗口较小时才使用此功能。工具通过 ha_search_tools 发现，并通过分类代理（读/写/删）执行。需要重启才能生效。",
+    "features.enable_tool_search.help": "用基于搜索的发现取代完整工具目录。将空闲上下文减少约 90%，降至约 5K token。⚠️ 如果客户端自带内置工具搜索/延迟工具（claude.ai、Claude Desktop、Claude Code），请勿启用此功能——两层搜索会相互冲突，且在这些客户端中其内置工具搜索是更好的选择；请保持关闭。工具是否延迟取决于客户端与模型的组合：当你的配置会一次性加载完整目录时才使用此功能——例如没有原生延迟工具的模型（如 Gemini、本地 OpenAI 兼容模型、Claude Haiku）、无论模型如何都会内联全部工具架构的客户端（如 GitHub Copilot CLI），或上下文窗口较小时。部分 Codex 模型和 ChatGPT 也带有延迟工具——请直接向你的客户端/模型确认其具备哪些功能，以免不必要地保持启用此功能。工具通过 ha_search_tools 发现，并通过分类代理（读/写/删）执行。需要重启才能生效。",
     "features.tool_search_max_results.label": "工具搜索最大结果数",
     "features.tool_search_max_results.help": "启用工具搜索时 ha_search_tools 返回的最大工具数。较小的值（2–3）可节省上下文 token，但可能遗漏相关工具。范围：2–10。需要重启。",
     "features.enable_tool_security_policies.label": "启用工具安全策略（高级）",

{ha_mcp_dev-7.14.2.dev2167 → ha_mcp_dev-7.14.2.dev2169}/src/ha_mcp/settings_ui/settings.js

@@ -1845,7 +1845,7 @@ document.getElementById('stopSidecarBtn').addEventListener('click', stopSidecar)
 const FEATURE_META = {
   enable_tool_search: {
     label: "Enable tool search",
-    help: "Replace the full tool catalog with search-based discovery. Reduces idle context from ~46K to ~5K tokens. ⚠️ Do NOT enable this if you use Claude in Sonnet or Opus modes. Those models have their own built-in tool search / deferred tools, which conflicts with ours. To use ha-mcp's tool search with Claude, disable Claude's built-in tool search first; otherwise leave this off. Use this only with LLMs that lack native deferred tools (e.g. Claude Haiku, local OpenAI-compatible models) or with smaller context windows. Tools are found via ha_search_tools and executed via categorized proxies (read/write/delete). Requires restart to take effect.",
+    help: "Replace the full tool catalog with search-based discovery. Reduces idle context by roughly 90%, to about 5K tokens. ⚠️ Do NOT enable this in clients with their own built-in tool search / deferred tools (claude.ai, Claude Desktop, Claude Code) — the two search layers conflict, and the client's built-in tool search is the better choice there; leave this off. Whether tools are deferred depends on your client and model combination: use this when your setup loads the full catalog up front — models without native deferred tools (e.g. Gemini, OpenAI-compatible local models, Claude Haiku), clients that inline all tool schemas regardless of model (e.g. GitHub Copilot CLI), or smaller context windows. Some Codex models and ChatGPT include deferred tools too — check your client/model directly to confirm its features so you don't leave this enabled unnecessarily. Tools are found via ha_search_tools and executed via categorized proxies (read/write/delete). Requires restart to take effect.",
   },
   tool_search_max_results: {
     label: "Tool search max results",

{ha_mcp_dev-7.14.2.dev2167 → ha_mcp_dev-7.14.2.dev2169/src/ha_mcp_dev.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ha-mcp-dev
-Version: 7.14.2.dev2167
+Version: 7.14.2.dev2169
 Summary: Home Assistant MCP Server - Complete control of Home Assistant through MCP
 Author-email: Julien <github@qc-h.net>
 License: MIT
@@ -357,9 +357,9 @@ Skills can still be installed manually for clients that prefer local skill files
 
 ## 🔍 Tool Discovery for AI Agents
 
-By default, the full tool catalog (~84 tools) is listed to the client through the standard MCP `tools/list` response. Clients with deferred / on-demand tool loading (Claude Sonnet, Claude Opus) handle that fine — tools are pulled into context only when needed, so idle context cost is near-zero.
+By default, the full tool catalog (~84 tools) is listed to the client through the standard MCP `tools/list` response. Clients with deferred / on-demand tool loading (claude.ai, Claude Desktop, Claude Code) handle that fine — tools are pulled into context only when needed, so idle context cost is near-zero.
 
-For models *without* deferred tool support — Claude Haiku, Gemini, ChatGPT OpenAI-compatible local models, smaller open-weights models — listing the full tool catalog up front adds a lot of idle context and can overwhelm smaller models. To address that, the server ships with a **search-based discovery mode** built on top of FastMCP's BM25 search transform.
+For setups *without* deferred tool support — models like Claude Haiku, Gemini, OpenAI-compatible local models and smaller open-weights models, or clients that inline all tool schemas regardless of model (e.g. GitHub Copilot CLI) — listing the full tool catalog up front adds a lot of idle context and can overwhelm smaller models. To address that, the server ships with a **search-based discovery mode** built on top of FastMCP's BM25 search transform.
 
 ### Smaller or local LLMs (Ollama, etc.)
 
@@ -389,11 +389,11 @@ The proxy split lets MCP clients apply different permission policies per categor
 
 ### When to enable
 
-- **Claude Haiku, OpenAI-compatible local models, Gemini, ChatGPT or any model without native deferred tool support** — large idle-context savings.
+- **Claude Haiku, OpenAI-compatible local models, Gemini, or any model without native deferred tool support** — large idle-context savings. The same applies to clients that inline all tool schemas regardless of model (e.g. GitHub Copilot CLI, even when running Claude Sonnet/Opus).
 - MCP clients that cap total tool count (some cap at 100) — surfaces a minimal set (~10 tools) instead of 84.
 - **Cost-sensitive deployments** — fewer idle tokens per turn.
 
-Leave it off when using Claude Sonnet/Opus or any client with deferred tool loading; the full catalog has no idle cost there and direct calls skip the search step. If you choose to use our toolsearch then you should disable the native Claude Opus/Sonnet toolsearch, which is called deferred tools in the settings.
+Leave it off in clients with deferred tool loading (claude.ai, Claude Desktop, Claude Code); the full catalog has no idle cost there, direct calls skip the search step, and the client's built-in tool search is the better choice — there is no benefit to running ha-mcp's on top of it. Whether tools are deferred depends on the client and model combination: the same model can behave differently per client — GitHub Copilot CLI running Claude Sonnet/Opus inlines the full catalog and still benefits from tool search here. Some Codex models and ChatGPT include deferred tools too — check your client/model directly to confirm its features so you don't leave this enabled unnecessarily.
 
 > 🔄 **Refresh your client's tool list after changing this (or any) setting.** Toggling `ENABLE_TOOL_SEARCH` (or changing pinned/disabled tools, Read Only Mode, etc.) changes the tools the server exposes, but your AI client keeps serving its **cached** tool list until it re-fetches. Restarting the add-on or Home Assistant does **not** refresh the client — reconnect or refresh the MCP server in your client (e.g. re-add/refresh the connector in ChatGPT, or close and reopen Claude Desktop). If you skip this, newly enabled tools won't appear in the client at all, and tools the server no longer exposes still show as available but return `Unknown tool` when called. ChatGPT sometimes keeps serving the stale list even after the connector is removed and re-added under the same name — if tools are still missing after re-adding, delete the connector and create a new one with a **different name**.