# Připojení wiki k Claude Desktop (MCP)

Wiki vystavuje **MCP server** na `https://api.wiki.s2.emersion.eu/mcp` (sprint #22).
Když si ho v Claude Desktop přidáš jako external MCP server, **Claude (cloudová verze)**
získá agentic přístup ke všem wiki tools — search, read, list-recent, ask, suggest-edit,
ingest-text. Claude pak při dotazech sám rozhoduje co a kdy ve wiki číst.

## Co k tomu potřebuješ

1. **Claude Desktop** — https://claude.ai/download
2. **Bearer token** z Keycloaku — viz níže, vyrobíš si ho jednorázově

## 1) Vyrobit access token z Keycloaku

Wiki MCP endpoint je Bearer-gated. Stáhneš si JWT z Keycloaku přes `direct grant` flow
nebo z prohlížeče (DevTools → cookies → `next-auth.session-token` → decode).

Nejjednodušší cesta — přihlásíš se ve wiki UI a v DevTools si vykopíruješ token:

```bash
# 1. Login do https://wiki.s2.emersion.eu
# 2. DevTools (F12) → Application/Storage → Cookies → vyhledej
#    "next-auth.session-token" (httpOnly), zkopíruj hodnotu
# 3. Pošli tento token k /api/auth/session a vrátí accessToken:
curl -sS https://wiki.s2.emersion.eu/api/auth/session \
  -H "Cookie: next-auth.session-token=<paste-here>" \
  | jq -r .accessToken
```

Token má omezenou životnost (typicky 5–15 min — Keycloak default).
Pro dlouho-běžné MCP připojení doporučuji **registrovat samostatný MCP client** v Keycloaku
s `client_credentials` flow → token nikdy nevyprší (nebo se obnovuje).

### Alternativa: dedikovaný service-account v Keycloak (doporučeno)

V Keycloak admin UI (`https://auth.wiki.s2.emersion.eu/admin/master/console`):

1. **Clients → Create client**
   - Client ID: `emersion-mcp-petr` (vlastní per-user)
   - Capability config: **Service accounts roles** ✓, **Client authentication** ✓
2. **Credentials** záložka → zkopíruj **Client secret**
3. **Service account roles** záložka → přiřaď stejné role jako máš ty (editor, admin, ...)
4. Vyrobíš token:

```bash
curl -sS -X POST \
  https://auth.wiki.s2.emersion.eu/realms/emersion/protocol/openid-connect/token \
  -d 'grant_type=client_credentials' \
  -d 'client_id=emersion-mcp-petr' \
  -d 'client_secret=<paste>' \
  | jq -r .access_token
```

Tenhle access_token má lifetime per realm setting (default ~5 min ale automaticky
obnovitelný — viz níže). Pro Claude Desktop si ho buď refreshuj manuálně každý den,
nebo si napiš mini wrapper co obnovuje + ukládá do `~/.claude/mcp-tokens/`.

## 2) Nakonfigurovat Claude Desktop

Claude Desktop config soubor:
- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
- Linux: `~/.config/Claude/claude_desktop_config.json`

Přidej do `mcpServers`:

```json
{
  "mcpServers": {
    "emersion-wiki": {
      "url": "https://api.wiki.s2.emersion.eu/mcp",
      "transport": "http",
      "headers": {
        "Authorization": "Bearer <paste-tvuj-token>"
      }
    }
  }
}
```

Restart Claude Desktop.

## 3) Použít

V Claude Desktop chatu uvidíš ikonu MCP (řezačka / connector) — wiki tools tam budou
viditelné. Zeptej se Claude něčeho jako:

> Kdo z naší engineering teamu má zkušenosti s Postgres? Najdi to v wiki Emersion.

Claude začne sám volat `search_wiki` → `read_page` → znovu search → ... a odpoví
s citacemi `[[wiki/...]]`. To je agentic flow — stejný princip jako v interním
chatu po sprint #28, ale tady ho realizuje **Anthropic Claude** namísto naší
backend instance.

## Co funguje vzdáleně

| Tool | Co umí | Auth role |
|---|---|---|
| `search_wiki` | hybridní hledání (BM25 + pgvector) | viewer+ |
| `read_page` | full markdown jedné stránky | viewer+ + RBAC ceiling |
| `list_recent` | stránky upravené v posledních N dnech | viewer+ |
| `ask_question` | spustí interní chat-RAG nad wiki, vrátí odpověď | viewer+ |
| `suggest_edit` | vytvoří `proposal` v inboxu (čeká na schválení) | editor+ |
| `ingest_text` | pošle paste do ingest pipeline | editor+ |

Všechny tools sdílí stejnou RBAC matrix jako wiki web UI — confidential stránky
viewer nevidí ani přes MCP.

## Troubleshooting

| Symptom | Příčina | Fix |
|---|---|---|
| `401 invalid_token` | token vypršel | re-fetch token přes service-account |
| `401 azp mismatch` | použil jsi token z `emersion-web` (NextAuth) | musíš vytvořit token z `emersion-mcp*` clientu |
| Žádné tools v Claude Desktop | špatná URL / firewall | curl `/mcp` ručně + zkontroluj `/.well-known/oauth-protected-resource` |
| Pomalé odpovědi | reranker cold-start v search_wiki | první call ~3 s, další <1 s (sprint #28 fix) |

## Princip

```
   Claude Desktop (Anthropic cloud)
        │
        │  MCP protocol (JSON-RPC over HTTP, Bearer auth)
        ▼
   https://api.wiki.s2.emersion.eu/mcp
        │
        ├─ /tools/list      ← Claude si vypíše dostupné tools
        ├─ /tools/call      ← Claude volá search_wiki / read_page / ...
        └─ /.well-known/    ← OAuth Protected Resource discovery (RFC 9728)
        │
        ▼
   wiki-api (Hono) + wiki-postgres + wiki-reranker + wiki-ollama
```

Wiki MCP server **neholí žádný LLM sám** — je to čistě tool registry. Claude
(cloudový) si dělá agentic loop sám, MCP jen poskytuje data.