solar-plan-mcp

エージェント。これはひとつの実用的な問いに答えます。明日、この消費者のセットを自家発電でまかなえるか。無理なら、何をずらすか。

屋根にパネル、バッテリー、インバーター、停電スケジュールは既知。エージェントは既製のMCPサーバーから天気予報を取得し、自作のMCPサーバーで時間ごとの期待発電量を計算し、計画を物理的なルールに照らして検証し、通らなければ柔軟な負荷をずらして、数字で改善したことを示します。

2つのMCP接続:

ドキュメント: ツールの契約 · 設計の根拠 · デモシナリオ

必要なもの

PVGISデータセットはすでにリポジトリ内にある (data/pvgis_kyiv_5kwp.csv、1.1 MB)。したがって自作サーバーはネットワークなしで動作します。ダウンロードは不要です。

インストール

git clone <цей-репозиторій>
cd solar-plan-mcp

python -m venv .venv                       # або: uv venv .venv
.venv\Scripts\python.exe -m pip install -r requirements.txt

Windows、これは見た目の問題ではない。以下のコマンドはすべてPowerShellで実行する。なぜならPowerShell 5.1では && はそもそも演算子ではないからだ。以降、すべて .venv\Scripts\python.exe を使う。

エンコーディングの変数が2つあり、それぞれ意味が違う。 PYTHONUTF8=1 はPythonにUTF-8で書き出すよう指示する。[Console]::OutputEncoding はPowerShellにも同じく読み取るよう指示する。2つ目がないと、ウクライナ語の出力は власний になる。これは実測済みで、特にパイプ (| Tee-Object、| Select-String) の中で起きる。なぜならそこではPowerShellがコンソールのコードページでバイトをデコードするからだ。したがって、新しいウィンドウを開くたびに:

[Console]::OutputEncoding = [Text.Encoding]::UTF8
$env:PYTHONUTF8 = "1"

天気サーバーをビルドする

Goはユーザープロファイルにインストールされる。管理者権限もレジストリの変更も不要:

# 1. портативний Go у профіль (один раз). curl.exe є у Windows 10 1803+
curl.exe -Lo go.zip https://go.dev/dl/go1.27.0.windows-amd64.zip
Expand-Archive go.zip -DestinationPath "$env:LOCALAPPDATA\Programs"

# 2. клон і збірка. GOROOT і PATH живуть лише в цьому вікні — так і треба
$env:GOROOT = "$env:LOCALAPPDATA\Programs\go"
$env:PATH = "$env:GOROOT\bin;$env:PATH"
New-Item -ItemType Directory -Force vendor | Out-Null
cd vendor
git clone https://github.com/mschneider82/mcp-openweather.git
cd mcp-openweather
git checkout e032683574a0723591445462ef7104d360ad0889
go build -o mcp-weather.exe .
cd ..\..

エージェントは既製バイナリをパス vendor\mcp-openweather\mcp-weather.exe で探します。別の場所にあるなら、移動せずに変数を設定してください: $env:WEATHER_MCP_BINARY = "…\mcp-weather.exe" (env.example 参照)。エージェントはセッション開始前にファイルの存在を確認し、SDK内部からのトレースではなく、一文で拒否します。

vendor/ は .gitignore に入っている。他人のgit履歴と13 MBのバイナリはこのリポジトリには無関係だ。コミットは固定されており、まさにそのコミットに対して契約ドキュメントが書かれている。

コースが別の mcp-openweather コミットを固定しているなら、それを使い、ここに記録せよ。docs/TOOLS.md の契約の説明は e032683 の main.go から書かれた。

キー

秘密情報はリポジトリに入らない。.env と .env.* は .gitignore に入っており、サンプルは値なしで env.example にある。

デモには3つのターミナルが必要で、$env: は1つのターミナルにしか存在しない。したがってキーはユーザーレベルで設定するのがよい。管理者権限は不要:

# так ключ не потрапляє ні в скролбек, ні в історію PSReadLine
$s = Read-Host "OWM_API_KEY" -AsSecureString
[Environment]::SetEnvironmentVariable("OWM_API_KEY",
  [Runtime.InteropServices.Marshal]::PtrToStringBSTR(
    [Runtime.InteropServices.Marshal]::SecureStringToBSTR($s)), "User")

新しい値が見えるのは新しいターミナルだけ。キーを公開せずに届いたか確認するには: .venv/Scripts/python.exe -c "import os; print(len(os.environ.get('OWM_API_KEY','')))" — 32 になるはず。カメラの前で dir env: を実行しないこと。キーが出力される。

セッション限定の $env:OWM_API_KEY = "…" も機能するが、ここでは正しい用途がひとつだけある。それは障害シナリオ用に別のウィンドウでキーをリセットすることだ: $env:OWM_API_KEY = ""。

キーは環境からのみ読み取られる。コードにも .mcp.json.example にも存在せず、そこには ${OWM_API_KEY} という置換がある。.env ファイルは誰も読まない。コードには os.environ.get しかない。したがって env.example を .env にコピーするのは無意味な行為だ。

モデルへのアクセス

自作サーバーと57個のテストはすべて、Anthropicの資格情報なしで動作する。これらは別物であり、混同すべきではない。モデルが必要なのはちょうど1つのファイル、agent/run.py だけだ。

Claude Agent SDKはAPIに直接アクセスしない。claude CLIを子プロセスとして起動し、そのCLIが認証を探す。したがって2つのものが必要:

1. PATH 内の claude。 確認: (Get-Command claude).Source。インストールは公式手順に従う。このプロジェクトではWinGetでインストールされ、%LOCALAPPDATA%\Microsoft\WinGet\Links\claude.exe にある。

2. 認証は2つの経路のいずれかで、CLIは見つかった方を使う:

   • claude login — 対話的ログイン。CLIはトークンを ~/.claude/.credentials.json に置く。 ここで使われたのはまさにこの経路だ: プロセス環境には ANTHROPIC_* 変数がひとつもなく、資格情報ファイルは存在する。2026年8月25日の記録済み実行はこの方法で通った。

   • 環境内の ANTHROPIC_API_KEY — console.anthropic.com のキー。 上記の OWM_API_KEY と同じように設定し、同じくリポジトリには入らない。

コードに固定されているもの: モデル claude-opus-5 (agent/run.py) と claude-agent-sdk==0.2.144 (requirements.txt)。別のアクセス権を持ち、このモデルIDが解決されない場合は、run.py 内で利用可能なものに置き換え、ここにどれを使ったか記録せよ。実行の残りはIDに依存しない。

このコードは資格情報を一切読み取らず、どこにも渡さない。agent/run.py は ANTHROPIC_API_KEY にも資格情報ファイルにもアクセスしない。それを行うのはCLIだ。リポジトリに秘密情報はなく、env.example は空のまま置かれている。

外部APIの制限

OpenWeatherの無料プランは1分あたり60回の呼び出しを許可する(ドキュメント)。エージェントの1回の実行は weather ツールを1回呼び出す。内部では天気サーバーがそれを2つのHTTPリクエスト(現在の天気 + 5日間予報)に変換する。つまり、連続リハーサルでも上限まで3桁の余裕がある。

コードにはポーリングループ、エラー時の再試行、バックグラウンド更新は一切ない。天気はモデルがツールを呼び出したときにちょうど1回だけ取得される。自作サーバーはネットワークにまったくアクセスしない。データセットは data/ にあるため、estimate_pv_generation、validate_energy_plan などの実行を何度行っても外部リクエストは発生しない。

起動: 2つの独立したプロセス

自作サーバーはエージェントとは別に起動し、エージェントについて何も知らない。

ターミナル1 — 自作MCPサーバー:

$env:PYTHONUTF8 = "1"
.venv\Scripts\python.exe -m solar_mcp --transport streamable-http --port 8931

ターミナル2 — エージェント:

[Console]::OutputEncoding = [Text.Encoding]::UTF8
$env:PYTHONUTF8 = "1"
.venv\Scripts\python.exe agent\run.py

--date なしでは、エージェントは明日の1日を計画する。製品の問いはまさに明日についてであり、OpenWeatherの予報は 現在 … +5日 しかカバーしない。したがって今日の1日はすでに半分が地平線の外にある。このウィンドウ外の日付は NO_FORECAST_FOR_DATE を返し、黙ってゼロにはしない。

天気サーバーはエージェント自身がstdioで起動する。接続はそのように設定されている。自作サーバーもstdioで起動できる (python -m solar_mcp、これがデフォルト)。その場合、Claude Codeのようなクライアントが待ち受ける形になり、.mcp.json.example に記述されているのもまさにこの形だ。デモにはHTTPの方がよい。サーバーが本当に別プロセスであることが見えるからだ。

エージェントの便利なフラグ:

--plan boiler:18:2 --plan aircon:18:3    # свій план замість дефолтного (можна кілька разів)
--date YYYY-MM-DD                        # інша доба; вт/чт/пт — без відключень, сб/нд — вечірнє вікно
--objective maximize_outage_reserve      # інша цільова функція
--city Lviv                              # інше місто
--width 120                              # скільки символів сліду друкувати

--date は予報の地平線内の1日のみ受け付ける — 明日 … 今日 + 5。範囲外の日付は NO_FORECAST_FOR_DATE を返し、スケジュールに停電ウィンドウがあっても救えない。スケジュールはリポジトリにあり任意の日付を知っているが、予報は5日しか生きない。実行前に確認: scripts/call_weather.py --city Kyiv --covers YYYY-MM-DD。

停電スケジュールの日付は週単位のパターンと来歴を持つ — data/outage_windows.json 参照。8月22〜26日のウィンドウは公開スケジュールから入力され、以降はデモが記録日付に依存しないよう、同じパターンが前方に繰り返されている。

すべてが動いていることの確認

# 4 інструменти домену + 1 допоміжний, зі схемами входу І виходу
.venv\Scripts\python.exe scripts\inspect_tools.py
.venv\Scripts\python.exe scripts\inspect_tools.py --url http://127.0.0.1:8931/mcp --schemas

# сервер погоди напряму: сирий текст і те, що з нього вийшло
.venv\Scripts\python.exe scripts\call_weather.py --city Kyiv

# 57 тестів: фізика, правила домену, планувальник, контракт через MCP-клієнта
$env:PYTHONUTF8 = "1"; $env:PYTHONPATH = "."
.venv\Scripts\python.exe -m pytest tests\ -q

テストはネットワークもOpenWeatherキーもモデルへのアクセスも必要としない。データセットはリポジトリにあり、外部サーバーの応答は tests/fixtures/ に記録されている。

ファイルの配置

solar_mcp/            власний MCP-сервер (окремий процес)
  server.py           інструменти й ресурс — увесь контракт
  models.py           схеми входу й виходу (Pydantic → справжні inputSchema/outputSchema)
  errors.py           закритий перелік кодів; помилка ≠ порожній результат
  pv.py               огинаюча ясного неба × прозорість × температурний дерейтинг
  rules.py            симуляція балансу, порушення, планувальник, порівняння
  forecast.py         розбір плоского тексту сервера погоди
  dataset.py store.py читання датасету; реєстр виданих оцінок
agent/run.py          Claude Agent SDK, дві MCP-конекції, слід викликів
scripts/              inspect_tools.py — контракт; call_weather.py — чужий сервер напряму
data/                 датасет + fetch_pvgis.py (провенанс)
tests/                57 тестів; у fixtures/ — три записані відповіді сервера погоди й одна синтетична
docs/                 TOOLS.md · DESIGN.md · DEMO.md

これらのディレクトリのうち2つは独自のREADMEを持ち、「データソース」と「フィクスチャ」を探すときにまさにそれらが対象になる: data/README.md — PVGISの行、料金、停電スケジュールの出所。 tests/fixtures/README.md — 外部サーバーから何が、いつ、何で記録されたか。

デザインの半分を支えるひとつの観察

天気サーバーは障害と空の応答を区別しない。キーなしでは is_error: false と、ゼロと空の都市名を含むテキストを返す。これは tests/fixtures/owm_no_api_key.txt に逐語で記録されている。READMEでは「FATAL: OWM_API_KEY environment variable not set」を約束しているにもかかわらず。

そこで自作サーバーは逆に作られた。閉じたエラーコードのリスト、原因となったフィールドを示す field、そして空が正当な場所(夜、違反なし)には別途 reason。詳細: DESIGN.md、TOOLS.md。