Homebridge

@mp-consulting/homebridge-ai-kit

适用于 Homebridge 的 AI 工具包，集于一个软件包中：

• MCP 服务：让 AI 助手（Claude Desktop、Claude Code、Cursor）通过 stdio 或 Streamable HTTP 控制配件、管理插件、编辑配置和读取日志。
• 助手：提供商适配器（Claude、OpenAI、Gemini 及任何兼容 OpenAI 的服务）、与 MCP 工具连接的 Agent 循环，以及开箱即用的功能（日志诊断、配置副驾驶、设备错误说明、更新风险简报、整理工具、每日摘要）。Homebridge Glass UI 和 MP Consulting 插件会使用这些功能。
• Homebridge 插件（HomebridgeAiKit 平台）：提供设置页面，可选择提供商和模型、测试连接、通过 HTTP 提供 MCP 服务并生成客户端配置。

无需 MCP 的 AI 构建模块也以独立软件包 @mp-consulting/homebridge-ai-core 发布——请参阅软件包。

原名为 @mp-consulting/homebridge-mcp-server。 旧的 homebridge-mcp-server 命令仍可使用，因此现有 MCP 客户端配置无需更改。请参阅从 homebridge-mcp-server 迁移。

目录

• 软件包
• 功能
• 提供商
• Homebridge 插件 · MCP 令牌
• MCP 服务
• 库 API
• 安全性
• 从 homebridge-mcp-server 迁移
• 开发

软件包

此仓库是一个 npm 工作区，会发布两个软件包，版本均为 2.0.0：

软件包	用途	运行时依赖
@mp-consulting/homebridge-ai-core	Homebridge 插件。 插件 UI 助手路由（来自 ./plugin 的 registerAiRoutes）、提供商、脱敏、提示词、配置和助手功能（除 runAgent 外的所有内容）。	仅 ajv
@mp-consulting/homebridge-ai-kit（本软件包）	Homebridge Glass UI 和 MCP。 包含 ai-core 中的所有内容（重新导出），以及 MCP 服务、runAgent、HomebridgeAiKit Homebridge 插件和 mcpClientSnippets。	ai-core、@modelcontextprotocol/sdk、socket.io-client、zod、undici、@homebridge/plugin-ui-utils

插件应依赖 ai-core，这样安装插件时就不会引入 MCP SDK、socket.io 或 zod。ai-kit 保持向后兼容：其 . 和 ./plugin 导出会以相同名称重新导出 ai-core 的所有内容，因此从 ai-kit 导入的代码仍可正常运行。

功能

MCP 工具（43 个）：配件（列表、获取、控制并检查值、使用 dryRun 批量控制、需要确认后才能操作的门锁 / 车库门 / 警报器、房间布局、传感器历史记录）、场景（列表、运行、保存）、服务（状态、重启、配对、缓存的配件）、子桥接（列表、健康状况、重启、停止、启动）、配置（读取时隐藏机密、完整写入、部分 patch_config、dryRun 差异、备份与还原）、实例备份、测试通知、插件（列表、搜索、版本、架构、更新日志、安装、更新、卸载）、系统信息和日志（最近的行、按正则表达式筛选搜索）。

可订阅的 MCP 资源：homebridge://accessories、homebridge://logs/recent、homebridge://status。变更通过 Homebridge UI 的 socket.io 命名空间推送；无法使用 socket 时，则通过轮询获取。

MCP 资源模板（在 resources/list 中列出，并支持补全）：homebridge://accessory/{uniqueId}（单个配件及其全部特征）、homebridge://plugin/{name}（单个已安装插件及其子桥接；带作用域的名称需进行 URL 编码）、homebridge://child-bridge/{id}（按用户名获取单个子桥接及其在 Glass UI 上的健康状况）。

MCP 提示词：diagnose-logs、plan-upgrade、audit-config、troubleshoot-device（device、symptom?）、nightly-health-check（hours?）、scene-builder（description、room?）。

助手功能（库）：diagnoseLogs、generatePluginConfig、explainDeviceError、assessPluginUpdate、suggestOrganization、dailyDigest、ask，以及用于处理任何需要调用工具的任务的 runAgent。所有输入在发送给提供方之前都会经过脱敏，并裁剪至适合其上下文窗口的长度；JSON 输出会根据架构进行检查，并自动尝试修复一次；系统会跟踪令牌用量和 Claude 费用。

提供方

所有提供方都使用原生 fetch（不使用 SDK）。每个提供方都会声明其支持的功能；不支持工具调用的功能会回退到仅使用提示词的回答。

provider	默认模型	API 密钥	工具	流式传输	上下文
anthropic	claude-sonnet-5-5	必需	是	是	1M（Haiku 为 200K）
openai	gpt-6.1-sol	必需	是	是	128K（设置 contextTokens 可使用更多）
gemini	gemini-3.8-flash	必需	是	是	1M
openai-compatible	llama3.1	可选	是	是	8K（设置 contextTokens）

• Claude 模型：claude-sonnet-5-5（默认）、claude-haiku-4-5-20251001（费用最低）、claude-opus-5-5（能力最强）。
• OpenAI 模型：gpt-6.1-sol（默认）、gpt-6-luna（费用最低）、gpt-6-astra（能力最强）。请求使用 Responses API，并设置 store: false（OpenAI 不会保留任何内容）；较新的模型只能通过该 API 调用工具。设置 "openaiApi": "chat" 可改用 Chat Completions，例如用于仅支持该接口的代理。
• openai-compatible 可与 Ollama（http://127.0.0.1:11434/v1，默认）、LM Studio（http://127.0.0.1:1234/v1）、vLLM 等类似服务配合使用。请将 contextTokens 设置为模型的上下文窗口大小，以便正确裁剪输入。
• 计划支持设备端 Apple Foundation Models 提供方。

Homebridge 插件

像安装其他插件一样安装它（Homebridge 1.8+ 或 2.x）：

npm install -g @mp-consulting/homebridge-ai-kit

然后在 Homebridge UI 中打开其设置。设置页面可编辑 HomebridgeAiKit 平台配置块、使用表单中的值测试连接，并显示可直接粘贴到 Claude Desktop、Claude Code 和 Cursor 中的配置。

{
  "platform": "HomebridgeAiKit",
  "name": "AI Kit",
  "enabled": true,
  "provider": "anthropic",            // anthropic | openai | gemini | openai-compatible
  "model": "claude-sonnet-5-5",       // optional, defaults per provider
  "apiKey": "sk-ant-…",               // secret, redacted wherever config is shown to a model
  "baseUrl": "http://127.0.0.1:11434/v1", // openai-compatible only (or a proxy)
  "contextTokens": 32768,             // optional override, mainly for local models
  "maxOutputTokens": 2048,
  "effort": "medium",                 // Claude and OpenAI: low | medium | high | xhigh | max (unset = model default)
  "openaiApi": "responses",           // openai / openai-compatible: responses | chat (default responses for OpenAI, chat for local servers)
  "maxRetries": 2,                    // retries on 408/429/5xx/529 and network errors (backoff, honours retry-after); 0 = off
  "mcp": {
    "http": {
      "enabled": false,
      "host": "127.0.0.1",
      "port": 8582,
      "token": "…",                   // bearer token MCP clients must send
      "homebridgeUrl": "http://127.0.0.1:8581",
      "homebridgeToken": "hbg_…",     // Glass UI API token the tools act with
      "homebridgeTokenId": "…",       // written by Glass UI so it can revoke that token; leave as is
      "homebridgeCertFingerprint": "AB:CD:…", // https UI with a self-signed certificate: its SHA-256 fingerprint
      "homebridgeCertPath": "/path/to/certificate.pem", // or a PEM with the UI's certificate or its CA
      "readOnly": false,              // true caps every client token at read-only
      "clients": [                    // more client tokens, each with a scope: read | control | admin
        { "name": "Dashboard", "token": "…", "scope": "read" }
      ],
      "allowedOrigins": ["https://my-dashboard.local"], // browser pages allowed besides localhost / this server's IP
      "auditLog": true,               // log every write tool call (JSONL)
      "auditLogPath": "/var/lib/homebridge/homebridge-ai-kit-audit.jsonl" // default: Homebridge storage path
    }
  }
}

启用 mcp.http.enabled 后，插件会在 Homebridge 运行期间通过 http://<host>:<port>/mcp 提供 MCP 服务。它需要客户端令牌（mcp.http.token、HOMEBRIDGE_AI_MCP_TOKEN，或 mcp.http.clients 中至少一个作用域令牌）以及 Homebridge 凭据：homebridgeToken 中的 Glass UI API 令牌，或 HOMEBRIDGE_* 环境变量。只读 API 令牌会为客户端提供只读访问权限。

MCP 令牌

MCP 服务使用两种不同的令牌：

令牌	用途	存储位置
客户端令牌	Claude、Cursor 或其他 MCP 客户端访问 HTTP MCP 服务时必须发送的令牌（Authorization: Bearer …）。可拥有完整访问权限（admin），也可在启用 mcp.http.readOnly 时仅拥有只读权限	mcp.http.token（或 CLI 的 HOMEBRIDGE_AI_MCP_TOKEN）
范围受限的客户端令牌	可选的额外客户端令牌，权限较少，例如供仪表板使用的只读令牌	mcp.http.clients（或 CLI 的 HOMEBRIDGE_AI_MCP_TOKENS）
Homebridge API 令牌	MCP 服务发送给 Homebridge UI 以运行其工具的令牌。其范围决定客户端可执行的操作：read 提供只读工具，admin 提供所有工具	mcp.http.homebridgeToken（或 CLI 的 HOMEBRIDGE_TOKEN）

设置或生成令牌的位置：

• Homebridge Glass UI 2.0.0-beta.6 或更高版本： 设置 → 助手 → MCP 服务 会生成客户端令牌、一键创建 Homebridge API 令牌（只读或管理员权限；替换或移除令牌时会将其撤销），并显示客户端配置。每个密钥只显示一次；此后页面只会提示是否已设置。
• 此插件的设置页面： 生成 会创建客户端令牌。将 Glass UI 中 用户 → API 令牌 创建的 Homebridge API 令牌粘贴到此处。
• CLI： 设置 HOMEBRIDGE_AI_MCP_TOKEN 和 HOMEBRIDGE_TOKEN（参见 MCP 服务），例如 HOMEBRIDGE_AI_MCP_TOKEN=$(openssl rand -base64 24)。

客户端令牌范围（每个范围均包含其前面范围的权限）：

范围	工具
read	所有只读工具
control	以及设备控制：set_accessory、set_security_accessory（锁仍需用户确认）、set_accessories、run_scene
admin	以及所有其他工具：配置写入和还原、备份、save_scene、测试通知、插件安装和更新、重启、缓存配件、子桥接器

主客户端令牌的范围为 admin（与之前相同）；启用 readOnly 时则为 read；readOnly 也会限制范围受限的令牌。会话归属于创建它的令牌。客户端令牌决定客户端可以看到哪些工具；Homebridge API 令牌仍会限制服务自身可执行的操作，因此 read API 令牌会使所有操作保持只读。

每次写入工具调用都会追加到审计日志（默认路径为 <Homebridge storage>/homebridge-ai-kit-audit.jsonl；可通过 mcp.http.auditLog / auditLogPath 配置，CLI 则使用 HOMEBRIDGE_AI_AUDIT_LOG）：每行一个 JSON 对象，包含 ts、tool、args（已隐藏密钥）、ok、error、session、client、principal（令牌名称：主令牌为 default，runAgent 为 agent）和 scope；notConfirmed: true 表示用户拒绝了具有破坏性的调用（MCP elicitation，或 runAgent 的 confirm），因此该调用并未执行。试运行也会记录，args 中会包含 dryRun: true。runAgent 使用相同的 audit 选项。日志达到 5 MB 时会轮转，并保留三个旧文件。

Glass UI 还会存储 homebridgeTokenId，即其创建的 API 令牌 ID，以便在替换或移除令牌时撤销该令牌。设置页面保存时会保留此字段（以及其他未显示的字段）。

通过 HTTPS 访问使用自签名证书的 Homebridge UI

Node 不接受自签名证书，因此除非告知 MCP 服务信任哪个证书，否则它无法访问通过这种方式提供服务的 Homebridge UI。验证绝不会关闭：此设置仅适用于服务向 Homebridge UI 发出的请求。

设置	CLI	信任的对象
mcp.http.homebridgeCertFingerprint	HOMEBRIDGE_CERT_FINGERPRINT	仅信任具有此 SHA-256 指纹的证书（固定证书）。任何其他证书，即使有效，也会被拒绝，并显示包含两个指纹的错误。
mcp.http.homebridgeCertPath	HOMEBRIDGE_CERT_PATH	除公共 CA 外，还信任此 PEM 文件中的证书：UI 自己的自签名证书（接受任意主机名，例如 127.0.0.1），或为其签发证书的 CA（执行常规主机名检查）。

在 Homebridge 所在的机器上，使用 openssl x509 -noout -fingerprint -sha256 -in <certificate.pem> 获取指纹（Glass UI 的自签名证书路径为 <storage>/ssl-certs/certificate.pem）；冒号和大小写不影响结果。同时设置两项时，证书链必须通过 PEM 验证，且证书必须与指纹匹配。证书续期后，请更新指纹。两项设置都仅适用于 https URL。资源订阅随后会通过轮询跟踪变化，因为 socket.io 连接仍使用 Node 的默认验证。

对 mcp.http 的更改会在重启 Homebridge 后生效，因为插件会在 Homebridge 加载时启动 HTTP 服务。请像保护密码一样保护这两个令牌：任何持有客户端令牌的人都可以使用 Homebridge API 令牌所允许的所有工具。

为其他插件提供助手路由

插件的自定义 UI 服务只需一次调用即可提供助手。请从 @mp-consulting/homebridge-ai-core/plugin 导入路由（ai-kit 的 ./plugin 会重新导出这些路由，但插件应依赖更精简的 ai-core）。浏览器端接口为 @mp-consulting/homebridge-ui-kit 中的 MpKit.ai：

// homebridge-ui/server.js
import { HomebridgePluginUiServer } from '@homebridge/plugin-ui-utils';
import { registerAiRoutes } from '@mp-consulting/homebridge-ai-core/plugin';

class UiServer extends HomebridgePluginUiServer {
  constructor() {
    super();
    registerAiRoutes(this, { pluginName: '@mp-consulting/homebridge-ewelink' });
    this.ready();
  }
}
new UiServer();

路由	请求体	返回结果
/ai/status	无	{ enabled, provider, model, capabilities }（绝不包含密钥）
/ai/explain	{ error, context?, device?, requestId? }	{ text, usage }
/ai/ask	{ prompt, context?, requestId? }	{ text, usage }
/ai/config	{ schema, request, current?, requestId? }	{ config, explanation, usage }

指定 requestId 后，服务端会先流式发送 ai:chunk { requestId, delta } 事件，随后发送 ai:done { requestId } 或 ai:error { requestId, message }。这些路由会在每次请求时读取 config.json 中的 HomebridgeAiKit 块，因此设置更改会立即生效。

MCP 服务

安装

方式	适用对象
从最新版本获取 homebridge-ai-kit-x.y.z.mcpb	Claude 应用：双击即可将其作为扩展安装，然后填写 Homebridge UI URL 和令牌（或用户名和密码）。无需 Node 或配置文件。
brew install mp-consulting/tap/homebridge-ai-kit	在 macOS / Linux 上安装 homebridge-ai-kit 命令，并由 Homebrew 保持更新
npx -y @mp-consulting/homebridge-ai-kit mcp	适用于任何 MCP 客户端，无需安装（参见下方配置）

该服务也已列入 MCP 注册表，名称为 io.github.mp-consulting/homebridge-ai-kit。

环境

变量	说明
HOMEBRIDGE_URL	Homebridge UI 的 URL，例如 http://192.168.1.100:8581（必需）
HOMEBRIDGE_TOKEN	Homebridge UI API 令牌（Glass UI hbg_…）。可替代用户名和密码
HOMEBRIDGE_USERNAME / HOMEBRIDGE_PASSWORD	未设置令牌时使用的 UI 登录信息
HOMEBRIDGE_READ_ONLY	true 会移除所有会更改内容的工具
HOMEBRIDGE_ELICITATION	false 会阻止服务要求用户确认具有破坏性的工具（MCP 询问）。默认开启；不支持询问的客户端不受影响
HOMEBRIDGE_ALLOW_SECRETS	设为 true 后，get_config 在收到请求（includeSecrets）时会返回真实密码和令牌。默认关闭；只读模式下会忽略此设置
HOMEBRIDGE_TIMEOUT_MS	请求超时时间（默认 30000）
HOMEBRIDGE_CERT_FINGERPRINT	要信任（固定）的 https Homebridge UI 自签名证书的 SHA-256 指纹。参见自签名证书
HOMEBRIDGE_CERT_PATH	要信任的 https Homebridge UI 证书或其 CA 的 PEM 文件
HOMEBRIDGE_AI_MCP_TOKEN	--http 所需的持有者令牌（完整访问权限，或通过 HOMEBRIDGE_READ_ONLY 设置为只读）
HOMEBRIDGE_AI_MCP_TOKENS	--http：带作用域的其他令牌，以逗号分隔的 scope:token 对，例如 read:abc,control:def
HOMEBRIDGE_AI_AUDIT_LOG	写入工具调用的 JSONL 审计日志路径（CLI 默认关闭）
HOMEBRIDGE_AI_MCP_ALLOWED_ORIGINS	--http：除本地回环地址和服务器自身 IP 外允许的浏览器来源，以逗号分隔（* 表示任何来源）
HOMEBRIDGE_AI_MCP_MAX_SESSIONS	--http：最大并发会话数（默认 32；会关闭最近最少使用的空闲会话以腾出空间）
HOMEBRIDGE_AI_MCP_SESSION_IDLE_MINUTES	--http：会话无请求达到此时长后关闭（默认 30）

stdio（Claude Desktop、Claude Code、Cursor）

{
  "mcpServers": {
    "homebridge": {
      "command": "npx",
      "args": ["-y", "@mp-consulting/homebridge-ai-kit", "mcp"],
      "env": {
        "HOMEBRIDGE_URL": "http://192.168.1.100:8581",
        "HOMEBRIDGE_TOKEN": "hbg_…"
      }
    }
  }
}

claude mcp add homebridge -e HOMEBRIDGE_URL=http://192.168.1.100:8581 -e HOMEBRIDGE_TOKEN=hbg_… -- npx -y @mp-consulting/homebridge-ai-kit mcp

Streamable HTTP

HOMEBRIDGE_AI_MCP_TOKEN=$(openssl rand -base64 24) \
HOMEBRIDGE_URL=http://127.0.0.1:8581 HOMEBRIDGE_TOKEN=hbg_… \
homebridge-ai-kit mcp --http --port 8582 --host 127.0.0.1

端点为 http://127.0.0.1:8582/mcp。每个请求都需要 Authorization: Bearer <HOMEBRIDGE_AI_MCP_TOKEN>。默认绑定到 127.0.0.1；只有在受信任的网络中才使用 --host 0.0.0.0，最好通过 HTTPS 访问。

• 来源检查。 按照 MCP 规范，带有 Origin 标头的请求（即来自网页的请求）会被拒绝并返回 403，除非其来源是本地回环地址（http://localhost:…、127.0.0.1、[::1]）、服务器自身的 IP 地址，或列于 HOMEBRIDGE_AI_MCP_ALLOWED_ORIGINS（插件：mcp.http.allowedOrigins）中。这可以阻止恶意网页通过 DNS 重绑定访问服务。桌面客户端不会发送 Origin，因此不受影响。
• 会话会在空闲 30 分钟后关闭，最多保留 32 个会话。具有开放流的会话不会被视为空闲。所有会话共用一个 Homebridge 更改订阅源，用于 resources/subscribe。
• 错误令牌。 来自同一地址的 5 次错误令牌尝试后，必须等待一段时间才能再次尝试（返回 429 和 Retry-After，等待时间逐步增加，最长为 5 分钟）；输入正确令牌后，计数会重置。

claude mcp add --transport http homebridge http://127.0.0.1:8582/mcp --header "Authorization: Bearer <token>"

工具

分组	工具
配件	list_accessories（按 room、type、name、manufacturer、excludeManufacturer 筛选）、get_accessory、set_accessory、set_security_accessory（锁、车库门、警报器；操作具有破坏性，因此需确认）、set_accessories（按 ID 或筛选条件设置多个目标，支持 dryRun；绝不操作锁、门或警报器）、get_accessory_layout、get_accessory_history
服务	get_homebridge_status、get_server_status、restart_homebridge、get_pairing_info、get_cached_accessories、remove_cached_accessory、reset_cached_accessories
子桥接	list_child_bridges、get_child_bridge_health*、restart_child_bridge、stop_child_bridge、start_child_bridge
场景*	list_scenes、run_scene（按 ID 或名称运行；拒绝执行会操作锁、车库门或警报器的场景）、save_scene（根据所选配件的当前状态保存场景；绝不记录锁、门或警报器）
通知*	send_test_notification
配置	get_config、update_config 和 patch_config（两者均支持 dryRun，以显示已脱敏的差异；每次写入都会注明用于撤销该操作的备份）、list_config_backups、restore_config
备份	create_backup、list_backups（位于 UI 备份目录中的完整实例备份）
插件	list_plugins、search_plugins、lookup_plugin、get_plugin_versions、get_plugin_config_schema、get_plugin_changelog、install_plugin、update_plugin、uninstall_plugin、get_plugin_job
系统	get_system_info（CPU 负载和温度、内存、网络吞吐量、运行时间）
日志	get_recent_logs、search_logs（按 since/until、最低 level、plugin 前缀筛选；显示匹配项周围的 context 行）

* 需要 Homebridge Glass UI；使用其他 Homebridge UI 时，这些工具会返回相应错误提示。

• 列出／获取工具（list_accessories、get_accessory、list_plugins、list_child_bridges、get_child_bridge_health、get_homebridge_status、get_server_status、search_logs、list_scenes）也会返回与其 outputSchema 匹配的 structuredContent。
• set_accessory 会先根据特征检查值（格式、最小值／最大值、步长、有效值、写入权限），将 "50" 转换为 50，或将 1 转换为 true，并说明问题所在，而不是发送无效值。
• set_accessory 会拒绝操作门锁、车库门和安全系统（LockTargetState、TargetDoorState、SecuritySystemTargetState，或 LockMechanism、GarageDoorOpener、SecuritySystem 服务的任何特征）；这些操作须通过 set_security_accessory 执行。该工具标注了 destructiveHint: true，因此 MCP 客户端和 runAgent 会在解锁、开门或解除警戒前征求用户确认。灯和开关仍可直接切换，无需提示。
• get_accessory_history 会返回某个配件在过去 hours 小时内记录的传感器值（温度、湿度、光照强度、电池电量、空气质量、电量、能耗）。hours 默认为 24，最多为 8760；也可以选择单个特征 type。每个系列都会提供 count、min／max（数值及时间）、按时间加权的 avg、last，以及平均降采样至 maxPoints 的 points（默认为 48，范围为 2–500）；时间精确到分钟，使用 UTC。此工具需要 Homebridge Glass UI（GET /api/accessories/:uniqueId/history）；Homebridge 在不安全模式下运行时会记录这些值。
• patch_config 会修改一个平台或配件区块（通过 platform／accessory 和 name 查找）；对象会进行合并，null 会移除键，而 __REDACTED__ 会保留当前密钥。
• install_plugin、update_plugin 和 uninstall_plugin 会在 Homebridge UI 上启动任务，并等待最多两分钟；对于耗时更长的任务，可使用 get_plugin_job 跟踪。它们需要 Homebridge Glass UI（POST /api/plugins/install|update|uninstall、GET /api/plugins/jobs/:id）。
• 日志工具需要通过 hb-service 管理的 Homebridge 安装。

库 API

import {
  createProvider, readAiConfig, runAgent, diagnoseLogs, generatePluginConfig, UsageTracker,
} from '@mp-consulting/homebridge-ai-kit';
import { HomebridgeClient } from '@mp-consulting/homebridge-ai-kit/mcp';

const config = await readAiConfig();            // HomebridgeAiKit block of ~/.homebridge/config.json
const provider = createProvider(config);

// One-shot feature, streamed
const { text } = await diagnoseLogs({ provider, logs, onChunk: (d) => process.stdout.write(d) });

// Agent with the MCP tools, acting as the current user
const client = new HomebridgeClient({ url: 'http://127.0.0.1:8581', getToken: () => mintShortLivedToken(user) });
const result = await runAgent({
  provider,
  client,
  messages: [{ role: 'user', content: 'Turn off every light downstairs' }],
  confirm: async (call) => askUser(`Allow ${call.name}?`), // destructive tools are refused without it
  onEvent: (e) => console.log(e),
});

导出项	用途
createProvider(config) → AiProvider	使用 ChatRequest { system?, messages, tools?, maxOutputTokens?, signal? } 提供 chat(req) 和 stream(req)
runAgent(opts) → AgentResult	循环调用模型 ↔ MCP 工具（内存传输），maxSteps 默认值为 8，支持 readOnly，以及用于破坏性工具的 confirm
diagnoseLogs、generatePluginConfig、explainDeviceError、assessPluginUpdate、suggestOrganization、dailyDigest、ask	现成的功能；均接受 onChunk、signal、systemContext
generateJson({ provider, schema, prompt })	经过架构校验的 JSON（ajv），并在修复失败后重试一次
trimToContext、estimateTokens	将输入控制在上下文窗口范围内（日志保留尾部内容）
UsageTracker、costOf	令牌和费用统计（Claude 价格；未知模型的费用为 null）
PROMPTS	提示词模板，与 MCP 提示词共享
readAiConfig、resolveAiConfig	读取 HomebridgeAiKit 配置块并补齐默认值
redactSecrets、restoreSecrets、redactText、redactPairing	防止凭据和配对码进入模型上下文
SlidingWindowRateLimiter、TtlCache、withConfirmTimeout、ConfirmationBroker、readLogTail、stripAnsi	服务端辅助工具：按用户限流、带过期时间的缓存、带超时的确认、日志尾部内容

此表中除 runAgent 以外的所有内容均来自 @mp-consulting/homebridge-ai-core，并在此处原样重新导出。

./mcp 导出 createServer、HomebridgeClient、runStdioServer、runHttpServer、createLiveSource、shareLiveSource、createAuditLog、令牌 SCOPES，以及 TLS 固定相关辅助工具 createTrustedFetch、normalizeFingerprint、pemFingerprints；./plugin 导出 registerAiRoutes 和 testAiConnection（来自 ai-core 的 ./plugin）、mcpClientSnippets 和 AiKitPlatform。

安全性

• 机密信息不会进入模型上下文。 get_config、patch_config 和 Assistant 功能会将密码、令牌、API 密钥（包括 AI Kit apiKey 和 MCP 令牌）以及桥接 PIN 替换为 __REDACTED__。写入时会将占位符还原为实际值。只有在服务器通过 HOMEBRIDGE_ALLOW_SECRETS=true（对于 createServer / runHttpServer，使用 allowSecrets）选择启用后，get_config 才会提供 includeSecrets，并且只读模式下绝不会提供。发送给提供方的自由文本（日志、错误）中，类似凭据的值也会被屏蔽。
• 破坏性操作需要征得同意。 每个工具都会声明 MCP readOnlyHint / destructiveHint；除非 confirm 回调允许，否则 runAgent 会拒绝破坏性工具。如果 MCP 客户端支持征询确认，服务器会自行请求用户确认每次破坏性工具调用（显示的参数会屏蔽机密信息；试运行会跳过确认；若用户拒绝或确认失败，则不会运行该工具）；设置 HOMEBRIDGE_ELICITATION=false 可关闭此功能。解锁门、打开车库门或解除警报只能通过破坏性工具 set_security_accessory 执行，因此也需要确认；set_accessories 和场景会拒绝这些目标。配置写入可通过 dryRun 预览，并可使用 restore_config 回滚。HOMEBRIDGE_READ_ONLY=true 会彻底移除写入工具。
• 工具输出会被视为数据。 日志（工具和 homebridge://logs/recent 资源）、更新日志以及其他来自 Homebridge 的自由文本都会以 <untrusted-data source="…"> 标签包裹后返回（runAgent 会包裹发送给模型的每个工具结果），数据内部的任何标签也会被转义（JSON 结果和 structuredContent 会保持为纯数据，以便解析）；基础系统提示词会告知模型，绝不能遵循工具输出中的指令，并且只有在用户提出要求时才能进行更改。结合对破坏性工具的确认机制，日志中即使出现“解锁前门”这样的内容，也无法打开门。
• HTTP 受到严格限制。 HTTP 传输要求使用 bearer 令牌，会以恒定时间进行令牌比较，默认绑定到 127.0.0.1。它会检查 Origin、使闲置会话过期，并降低重复错误令牌尝试的频率。
• 遵循最小权限原则并保留审计记录。 额外的客户端令牌可限制为 read 或 control 权限，每次写入工具调用都会记录经过机密信息屏蔽的参数（参见 MCP 令牌）。
• update_config 会拒绝不完整的配置，正则表达式日志搜索会在工作线程中运行，并在 5 秒后终止。
• 如果 HOMEBRIDGE_URL 使用纯 http 向非本地主机发送凭据，服务器会发出警告。
• 始终启用 TLS 验证。 只有通过 HOMEBRIDGE_CERT_FINGERPRINT / HOMEBRIDGE_CERT_PATH（或相应的 mcp.http 设置）才能信任自签名的 Homebridge UI 证书，而且仅对发往 Homebridge UI 的请求生效；不匹配的证书会被拒绝。

从 homebridge-mcp-server 迁移

npm uninstall -g @mp-consulting/homebridge-mcp-server
npm install -g @mp-consulting/homebridge-ai-kit

该软件包会同时安装 homebridge-ai-kit 和 homebridge-mcp-server 别名，且环境变量保持不变，因此现有配置仍可正常使用。新配置应使用 homebridge-ai-kit mcp。现在，MCP 服务报告的名称为 homebridge-ai-kit，库的使用者可从 @mp-consulting/homebridge-ai-kit/mcp 导入 createServer 和 HomebridgeClient。

开发

git clone https://github.com/mp-consulting/homebridge-ai-kit.git
cd homebridge-ai-kit
npm install
npm run build          # builds packages/ai-core, copies the ui-kit assets into homebridge-ui/public/lib, then tsc

此仓库是一个 npm 工作区：根目录是 ai-kit，packages/ai-core 是 ai-core。根目录脚本会运行两个包（先运行 ai-core）；npm run <script> -w packages/ai-core 则只会为 ai-core 运行一个脚本。ai-kit 的测试会将 @mp-consulting/homebridge-ai-core 解析到其源代码，而 typecheck 和 build 使用 ai-core 的 dist，因此会先构建它。

npm run dev            # MCP server on stdio with tsx
npm test               # Run tests
npm run test:coverage  # Tests with coverage thresholds (as CI does)
npm run lint           # ESLint
npm run typecheck      # Type-check src and test (both packages)

发布。 发布工作流会先发布 @mp-consulting/homebridge-ai-core（如果该版本已发布到 npm，则跳过），然后发布依赖于它的 @mp-consulting/homebridge-ai-kit。两者都使用 npm 可信发布（OIDC）：首次发布前，请在 npmjs.com 上为新的 @mp-consulting/homebridge-ai-core 包名也配置可信发布者（仓库 mp-consulting/homebridge-ai-kit，工作流 publish.yml）；如果 npm 只允许为现有包添加可信发布者，请手动从 packages/ai-core 发布一次 ai-core 2.0.0。必须先发布 ai-core 的首个版本，才能从 npm 安装 ai-kit 2.0.0。

发布到 npm 后，同一工作流会使用 scripts/make-mcpb.sh 构建 Claude 扩展（清单模板为 mcpb/manifest.json；其工具列表来自 scripts/mcpb-tools.mjs），在设置了 DEVELOPER_ID_CERTIFICATE 和 DEVELOPER_ID_CERTIFICATE_PASSWORD 密钥时使用 mcpb sign 对其签名，将其附加到发布中，并将 server.json 发布到 MCP 注册表（GitHub OIDC）。mp-consulting/homebrew-tap 中的 Homebrew formula 会自动获取每个 npm 版本（每 6 小时一次）。

许可证

MIT