sens-mcp

Un servidor MCP (Model Context Protocol) y kit de inicio para desarrolladores para la SENS Energy API — la API de datos del mercado eléctrico polaco (operadores de distribución, tarifas y cálculos de precios compuestos).

Resuelve el problema del «arranque en frío» para los LLM y los agentes de IA (Claude Desktop, Cursor, LangChain, n8n, ...) que se comunican con la API: el mercado eléctrico polaco tiene su propio vocabulario (OSD vs. sprzedawca, grupos tarifarios G11/G12/G12w/...) que los modelos no conocen de serie, y las respuestas REST sin procesar son demasiado grandes y demasiado fáciles de mal calcular a mano.

sens-mcp ofrece:

• Descubribilidad zero-shot — un recurso MCP (resource: sens://market/cheat-sheet) y herramientas de descubrimiento (resolve_operator, search_tariffs) que enseñan al modelo el vocabulario del mercado en menos de ~400 tokens.

• Autocorrección accionable — los errores de las herramientas devuelven JSON estructurado con sugerencias (did you mean G12w?) en lugar de fallos HTTP sin formato, de modo que un agente en un bucle ReAct pueda reparar su propia llamada siguiente.

• Cálculos de una única fuente de verdad — todo el cálculo de precios/volúmenes se realiza en el backend de SENS; la herramienta nunca recalcula los totales por su cuenta en el lado del cliente.

• Inicio no bloqueante — el servidor arranca al instante con un esquema de mercado de respaldo incorporado; los metadatos de tarifas en tiempo de ejecución se refrescan en segundo plano.

Inicio rápido

Ejecutar con uvx (recomendado, sin paso de instalación)

export SENS_API_KEY=sens_live_your_key_here
uvx sens-mcp

O instalarlo con pip

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

Variables de entorno

Related MCP server: US ISO Grid MCP

Uso con un agente de IA

Claude Desktop

Añádelo a claude_desktop_config.json (consulta configs/claude_desktop_config.json):

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

Cursor

Añádelo a .cursor/mcp.json (consulta configs/cursor_mcp.json) — la misma estructura que el anterior.

Herramientas expuestas

Recurso: sens://market/cheat-sheet — una hoja de referencia rápida de Markdown con el vocabulario del mercado eléctrico polaco (OSDs, grupos de tarifas y estructura de los componentes de precio).

Ejemplos para desarrolladores (no requiere MCP)

Fragmentos de código independientes que acceden directamente a la API REST de SENS:

• examples/python/get_prices.py

• examples/python/list_tariffs.py

• examples/python/async_stream.py — sincronización delta con since

• examples/typescript/get_prices.ts

• examples/curl/api_requests.sh

Referencia de la API (lo esencial)

• URL base: https://api.getsens.energy

• Autenticación: cabecera X-API-KEY: <your key> (no es Bearer, sino un parámetro de consulta).

• GET /api/v1/prices — osd, sprzedawca, taryfa, market, date, since, page, size (máx. 1000).

• GET /api/v1/tariffs — since/If-Modified-Since para consultas delta, page, size.

• GET /api/v1/tariffs/components?tariff_id=... — desglose de componentes para una única tarifa; admite también since.

Documentación completa de Swagger/OpenAPI: https://api.getsens.energy/api/docs. Documentación completa para desarrolladores (inicio rápido, guía de integración MCP, vocabulario del mercado): docs.getsens.energy.

Desarrollo

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

Las pruebas simulan todas las llamadas HTTP con respx — nada en la suite de pruebas predeterminada llega a la API real.

Suite de integración en vivo (optativo)

tests/test_live_integration.py ejecuta el servidor real como subproceso sobre el protocolo stdio real de y MCP sobre la API real de producción de SENS, y comprueba la paridad byte a byte entre las respuestas MCP de las herramientas y las llamadas directas de httpx a los mismos endpoints. Excluida por defecto; ejecútala explícitamente con una clave real:

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

Licencia

MIT