Przejdź do głównej zawartości

Context7: aktualna dokumentacja bibliotek dla agenta (MCP, CLI i tryb skills)

Context7 to usługa dokumentacyjna Upstash dla agentów kodujących: na żądanie zwraca dokumentację i przykłady kodu dla konkretnej wersji biblioteki, przez zdalny serwer MCP, pakiet @upstash/context7-mcp albo CLI ctx7 ze skillem, bez MCP. Ogranicza błędy wynikające z przestarzałego API, ale dowodem poprawności kodu pozostają type check i testy.

Prosisz agenta o przechwytywanie żądań w Next.js, a on pisze middleware.ts. Kod się kompiluje, tylko że framework już to wycofał: od Next.js 16.0.0 konwencja pliku to proxy.ts (dokumentacja API proxy.js Next.js, odczyt 2026-09-26). Model nie jest niedbały. Jego dane treningowe kończą się przed wydaniem, które masz zainstalowane, a nic w sesji nie powiedziało mu, że jest inaczej.

Ta strona jest dla programistów, którzy chcą, żeby agent pisał pod wersję biblioteki z lockfile’a, i dla tech leadów, którzy chcą, żeby to był domyślny standard zespołu, a nie nawyk jednej osoby.

  • Context7 zainstalowany w Claude Code, Codex i Cursorze, z kluczem API poza commitowanymi plikami.
  • Wybór między trybem MCP a trybem CLI + Skills, z jasno opisanym kompromisem.
  • Prompty, które przypinają ID biblioteki i wersję, żeby agent nie zgadywał, o który pakiet ci chodzi.
  • Proces aktualizacji zależności: Context7 dla nowego API, potem codemod, testy i review.
  • Krótką listę innych serwerów dokumentacji i skilli dostawców na przypadki, których Context7 nie pokrywa.
  • Siedem typowych awarii i sposób wyjścia z każdej.

Serwer MCP w wersji @upstash/context7-mcp 4.1.1 (npm, sprawdzone 2026-09-26) udostępnia dokładnie dwa narzędzia:

NarzędzieArgumentyCo robi
resolve-library-idlibraryName, queryZamienia nazwę, np. „next.js”, na ID biblioteki w Context7, np. /vercel/next.js, z rankingiem względem twojego zadania
query-docslibraryId, queryZwraca fragmenty dokumentacji i przykłady kodu tej biblioteki pasujące do zadania

Typowe wyszukanie to dwa wywołania: najpierw resolve, potem query. Gdy podasz ID w prompcie („use library /vercel/next.js”), agent pomija pierwsze wywołanie. To szybsze i eliminuje najczęstszy błąd: trafienie w fork albo pakiet o podobnej nazwie.

CLI odwzorowuje te same dwa kroki: ctx7 library <name> [query] i ctx7 docs <libraryId> <query> (ctx7 0.5.12, --help, sprawdzone 2026-09-26).

Upstash daje dwa sposoby podłączenia tej samej usługi. CLI ctx7, które przeprowadza konfigurację i obsługuje tryb skills, wymaga Node.js 18 lub nowszego.

Tryb MCPTryb CLI + Skills
Co się instalujeWpis serwera wskazujący na https://mcp.context7.com/mcp (albo lokalny proces stdio)Skill, który każe agentowi uruchamiać w powłoce ctx7 library i ctx7 docs
Kiedy agent z tego korzystaGdy sam zdecyduje się wywołać narzędzie albo gdy napiszesz „use context7”Gdy opis skilla pasuje do zadania; skill uruchamia się przy pytaniach o biblioteki
Gdzie działaW każdym kliencie MCP: Claude Code, Codex, Cursor i ponad 30 innych (README Upstash)W agentach, które ładują skille i mogą uruchamiać polecenia powłoki
Kiedy wybraćZespół już centralnie zarządza serwerami MCPChcesz krótkiej listy serwerów MCP albo agent nie obsługuje MCP

npx ctx7 setup pyta o tryb, loguje cię przez OAuth, generuje klucz API i zapisuje konfigurację. Dodaj --mcp albo --cli, żeby pominąć pytanie, oraz --claude, --codex lub --cursor, żeby wskazać jednego agenta. -p konfiguruje bieżący projekt zamiast profilu użytkownika. npx ctx7 remove cofa zmiany.

Najszybsza ścieżka jest wszędzie ta sama: uruchom w terminalu npx ctx7 setup i odpowiedz na pytania. Ścieżki ręczne poniżej są dla zespołów, które chcą trzymać konfigurację w repozytorium albo kontrolować, gdzie leży klucz.

Darmowy klucz API z panelu Context7 podnosi limity zapytań. Hostowany serwer działa też bez klucza.

Zdalny serwer, zakres projektu, klucz czytany ze zmiennej środowiskowej (przetestowane na Claude Code 2.1.283):

Okno terminala
claude mcp add --scope project --transport http context7 https://mcp.context7.com/mcp \
--header 'Authorization: Bearer ${CONTEXT7_API_KEY}'

Pojedyncze cudzysłowy są tu istotne. Claude Code zapisuje w .mcp.json dosłownie "Authorization": "Bearer ${CONTEXT7_API_KEY}" i rozwija zmienną w czasie działania, więc możesz zacommitować plik bez klucza.

Alternatywy:

Okno terminala
# Lokalny proces stdio, zakres użytkownika; serwer czyta CONTEXT7_API_KEY ze środowiska
claude mcp add --scope user context7 -e CONTEXT7_API_KEY=YOUR_API_KEY -- npx -y @upstash/context7-mcp@4.1.1
# Oficjalny plugin (wpis w claude-plugins-official, 417 801 instalacji na claude.com/plugins, sprawdzone 2026-09-26)
claude plugin install context7@claude-plugins-official
# Tryb CLI + Skills, bez serwera MCP
npx ctx7 setup --cli --claude

Nazwę serwera podaj przed -e: flaga przyjmuje wiele wartości, więc w zapisie -e KEY=value context7 Claude Code potraktuje context7 jako drugą zmienną i zgłosi Invalid environment variable format. Jeśli claude plugin install zgłasza brak marketplace’u, użyj w sesji marketplace’u samego Upstash: /plugin marketplace add upstash/context7, a potem /plugin install context7@context7-marketplace.

Zastąp YOUR_API_KEY kluczem z panelu Context7 albo pomiń nagłówek, żeby działać anonimowo z niższymi limitami.

Uruchom /mcp w sesji Claude Code lub Codex albo codex mcp list w terminalu (w Cursorze otwórz listę MCP w ustawieniach) i sprawdź, czy context7 jest połączony i ma dwa narzędzia. Potem wklej pierwszy prompt poniżej i obserwuj, czy pojawia się wywołanie resolve-library-id, a po nim query-docs. W trybie CLI + Skills szukaj zamiast tego ctx7 library i ctx7 docs w wyjściu powłoki.

Aktualna dokumentacja na żądanie: przykład z Next.js

Dział zatytułowany „Aktualna dokumentacja na żądanie: przykład z Next.js”

Dobrym pierwszym testem jest prompt oparty na przykładzie z README Upstash, bo poprawna odpowiedź zmieniła się w niedawnym wydaniu:

Czego oczekiwać na Next.js 16: agent rozwiązuje albo przyjmuje /vercel/next.js, wywołuje query-docs i pisze proxy.ts z eksportowaną funkcją proxy, a nie middleware.ts. Na Next.js 15 powinien napisać middleware.ts. Jeśli na 16 bez komentarza tworzy middleware.ts, odpowiedział z danych treningowych; sprawdź w logu narzędzi, czy w ogóle odpytał dokumentację.

Przypinanie ID to nawyk, który warto zbudować. Format z README to „use library /owner/repo”:

Gdy nie znasz jeszcze ID, każ agentowi pokazać kandydatów, zanim napisze kod, żeby to ty wybrał bibliotekę, a nie ranking:

To samo wyszukanie zrobisz sam poleceniem npx ctx7 library drizzle "push schema".

Dopisywanie „use context7” do każdego promptu nie skaluje się na zespół. Wpisz regułę do pliku, który agent czyta na starcie sesji. README Upstash proponuje takie brzmienie:

Always use Context7 when I need library/API documentation, code generation, setup or configuration steps without me having to explicitly ask.

Umieść ją w CLAUDE.md dla Claude Code, w AGENTS.md dla Codex i jako regułę (Cursor Settings > Rules) w Cursorze. Tryb CLI + Skills nie potrzebuje reguły: ctx7 setup instaluje skill, który sam uruchamia się przy pytaniach o biblioteki. Jak utrzymać te pliki na tyle krótkie, żeby agent nadal je czytał, opisuje strona o dokumentacji jako kontekście dla AI.

Aktualizacja do nowej wersji głównej to miejsce, gdzie przestarzałe dane treningowe kosztują najwięcej i gdzie Context7 się zwraca. Nie zastępuje codemodu ani testów; dostarcza nowe API, żeby agent mógł poprawić to, czego codemod nie ruszył. Prompty są takie same we wszystkich trzech narzędziach.

Przykład poniżej to aktualizacja aplikacji z Next.js 15 do 16. Ten sam schemat pasuje do każdej biblioteki z changelogiem i codemodem.

  1. Zapisz stan wyjściowy. Na świeżej gałęzi uruchom pełną bramkę (type check, lint, testy, build) i zapisz wynik. Zanotuj zainstalowaną wersję poleceniem npm ls next. Jeśli testy słabo pokrywają kod, który zmienisz, najpierw je wzmocnij; zobacz, jak ocenić siłę wyroczni testowej.

  2. Weź listę zmian z aktualnej dokumentacji, nie z pamięci modelu.

    Przejrzyj ten plik. To kontrakt na resztę aktualizacji i jest na tyle krótki, że da się go przeczytać w całości.

  3. Uruchom codemody, zanim agent dotknie kodu. Codemody są deterministyczne i dają jeden mechaniczny diff do przejrzenia. Dla zmiany nazwy middleware dokumentacja Next.js podaje npx @next/codemod@canary middleware-to-proxy ., które zmienia nazwę pliku i funkcji. Zacommituj wynik codemodu osobno.

  4. Resztę niech poprawi agent, jedno pojęcie na zapytanie. Poproś go, żeby przeszedł przez pozostałe punkty z docs/upgrade-next-16.md, odpytując Context7 osobno dla każdego i kończąc, gdy bramka jest zielona. Pomoc ctx7 docs mówi to wprost: jedno pytanie o jeden temat na wywołanie i osobne zapytanie dla każdego odrębnego pojęcia.

  5. Uruchom bramkę i porównaj ze stanem wyjściowym. Type check, lint, testy i build muszą przejść. Każde nowe ostrzeżenie o wycofaniu API (deprecation) w wyjściu buildu traktuj jak błąd.

  6. Przegląd na podstawie dowodów. Pull request zawiera plik planu, commit z codemodem, commit z poprawkami agenta i wynik bramki. Recenzent sprawdza, czy każdy punkt planu jest zamknięty i czy żaden test nie został osłabiony; zobacz code review PR-a agenta bez czytania każdej linii.

Context7 zwiększa szansę, że agent wybierze aktualne API. Sam niczego nie dowodzi: dokumentację tworzy społeczność, a README Upstash zastrzega, że nie gwarantuje jej dokładności ani kompletności. Dowodem są bramki, które sprawdzają kod względem zainstalowanego pakietu, a człowiek zatwierdza wynik tych bramek.

KontrolaCo wyłapujeKto za nią odpowiada
Type check względem typów zainstalowanego pakietuWymyślone funkcje, usunięte opcje, złe sygnaturyCI, blokująca
Testy i build na zaktualizowanym lockfile’uZmiany zachowania, których typy nie widząCI, blokująca
Ostrzeżenia o wycofaniu API w wyjściu buildu i testówKod, który działa dziś na API zaplanowanym do usunięciaCI, blokująca, gdy stan wyjściowy jest czysty
ID biblioteki i wersja, o które pytał agent, wypisane w PRDokumentacja pobrana dla złej biblioteki lub wersjiAutor (agent), weryfikuje recenzent
Nowe lub zmienione zależności w diffie lockfile’aPakiet dodany przez agenta, bo wspominała o nim dokumentacjaCI; zobacz kontrolę zależności w zmianach agentów

Tech lead zatwierdza na podstawie tych dowodów, a nie czytając każdą zmienioną linię. Strona o pakiecie dowodów zawiera szablon PR, który czyni te pozycje obowiązkowymi.

Claude Code i Codex ładują schematy narzędzi MCP na żądanie (wyszukiwanie narzędzi (tool search) jest domyślnie włączone w Claude Code 2.1.283 i codex-cli 0.157.1), więc dwie definicje narzędzi kosztują niewiele. Prawdziwym kosztem jest wynik query-docs, który przy każdym wywołaniu trafia do kontekstu. Szerokie pytanie w stylu „przeczytaj dokumentację Expressa” zwraca dużo więcej niż „sekcja o middleware uwierzytelniania”.

Zmierz to, zamiast zgadywać. W Claude Code uruchom /context przed jednym wyszukaniem i po nim; dla pluginu claude plugin details context7 pokazuje przewidywany koszt w tokenach, choć ta liczba pomija schematy narzędzi MCP. Ograniczaj zapytania do jednego pojęcia, a dłuższe poszukiwania przenieś do subagenta, żeby do głównej sesji wróciło tylko podsumowanie. Ogólny wzorzec opisuje strona o obniżaniu kosztu tokenów MCP.

Stan na 2026-09-26: 62,4 tys. gwiazdek repozytorium upstash/context7 na GitHubie, wpis io.github.upstash/context7 4.1.1 w oficjalnym MCP Registry i 417 801 instalacji pluginu context7 w katalogu pluginów Claude (claude.com/plugins). Nie podajemy liczby pobrań z npm, bo jej nie odczytano.

Inne serwery dokumentacji i kiedy lepszy jest skill dostawcy

Dział zatytułowany „Inne serwery dokumentacji i kiedy lepszy jest skill dostawcy”

Context7 szeroko pokrywa biblioteki open source. Dla platformy jednego dostawcy jego własny serwer albo skill jest zwykle pełniejszy.

ŹródłoDo czegoInstalacja (pokazano Claude Code)UwierzytelnianieDowód
Microsoft Learn MCPDokumentacja i przykłady kodu dla Azure, .NET i Microsoft 365. Narzędzia: microsoft_docs_search, microsoft_docs_fetch, microsoft_code_sample_search. ?maxTokenBudget=2000 w adresie ogranicza rozmiar odpowiedziclaude mcp add --transport http microsoft-learn https://learn.microsoft.com/api/mcpBrakZweryfikowane; 1,9 tys. gwiazdek; plugin microsoft-docs
AWS Knowledge MCPDokumentacja i wytyczne AWSclaude mcp add --transport http aws-knowledge https://knowledge-mcp.global.api.awsBrak; limitowaneZweryfikowane
Hugging Face MCPModele, zbiory danych i Spaces na Hubieclaude mcp add hf-mcp-server -t http "https://huggingface.co/mcp?login"Logowanie lub token HFZweryfikowane (README dostawcy)
DeepWiki MCPPytania o budowę publicznego repozytorium na GitHubie. Narzędzia: read_wiki_structure, read_wiki_contents, ask_questionclaude mcp add --transport http deepwiki https://mcp.deepwiki.com/mcpBrak; tylko publiczne repozytoriaŹródło wtórne: z dokumentacji i bloga Cognition przez fragmenty wyszukiwarki, bez pobrania strony
Fetch (serwer referencyjny)Pojedyncza strona, której Context7 nie zaindeksował, np. changelogclaude mcp add fetch -- uvx mcp-server-fetchBrakZweryfikowane; pakiet Pythona, uruchamiany przez uvx, nie npx

W Codex zdalne serwery dodasz poleceniem codex mcp add <name> --url <url>, a w Cursorze formą z url w mcp.json pokazaną wyżej. Linie dla Microsoft Learn i AWS złożono z adresu podanego przez dostawcę i zweryfikowanej składni claude mcp add.

Skille dostawców, które zastępują wyszukiwanie w dokumentacji. Część frameworków dostarcza dziś wiedzę razem z samym frameworkiem:

  • Next.js: skille workflow są w repozytorium frameworka (npx skills add vercel/next.js), a od Next.js 16.3 wiedza referencyjna trafia do dokumentacji dołączonej do pakietu oraz do AGENTS.md/CLAUDE.md generowanego przez next dev. Na Next.js 16.1 lub starszym npx @next/codemod@canary agents-md pobiera dokumentację dopasowaną do wersji. Starsze repozytorium vercel-labs/next-skills jest wycofane.
  • Stripe: npx skills add https://docs.stripe.com instaluje skille Stripe prosto z jego strony z dokumentacją.
  • Skille z indeksu Context7: npx ctx7 skills install /google-gemini/gemini-skills gemini-api-dev instaluje skill dostawcy przez CLI ctx7.

Reguła decyzyjna: gdy dokumentacja jest dołączona do zainstalowanego pakietu, wybierz ją, bo z definicji pasuje do wersji z lockfile’a. Context7 stosuj, gdy biblioteka takiej dokumentacji nie ma, a Fetch, gdy Context7 jej nie zaindeksował. Instalację i aktualizację skilli opisuje strona o instalowaniu i zarządzaniu skillami.

Agent trafił w złą bibliotekę. Fork albo pakiet o podobnej nazwie wygrywa ranking, a kod używa API, którego w twojej bibliotece nie ma. Wyjście: przypnij ID (use library /owner/repo) i dopisz przypięte ID głównych zależności do CLAUDE.md lub AGENTS.md.

Dokumentacja dotyczy złej wersji. Agent pobrał dokumentację najnowszego wydania, a lockfile przypina starsze. Wyjście: każ mu najpierw odczytać wersję z package.json lub lockfile’a i podać ją w zapytaniu, tak jak robią to prompty powyżej; według README Context7 dopasowuje wersję wymienioną w prompcie. Jeśli podejrzewasz, że indeks nie nadąża za wydaniem, podaj agentowi adres changeloga biblioteki przez serwer Fetch i poproś o porównanie obu źródeł.

Context7 nie zna biblioteki. Wyjście: potwierdź to poleceniem npx ctx7 library <name>, a potem podaj agentowi adres dokumentacji przez serwer Fetch albo zainstaluj skill dostawcy. Autorzy bibliotek mogą zgłosić swoją dokumentację do Context7.

Agent w ogóle go nie wywołuje. Odpowiada z danych treningowych, bo nic mu nie kazało sprawdzać. Wyjście: dopisz regułę z tej strony do pliku instrukcji agenta albo przejdź na tryb CLI + Skills, którego skill sam uruchamia się przy pytaniach o biblioteki.

Żądania kończą się błędem 403 lub 429. Użycie anonimowe ma niższe limity, a firmowe proxy może blokować mcp.context7.com. Wyjście: dodaj klucz API; poproś o dopuszczenie hosta; dla prywatnego wdrożenia ctx7 setup przyjmuje --base-url.

Klucz trafił do Gita. Ktoś wkleił go do .mcp.json albo .cursor/mcp.json. Wyjście: unieważnij i wygeneruj klucz na nowo w panelu Context7, a potem używaj ${CONTEXT7_API_KEY} w Claude Code, bearer_token_env_var w Codex albo globalnego ~/.cursor/mcp.json w Cursorze.

Zła nazwa pakietu. @context7/mcp, @upstash/context7 i context7-mcp zwracają w npm 404. Serwer to @upstash/context7-mcp, a CLI to ctx7. Wyjście: zainstaluj @upstash/context7-mcp jako serwer albo uruchom npx ctx7 jako CLI, a każdą nazwę sprawdź poleceniem npm view <name> version, zanim dopiszesz ją do konfiguracji.