sens-mcp

これは、SENS Energy Data API（ポーランドの電力市場データ API。配電事業者、料金プラン、複合価格計算）向けの MCP（Model Context Protocol）サーバーおよび開発者向けスターターキットです。

これは、API と通信する LLM や AI エージェント（Claude Desktop、Cursor、LangChain、n8n など）が直面する「コールドスタート」問題を解決します。ポーランドのエネルギー市場には独自の語彙（OSD vs. sprzedawca、料金グループ G11/G12/G12w など）があり、モデルはそれらを初期状態では知りません。また、生の REST レスポンスは大きすぎるうえに、手計算で照合・計算すると誤りやすいものです。

sens-mcp が提供するもの:

• ゼロショットの発見 — MCP リソース（sens://market/cheat-sheet）と発見ツール（resolve_operator、search_tariffs）を使い、約400トークン未満の情報量でモデルに市場の語彙を学習させます。

• 実効的な自己修正 — ツールのエラーは生の HTTP エラーではなく、did you mean G12w? のような提案を含む構造化 JSON を返すため、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

AI エージェントでの利用

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 — ポーランド電力市場の語彙（OSD、料金グループ、価格構成要素の構造）をまとめた Markdown チートシート。

開発者向けサンプル (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 認証ではない、クエリパラメータでもない）

• 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=... — 単一のtariffの構成要素の詳細を取得。since にも対応。

完全な Swagger/OpenAPI ドキュメント: https://api.getsens.energy/api/docs。 詳細な開発者向けドキュメント（クイックスタート、MCP 連携ガイド、市場用語）: docs.getsens.energy。

開発

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

テストではすべての HTTP 呼び出しを respx でモックしています。デフォルトのテストスイートはライブ API に一切アクセスしません。

ライブ統合テストスイート（オプトイン）

tests/test_live_integration.py は、実際の MCP stdio プロトコルを介して実サーバーをサブプロセスとして起動し、実際の本番 SENS API に対して実行します。さらに、MCP ツールのレスポンスと、同じエンドポイントへの生の httpx 呼び出しがバイト単位で一致することを検証します。デフォルトでは除外されていますが、実際の API キーを使って明示的に実行できます：

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

ライセンス

MIT