sens-mcp

MCP-сервер (Model Context Protocol) и стартовый набор для разработчика для SENS Energy Data API — API рынка электроэнергии Польши (операторы распределительной сети, тарифы и расчёт составных цен).

Он решает проблему «холодного старта» для LLM и ИИ-агентов (Claude Desktop, Cursor, LangChain, n8n, ...), которые обращаются к API: у польского рынка электроэнергии есть собственная терминология (OSD против sprzedawca, тарифные группы G11/G12/G12w/...), которую модели не знают из коробки, а «сырые» REST-ответы слишком большие, и в них легко ошибиться при ручном расчёте.

sens-mcp предоставляет:

• Zero-shot обнаружимость — MCP-ресурс (sens://market/cheat-sheet) и инструменты поиска (resolve_operator, search_tariffs), которые знакомят модель с терминологией рынка за ~400 токенов.

• Практичная самокоррекция — ошибки инструментов возвращают структурированный JSON с подсказками (did you mean G12w?), а не «сырые» сбои HTTP, поэтому агент в цикле ReAct может исправить свой следующий вызов.

• Единый источник истины для расчётов — вся математика цен/объёмов выполняется на бэкенде SENS; инструмент никогда не пересчитывает итоги на стороне клиента.

• Некблокирующий запуск — сервер стартует мгновенно со встроенной резервной схемой рынка; актуальные метаданные тарифов обновляются в фоновом режиме.

Быстрый старт

Запуск через uvx (рекомендуется, без установки)

export SENS_API_KEY=sens_live_your_key_here
uvx sens-mcp

Или установка через pip

pip install sens-mcp
export SENS_API_KEY=sens_live_your_key_here
python -m sens_mcp

Переменные окружения

Related MCP server: US ISO Grid MCP

Использование с ИИ-агентом

Claude Desktop

Добавьте в claude_desktop_config.json (см. configs/claude_desktop_config.json):

{
  "mcpServers": {
    "sens-energy": {
      "command": "uvx",
      "args": ["sens-mcp"],
      "env": {
        "SENS_API_KEY": "sens_live_your_key_here"
      }
    }
  }
}

Cursor

Добавьте в .cursor/mcp.json (см. configs/cursor_mcp.json) — так же, как в примере выше.

Предоставляемые инструменты

Ресурс: sens://market/cheat-sheet — шпаргалка в формате Markdown по терминологии польского рынка электроэнергии (OSD, тарифные группы, структура ценовых компонентов).

Примеры для разработчиков (MCP не требуется)

Автономные фрагменты кода, обращающиеся к SENS REST API напрямую:

• examples/python/get_prices.py

• examples/python/list_tariffs.py

• examples/python/async_stream.py — дельта-синхронизация через since

• examples/typescript/get_prices.ts

• examples/curl/api_requests.sh

Справочник по API (основное)

• Базовый URL: https://api.getsens.energy

• Аутентификация: заголовок X-API-KEY: <ваш ключ> (не Bearer и не query-параметр).

• GET /api/v1/prices — osd, sprzedawca, taryfa, market, date, annual_kwh, region, since, page, size (макс. 1000).

• GET /api/v1/tariffs — since/If-Modified-Since для дельта-запросов, page, size.

• GET /api/v1/tariffs/components?tariff_id=... — разбивка компонентов для отдельного тарифа; также поддерживает since.

Полную документацию Swagger/OpenAPI: https://api.getsens.energy/api/docs. Полную документацию для разработчиков (quickstart, гайд по MCP-интеграции, терминология рынка): docs.getsens.energy.

Разработка

python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
pytest

Тесты подменяют все HTTP-вызовы с помощью respx — ничего в тестовом наборе по умолчанию не обращается к реальному API.

Jивые интеграционные тесты (по желанию)

tests/test_live_integration.py запускает реальный сервер как подпроцесс через реальный протокол MCP stdio на реальную продукционную SENS API и проверяет побайтовое совпадение ответов MCP-инстру-Men и «сырых» вызовов httpx к тем же endpoint. Тест отключён по умолчанию; запуск явно с настоящим ключом:

SENS_API_KEY=<a real key> pytest -m live tests/test_live_integration.py -v

Лицензия

MIT