Tool Gateway

Tool Gateway to hub MCP (speedwave_<project>_mcp_hub) i jednocześnie jedyny serwer MCP widoczny dla Claude. Niezależnie od liczby włączonych integracji Claude otrzymuje dostęp do dokładnie dwóch narzędzi: search_tools oraz execute_code.

Dwa narzędzia

Narzędzie search_tools wyszukuje dostępne funkcje we wszystkich aktywnych integracjach, w tym w narzędziach systemowych. Z kolei execute_code przekazuje wykonanie do odpowiedniego workera, udostępniając każdą integrację w postaci nazwanego obiektu, np. redmine.listIssueIds().

Poglądowy fragment kodu dla execute_code

// Claude używa najpierw search_tools do odnalezienia tych wywołań.
const ids = await redmine.listIssueIds({ project: "speedwave" });
const issues = await batch(ids.map((id) => redmine.getIssue({ id })));
return issues.results;

Powyższe obiekty należy traktować jako przykład ilustrujący działanie mechanizmu, a nie jako stały kontrakt API.

1. Claude wywołuje search_tools ze słowem kluczowym, a hub zwraca pasujące nazwy narzędzi wraz z ich opisami.

2. Claude przygotowuje krótki skrypt wywołujący znalezione narzędzia.

3. Claude wywołuje execute_code z przygotowanym skryptem, po czym hub uruchamia go w piaskownicy (sandbox), przekazuje poszczególne wywołania do odpowiednich workerów i zwraca wynik.

Narzędzie pozostaje ukryte, dopóki nie zostanie odnalezione przez search_tools, co pozwala utrzymać niskie zużycie tokenów w dużych projektach. Worker może udostępnić narzędzie od razu, ustawiając flagę _meta: { deferLoading: false }.

Brak danych logowania w hubie

Każdy worker montuje wyłącznie własne poświadczenia w trybie tylko do odczytu; sam hub nie przechowuje żadnych danych uwierzytelniających. Szczegóły dotyczące tych gwarancji opisano w sekcji Model izolacji. Narzędzia systemowe działają inaczej: hub łączy się z nimi na hoście za pośrednictwem mostka HTTP, który rozpoznaje wyłącznie zdefiniowane nazwy usług.

flowchart LR
  Claude["Claude"] -->|search_tools| Hub
  Claude -->|execute_code| Hub["MCP hub (port 4000, zero tokenów)"]
  Hub -->|"gitlab.getMrFull()"| GL["worker gitlab (/tokens:ro)"]
  Hub -->|"redmine.listIssueIds()"| RM["worker redmine (/tokens:ro)"]
  Hub -->|"os.createEvent() przez mostek HTTP"| OS["narzędzia systemowe na hoście"]

Bezpieczna piaskownica (sandbox)

execute_code blokuje niebezpieczne API (eval, require, process oraz bezpośredni dostęp do systemu plików i sieci) jeszcze przed uruchomieniem skryptu, udostępniając jedynie ograniczoną listę bezpiecznych obiektów globalnych, takich jak JSON czy Array.

Rozważano cięższe mechanizmy izolacji, jednak zostały one odrzucone: biblioteka isolated-vm znajdowała się w trybie wyłącznie utrzymaniowym z plikami binarnymi niedopasowanymi do ABI środowiska Node 24, quickjs powodował problemy z batch() i Promise.allSettled przy operacjach asynchronicznych, a moduł vm środowiska Node nie stanowił rzeczywistej granicy bezpieczeństwa. Z tego względu execute_code bazuje na konstrukcji AsyncFunction z listą zablokowanych funkcji, a właściwą warstwę ochronną stanowi zabezpieczony kontener.

Uwaga

Ograniczenia piaskownicy należy traktować jako dodatkową linię obrony (defense in depth), a nie zastępstwo dla weryfikacji uprawnień samej integracji.

Ewentualna ucieczka z piaskownicy prowadzi jedynie do zabezpieczonego kontenera, który nie zawiera wrażliwych poświadczeń, a wszystkie wykonane operacje są odnotowywane w rejestrze audytowym.

Czytelne komunikaty błędów

Zanim błąd trafi do Claude, hub odpowiednio go sanityzuje: ścieżki do plików są zastępowane znacznikiem [file], numery linii zostają usunięte, a długość komunikatu jest ograniczana do 500 znaków. W przypadku wywołania nieistniejącej metody zwracana jest lista dostępnych metod danego obiektu, a błędy w nazewnictwie typu service_method otrzymują sugestię poprawki w formacie camelCase. Każdy błąd zawiera również flagę retryable (ustawianą na true m.in. przy przekroczeniu limitu czasu). Mechanizm ten działa wyłącznie w ramach bieżącej sesji; między sesjami hub nie zachowuje stanu.

Tokenizacja i audyt

Hub maskuje również wyniki integracji przed przekazaniem ich do Claude. Jest to jeden z dwóch punktów kontrolnych opartych na tym samym silniku: lokalne proxy projektu skanuje w analogiczny sposób wszystkie żądania kierowane do dostawcy modelu. Zasady działania tego mechanizmu opisano w artykule Tokenizacja. Informacje o wykrytych danych z obu punktów trafiają do plików audit-proxy.jsonl i audit-hub.jsonl w katalogu ~/.speedwave/audit/<project>/ jako zagregowane liczniki (z podziałem na warstwę, kategorię i akcję), bez zapisywania oryginalnych wartości. Niezależnie od tego hub rejestruje każde wywołanie execute_code, odnotowując jego typ, docelową integrację oraz przekazane parametry.

Jednolita ścieżka wykrywania dla wszystkich workerów

Wbudowane workery oraz zewnętrzne wtyczki korzystają ze wspólnego mechanizmu wykrywania i jednakowych zasad _meta – lista wbudowanych narzędzi nie jest na stałe zaszyta w kodzie. Jeśli dany worker jest niedostępny podczas startu huba, tworzony jest dla niego pusty wpis do czasu zaktualizowania stanu przez proces w tle. Więcej informacji o architekturze kontenerów znajdziesz w sekcji Workery.