MCP server — technický manuál
JÁ² Akademie implementuje MCP Streamable HTTP transport (jeden POST endpoint, JSON-RPC 2.0).
Endpoint
POST /api/mcp
Content-Type: application/json
Authorization: Bearer <tvuj-token>
Token získáš v /konektory po přihlášení. Je to podepsaný JWT (začíná eyJ…), scopovaný na tvůj účet a roli — zobrazí se jen 1× při vygenerování, pak už ho z akademie nevyčteš. Klíč jde kdykoli zneplatnit (revoke) v /konektory.
JSON-RPC 2.0 methods
| Method | Auth | Co dělá |
|---|---|---|
initialize | bez | Handshake (protocolVersion: "2024-11-05") |
notifications/initialized | bez | Ack od klienta (no response) |
tools/list | Bearer | Seznam všech tools |
tools/call | Bearer | Spustí konkrétní tool |
Error codes
| Code | Význam |
|---|---|
-32700 | Parse error (invalid JSON) |
-32600 | Invalid Request |
-32601 | Method not found |
-32602 | Invalid params |
-32603 | Internal error |
-32001 | Unauthorized (chybí token, neznámý, revoked) |
Dostupné tooly
Tooly jsou konsolidované podle domény — jeden tool na doménu, konkrétní operaci vybírá parametr action (např. ja2_project { action: "list" }). Autoritativní a vždy aktuální seznam ti vrátí ja2_help (průvodce) a ja2_capabilities (strojový výpis podle tvé role) — dokumentace níže je orientační mapa.
Jádro
| Tool | Co dělá |
|---|---|
ja2_bootstrap | All-in-one payload (kontext + projekty/prostory + manifest toolů + operating instructions) — 1× na začátku session |
ja2_help | Průvodce: co umím, jak na typické úkoly |
ja2_capabilities | Strojový seznam všech toolů dostupných tvé roli |
ja2_me | Tvůj kontext — vrstvy (osobní / expertní / podnikatelská) + CRM profil (jen tvoje data) |
ja2_project | Projekty a prostory — list / get (merged kontext: projekt + nadřazené prostory + globál) / zakládání a plnění |
ja2_remember | Zápis do paměti — fakt (slot), aktualizace kontextové vrstvy, nebo postřeh čekající na tvé schválení |
ja2_recall | Hledání v tvé paměti (poznámky vč. archivu) |
ja2_skill | Knihovna dovedností — list / get |
Studio (workspace, power user)
ja2_workspace — jeden tool s akcemi index (preferovaný vstup) / outline / read / search / grep / list / write. Vyžaduje permission akademie.workspace; bez ní vrací Forbidden.
Další domény
Kurzy a výuka (ja2_course / ja2_chapter / ja2_lesson), komunita (ja2_community / ja2_post / ja2_event / ja2_enrollment), zázraky (ja2_miracle), Signál (ja2_mise), sdílení souborů (ja2_folder / ja2_share / ja2_window), a pro průvodce ja2_student / ja2_call. Přesný výčet pro tvou roli = ja2_capabilities.
Klient: doporučený workflow
1. initialize → handshake
2. tools/list → vidíš, co máš k dispozici
3. tools/call ja2_bootstrap → načti celý kontext (1× za session)
4. … další tools podle potřeby …
Tools manifest (bez auth)
Bezpečný discovery endpoint pro statickou kontrolu — vrátí JSON s manifest tools (bez user data):
GET /api/mcp/tools
Vrátí: { tools: [{name, description, args?}, ...] }. Tento endpoint nevyžaduje Bearer token (jen čtení manifestu).
Raw dokumentace pro AI
Pokud jsi AI agent (např. Claude), můžeš si stáhnout tuto stránku jako čistý markdown:
GET /api/docs/mcp
Vrátí text/markdown; charset=utf-8 bez HTML formátování. Hodí se pro RAG / reference.