solarnetwork-mcp

solarnetwork-mcp

Um servidor MCP que transforma a telemetria solar da SolarNetwork em ferramentas que um agente de IA pode chamar.

Nenhuma credencial necessária. Ele opera nos endpoints públicos da SolarNetwork, onde cerca de 52 sites solares ao vivo publicam dados reais de geração, irradiância e clima — vários deles atualizados a cada minuto, com seis anos de histórico.

O que ele pode fazer

Ler telemetria solar

• Descobrir nós públicos sem credenciais, filtrando por fuso horário ou atividade
• Classificar cada stream em um site: medidor do site, inversor, irradiância, clima, anomalia de ML
• Consultar séries temporais em qualquer agregação, de cinco minutos a um ano
• Obter energia acumulada real a partir de leituras do medidor, em vez de potência média
• Verificar se um stream ainda está ativo, por timestamp em vez de por valor

Encontrar falhas de equipamento, com datas

• Detectar interrupções de inversores e identificar o dia exato de início e fim
• Distinguir um dispositivo morto de um que está gerando, mas não reportando potência
• Identificar um dispositivo que ficou silencioso enquanto seus pares continuam reportando
• Sinalizar reinicializações de contadores do medidor, que corrompem silenciosamente todos os totais de energia que os abrangem
• Detectar entradas de registro para hardware que nunca existiu
• Estimar energia perdida por falha, escalada a partir da saída dos pares pela capacidade de cada dispositivo

Não gerar falsos alarmes

• A detecção é relativa aos pares, então cobertura de nuvens não pode ser registrada como falha
• A irradiância é usada como controle físico de clima quando existe um piranômetro
• Falhas já em andamento quando a janela abre são rotuladas como limites inferiores, não como datas de início inventadas
• Sites que não podem ser avaliados são reportados como não avaliados, nunca como saudáveis

Escrever relatórios acionáveis

• Ordens de serviço priorizadas com causa em linguagem simples, evidências, etapas numeradas, ferramentas e critérios de aceite
• Pacotes de campo em PDF imprimíveis com caixas de seleção e uma folha de anotações
• Markdown para colar em um ticket, ou JSON para pós-processamento
• ASCII puro em todo o conteúdo, para que nada vire caixas pretas em um PDF ou sistema de tickets

O que ele não pode fazer

Vale saber antes de depender dele:

• Sites com menos de dois inversores não podem ser avaliados. A comparação entre pares precisa de pares. A ferramenta diz isso em vez de reportar um resultado limpo.
• Sem classificações de placa. Os nós públicos não as expõem, então os valores de perda são estimativas escaladas por pares, não cálculos de garantia.
• A detecção de falhas opera em intervalos diários. Um dispositivo silencioso por seis horas é invisível.
• A classificação de streams depende de uma convenção de caminho. Sites que nomeiam streams como Main ou SMAInverter1 retornam não classificados.

O que ele realmente faz

Sem ele, responder "há algo errado neste site?" significa saber o ID do nó, o endpoint /datum/list, que aggregation=Day existe, que watts e wattHours são perguntas diferentes, e então ler JSON.

Com ele, você pergunta:

"Há algo errado no nó 1000? Se a saída estiver baixa, me diga se é clima ou equipamento."

e o agente descobre os streams do site, escolhe um intervalo de datas, executa a agregação, compara cada inversor com seus pares e responde em inglês. Uma frase de entrada, um diagnóstico de saída.

O servidor faz as partes em que um modelo de linguagem é ruim — assinatura de requisições, paginação, semântica de unidades, saber qual dos nove streams é um sensor de clima. O agente faz as partes em que é bom — decidir o que perguntar e interpretar a resposta.

Veja funcionando em 60 segundos

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

Isso aciona todas as ferramentas pelo protocolo MCP real contra dados ao vivo. Sem agente, sem chave de API, sem configuração. Se imprimir descobertas para o nó 1000, está tudo certo.

Entregue isso ao seu agente

Copie o bloco inteiro abaixo para o Claude Code, Cursor ou qualquer agente compatível com MCP. Ele instala o servidor, configura-se, prova que a instalação funciona e então executa uma demonstração guiada de cada capacidade contra sites solares públicos ao vivo.

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.

Verifique você mesmo

Como opera em dados públicos, você não precisa aceitar nenhuma de suas conclusões como verdade. Cada descoberta é reproduzível de forma independente a partir da sua própria máquina:

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

28 asserções contra janelas históricas fixas em nós públicos ao vivo. Sem credenciais. Entre elas:

Verificação	Nó	Expectativa
Linha do tempo de falha	1000	Interrupção do inversor 1, exatamente de 2026-05-17 a 2026-08-03, 79 dias
Falha de telemetria	1000	Inversor 4 reportando 0 W desde 2026-03-25 enquanto ainda gera
Paginação	1000	Um ano excede o limite de página de 1000 linhas do SolarQuery; cada linha é buscada
Integridade do medidor	781	Reinicialização do contador sinalizada, e energia do site nunca reportada como negativa
Integridade do medidor	900	Reinicialização do contador identificada em 2026-06-03
Honestidade de cobertura	949	Um nó sem inversores reporta "não avaliado", nunca "saudável"
Escolha do medidor do site	464	O medidor real vence sobre um stub /TEST/GEN/1 remanescente
Saída do relatório	1000	Ordens de serviço, critérios de aceite, apenas ASCII puro

Uma falha significa que o servidor regrediu, ou que a SolarNetwork reafirmou o histórico. Cada asserção imprime o que esperava contra o que obteve, então os dois são fáceis de distinguir.

Carregue no seu agente

Todo cliente quer os mesmos três fatos: execute node, passe dist/index.js, fale via stdio. Apenas a localização do arquivo difere.

Use o caminho absoluto para dist/index.js na sua máquina. Barras normais funcionam no Windows também.

O .mcp.json commitado aqui usa um caminho relativo, para que qualquer pessoa que clone o repositório obtenha um servidor funcional sem editar nada. Isso só funciona para clientes que iniciam o servidor a partir da raiz do projeto, o que o Claude Code faz; outros clientes podem precisar da forma absoluta.

Claude Code

Já configurado — .mcp.json está na raiz do repositório, então uma sessão iniciada neste diretório o detecta automaticamente. Basta editar o caminho:

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

Ou registre-o globalmente de qualquer lugar:

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

Claude Desktop

Edite 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"]
    }
  }
}

Reinicie o aplicativo. Um ícone de ferramentas aparece na caixa de mensagem.

Cursor

.cursor/mcp.json no seu projeto, ou ~/.cursor/mcp.json para todos os projetos. Mesmo bloco mcpServers acima.

Windsurf

~/.codeium/windsurf/mcp_config.json. Mesmo bloco mcpServers.

VS Code (modo agente Copilot)

.vscode/mcp.json — observe que a chave é servers, não mcpServers:

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

Zed

Em settings.json, sob context_servers:

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

Qualquer outra coisa

Qualquer cliente MCP pode iniciá-lo via stdio:

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

Para acioná-lo a partir de código, scripts/smoke.mjs é um exemplo completo e funcional usando o SDK oficial de TypeScript.

Verificando se carregou

Pergunte ao seu agente: "Quais ferramentas solares você tem?" Você deve ver dez. Se não, as causas usuais são um caminho relativo, um npm run build ausente, ou o cliente não ter sido reiniciado.

As ferramentas

Descoberta

Ferramenta	Responde
list_public_nodes	"Quais nós posso até mesmo olhar?"
list_sources	"O que este nó mede?"
get_latest	"O que está acontecendo agora?"

Dados

Ferramenta	Responde
query_datum	"Mostre-me a saída neste período"
get_energy	"Quantos kWh ele realmente gerou?"

Análise

Ferramenta	Responde
asset_review	"O que quebrou, quando começou e quanto custou?"
diagnose_site	"Há algo errado agora, clima ou equipamento?"
compare_fleet	"Qual dos meus sites precisa de atenção primeiro?"
get_anomalies	"O que o detector de ML da própria plataforma diz?"

Relatórios

Ferramenta	Responde
create_service_report	"Me dê uma ordem de serviço que eu possa entregar a um técnico"

Coisas para perguntar

Comece aqui — estes são nós reais e ao vivo:

Orientação

Quais nós públicos da SolarNetwork estão ativos em fusos horários dos EUA?

O que o nó 1000 mede e até onde seus dados retrocedem?

Agora

O que o nó 892 está gerando agora e como está o clima lá?

O nó 892 carrega um sensor de clima e um piranômetro, então o agente obtém temperatura, cobertura de nuvens e irradiância junto com a saída.

Diagnóstico — os interessantes

Há algo errado no nó 1000?

O nó 892 lista seis inversores, mas não vejo geração. O que está acontecendo?

Frota

Classifique os nós 880, 884, 953, 964, 976, 987 e 1000 por saída na semana passada. Qual devo olhar primeiro?

Multi-etapas, onde o encadeamento aparece

Encontre um nó dos EUA ativo com pelo menos quatro inversores e dados de irradiância, e então diagnostique-o nas últimas duas semanas.

O que você recebe de volta

Saída real de diagnose_site no nó 1000:

[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.

Essa segunda descoberta é o ponto de todo o projeto. INV/4 lê 0 W enquanto seus três pares produzem 400–700 W, o que parece exatamente um inversor morto — e uma versão anterior desta ferramenta dizia isso. Não está morto: seu medidor acumulou 826 kWh naquele mês. Inversores em um mesmo site usam convenções de relatório diferentes. Uma verificação de saúde baseada apenas em watts paginaria alguém sobre um inversor funcionando toda noite.

Seus próprios nós

Defina duas variáveis de ambiente e o servidor muda dos endpoints públicos /pub para os autenticados /sec. A superfície de ferramentas permanece inalterada:

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

A autenticação é o esquema SNWS2 da SolarNetwork — HMAC-SHA256 sobre uma requisição canonicalizada com uma chave com escopo de data. Está implementada, mas não testada; não tenho um par de tokens para verificar.

Como funciona

Três arquivos, ~900 linhas no total:

• src/solarnetwork.ts — cliente de API, paginação, assinatura de requisições
• src/analysis.ts — análise de ID de fonte, diagnóstico por site
• src/index.ts — as dez definições de ferramentas

As descrições das ferramentas são a interface real. Um agente só encadeia list_sources → query_datum corretamente se as descrições disserem quando usar cada uma. Acertar essa redação importou mais para o funcionamento disso do que qualquer tratamento de dados.

Limitações

• Os metadados de nós são vazios em nós públicos, então não há capacidade de placa e, portanto, nenhuma comparação normalizada por capacidade. compare_fleet classifica a saída bruta e diz isso — um site grande superará um pequeno e saudável.
• list_public_nodes lê uma varredura pontual (data/nodes.json), não uma listagem ao vivo. Chame list_sources para confirmar antes de confiar em um nó.
• Sem cache. Chamadas repetidas do agente re-acessam a API.
• Sem testes de unidade. scripts/smoke.mjs é uma sonda ao vivo, não uma suíte de testes.
• O SolarQuery converte silenciosamente agregações de granularidade fina para horárias em intervalos acima de ~7 dias. query_datum passa sua agregação como está, então intervalos longos retornam dados mais grosseiros do que o solicitado.

Mais detalhes: USAGE.md para exemplos práticos e uma comparação de esforço, DATA.md para o inventário completo do que é público vs. restrito por credenciais.

Licença

Proprietária / Todos os Direitos Reservados. Consulte LICENSE para detalhes.