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í. Format ak2_xxxxx (32 base64url znaků). SHA-256 hashed v DB — plain text se ti zobrazí jen 1× při vygenerování.
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
Kontext (čtení)
| Tool | Co vrátí |
|---|---|
ja2_bootstrap | All-in-one payload (kontext + značky + projekty + tools manifest + Angel operating instructions) |
ja2_get_personal_context | Osobní vrstva (5 slotů) |
ja2_get_expert_context | Expertní vrstva (2 sloty) |
ja2_get_angel_context | Angel persona (jak má mluvit) |
ja2_list_brands | Seznam značek + počet vyplněných slotů |
ja2_get_brand(brand_id) | Kontext konkrétní značky |
ja2_list_projects | Seznam projektů |
ja2_get_project(project_id) | 3-tier merged kontext: project + brand + global + user-meta |
ja2_get_my_crm | CRM profil — registrace, vstupenky, vouchery, support history (jen tvoje data, strict isolation) |
Kontext (zápis)
| Tool | Args | Co dělá |
|---|---|---|
ja2_update_context | scope, file_type, content_md, action | Přímý zápis (pro „zapamatuj si že…") |
ja2_log_insight | content_md, proposed_layer, confidence | Návrh změny → review v /checkpoint |
Studio (workspace, jen power user)
Vyžaduje permission akademie.workspace. Bez ní tooly vrátí Forbidden.
| Tool | Co dělá |
|---|---|
ja2_workspace_index | Preferovaný entry — overview všech files s headings, tagy, summary, by_folder, tags_index |
ja2_workspace_outline(path) | Heading tree jednoho souboru bez načtení celku |
ja2_workspace_read(path) | Načti konkrétní soubor |
ja2_workspace_search(query) | Fuzzy full-text search |
ja2_workspace_grep(pattern, is_regex?, case_sensitive?) | Precision regex search s line context |
ja2_workspace_list | Plain list paths (lightweight, preferuj index) |
ja2_workspace_write(path, content_md, title?) | Upsert soubor |
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.