solarnetwork-mcp

solarnetwork-mcp

Un servidor MCP que convierte la telemetría solar de SolarNetwork en herramientas que un agente de IA puede invocar.

No se requieren credenciales. Funciona contra los endpoints públicos de SolarNetwork, donde ~52 sitios solares en vivo publican datos reales de generación, irradiancia y clima — varios de ellos actualizándose al minuto, con seis años de historial.

Qué puede hacer

Leer telemetría solar

• Descubrir nodos públicos sin credenciales, filtrar por zona horaria o actividad
• Clasificar cada flujo en un sitio: medidor de sitio, inversor, irradiancia, clima, anomalía ML
• Consultar series temporales en cualquier nivel de agregación, de cinco minutos a un año
• Obtener energía acumulada real a partir de lecturas del medidor, no de potencia promediada
• Verificar si un flujo sigue activo, por marca de tiempo y no por valor

Encontrar fallas de equipos, con fechas

• Detectar cortes de inversores y fijar el día exacto de inicio y fin
• Distinguir un dispositivo muerto de uno que genera pero no reporta potencia
• Detectar un dispositivo que ha quedado en silencio mientras sus hermanos siguen reportando
• Marcar reinicios de contadores de medidores, que corrompen silenciosamente todo total de energía que los abarque
• Detectar entradas de registro para hardware que nunca ha existido
• Estimar energía perdida por falla, escalada desde la salida de los hermanos según la capacidad propia de cada dispositivo

No generar falsas alarmas

• La detección es relativa entre pares, por lo que la cobertura de nubes no puede registrarse como falla
• La irradiancia se usa como control físico del clima donde existe un piranómetro
• Las fallas ya activas cuando se abre la ventana se etiquetan como límites inferiores, no como fechas de inicio inventadas
• Los sitios que no pueden evaluarse se reportan como no evaluados, nunca como saludables

Escribir informes accionables

• Órdenes de trabajo priorizadas con causa en lenguaje claro, evidencia, pasos numerados, herramientas y criterios de aprobación
• Paquetes de campo PDF imprimibles con casillas de verificación y una hoja de notas
• Markdown para pegar en un ticket, o JSON para posprocesamiento
• ASCII puro en todo, para que nada se convierta en cuadros negros en un PDF o un sistema de tickets

Qué no puede hacer

Vale la pena saberlo antes de depender de ello:

• Los sitios con menos de dos inversores no pueden evaluarse. La comparación entre pares necesita pares. La herramienta lo dice en lugar de reportar un resultado limpio.
• Sin clasificaciones de placa. Los nodos públicos no las exponen, por lo que las cifras de pérdida son estimaciones escaladas entre pares, no cálculos de garantía.
• La detección de fallas se ejecuta en bloques diarios. Un dispositivo en silencio durante seis horas es invisible.
• La clasificación de flujos depende de una convención de rutas. Los sitios que nombran flujos Main o SMAInverter1 vuelven sin clasificar.

Qué hace realmente

Sin ello, responder "¿hay algo mal en este sitio?" significa conocer el ID del nodo, el endpoint /datum/list, que aggregation=Day existe, que watts y wattHours son preguntas diferentes, y luego leer JSON.

Con ello, preguntas:

"¿Hay algo mal en el nodo 1000? Si la salida está baja, dime si es clima o equipo."

y el agente descubre los flujos del sitio, elige un rango de fechas, ejecuta la agregación, compara cada inversor con sus hermanos, y responde en inglés. Una frase de entrada, un diagnóstico de salida.

El servidor hace las partes en las que un modelo de lenguaje es malo — firma de solicitudes, paginación, semántica de unidades, saber cuál de nueve flujos es un sensor de clima. El agente hace las partes en las que es bueno — decidir qué preguntar e interpretar la respuesta.

Véalo funcionando en 60 segundos

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

Eso impulsa cada herramienta sobre el protocolo MCP real contra datos en vivo. Sin agente, sin clave API, sin configuración. Si imprime hallazgos para el nodo 1000, estás listo.

Entréguelo a su agente

Copie todo el bloque de abajo en Claude Code, Cursor, o cualquier agente compatible con MCP. Instala el servidor, se configura solo, prueba que la instalación funciona, y luego ejecuta una demostración guiada de cada capacidad contra sitios solares públicos en 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.

Verifíquelo usted mismo

Como se ejecuta sobre datos públicos, no tiene que confiar en ninguna de sus conclusiones. Cada hallazgo es reproducible de forma independiente desde su propia máquina:

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

28 aserciones contra ventanas históricas fijas en nodos públicos en vivo. Sin credenciales. Entre ellas:

Verificación	Nodo	Expectativa
Línea de tiempo de fallas	1000	Corte del inversor 1, exactamente 2026-05-17 a 2026-08-03, 79 días
Falla de telemetría	1000	Inversor 4 reportando 0 W desde 2026-03-25 mientras sigue generando
Paginación	1000	Un año excede el límite de página de 1000 filas de SolarQuery; cada fila se obtiene
Integridad del medidor	781	Reinicio de contador señalado, y la energía del sitio nunca reportada negativa
Integridad del medidor	900	Reinicio de contador precisado a 2026-06-03
Honestidad de cobertura	949	Un nodo sin inversores reporta "no evaluado", nunca "saludable"
Elección del medidor del sitio	464	El medidor real gana sobre un stub sobrante /TEST/GEN/1
Salida del informe	1000	Órdenes de trabajo, criterios de aceptación, solo ASCII puro

Una falla significa que el servidor retrocedió, o que SolarNetwork reformuló el historial. Cada aserción imprime lo que esperaba contra lo que obtuvo, para que sea fácil distinguirlos.

Cárguelo en su agente

Cada cliente quiere los mismos tres datos: ejecutar node, pasarle dist/index.js, hablar por stdio. Solo difiere la ubicación del archivo.

Use la ruta absoluta a dist/index.js en su máquina. Las barras diagonales funcionan también en Windows.

El .mcp.json comprometido aquí usa una ruta relativa en su lugar, para que cualquiera que clone el repositorio obtenga un servidor funcional sin editar nada. Eso solo funciona para clientes que lanzan el servidor desde la raíz del proyecto, lo cual Claude Code hace; otros clientes pueden necesitar la forma absoluta.

Claude Code

Ya configurado — .mcp.json está en la raíz del repositorio, así que una sesión iniciada en este directorio lo recoge automáticamente. Solo edite la ruta:

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

O regístrelo globalmente desde cualquier 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 la aplicación. Aparece un ícono de herramientas en el cuadro de mensaje.

Cursor

.cursor/mcp.json en su proyecto, o ~/.cursor/mcp.json para cada proyecto. Mismo bloque mcpServers que arriba.

Windsurf

~/.codeium/windsurf/mcp_config.json. Mismo bloque mcpServers.

VS Code (modo agente Copilot)

.vscode/mcp.json — note que la clave es servers, no mcpServers:

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

Zed

En settings.json, bajo context_servers:

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

Cualquier otra cosa

Cualquier cliente MCP puede lanzarlo por stdio:

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

Para manejarlo desde código, scripts/smoke.mjs es un ejemplo completo y funcional usando el SDK oficial de TypeScript.

Verificando que se cargó

Pregunte a su agente: "¿Qué herramientas solares tienes?" Debería ver diez. Si no, las causas habituales son una ruta relativa, un npm run build faltante, o el cliente no reiniciado.

Las herramientas

Descubrimiento

Herramienta	Responde
list_public_nodes	"¿Qué nodos puedo siquiera mirar?"
list_sources	"¿Qué mide este nodo?"
get_latest	"¿Qué está pasando ahora mismo?"

Datos

Herramienta	Responde
query_datum	"Muéstrame la salida en este período"
get_energy	"¿Cuántos kWh generó realmente?"

Análisis

Herramienta	Responde
asset_review	"¿Qué se rompió, cuándo empezó, y cuánto costó?"
diagnose_site	"¿Hay algo mal ahora mismo, clima o equipo?"
compare_fleet	"¿Cuál de mis sitios necesita atención primero?"
get_anomalies	"¿Qué dice el propio detector ML de la plataforma?"

Informes

Herramienta	Responde
create_service_report	"Dame una orden de trabajo que pueda entregar a un técnico"

Cosas para preguntarle

Empiece aquí — estos son nodos reales y en vivo:

Orientación

¿Qué nodos públicos de SolarNetwork están en vivo en zonas horarias de EE. UU.?

¿Qué mide el nodo 1000, y hasta dónde llegan sus datos?

Ahora mismo

¿Qué está generando el nodo 892 ahora mismo, y qué clima hay allí?

El nodo 892 lleva un sensor de clima y un piranómetro, así que el agente obtiene temperatura, cobertura de nubes e irradiancia junto con la salida.

Diagnóstico — los interesantes

¿Hay algo mal en el nodo 1000?

El nodo 892 lista seis inversores pero no veo generación. ¿Qué está pasando?

Flota

Clasifica los nodos 880, 884, 953, 964, 976, 987 y 1000 por salida de la semana pasada. ¿Cuál debería mirar primero?

Multi-paso, donde el encadenamiento se muestra

Encuentra un nodo de EE. UU. en vivo con al menos cuatro inversores y datos de irradiancia, luego diagnostícalo por las últimas dos semanas.

Lo que obtienes de vuelta

Salida real de diagnose_site en el nodo 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.

Ese segundo hallazgo es el punto de todo el proyecto. INV/4 lee 0 W mientras sus tres hermanos producen 400–700 W, lo que parece exactamente un inversor muerto — y una versión anterior de esta herramienta lo decía. No está muerto: su medidor acumuló 826 kWh ese mes. Los inversores en un mismo sitio usan convenciones de reporte diferentes. Una verificación de salud basada solo en watts haría llamar a alguien por un inversor funcional cada noche.

Sus propios nodos

Establezca dos variables de entorno y el servidor cambia de los endpoints públicos /pub a los autenticados /sec. La superficie de herramientas no cambia:

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

La autenticación es el esquema SNWS2 de SolarNetwork — HMAC-SHA256 sobre una solicitud canonicalizada con una clave con alcance de fecha. Está implementada pero sin probar; no tengo un par de tokens para verificar contra ella.

Cómo funciona

Tres archivos, ~900 líneas en total:

• src/solarnetwork.ts — cliente API, paginación, firma de solicitudes
• src/analysis.ts — análisis de ID de fuente, diagnóstico por sitio
• src/index.ts — las diez definiciones de herramientas

Las descripciones de las herramientas son la interfaz real. Un agente solo encadena list_sources → query_datum correctamente si las descripciones dicen cuándo recurrir a cada una. Lograr esa redacción correcta importó más para que esto funcione que cualquiera del manejo de datos.

Límites

• Los metadatos de nodo están vacíos en nodos públicos, así que no hay capacidad de placa y por lo tanto no hay comparación normalizada por capacidad. compare_fleet clasifica la salida bruta y lo dice — un sitio grande superará a uno pequeño y saludable.
• list_public_nodes lee un escaneo puntual (data/nodes.json), no un listado en vivo. Llame a list_sources para confirmar antes de confiar en un nodo.
• Sin caché. Las llamadas repetidas del agente vuelven a golpear la API.
• Sin pruebas unitarias. scripts/smoke.mjs es una sonda en vivo, no un conjunto de pruebas.
• SolarQuery coacciona silenciosamente la agregación de grano fino a horaria para rangos de más de ~7 días. query_datum pasa su agregación tal cual, así que los rangos largos devuelven datos más gruesos de lo solicitado.

Más detalle: USAGE.md para ejemplos trabajados y una comparación de esfuerzo, DATA.md para el inventario completo de lo que es público vs. restringido por credenciales.

Licencia

Propietaria / Todos los derechos reservados. Ver LICENSE para detalles.