solarnetwork-mcp

SolarNetwork の太陽光テレメトリを AI エージェントが呼び出せるツールに変える MCP サーバーです。

認証情報は不要です。 SolarNetwork の公開エンドポイントに対して動作し、約 52 の稼働中の太陽光サイトが実際の発電量、日射量、気象データを公開しています。そのうちいくつかは毎分更新され、6 年分の履歴があります。

できること

太陽光テレメトリの読み取り

• 認証情報なしで公開ノードを発見し、タイムゾーンや稼働状況でフィルタリング

• サイト上のすべてのストリームを分類: サイトメーター、インバーター、日射量、気象、ML 異常

• 5 分から 1 年までの任意のロールアップで時系列をクエリ

• 平均電力ではなくメーターの読み値から実際の累積エネルギーを取得

• ストリームがまだ稼働しているかを、値ではなくタイムスタンプで確認

機器の故障を日付付きで発見

• インバーターの停止を検出し、正確な開始日と終了日を特定

• 発電はしているが電力を報告していない機器と、完全に停止している機器を区別

• 兄弟機が報告を続けているのに、ある機器だけが沈黙しているのを検出

• メーターのカウンターリセットをフラグ付け。これは、それをまたぐすべてのエネルギー合計を静かに破壊します

• 存在したことのないハードウェアのレジストリエントリを発見

• 故障ごとの損失エネルギーを、各機器の容量に基づいて兄弟機の出力からスケーリングして推定

誤報を出さない

• 検出はピア相対方式なので、雲量は故障として記録されない

• 日射計が存在する場合は、日射量を物理的な気象コントロールとして使用

• ウィンドウ開始時にすでに進行中の故障は、下限としてラベル付けされ、発明された開始日とはされない

• 評価できないサイトは「評価されていない」と報告され、「健全」とは決して報告されない

人が行動できるレポートを作成

• 優先順位付けされた作業指示書。平易な言葉での原因、証拠、番号付き手順、ツール、承認基準

• チェックボックスとメモ欄付きの印刷可能な PDF フィールドパック

• チケットに貼り付けるための Markdown、または後処理用の JSON

• 全体がプレーン ASCII なので、PDF やチケットシステムで文字化けしない

できないこと

これに依存する前に知っておくべきこと:

• インバーターが 2 台未満のサイトは評価できません。 ピア比較にはピアが必要です。ツールはクリーンな結果を報告するのではなく、その旨を伝えます。

• 定格銘板はありません。 公開ノードはそれらを公開しないため、損失数値はピアスケーリングされた推定値であり、保証計算ではありません。

• 故障検出は日次バケットで実行されます。 6 時間沈黙した機器は見えません。

• ストリーム分類はパス規約に依存します。 ストリームに Main や SMAInverter1 という名前を付けるサイトは、未分類のまま返されます。

実際に何をするのか

これがない場合、「このサイトで何か問題がありますか?」に答えるには、ノード ID、/datum/list エンドポイント、aggregation=Day が存在すること、watts と wattHours が異なる質問であること、そして JSON を読むことを知っている必要があります。

これがあれば、次のように尋ねるだけです:

「ノード 1000 で何か問題はありますか? 出力が低下している場合、天候によるものか機器によるものか教えてください。」

するとエージェントはサイトのストリームを発見し、日付範囲を選択し、集計を実行し、各インバーターを兄弟機と比較し、英語で回答します。1 文の入力で、診断結果が出力されます。

サーバーは、言語モデルが苦手な部分 (リクエスト署名、ページネーション、単位のセマンティクス、9 つのストリームのうちどれが気象センサーかを知ること) を担当します。エージェントは、得意な部分 (何を尋ねるかを決定し、回答を解釈すること) を担当します。

60 秒で動作を確認

npm install && npm run build && npm run smoke

これは、実際の MCP プロトコルを介してライブデータに対してすべてのツールを駆動します。エージェントも API キーも設定も不要です。ノード 1000 の結果が出力されれば、準備完了です。

エージェントに渡す

以下のブロック全体を Claude Code、Cursor、または MCP 対応のエージェントにコピーしてください。サーバーをインストールし、自己配線し、インストールが機能することを証明し、ライブの公開太陽光サイトに対してすべての機能のガイド付きデモを実行します。

Set up and demo the solarnetwork MCP server for me.

1. INSTALL
   git clone https://github.com/gopisrikrishna/solarnetwork-mcp.git
   cd solarnetwork-mcp
   npm install
   npm run build

2. VERIFY THE INSTALL
   Run: npm run verify
   This runs 28 assertions against live public solar data. No credentials needed.
   Tell me how many passed. If any fail, show me which and stop.

3. CONNECT IT
   Register the server with yourself over stdio:
     command: node
     args:    ./dist/index.js   (run from the solarnetwork-mcp directory)
   The repo ships a .mcp.json that already does this. Restart/reconnect if your
   client needs it, then confirm you can see 10 tools and list their names.

4. DEMO IT
   Work through these against real public nodes and show me what you find.
   Explain your reasoning at each step, do not just dump JSON.

   a) DISCOVERY
      Which public nodes are live in US timezones? Then: what does node 1000
      measure, and how far back does its data go?

   b) ENERGY
      How much did node 1000 generate in July 2026? Use the right tool for a
      billing-shaped question and tell me why you chose it.

   c) FAULT DETECTION  <- the interesting one
      Run an asset review on node 1000 for 2026-01-01 to 2026-09-01.
      Tell me what broke, exactly when it started and ended, and what it cost.
      There is a real 79-day inverter outage in there, and a second fault where
      a device reports 0 watts while still generating. Explain the difference
      between those two failure modes and why it matters.

   d) NOT BEING FOOLED
      Run an asset review on node 949 for July 2026. It will find nothing.
      Explain why "no faults found" does NOT mean the site is healthy here.

   e) DATA INTEGRITY
      Run an asset review on node 781 for 2026-01-01 to 2026-09-01.
      Its site meter counter reset mid-year. Show me how the tool handles it and
      what would have gone wrong without that handling.

   f) CROSS-CHECK
      Node 392 publishes the platform's own ML anomaly streams. Compare what
      get_anomalies says against what the asset review found. Do they agree?

   g) REPORT
      Generate a PDF service report for node 1000 over the same window, written
      for an on-site technician. Save it and tell me the path, how many pages,
      and summarise the priority 1 jobs.

5. WRAP UP
   Tell me in plain language: what is wrong with node 1000, how much energy has
   been lost, and what you would send a technician to do first.

自分で検証する

公開データで動作するため、結論を信頼する必要はありません。すべての結果は、自分のマシンから独立して再現できます:

npm install && npm run build && npm run verify

ライブの公開ノード上の固定された履歴ウィンドウに対する 28 のアサーション。認証情報は不要です。その一部:

失敗は、サーバーがリグレッションしたか、SolarNetwork が履歴を言い直したことを意味します。各アサーションは、期待値と実際の値を出力するため、2 つを簡単に区別できます。

エージェントにロードする

すべてのクライアントは同じ 3 つの事実を必要とします: node を実行し、dist/index.js を渡し、stdio で通信します。ファイルの場所だけが異なります。

マシン上の dist/index.js への絶対パスを使用してください。Windows でもスラッシュは機能します。

ここにコミットされている .mcp.json は代わりに相対パスを使用しているため、リポジトリをクローンした人は誰でも何も編集せずに動作するサーバーを取得できます。これは、プロジェクトルートからサーバーを起動するクライアント (Claude Code が該当) でのみ機能します。他のクライアントは絶対形式が必要な場合があります。

Claude Code

すでに設定済み — .mcp.json がリポジトリルートにあるため、このディレクトリで開始されたセッションは自動的にそれを取得します。パスを編集するだけです:

{
  "mcpServers": {
    "solarnetwork": {
      "command": "node",
      "args": ["/absolute/path/to/solarnetwork-mcp/dist/index.js"]
    }
  }
}

または、任意の場所からグローバルに登録します:

claude mcp add solarnetwork -- node /absolute/path/to/solarnetwork-mcp/dist/index.js

Claude Desktop

claude_desktop_config.json を編集します:

• macOS — ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows — %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "solarnetwork": {
      "command": "node",
      "args": ["/absolute/path/to/solarnetwork-mcp/dist/index.js"]
    }
  }
}

アプリを再起動します。メッセージボックスにツールアイコンが表示されます。

Cursor

プロジェクト内の .cursor/mcp.json、またはすべてのプロジェクト用の ~/.cursor/mcp.json。上記と同じ mcpServers ブロック。

Windsurf

~/.codeium/windsurf/mcp_config.json。同じ mcpServers ブロック。

VS Code (Copilot エージェントモード)

.vscode/mcp.json — キーは mcpServers ではなく servers であることに注意:

{
  "servers": {
    "solarnetwork": {
      "type": "stdio",
      "command": "node",
      "args": ["/absolute/path/to/solarnetwork-mcp/dist/index.js"]
    }
  }
}

Zed

settings.json の context_servers の下:

{
  "context_servers": {
    "solarnetwork": {
      "command": { "path": "node", "args": ["/absolute/path/to/dist/index.js"] }
    }
  }
}

その他

任意の MCP クライアントが stdio 経由で起動できます:

node /absolute/path/to/solarnetwork-mcp/dist/index.js

コードから駆動するには、scripts/smoke.mjs が公式 TypeScript SDK を使用した完全な動作例です。

ロードされたか確認

エージェントに「What solar tools do you have?」と尋ねてください。10 個表示されるはずです。表示されない場合、通常の原因は相対パス、npm run build の欠落、またはクライアントが再起動されていないことです。

ツール

発見

データ

分析

レポート

尋ねること

ここから始めてください — これらは実際のライブノードです:

オリエンテーション

米国タイムゾーンで稼働中の公開 SolarNetwork ノードはどれですか?

ノード 1000 は何を測定し、データはどのくらい遡れますか?

今すぐ

ノード 892 は今何を発電していますか? そこの天気はどうですか?

ノード 892 には気象センサーと日射計が搭載されているため、エージェントは出力に加えて温度、雲量、日射量を取得できます。

診断 — 興味深いもの

ノード 1000 で何か問題はありますか?

ノード 892 には 6 台のインバーターがリストされていますが、発電が見えません。何が起きていますか?

フリート

ノード 880、884、953、964、976、987、1000 を先週の出力でランク付けしてください。最初にどれを確認すべきですか?

マルチステップ — チェーンが示すところ

少なくとも 4 台のインバーターと日射量データを持つ米国のライブノードを見つけ、過去 2 週間診断してください。

返ってくるもの

ノード 1000 に対する diagnose_site の実際の出力:

[high] reporting-gap   /0145/S1/G1/GEN/101, /102, /103
       Registered on this node but returned no data for the window. That is a
       reporting or comms outage rather than a performance problem, so the
       device may well be generating.

[low]  inconsistent-instrumentation   /0145/S1/G1/INV/4
       Reports 0 W, but its `wh` field is non-zero (peak 16508), so it is moving
       energy. This device populates energy fields only, unlike its peers, so
       power-based comparison would wrongly read it as dead.

2 番目の結果がこのプロジェクト全体の要点です。INV/4 は 0 W を読み取りますが、3 つの兄弟機は 400〜700 W を生成しており、これは完全に死んだインバーターのように見えます — そしてこのツールの以前のバージョンはそう言っていました。しかし、それは死んでいません: そのメーターはその月に 826 kWh を蓄積しました。あるサイトのインバーターは異なる報告規約を使用しています。watts だけに基づくヘルスチェックは、毎晩、動作中のインバーターについて誰かにページを送信することになります。

独自のノード

2 つの環境変数を設定すると、サーバーは公開 /pub エンドポイントから認証付き /sec エンドポイントに切り替わります。ツールサーフェスは変更されません:

SN_TOKEN_ID=... SN_TOKEN_SECRET=... node dist/index.js

認証は SolarNetwork の SNWS2 スキームです — 正規化されたリクエストに対する HMAC-SHA256 で、日付スコープのキーを使用します。実装されていますが、テストされていません。検証するためのトークンペアがありません。

仕組み

3 つのファイル、合計約 900 行:

• src/solarnetwork.ts — API クライアント、ページング、リクエスト署名

• src/analysis.ts — ソース ID 解析、サイトごとの診断

• src/index.ts — 10 のツール定義

ツールの説明が実際のインターフェースです。エージェントが list_sources → query_datum を正しくチェーンするには、説明がそれぞれをいつ使用するかを示している必要があります。その文言を正しくすることが、データ処理のどれよりも、これが機能するかどうかに重要でした。

制限

• 公開ノードのノードメタデータは空であるため、定格容量がなく、容量正規化された比較はありません。compare_fleet は生の出力をランク付けし、その旨を述べます — 大きなサイトは小さな健全なサイトよりも上位になります。

• list_public_nodes はポイントインタイムスキャン (data/nodes.json) を読み取ります。ライブリストではありません。ノードに依存する前に list_sources を呼び出して確認してください。

• キャッシュはありません。エージェントの呼び出しが繰り返されると、API に再ヒットします。

• 単体テストはありません。scripts/smoke.mjs はライブプローブであり、テストスイートではありません。

• SolarQuery は、約 7 日を超える範囲では、細かい集計を時間単位に静かに強制します。query_datum は集計をそのまま渡すため、長い範囲は要求よりも粗いデータを返します。

詳細: USAGE.md には動作例と労力比較、DATA.md には公開されているものと資格情報で保護されているものの完全なインベントリがあります。

ライセンス

MIT