solarnetwork-mcp

SolarNetwork 태양광 원격 측정 데이터를 AI 에이전트가 호출할 수 있는 도구로 바꿔주는 MCP 서버입니다.

자격 증명이 필요 없습니다. SolarNetwork의 공개 엔드포인트를 대상으로 실행되며, 약 52개의 실시간 태양광 사이트가 실제 발전량, 일사량, 날씨 데이터를 게시합니다. 그중 여러 사이트는 1분 단위로 업데이트되며 6년간의 이력이 있습니다.

할 수 있는 일

태양광 원격 측정 데이터 읽기

• 자격 증명 없이 공개 노드 검색, 시간대 또는 활성 상태로 필터링

• 사이트의 모든 스트림 분류: 사이트 미터, 인버터, 일사량, 날씨, ML 이상

• 5분에서 1년까지 모든 롤업으로 시계열 조회

• 평균 전력이 아닌 미터 판독값에서 실제 누적 에너지 얻기

• 값이 아닌 타임스탬프로 스트림이 여전히 활성 상태인지 확인

장비 결함 찾기, 날짜 포함

• 인버터 중단 감지 및 정확한 시작일과 종료일 특정

• 죽은 장치와 발전 중이지만 전력을 보고하지 않는 장치 구분

• 형제 장치가 계속 보고하는 동안 조용해진 장치 포착

• 미터 카운터 리셋 플래그 지정 — 이는 해당 기간을 포함하는 모든 에너지 합계를 조용히 손상시킴

• 존재한 적 없는 하드웨어에 대한 레지스트리 항목 발견

• 결함당 손실 에너지 추정, 각 장치의 자체 용량에 따라 형제 출력에서 스케일링

오경보를 울리지 않기

• 감지는 피어 상대적이므로 구름 덮임이 결함으로 등록될 수 없음

• 일사량계가 있는 곳에서는 일사량을 물리적 날씨 제어로 사용

• 창이 열릴 때 이미 진행 중인 결함은 하한으로 표시되며, 시작 날짜를 임의로 만들지 않음

• 평가할 수 없는 사이트는 평가되지 않음으로 보고되며, 절대 정상으로 보고되지 않음

사람이 행동할 수 있는 보고서 작성

• 우선순위가 지정된 작업 지시서: 평이한 언어의 원인, 증거, 번호 매겨진 단계, 도구 및 승인 기준 포함

• 체크박스와 메모 시트가 있는 인쇄 가능한 PDF 현장 팩

• 티켓에 붙여넣기 위한 Markdown 또는 후처리용 JSON

• 전체에 걸쳐 일반 ASCII만 사용하므로 PDF나 티켓 시스템에서 검은 상자로 변하지 않음

할 수 없는 일

의존하기 전에 알아두어야 할 사항:

• 인버터가 2개 미만인 사이트는 평가할 수 없습니다. 피어 비교에는 피어가 필요합니다. 도구는 깔끔한 결과를 보고하는 대신 그렇게 말합니다.

• 명판 정격이 없습니다. 공개 노드는 이를 노출하지 않으므로 손실 수치는 피어 스케일링 추정치이며 보증 계산이 아닙니다.

• 결함 감지는 일일 버킷으로 실행됩니다. 6시간 동안 조용한 장치는 보이지 않습니다.

• 스트림 분류는 경로 규칙에 의존합니다. 스트림 이름을 Main 또는 SMAInverter1로 지정한 사이트는 분류되지 않은 채로 반환됩니다.

실제로 하는 일

이 도구가 없으면 *"이 사이트에 문제가 있나요?"*에 답하려면 노드 ID, /datum/list 엔드포인트, aggregation=Day가 존재한다는 것, watts와 wattHours가 다른 질문이라는 것을 알고 JSON을 읽어야 합니다.

이 도구가 있으면 다음과 같이 물어보세요:

"노드 1000에 문제가 있나요? 출력이 낮다면 날씨 때문인지 장비 때문인지 알려주세요."

그러면 에이전트가 사이트의 스트림을 발견하고, 날짜 범위를 선택하고, 집계를 실행하고, 각 인버터를 형제와 비교한 후 영어로 답합니다. 한 문장을 입력하면 진단이 나옵니다.

서버는 언어 모델이 잘하지 못하는 부분을 처리합니다 — 요청 서명, 페이지네이션, 단위 의미론, 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가 이력을 재작성했음을 의미합니다. 각 어서션은 기대한 것과 얻은 것을 출력하므로 둘을 쉽게 구분할 수 있습니다.

에이전트에 로드하기

모든 클라이언트는 동일한 세 가지 사실을 요구합니다: 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 agent mode)

.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를 사용하는 완전한 작업 예제입니다.

로드 확인

에이전트에게 물어보세요: "어떤 태양광 도구가 있나요?" 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.

두 번째 결과가 이 프로젝트 전체의 핵심입니다. INV/4는 0W를 읽는 반면 세 형제는 400–700W를 생산하며, 이는 정확히 죽은 인버터처럼 보입니다 — 그리고 이 도구의 이전 버전도 그렇게 말했습니다. 하지만 죽은 것이 아닙니다: 그 미터는 그 달에 826kWh를 누적했습니다. 한 사이트의 인버터는 서로 다른 보고 규칙을 사용합니다. watts만 기준으로 한 상태 점검은 매일 밤 작동 중인 인버터에 대해 누군가에게 페이지를 보낼 것입니다.

자신의 노드

두 개의 환경 변수를 설정하면 서버가 공개 /pub 엔드포인트에서 인증된 /sec 엔드포인트로 전환됩니다. 도구 표면은 변경되지 않습니다:

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

인증은 SolarNetwork의 SNWS2 체계입니다 — 날짜 범위 키가 있는 정규화된 요청에 대한 HMAC-SHA256. 구현되었지만 테스트되지 않았습니다; 검증할 토큰 쌍이 없습니다.

작동 방식

세 개의 파일, 총 약 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에는 공개 vs 자격 증명 게이트의 전체 목록이 있습니다.

라이선스

MIT