solar-plan-mcp

내일 이 소비자 세트를 자체 발전으로 감당할 수 있을지, 안 되면 무엇을 옮길지를 답하는 에이전트입니다: 내일 이 소비자 세트를 자체 발전으로 감당할 수 있을지, 안 되면 무엇을 옮길지?

패널이 있는 지붕, 배터리, 인버터, 알려진 정전 일정. 에이전트는 준비된 MCP 서버에서 날씨 예보를 가져오고, 자체 MCP 서버에서 시간별 예상 발전량을 계산하며, 계획을 물리적 규칙에 대비해 검증하고, 통과하지 못하면 유연한 부하를 옮기고 숫자로 개선되었음을 증명합니다.

두 개의 MCP 연결:

문서: 도구 계약 · 디자인 근거 · 데모 시나리오

필요 사항

PVGIS 데이터셋은 이미 저장소에 있습니다 (data/pvgis_kyiv_5kwp.csv, 1.1MB), 따라서 자체 서버는 네트워크 없이 작동합니다. 다운로드할 것이 없습니다.

설치

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를 사용합니다.

인코딩 변수 두 개, 그리고 서로 다릅니다. PYTHONUTF8=1은 Python에게 UTF-8로 쓰라고 지시합니다; [Console]::OutputEncoding은 PowerShell에게 동일하게 읽으라고 지시합니다. 두 번째가 없으면 우크라이나어 출력이 власний로 변합니다 — 측정된 결과이며, 특히 파이프(| 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 히스토리와 13MB 바이너리는 이 저장소와 무관합니다. 커밋은 고정되어 있으며 — 바로 그 커밋을 기준으로 계약 문서가 작성되었습니다.

과정에서 다른 mcp-openweather 커밋을 고정한다면 그것을 사용하고 여기에 기록하세요; docs/TOOLS.md의 계약 설명은 e032683의 main.go를 기준으로 작성되었습니다.

키

비밀은 저장소에 들어가지 않습니다: .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. PATH에 claude. 확인: (Get-Command claude).Source. 설치 — 공식 지침에 따름; 이 프로젝트에서는 WinGet으로 설치되었고 %LOCALAPPDATA%\Microsoft\WinGet\Links\claude.exe에 있습니다.

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 무료 플랜은 분당 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일만 덮으므로 오늘 하루는 이미 절반이 지평선 밖입니다. 이 창 밖의 날짜는 조용한 0이 아니라 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를 반환하며, 정전 창이 일정에 있다고 해서 구해지지 않습니다: 일정은 저장소에 있고 어떤 날짜든 알지만 예보는 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

이 중 두 디렉터리는 자체 README가 있으며 "데이터 소스"와 "픽스처"를 찾을 때 바로 그것을 봅니다: data/README.md — PVGIS 행, 요금, 정전 일정의 출처; tests/fixtures/README.md — 외부 서버에서 정확히 무엇을, 언제, 무엇으로 기록했는지.

디자인 절반의 기반이 되는 한 가지 관찰

날씨 서버는 고장과 빈 응답을 구분하지 못합니다. 키 없이 is_error: false와 0과 빈 도시 이름이 있는 텍스트를 반환합니다 — tests/fixtures/owm_no_api_key.txt에 그대로 기록되어 있지만, README는 "FATAL: OWM_API_KEY environment variable not set"을 약속합니다.

따라서 자체 서버는 반대로 만들어졌습니다: 닫힌 오류 코드 목록, 잘못된 필드를 가리키는 field, 그리고 합법적으로 비어 있는 곳(밤, 위반 없음)에는 별도로 reason. 자세한 내용: DESIGN.md, TOOLS.md.