solar-plan-mcp

Агент, который отвечает на один бытовой вопрос: вытяну ли я завтра этот набор потребителей на собственной генерации, а если нет — что перенести?

Крыша с панелями, батарея, инвертор, известный график отключений. Агент берёт прогноз погоды с готового MCP-сервера, считает ожидаемую выработку по часам на собственном MCP-сервере, проверяет план против физических правил, а если тот не проходит — переносит гибкие нагрузки и доказывает числом, что стало лучше.

Два MCP-подключения:

Документация: контракты инструментов · рацио дизайна · сценарий демонстрации

Что нужно

Датасет PVGIS уже лежит в репозитории (data/pvgis_kyiv_5kwp.csv, 1.1 МБ), поэтому собственный сервер работает без сети. Скачивать ничего не нужно.

Related MCP server: Solar MCP

Установка

Windows, и это не косметика: все команды — в PowerShell, потому что && в PowerShell 5.1 вообще не оператор. Далее везде .venv\Scripts\python.exe.

Сначала две переменные кодировки, и они разные. PYTHONUTF8=1 говорит Python писать UTF-8; [Console]::OutputEncoding говорит PowerShell так же его читать. Без второй вывод на украинском превращается в власний — измерено, и именно в трубе (| Tee-Object, | Select-String), потому что там PowerShell декодирует байты кодовой страницей консоли. Выставлять в каждом новом окне, и до установки, а не после:

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

git clone https://github.com/prasolantoncp-bot/solar-plan-mcp.git
cd solar-plan-mcp

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

Нужен Python 3.13 — именно тот, что отвечает на python --version, потому что venv наследует версию интерпретатора, которым его создали.

Почему версии закреплены. Демонстрация должна воспроизводиться, а не «где-то работать». mcp==2.0.0 — это уже MCPServer вместо FastMCP, и код под 1.x здесь не пойдёт; claude-agent-sdk==0.2.144 — на ней проверены tools и формат init-сообщения, из которого агент печатает оба подключения; tzdata — потому что Windows не имеет системной базы часовых поясов, а без Europe/Kyiv не будет ни одного местного часа. Сам requirements.txt держится в ASCII намеренно: pip читает его кодировкой локали, и одна кириллическая буква в комментарии валит pip install -r с UnicodeDecodeError на любой машине, где локаль не UTF-8. Измерено на cp1252 из чистого клона — поэтому объяснение живёт здесь, а не в том файле.

Собрать сервер погоды

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 МБ бинарника в этом репозитории ни при чём. Коммит зафиксирован — именно на нём написана документация контракта.

Если курс фиксирует другой коммит mcp-openweather — берите его и запишите здесь; описание контракта в docs/TOOLS.md писалось с main.go на e032683.

Ключ

Секреты в репозиторий не попадают: .env и .env.* в .gitignore, а образец лежит в env.example без единого значения.

Демонстрация требует трёх терминалов, а $env: живёт лишь в одном, поэтому ключ стоит выставить на уровне пользователя — прав администратора для этого не нужно:

# так ключ не потрапляє ні в скролбек, ні в історію 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 — это разные вещи, и путать их не стоит. Модель нужна ровно одному файлу, agent/run.py.

Claude Agent SDK не обращается к API сам: он спавнит claude CLI как дочерний процесс, и именно тот CLI ищет авторизацию. Поэтому нужны две вещи:

1. claude в PATH. Проверка: (Get-Command claude).Source. Установка — по официальной инструкции; в этом проекте он поставлен через WinGet и лежит в %LOCALAPPDATA%\Microsoft\WinGet\Links\claude.exe.

2. Авторизация — один из двух путей, и CLI берёт тот, который найдёт:

   • claude login — интерактивный вход; токен CLI кладёт в ~/.claude/.credentials.json. Именно этот путь использован здесь: в окружении процесса нет ни одной переменной ANTHROPIC_*, а файл креденшлов есть. Записанный прогон 25 августа 2026 прошёл так.

   • 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 даёт 60 вызовов в минуту (документация). Один прогон агента делает один вызов инструмента weather; внутри сервер погоды превращает его в два HTTP-запроса (текущая погода + прогноз на 5 суток). То есть до потолка три порядка запаса даже при непрерывных репетициях.

В коде нет ни одного цикла опроса, повтора при ошибке или фонового обновления: погода запрашивается ровно тогда, когда модель вызывает инструмент. Собственный сервер в сеть не ходит вообще — его датасет лежит в data/, поэтому сколько угодно прогонов estimate_pv_generation, validate_energy_plan и остальных не создают ни одного внешнего запроса.

Запуск: два независимых процесса

Собственный сервер поднимается отдельно от агента и об агенте не знает ничего.

Терминал 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 агент планирует завтрашние сутки: вопрос продукта именно про завтра, а прогноз OpenWeather накрывает лишь сейчас … +5 суток, так что сегодняшние сутки уже наполовину вне горизонта. Дата вне этого окна даст 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 принимает лишь сутки в пределах горизонта прогноза — завтра … сегодня + 5. Дата вне него даст NO_FORECAST_FOR_DATE, и наличие окна отключения в графике этого не спасает: график лежит в репозитории и знает любую дату, а прогноз живёт пять суток. Проверить перед запуском: scripts/call_weather.py --city Kyiv --covers YYYY-MM-DD.

Даты в графике отключений имеют недельный узор и провенанс — см. data/outage_windows.json: окна на 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

Два из этих каталогов имеют собственный 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.