Używanie SENS z agentami AI (MCP)

sens-mcp to serwer Model Context Protocol i starter kit dla deweloperów, który uczy modele LLM (Claude Desktop, Cursor, LangChain, n8n, ...) słownictwa polskiego rynku energii (OSD vs. sprzedawca, grupy taryfowe G11/G12/G12w/...) i pozwala im bezpiecznie odpytywać SENS API bez ręcznego pisania integracji REST.

Uwaga: repozytorium sens-toolkit jest obecnie lokalne i prywatne — link do GitHuba poniżej (SofiaFlux/sens-toolkit) zakłada docelową publikację jako open-source starter kit i nie jest jeszcze aktywny. Do czasu publikacji traktuj tę stronę jako opis docelowego stanu.

Dlaczego nie tylko surowe REST?

• Słownictwo rynku od razu dostępne — zasób MCP sens://market/cheat-sheet uczy model podstaw (OSD, sprzedawca, grupy taryfowe) w mniej niż ~400 tokenach, zamiast liczyć na to, że model "zgadnie" polskie nazewnictwo.
• Samo-naprawiające się błędy — narzędzia zwracają strukturalny JSON z sugestiami (did you mean G12w?) zamiast surowego błędu HTTP, więc agent w pętli ReAct może naprawić swoje kolejne wywołanie.
• Jedno źródło prawdy dla obliczeń — wszystkie wyliczenia cen/wolumenu dzieją się po stronie backendu SENS; toolkit nigdy nie przelicza sumy samodzielnie po stronie klienta.

Instalacja

uvx (zalecane, bez instalacji)

export SENS_API_KEY=sens_live_your_key_here
uvx sens-mcp

lub pip

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

Zmienna	Wymagana	Domyślnie	Opis
SENS_API_KEY	Tak	—	Twój klucz API SENS. Wysyłany jako nagłówek X-API-KEY.
SENS_BASE_URL	Nie	https://api.getsens.energy	Nadpisanie dla środowiska staging/self-hosted.

Konfiguracja Claude Desktop

Dodaj do claude_desktop_config.json:

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

Konfiguracja Cursor

Ten sam kształt w .cursor/mcp.json:

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

Dostępne narzędzia (tools)

Narzędzie	Przeznaczenie
resolve_operator(query, region=None)	Rozwiązuje literówki i nazwy potoczne miasta/firmy na dokładne wartości osd/sprzedawca oczekiwane przez API.
search_tariffs(customer_type, zone_preference=None, operator=None)	Wyszukuje pasujące kody taryf dla profilu klienta (gospodarstwo domowe / mała firma / przemysł).
get_prices(osd, taryfa, ...)	Pobiera złożone ceny i rozbicie stawek; przekaż annual_kwh dla dokładnych sum ważonych wolumenem.
get_tariff_components(tariff_id)	Pokazuje zatwierdzone przez URE składniki stałe/zmienne danej taryfy.

Zasób sens://market/cheat-sheet — ściąga w Markdown ze słownictwem polskiego rynku energii (OSD, grupy taryfowe, struktura składników ceny).

Repozytorium

Kod źródłowy, testy i przykłady: github.com/SofiaFlux/sens-toolkit (placeholder — repo jest dziś lokalne, zobacz uwagę na górze strony).