mcpField
A
API Catalog

API Catalog

github.com/tonylofgren开发10946 次安装6 天前更新
代码仓库

关于 API Catalog

面向 Home Assistant 开发者的 API 参考技能，提供常见服务的认证说明与代码示例，涵盖 Node-RED、HA YAML 和自定义集成。

主要功能

  1. 01常见 API 认证模式参考
  2. 02Node-RED 流程代码示例
  3. 03HA YAML REST 配置示例
  4. 04自定义集成开发指引
  5. 05凭据安全与限流检查

适用场景

  1. 01将天气或能源 API 接入 Home Assistant
  2. 02用 Node-RED 获取外部服务数据
  3. 03配置带凭据的 REST 传感器

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/tonylofgren/aurora-smart-home --skill api-catalog

安装后在 Claude Code 中输入/api-catalog确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

references/
energy-apis.md
global-apis.md
smarthome-apis.md
transport-apis.md
weather-apis.md

详细介绍

Home Assistant API 目录

用于将外部 API 和服务连接到 Home Assistant 的参考技能。

概述

此技能介绍了身份验证模式，以及将常用 API 连接到 Home Assistant 的可运行代码示例。支持三种方法：

  • Node-RED - HTTP 请求节点流程（最快上手）
  • HA YAML - rest 传感器和 rest_command（适合简单轮询）
  • 自定义集成 - 可发布到 HACS 的完整 Python 组件（使用 ha-integration 技能）

铁律

CREDENTIALS IN SECRETS - NEVER HARDCODED IN FLOWS OR YAML

API 密钥应存储在 Node-RED 凭据、ESPHome secrets.yaml 或 HA secrets.yaml 中。 切勿将真实令牌粘贴到聊天中、导出的流程中，或提交到 git 的 YAML 文件中。

如何使用此技能

  1. 用户提及某个 API 或服务的名称
  2. 阅读相关参考文件，了解身份验证设置和端点
  3. 根据用户选择的方法（Node-RED / YAML / 集成）生成可运行的代码
  4. 提供凭据设置说明

参考文件

类别文件涵盖的 API
能源和电力references/energy-apis.mdTibber、Nordpool、Energi Data Service
天气references/weather-apis.mdSMHI、OpenWeatherMap、yr.no、Tomorrow.io
交通references/transport-apis.mdSL、Trafikverket、Resrobot、Entur (NO)
智能家居云服务references/smarthome-apis.mdShelly Cloud、Tuya IoT、Philips Hue、IKEA Dirigera
全球 / 其他references/global-apis.mdOpenAI、Spotify、Google Calendar、Telegram、GitHub

身份验证模式一览

模式工作方式示例
请求头中的 API 密钥Authorization: Bearer {key} 或 X-API-Key: {key}Tibber、OpenAI
URL 中的 API 密钥将 ?appid={key} 附加到 URLOpenWeatherMap
OAuth2先获取访问令牌，然后定期刷新Spotify、Google
本地令牌在设备上按一次按钮进行身份验证Philips Hue
无需身份验证公共 API，无需凭据SMHI、yr.no、Nordpool
基本身份验证Base64 编码的用户名 + 密码某些本地设备

输出方法

对于每个 API，根据用户的需求生成相应方法的代码：

Node-RED： http request 节点 + 用于解析的 function 节点 + 用于推送到 HA 的 api-call-service HA YAML： configuration.yaml 中的 rest 传感器平台或 rest_command 完整集成： 使用 ha-integration 技能和 polling-integration 模板

常见模式

Node-RED：请求头中的 API 密钥
{
  "type": "http request",
  "method": "GET",
  "url": "https://api.example.com/data",
  "headers": {"Authorization": "Bearer {{env.API_KEY}}"},
  "ret": "obj"
}
Node-RED：GraphQL（Tibber 风格）
{
  "type": "http request",
  "method": "POST",
  "url": "https://api.tibber.com/v1-beta/gql",
  "headers": {
    "Authorization": "Bearer {{env.TIBBER_TOKEN}}",
    "Content-Type": "application/json"
  },
  "payload": "{\"query\": \"{ viewer { homes { currentSubscription { priceInfo { current { total } } } } } }\"}",
  "ret": "obj"
}
HA YAML：REST 传感器
rest:
  - scan_interval: 300
    resource: https://api.example.com/current
    headers:
      Authorization: !secret example_api_key
    sensor:
      - name: "Example Value"
        value_template: "{{ value_json.data.value }}"
        unit_of_measurement: "°C"

输出前检查清单

  • 凭据使用 !secret（YAML）、Node-RED 凭据或环境变量，绝不硬编码
  • 遵守速率限制（相应设置 scan_interval 或流程计时器）
  • 包含错误处理（Node-RED catch 节点或 YAML 超时）
  • 对于 OAuth2：说明刷新令牌流程
  • 注明 API 端点及其返回的数据

集成

搭配使用：

  • node-red 技能 - 用于实现流程 JSON
  • ha-yaml 技能 - 用于使用获取的数据配置 YAML 传感器和自动化
  • ha-integration 技能 - 用于构建可发布到 HACS 的完整 Python 集成

评论

支持 Markdown