Spec — MCP tool invocation card

MCP normative source: https://modelcontextprotocol.io/specification/2025-11-25/server/tools. Companion: mcp-permission-prompt.kmd (consent gate antes do invoke), mcp-server-state.kmd (status do server que hospeda o tool).

Princípios

1. Visibility-first — todo tool call MUST aparecer na UI imediatamente, mesmo durante streaming.
2. No silent invocations — tool calls não documentados visualmente violam spec MCP.
3. Args + result side-by-side — usuário consegue auditar input e output.
4. Truncation com escape — outputs grandes truncados mas copy-to-clipboard sempre full.

R1 — Anatomia

┌─────────────────────────────────────────────┐
│  [🔧] tool_name           [status_badge]    │  ← header (clickable)
│  Tool from <server_origin_chip>             │
├─────────────────────────────────────────────┤
│  ▼ Arguments                                │  ← body (collapsed by default)
│  { "query": "...", "limit": 10 }            │
├─────────────────────────────────────────────┤
│  ▼ Result                                   │  ← footer (auto-expand on success)
│  [content rendered per R2]                  │
└─────────────────────────────────────────────┘

R2 — Result content types

MCP tools/call retorna content[] array. Cada item tem type ∈ {text, image, resource_link, embedded_resource}. Card MUST renderizar todos os 4 tipos:

Multiple content items: render sequencialmente em ordem, separados por divider de 1dp.

R3 — Status states

Badge no header per estado do tools/call:

Transições: pending → running → (success | error | cancelled). Card NUNCA pula direto de pending pra success (sempre passa por running).

R4 — Truncation

Outputs grandes (>2000 chars text, >500KB image):

• Text: collapse com "Show more" link após 30 linhas; full text mantido em DOM mas visualmente clipped.
• Image: thumbnail por default; tap-to-fullscreen overlay.
• Tool call args > 100 lines: collapse com "Expand args".

Copy-to-clipboard SEMPRE full, independente do estado visual.

R5 — Schema-driven form view (opcional)

Quando MCP tools/list[].inputSchema está presente (JSON Schema), card SHOULD oferecer toggle "Raw JSON" ↔ "Form view":

• Form view renderiza inputs schema-aware (string → text field, number → spinner, enum → segmented control, boolean → switch).
• Required fields marcados com asterisco; help text de description.
• Form é read-only (já invocado); modo edit-and-retry vai em ticket separado #re-invocation (futuro).

R6 — Surface bindings

Surfaces MUST exportar API consistente (constructor + state callbacks), diferindo apenas em props específicos do framework.

R7 — Multi-tenant + storage

Tool invocation persistida pra conversation history (cross-link #115) respeita policies/multi-tenant-by-default.kmd:

• Storage key: (koder_user_id, workspace_id, conversation_id, message_id, tool_call_id).
• Cross-tenant lookup retorna 404 (não 403, per multi-tenancy contract).
• Audit log da invocation persistido em services/foundation/audit/ com user + workspace + tool + args hash.

R8 — Acessibilidade

• Card é semanticamente <article role="region" aria-label="Tool invocation: <name>">.
• Status badge anuncia mudança via aria-live="polite".
• Args e result são <details><summary> em Web; equivalente expansível em Flutter/Compose.
• Reduced-motion: skip breathing dot animation; status muda direto.
• Screen reader: anuncia tool name + server origin + status; args só ao expandir.

R9 — Per-preset variation

T1 — Test contract

Toda surface implementadora MUST passar:

• T1 Mount: render card com estado pending + tool name visível + args collapsed.
• T2 Expand args: tap header → args visible; tap novamente → collapse.
• T3 Status transition: pending → running → success → render result; assert badge atualiza.
• T4 Error + retry: status error → retry button visible → tap → status volta a running.
• T5 Each content type: text, image, resource_link, embedded_resource (4 sub-tests).
• T6 Truncation: text > 2000 chars → "Show more" visible; expand → full text.
• T7 Copy-to-clipboard: copy ação copia full args (não truncado).
• T8 A11y: screen reader announces status change; reduced-motion skips breathing dot.

Cross-link

• Companion: mcp-permission-prompt.kmd, mcp-server-state.kmd
• Consumer pattern: chat-message-bubble.kmd hospeda tool cards inline
• Code rendering: code-block.kmd (referenciado em R2 text type)
• Tokens visuais: themes/color-roles.kmd, themes/typography.kmd R9
• Backend: services/ai/mcp/, services/ai/mcp-registry/
• MCP normative: https://modelcontextprotocol.io/specification/2025-11-25/server/tools