MCP API¶

Dveřník poskytuje server Model Context Protocol (MCP) na adrese /mcp pomocí přenosu Streamable HTTP. To umožňuje AI agentům (např. Claude Code, OpenCode, Cursor) interagovat se systémem programově.

Konfigurace¶

Server MCP je řízen vlastností konfigurace MCP_ENABLED (proměnná prostředí nebo kolekce app_config), která ve výchozím nastavení má hodnotu false. Pokud je vypnutý, endpoint vrací HTTP 503.

Konfigurační klíč	Výchozí hodnota	Popis
`MCP_ENABLED`	`false`	Zapnutí/vypnutí serveru MCP za běhu

Server MCP lze přepínat dynamicky — změny MCP_ENABLED se projeví okamžitě bez restartu.

Autentizace¶

Všechny požadavky MCP vyžadují bearer token v hlavičce Authorization:

Authorization: Bearer dvmcp_<base64url token>

Tokeny se vytvářejí pro každého uživatele přes API nebo administrační rozhraní.

Vytvoření tokenu¶

Uživatelský endpoint:

POST /api/v1/me/api-tokens
Content-Type: application/json
Authorization: Bearer <pb_auth_token>

{"name": "my-claude-token"}

Administrátorský endpoint (pro libovolného uživatele):

POST /api/v1/admin/users/{userId}/api-tokens
Content-Type: application/json
Authorization: Bearer <pb_auth_token>

{"name": "my-claude-token"}

Odpověď obsahuje kompletní token (dvmcp_<base64url>) — je to jediná příležitost, kdy se zobrazí.

Seznam tokenů¶

GET /api/v1/me/api-tokens
Authorization: Bearer <pb_auth_token>

Zrušení tokenu¶

DELETE /api/v1/me/api-tokens/{tokenId}
Authorization: Bearer <pb_auth_token>

Připojení¶

OpenCode¶

{
  "mcp": {
    "my-dvernik": {
      "enabled": true,
      "type": "remote",
      "url": "https://my-instance.dvernik.cz/mcp",
      "headers": {
        "Authorization": "Bearer dvmcp_<your-token>"
      }
    }
  }
}

Claude Desktop¶

{
  "mcpServers": {
    "dvernik": {
      "type": "sse",
      "url": "https://your-instance.example.com/mcp",
      "headers": {
        "Authorization": "Bearer dvmcp_<your_token>"
      }
    }
  }
}

Nástroje¶

Uživatelské nástroje¶

Dostupné všem přihlášeným uživatelům.

Nástroj	Popis	Argumenty
`get_zones`	Seznam dostupných zón s cenami a obsazeností	—
`get_dashboard`	Získání přehledu (kredit, dluh, role, aktivní relace včetně `settlement` — jen pro čtení náhled vyúčtování, viz Relace a vyúčtování)	—
`start_session`	Zahájení relace v zóně (idempotentní)	`zone_id`
`end_session`	Ukončení aktivní relace; textový výsledek obsahuje `final_price` (cena po slevách a zaokrouhlení), zaokrouhlení (`rounding`) i `amount_due` (zbývá doplatit)	`session_id`
`get_active_session`	Získání detailů aktivní relace	—
`get_session_devices`	Seznam zařízení v relaci	`session_id`
`control_device`	Ovládání zařízení v relaci	`session_id`, `device_id`, `action`
`get_my_products`	Seznam zakoupených produktů	—
`get_products_catalog`	Seznam produktů k zakoupení	—
`purchase_product`	Zakoupení produktu za kredit	`product_id`
`get_my_topups`	Historie dobití kreditu	—
`create_topup`	Vytvoření požadavku na dobití kreditu	`amount`
`get_session_history`	Seznam minulých relací (každá s `final_price` = cena po slevách a zaokrouhlení, `discount` = jen skutečné slevy, `price_rounding` = ± zaokrouhlení a `amount_due` = zbývá doplatit; stejné pole má admin nástroj `list_sessions`)	`page` (nepovinné), `perPage` (nepovinné)
`get_session_timeline`	Časová osa akcí v relaci; každá událost má `status` (`success` \| `failed` \| `not_sent`) a u `failed` i `failure_reason`. Neúspěšné pokusy se do ceny nepočítají. Technický `error_detail` MCP nevrací.	`session_id`
`get_my_reservations`	Seznam rezervací	—
`create_reservation`	Vytvoření rezervace	`zone_id`, `date_start`, `time_start`, `time_end`, `date_end` (nepovinné), `purpose` (nepovinné), `description` (nepovinné), `is_recurring` (nepovinné), `weekday` (nepovinné)
`delete_reservation`	Smazání rezervace	`reservation_id`
`get_public_zones`	Získání veřejných informací o zónách	—
`ask_dvernik_help`	Zeptat se na konfiguraci, používání nebo řešení problémů Dveřníku	`question`
`search_documentation` nebo `documentation_lookup`	Hledat v dokumentaci	`question`

Administrátorské nástroje¶

Dostupné pouze uživatelům s rolí admin.

Nástroj	Popis	Argumenty
`list_users`	Seznam uživatelů (volitelný filtr vyhledávání)	`search` (nepovinné)
`get_user_products`	Získání zakoupených produktů uživatele	`user_id`
`assign_product`	Přiřazení produktu uživateli	`user_id`, `product_definition_id`
`remove_user_product`	Odebrání produktu od uživatele	`user_product_id`
`list_api_tokens`	Seznam API tokenů uživatele	`user_id`
`revoke_api_token`	Zrušení API tokenu	`token_id`
`list_presets`	Seznam vestavěných předvoleb konfigurace (zařízení, produkty, region, ceníky)	`kind` (nepovinné), `target` (nepovinné, objekt)
`validate_config`	Zkušební kontrola hodnoty podle kontraktu, nic se neukládá; vrací `{valid, issues[]}`	`kind`, `target` (nepovinné), `value`
`get_config_health`	Existující záznamy, které nesplňují kontrakty (stejný dokument jako `GET /api/v1/admin/config/health`)	—

Nástroje pro konfiguraci volají stejné služby jako administrátorské REST endpointy (/api/v1/admin/presets, /api/v1/admin/contracts/validate, /api/v1/admin/config/health), takže se výsledky neliší. Hromadný export a import instalace se přes MCP záměrně nenabízí — zůstává vědomou akcí v administraci (viz Nová instalace). Podrobnosti o kontraktech viz Kontrakty a předvolby.

Příklad: `validate_config`¶

{ "kind": "product", "target": { "product_type": "entry_bundle" }, "value": { "entries": 0 } }

Odpověď:

{ "valid": false, "issues": [ { "path": "entries", "message": "...", "severity": "error" } ] }

Druhy (kind): device (target.communication_adapter, target.device_type, hodnota = adapter_config), product (target.product_type, hodnota = parameters), app_config (target.key, hodnota = text), zone_pricing_rule a device_pricing_rule (hodnota = jedno pravidlo). Varování (severity: warning) ukládání neblokují.

Idempotence¶

start_session je idempotentní. Více volání pro stejného uživatele ve stejné zóně vrací stejné ID relace s Created=false při opakovaných voláních. Toto je bezpečné i při souběžném přístupu — mutex pro dvojici (uživatel, zóna) zabraňuje souběhu.

Formát odpovědi¶

Všechny nástroje vrací odpovědi ve formátu JSON nebo prostý text. Při chybě odpověď sleduje formát:

<error_code>: <detail chyby>

Běžné kódy chyb: - unauthorized — Neplatný nebo chybějící token - zone_at_capacity — Zóna dosáhla maximálního počtu souběžných relací - zone_closed — Zóna je momentálně uzavřená - max_debt_exceeded — Dluh uživatele překračuje maximální povolený - insufficient_credit — Uživatel nemá dostatečný kredit - session_not_active — Pokus o ukončení relace, která není aktivní