Architektura

Ta strona opisuje, jak Cryptohopper Market Data MCP jest zbudowany wewnętrznie, jak żądania przepływają przez system oraz jakie gwarancje zapewnia w zakresie świeżości i dostępności danych.

Dla wprowadzenia koncepcyjnego zobacz Czym jest MCP?

Przegląd komponentów

Cryptohopper MCP składa się z czterech warstw:

1. Warstwa protokołu: Implementuje specyfikację MCP — wykrywanie narzędzi, wywoływanie, strumieniowe odpowiedzi.
2. Warstwa uwierzytelniania i limitów: Weryfikuje tokeny bearer, wymusza dostęp do warstw cenowych, zlicza wywołania względem tygodniowych limitów.
3. Warstwa agregacji danych: Odpytuje zewnętrzne giełdy, normalizuje odpowiedzi do wspólnego schematu.
4. Konektory giełd: Adaptery dla poszczególnych giełd, które tłumaczą między natywnymi API giełd a wewnętrznym schematem.

Żądanie od klienta MCP przepływa przez wszystkie cztery warstwy po kolei.

Przepływ żądania

Typowe wywołanie narzędzia przebiega następująco:

1. Klient wysyła żądanie. Klient MCP wysyła żądanie JSON-RPC przez strumień SSE, zawierające nazwę narzędzia i argumenty.
2. Warstwa protokołu weryfikuje. Żądanie jest sprawdzane względem schematu JSON narzędzia. Nieprawidłowe żądania zwracają INVALID_PARAMETER lub MISSING_PARAMETER.
3. Warstwa uwierzytelniania weryfikuje token. Token bearer jest rozwiązywany do konta. Nieprawidłowe lub unieważnione tokeny zwracają UNAUTHORIZED.
4. Warstwa limitów sprawdza ograniczenia. Wywołanie jest zliczane względem tygodniowego limitu konta i krótkookresowego limitu szybkości. Przekroczenie któregokolwiek limitu zwraca QUOTA_EXCEEDED lub RATE_LIMIT_EXCEEDED.
5. Sprawdzenie warstwy cenowej. Żądana giełda oraz — dla zapytań o świece — głębokość historyczna są weryfikowane względem listy dozwolonych elementów warstwy cenowej. Naruszenia zwracają EXCHANGE_NOT_SUPPORTED lub HISTORY_LIMIT_EXCEEDED.
6. Warstwa agregacji przekierowuje. Żądanie jest kierowane do odpowiedniego konektora giełdy.
7. Konektor odpytuje zewnętrzne źródło. Konektor wykonuje odpowiednie wywołanie do zewnętrznego API giełdy.
8. Odpowiedź jest normalizowana. Zewnętrzna odpowiedź jest mapowana do wewnętrznego schematu i zwracana do klienta przez strumień SSE.

Każdy z tych kroków może zakończyć żądanie błędem. Semantyka błędów jest opisana w referencji błędów.

Transport

MCP używa HTTP z Server-Sent Events (SSE):

• Początkowe połączenie i uwierzytelnianie: standardowe żądanie HTTP.
• Bieżące wywołania narzędzi: dwukierunkowy przepływ JSON-RPC przez SSE.

Wybór SSE jest częścią specyfikacji MCP. Obsługuje strumieniowe odpowiedzi i długotrwałe połączenia bez narzutu niestandardowych handshake'ów websocket.

Punkt końcowy usługi to https://mcp-data.cryptohopper.com/mcp. Cały ruch jest szyfrowany TLS.

Bezstanowość

Serwer MCP nie przechowuje stanu sesji między żądaniami. Każde wywołanie narzędzia jest niezależne:

• Brak kursora lub iteratora po stronie serwera.
• Brak pamięci podręcznej dla sesji.
• Brak niejawnego kontekstu przenoszonym między wywołaniami.

Stan, który musi być zachowany między wywołaniami, jest odpowiedzialnością klienta. W przepływach pracy agentów model przechowuje stan w swoim własnym oknie kontekstu.

Świeżość danych

Każdy typ danych ma inny profil świeżości:

Typ danych	Źródło	Świeżość
Ticker	Zewnętrzna giełda	Niemal w czasie rzeczywistym, odświeżany przy każdym wywołaniu
Księga zleceń	Zewnętrzna giełda	Zrzut w momencie żądania; brak strumieniowych aktualizacji
Bieżąca świeca	Zewnętrzna giełda	Bieżący słupek odzwierciedla najnowsze transakcje
Historyczna świeca	Zewnętrzna giełda + pamięć podręczna	Niezmienna po zamknięciu świecy

Wywołania ticker i księgi zleceń zawsze pobierają dane z zewnętrznej giełdy. Historyczne świece mogą być serwowane z pamięci podręcznej, gdy słupek już się zamknął, ponieważ zamknięte słupki są niezmienne.

Uwaga: MCP nie zapewnia trybu strumieniowego pub/sub. Każde wywołanie to pobieranie danych w danym momencie.

Model agregacji

Każdy konektor giełdy implementuje ten sam wewnętrzny interfejs, ale opakowuje specyficzne API giełdy. Warstwa agregacji:

• Normalizuje formaty symboli. Giełdy używają różnych notacji par (BTCUSDT vs BTC-USDT vs BTC/USDT); MCP udostępnia jednolity format BASE/QUOTE.
• Harmonizuje nazwy pól. API giełd różnią się sposobem nazywania pól bid, ask, ostatniej ceny i wolumenu; MCP zwraca wspólny schemat.
• Obsługuje konwencje stref czasowych i znaczników czasu. Wszystkie znaczniki czasu w odpowiedziach są w formacie UTC, ISO-8601.
• Filtruje do obsługiwanych par. Rynki niebędące rynkami spot (perpetuals, opcje) są wyłączone z odpowiedzi MCP, nawet jeśli zewnętrzna giełda je oferuje.

Zobacz model danych dla pełnego schematu odpowiedzi.

Różnice między giełdami

MCP dąży do jednolitego wyjścia, ale różnice między zewnętrznymi giełdami nie zawsze mogą być całkowicie ukryte:

• Głębokość księgi zleceń. Różne giełdy udostępniają różne maksymalne głębokości. MCP zwraca to, co udostępnia zewnętrzne źródło.
• Interwały czasowe świec. Nie każda giełda obsługuje każdy interwał czasowy. Nieobsługiwane kombinacje zwracają TIMEFRAME_NOT_SUPPORTED.
• Historyczny zasięg wstecz. Giełdy różnią się tym, jak daleko wstecz serwują dane historyczne. Żądania w ramach limitów warstwy cenowej MCP mogą nadal zakończyć się niepowodzeniem, jeśli zewnętrzna giełda nie serwuje takiej głębokości; zwraca to DATA_UNAVAILABLE.

Możliwości poszczególnych giełd są odzwierciedlone w odpowiedzi na narzędzia list-pairs i list-exchanges.

Niezawodność zewnętrznych źródeł

Zewnętrzne API giełd mogą być niedostępne lub wolne. MCP nie ponawie wywołań zewnętrznych w imieniu klienta; niepowodzenie zewnętrznego źródła zwraca EXCHANGE_UNAVAILABLE lub DATA_UNAVAILABLE.

Oczekuje się, że klienci ponowią próbę w przypadku przejściowych błędów po krótkiej przerwie. Dobrze zaprojektowani klienci MCP robią to automatycznie.

Sam MCP jest zaprojektowany z myślą o wysokiej dostępności, ale zależy od kondycji zewnętrznych giełd dla kompleksowej niezawodności.

Współbieżność

Dozwolone są wielokrotne równoczesne wywołania narzędzi od pojedynczego klienta. Każde wywołanie jest niezależne i jest liczone osobno względem limitu. Limit szybkości ma zastosowanie zarówno do równoczesnych, jak i sekwencyjnych wywołań.

Klienci, którzy wykonują wiele jednoczesnych żądań, powinni ograniczać tempo, aby uniknąć osiągnięcia limitu szybkości.

Granica bezpieczeństwa

Serwer MCP:

• Kończy TLS na krawędzi.
• Weryfikuje token bearer przy każdym żądaniu.
• Nie przyjmuje ani nie działa na poświadczeniach dla żadnej zewnętrznej giełdy. Cały dostęp do zewnętrznych giełd wykorzystuje własne poświadczenia MCP, skonfigurowane po stronie serwera.
• Nie udostępnia klientowi surowych komunikatów o błędach zewnętrznej giełdy — błędy są mapowane do własnych kodów błędów MCP.

Klucze po stronie klienta to jedyne poświadczenia, które klienci muszą dostarczyć. Zobacz najlepsze praktyki bezpieczeństwa kluczy API.

Wersjonowanie

Powierzchnia protokołu MCP jest wersjonowana zgodnie ze specyfikacją MCP. Schematy narzędzi mogą ewoluować z czasem:

• Zmiany addytywne (nowe narzędzia, nowe opcjonalne argumenty, nowe pola odpowiedzi) nie powodują problemów ze zgodnością.
• Zmiany łamiące zgodność (usunięte pola, zmienione typy argumentów) są ogłaszane z wyprzedzeniem.

Klienci odkrywają bieżącą powierzchnię narzędzi dynamicznie przy połączeniu, więc zmiany addytywne wchodzą w życie bez ponownego wdrażania klienta.