@arcote.tech/arc-mcp

Serwer Model Context Protocol dla Arc — wystawia narzędzia Arc (ArcTool) klientom MCP, takim jak Claude Desktop, przez transport streamable HTTP.

Te same toole obsługują czat AI w aplikacji i kanał MCP. Jedno źródło prawdy, zero duplikacji: ArcTool.toJsonSchema() daje kształt wymagany przez tools/list, a executeWithContext() jest wprost implementacją tools/call.

Użycie

import { mcpServer } from "@arcote.tech/arc-mcp";

export const subiektMcp = mcpServer("subiektMcp")
  .path("/mcp")
  .serverInfo({ name: "Berotex Subiekt", version: "1.0.0" })
  .instructions("Dane magazynowe i sprzedażowe z Subiekta GT.")
  .protectBy(workspaceToken, () => true)
  .scopeFrom((p) => p.workspaceId)
  .useTools(subiektTools)
  .build();

build() zwraca zwykły route, więc rejestrujesz go w context([...]) jak każdy inny element.

Realny URL to /route/mcp — prefiks /route dokłada host Arc i nie da się go pominąć.

Obsługiwane metody

| Metoda | Zachowanie | |---|---| | initialize | Negocjacja wersji (2025-06-18, 2025-03-26, 2024-11-05), capabilities.tools, serverInfo, opcjonalne instructions | | notifications/initialized | Notyfikacja — odpowiedź 202 bez ciała | | tools/list | Deskryptory z polem inputSchema | | tools/call | Wykonanie narzędzia → { content: [{ type: "text", text }] } | | ping | Pusty wynik |

Batch JSON-RPC (tablica wiadomości) jest obsługiwany, mimo że spec 2025-06-18 go wycofał — starsi klienci go używają, a koszt obsługi jest zerowy.

Decyzje projektowe

Serwer jest bezstanowy. Nie wydaje Mcp-Session-Id, a GET i DELETE zwracają 405 (spec wprost na to pozwala). Narzędzia Arc odpowiadają synchronicznie w ramach POST-a, więc kanał SSE server→client nie miałby czego nieść, a stan sesji w pamięci procesu psułby się przy wielu instancjach i przy federacji modułów.

Toole interaktywne są pomijane. Tool bez .handle(), który odpowiada przez respond() z interfejsu, nie ma odpowiednika w MCP — protokół nie potrafi poprosić klienta o interakcję użytkownika. Takie toole nie pojawią się w tools/list; sprawdzisz je przez getter .skippedTools. Jeśli żaden tool nie ma handlera, build() rzuca wyjątkiem, zamiast wystawić pusty serwer.

Błąd narzędzia to poprawna odpowiedź. Wyjątek z handlera wraca jako result z isError: true, nie jako błąd JSON-RPC — model ma go zobaczyć i zareagować, a błąd transportowy zerwałby mu kontekst. Błędami JSON-RPC są tylko naruszenia protokołu (nieznana metoda, brak nazwy narzędzia, zły JSON).

Zdolności resources i prompts nie są deklarowane. Arc nie ma czym ich wypełnić, a pusta zdolność tylko myli klientów.

Autoryzacja

Domyślnie route wymaga tokena — bez .protectBy() ani .public() host przepuści tylko żądania z dowolnym ważnym tokenem Arc. Token czytany jest z nagłówka Authorization: Bearer <token>, czyli dokładnie tak, jak wysyłają go klienci MCP.

.scopeFrom(fn) mapuje parametry tokena na wartość identifyBy widoczną w handlerach jako ctx.identifyBy — odpowiednik .billTo(...) z ArcChat.

Weryfikacja

curl -X POST localhost:5005/route/mcp \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <token>' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'