Serwer MCP

https://zanreal.com/mcp to serwer Model Context Protocol, który udostępnia dokumentację z tej witryny (/docs) agentom AI i innym klientom MCP przez Streamable HTTP. Jest publiczny, bezstanowy i działa wyłącznie do odczytu - nie musisz się nigdzie rejestrować, generować klucza API, a żadne z jego narzędzi niczego nie zapisuje.

Wystarczy wskazać ten adres w dowolnym kliencie MCP, a ten będzie mógł wylistować, przeszukać i odczytać każdą stronę tej dokumentacji, w obu językach.

Podłączenie klienta

Dodanie serwera do klienta obsługującego Streamable HTTP sprowadza się do samego adresu URL:

{
  "mcpServers": {
    "zanreal-docs": {
      "url": "https://zanreal.com/mcp"
    }
  }
}

Można też rozmawiać z nim bezpośrednio. Każde żądanie to pojedynczy obiekt JSON-RPC 2.0 wysłany jako POST, z nagłówkami content-type: application/json oraz accept: application/json, text/event-stream - serwer odpowiada w formacie Streamable HTTP, czyli jedną ramką event: message / data: ..., a nie zwykłym JSON-em:

curl https://zanreal.com/mcp \
  -H "content-type: application/json" \
  -H "accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

event: message
data: {"result":{"tools":[{"name":"list_docs_pages", ...}, ...]},"jsonrpc":"2.0","id":1}

Wywołanie narzędzia wygląda tak samo, tylko z metodą tools/call i obiektem params wskazującym nazwę narzędzia i jego argumenty:

curl https://zanreal.com/mcp \
  -H "content-type: application/json" \
  -H "accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "get_docs_page",
      "arguments": { "path": "/docs/oss/search" }
    }
  }'

Serwer nie trzyma stanu w sesji HTTP - wywołanie initialize jest opcjonalne, więc klient, który od razu przechodzi do tools/list albo tools/call, zostanie obsłużony bez problemu. Każda odpowiedź niesie nagłówek Mcp-Session-Id dla klientów, które chcą go trzymać, ale żadne z poniższych narzędzi go nie wymaga.

Narzędzia

Wszystkie trzy narzędzia są tylko do odczytu (readOnlyHint: true) i żadne z nich nie przyjmuje argumentu, który cokolwiek zapisuje.

list_docs_pages

Listuje każdą stronę dokumentacji w kolejności, w jakiej pojawia się w panelu bocznym.

Zwraca tablicę JSON obiektów { title, url, description }, gdzie url to pełny link https://zanreal.com/... z prefiksem żądanej wersji językowej.

search_docs

Przeszukuje pełnotekstowo całą dokumentację i zwraca ranking trafień - zarówno całych stron, jak i pojedynczych nagłówków.

Każdy wynik ma pole type ("page" albo "heading"), dopasowaną treść (content), okruszki (breadcrumbs) oraz url, który można przekazać bezpośrednio do get_docs_page.

get_docs_page

Odczytuje jedną stronę jako gotowy Markdown - z rozwiniętymi już linkami względnymi i blokami instalacji pakietu.

path przyjmuje każdą z form, jakie zwracają dwa pozostałe narzędzia:

• pełny adres URL na tej witrynie (https://zanreal.com/pl/docs/oss/search/api)
• pełną ścieżkę na witrynie (/docs/oss/search/api, opcjonalnie z prefiksem językowym)
• gołą ścieżkę slugów (oss/search/api), opcjonalnie z prefiksem docs/ i wersją językową

Prefiks językowy w path zawsze wygrywa z argumentem locale. Zarówno list_docs_pages, jak i search_docs zwracają adresy, które już niosą prefiks językowy - a sens przekazania takiego adresu prosto do get_docs_page polega właśnie na tym, że strona wraca w języku, w którym została znaleziona. Dlatego jawny prefiks /pl/... jest respektowany, nawet jeśli wywołanie przekazało też locale: "en". Argument locale ma znaczenie tylko wtedy, gdy path nie niesie żadnego prefiksu - na przykład przy gołym slugu.

Adres spoza tej witryny jest odrzucany wprost, a nie reinterpretowany względem jej własnego drzewa dokumentacji.

Żądania i limity

CORS jest otwarty (Access-Control-Allow-Origin: *), więc klient MCP działający w przeglądarce może wywołać ten serwer bezpośrednio, bez proxy.

Kilka limitów, o których warto wiedzieć przed integracją:

• Ciało żądania jest ograniczone do 64 KiB. Realne wywołanie któregokolwiek z narzędzi jest niewielkie - najdłuższy pojedynczy argument to 300-znakowy path w get_docs_page - więc to spory zapas, nie ciasny budżet.
• Batching JSON-RPC jest odrzucany. Ciało będące tablicą JSON na najwyższym poziomie kończy się błędem {"error":{"code":-32600,"message":"JSON-RPC batching is not supported. ..."}} i kodem HTTP 400, zamiast zostać wykonane. Rewizja protokołu 2025-06-18 usunęła batching z MCP, a ten serwer nigdy go nie obsługiwał - wysyłaj jeden obiekt żądania na jedno żądanie HTTP.
• 60 żądań na minutę z jednego adresu IP. Przekroczenie limitu zwraca HTTP 429. Limiter działa w trybie „fail open" - gdy jego magazyn danych jest niedostępny, żądania są obsługiwane zamiast blokowane, bo ten endpoint i tak czyta wyłącznie publicznie dostępną dokumentację.

Opis w formacie do odczytu maszynowego

https://zanreal.com/.well-known/mcp/server-card.json publikuje listę narzędzi i adres tego serwera w jednym dokumencie JSON, dla klientów i katalogów, które odkrywają serwery MCP przez pobranie znanego adresu URL, zamiast najpierw się z nimi łączyć.