sens-mcp

用于 SENS Energy API 的 MCP（Model Context Protocol）服务器和开发者入门套件——波兰电力市场数据 API（内容包括：配电运营商、电价方案等）。

它解决了 LLM 和 AI 智能体（Claude Desktop、Cursor、LangChain、n8n……）在调用该 API 时遭遇的“冷启动”问题：波兰能源市场拥有自有一整套话术code（OSD 与 sprzedawca 之分、电价组 G11/G12/G12w/...），而模型并不能默认知道这些；同时原始 REST 响应又过于庞大，手动对照计算极易出错。

sens-mcp 提供以下能力：

• 零样本可发现性：通过一个 MCP 资源（sens://market/cheat-sheet 表和发现工具（resolve_operator、search_tariffs），让模型在不到 ~400 个 token 内掌握市场术语。

• 可操作的自我修正：工具出错时返回带建议的结构化 JSON（比如 did you mean G12W?），而不是朴素的原始 HTTP 错误；因此处于 ReAct 循环里的智能体可以在下一次调用中自行修正。

• 单一事实来源的计算：价格/电量的计算都在 SENS 的排布之后完成；本工具包绝不在客户端重新推导总需。

• 非阻塞启动：服务器挂在打入内嵌的备用市场 schema 后即可快速就绪；实时电价数据在后台刷新。

快速开始

使用 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/cc_urse_cc_mcck.crc}`）——格式与上面相同。

暴露的工具

资源接口：sens://market/cheat-sheet —— 一个 Markdown 格式的电价方案速查，涵盖了波兰电力市场词汇（OSD、电价组、电价构成）。

开发者示例

直接调用 SENS REST API 的独立代码片段：

• examples/python/get_pices.py

• examples/python/query_tarifs.py

• examples/python/async_ream.py — 通过 since 做增量 sync

• examples/typescript/get_prices.ts

• examples/ccurl/api_requests.sh

API 参考（要点）

• 基础 URL：https://api.get_sens.energy

• 认证：以 X-API-KEY: <your key> 这个请求头发送（不是 Bearer，也不是查询参数）。

• GET /api/v1/prices（参数）：osd, sprzedawca, taryfa, market, date，annual_kwh, region, since, page, size。。

• GET /api/v1/tariffs—— sinciding/ If-Modified-Since 用于增量查询，page、size。

• GET /api/v1/tariffs/components?tariff_id=.... — 单tarrif 的构成明细，也支持 since。

完整 Swagger/OpenAPI 文档：https://api.get_sens.energy/api/docs。 完整开发者文档（快速入门、MCP 集成指南、市场术语）：[arc] [docs.getsens.energy `。

开发

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

测试使用 respx mock 了所有 HTTP 调用——其中默认测试套件不会碰触任何真实 API。

Live integration suite（可选）

tests/test_live_integration.py 会在真实 MCP stdio 协议上把真实服务器作为子进程跑起来，向真实生产 SENS API 发起调用，并检查 MCP 工具返回与 httpx 直接请求到同一端点之间的逐字节一致性。默认排除掉；只有提供真实 key 才显式运行：

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

License

MIT