solarnetwork-mcp

MCP-сервер, который превращает солнечную телеметрию SolarNetwork в инструменты, которые может вызывать ИИ-агент.

Учётные данные не требуются. Он работает с публичными конечными точками SolarNetwork, где ~52 живые солнечные станции публикуют реальные данные о генерации, облучённости и погоде — несколько из них обновляются ежеминутно, с шестилетней историей.

Что он умеет

Читать солнечную телеметрию

• Обнаруживать публичные узлы без учётных данных, фильтровать по часовому поясу или активности

• Классифицировать каждый поток на станции: счётчик станции, инвертор, облучённость, погода, ML-аномалия

• Запрашивать временные ряды с любым шагом агрегации от пяти минут до года

• Получать истинную накопленную энергию из показаний счётчика, а не усреднённую мощность

• Проверять, жив ли поток, по временной метке, а не по значению

Находить неисправности оборудования, с датами

• Обнаруживать отключения инверторов и определять точный день начала и окончания

• Отличать мёртвое устройство от того, которое генерирует, но не сообщает мощность

• Ловить устройство, которое замолчало, пока его соседи продолжают сообщать

• Отмечать сбросы счётчиков, которые молча портят все итоги по энергии, охватывающие их

• Находить записи реестра для оборудования, которого никогда не существовало

• Оценивать потери энергии на каждую неисправность, масштабируя от выработки соседей с учётом собственной мощности каждого устройства

Не поднимать ложных тревог

• Обнаружение основано на сравнении с соседями, поэтому облачность не может быть зарегистрирована как неисправность

• Облучённость используется как физический погодный контроль там, где есть пиранометр

• Неисправности, уже активные на момент открытия окна, помечаются как нижние границы, а не выдуманные даты начала

• Станции, которые невозможно оценить, сообщаются как не оценены, а не как здоровые

Писать отчёты, по которым можно действовать

• Приоритизированные наряды на работы с объяснением причины на простом языке, доказательствами, нумерованными шагами, инструментами и критериями приёмки

• Печатные PDF-полевые комплекты с галочками и листом для заметок

• Markdown для вставки в тикет или JSON для постобработки

• Только простой ASCII, чтобы ничего не превращалось в чёрные квадраты в PDF или системе тикетов

Что он не умеет

Стоит знать, прежде чем полагаться на него:

• Станции с менее чем двумя инверторами не могут быть оценены. Сравнение с соседями требует соседей. Инструмент говорит об этом, а не сообщает чистый результат.

• Нет паспортных характеристик. Публичные узлы их не раскрывают, поэтому цифры потерь — это оценки, масштабированные от соседей, а не расчёты по гарантии.

• Обнаружение неисправностей работает на суточных интервалах. Устройство, молчавшее шесть часов, невидимо.

• Классификация потоков зависит от соглашения об именах. Станции, называющие потоки Main или SMAInverter1, возвращаются неклассифицированными.

Что он на самом деле делает

Без него ответ на вопрос "что-то не так на этой станции?" означает знание ID узла, конечной точки /datum/list, того, что существует aggregation=Day, что watts и wattHours — это разные вопросы, и затем чтение JSON.

С ним вы спрашиваете:

"Что-то не так на узле 1000? Если выработка упала, скажите, это погода или оборудование."

и агент обнаруживает потоки станции, выбирает диапазон дат, запускает агрегацию, сравнивает каждый инвертор с его соседями и отвечает на английском. Одно предложение на входе — диагноз на выходе.

Сервер делает те части, в которых языковая модель плоха — подпись запросов, пагинацию, семантику единиц, знание того, какой из девяти потоков является датчиком погоды. Агент делает те части, в которых он хорош — решает, что спросить, и интерпретирует ответ.

Посмотрите, как это работает за 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)

.vscode/mcp.json — обратите внимание, ключ называется servers, а не mcpServers:

{
  "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.

Проверка загрузки

Спросите своего агента: "Какие у тебя есть солнечные инструменты?" Вы должны увидеть десять. Если нет, обычные причины — относительный путь, отсутствующий npm run build или клиент не был перезапущен.

Инструменты

Обнаружение

Данные

Анализ

Отчётность

Что можно спросить

Начните с этого — это реальные, живые узлы:

Ориентация

Какие публичные узлы SolarNetwork активны в часовых поясах США?

Что измеряет узел 1000 и насколько далеко назад уходят его данные?

Прямо сейчас

Что узел 892 генерирует прямо сейчас и какая там погода?

Узел 892 несёт датчик погоды и пиранометр, поэтому агент получает температуру, облачность и облучённость вместе с выработкой.

Диагностика — самые интересные

Что-то не так на узле 1000?

Узел 892 перечисляет шесть инверторов, но я не вижу генерации. Что происходит?

Флот

Ранжируй узлы 880, 884, 953, 964, 976, 987 и 1000 по выработке за прошлую неделю. На какой мне смотреть в первую очередь?

Многошаговый, где видна цепочка

Найди живой узел в США с как минимум четырьмя инверторами и данными облучённости, затем продиагностируй его за последние две недели.

Что вы получаете в ответ

Реальный вывод diagnose_site на узле 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.

Вторая находка — суть всего проекта. INV/4 показывает 0 Вт, пока его три соседа выдают 400–700 Вт, что выглядит точно как мёртвый инвертор — и более ранняя версия этого инструмента так и говорила. Он не мёртв: его счётчик накопил 826 кВт·ч за тот месяц. Инверторы на одной станции используют разные соглашения о отчётности. Проверка здоровья, основанная только на watts, вызывала бы человека каждую ночь из-за работающего инвертора.

Ваши собственные узлы

Установите две переменные окружения, и сервер переключится с публичных конечных точек /pub на аутентифицированные /sec. Поверхность инструментов не меняется:

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

Аутентификация — это схема SNWS2 от SolarNetwork — HMAC-SHA256 по канонизированному запросу с ключом, ограниченным по дате. Она реализована, но не протестирована; у меня нет пары токенов для проверки.

Как это работает

Три файла, ~900 строк:

• src/solarnetwork.ts — API-клиент, пагинация, подпись запросов

• src/analysis.ts — разбор ID источников, диагностика станции

• src/index.ts — определения десяти инструментов

Описания инструментов — это настоящий интерфейс. Агент правильно связывает 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 с полным перечнем того, что публично, а что за учётными данными.

Лицензия

MIT