mcpField
A
API Catalog

API Catalog

github.com/tonylofgren開発10946 回インストール6 日前に更新
リポジトリ

API Catalog について

外部 API やサービスを Home Assistant に接続する開発者向けのリファレンススキルです。Node-RED、HA YAML、カスタムインテグレーションの認証方法とコード例を扱います。

主な機能

  1. 01一般的な API 認証方式の解説
  2. 02Node-RED フローのコード例
  3. 03HA YAML の REST 設定例
  4. 04カスタムインテグレーションの手引き
  5. 05認証情報・レート制限・エラーの確認

活用シーン

  1. 01天気やエネルギーの API を Home Assistant に接続
  2. 02Node-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 に接続するためのリファレンススキルです。

概要

このスキルでは、次の 3 つの方法で一般的な 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 キーURL に ?appid={key} を追加OpenWeatherMap
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 完全なインテグレーション: polling-integration テンプレートを使用して ha-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 対応