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.
Co daje ci dobrze skonfigurowany Context7
Dział zatytułowany „Co daje ci dobrze skonfigurowany Context7”- 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.
Jak działa Context7: dwa narzędzia, dwa kroki
Dział zatytułowany „Jak działa Context7: dwa narzędzia, dwa kroki”Serwer MCP w wersji @upstash/context7-mcp 4.1.1 (npm, sprawdzone 2026-09-26) udostępnia dokładnie dwa narzędzia:
| Narzędzie | Argumenty | Co robi |
|---|---|---|
resolve-library-id | libraryName, query | Zamienia nazwę, np. „next.js”, na ID biblioteki w Context7, np. /vercel/next.js, z rankingiem względem twojego zadania |
query-docs | libraryId, query | Zwraca 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).
Tryb MCP czy tryb CLI + Skills?
Dział zatytułowany „Tryb MCP czy tryb CLI + Skills?”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 MCP | Tryb CLI + Skills | |
|---|---|---|
| Co się instaluje | Wpis 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 korzysta | Gdy 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ła | W 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 MCP | Chcesz 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.
Instalacja Context7 w Claude Code, Codex i Cursorze
Dział zatytułowany „Instalacja Context7 w Claude Code, Codex i Cursorze”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):
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:
# Lokalny proces stdio, zakres użytkownika; serwer czyta CONTEXT7_API_KEY ze środowiskaclaude 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 MCPnpx ctx7 setup --cli --claudeNazwę 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.
Zdalny serwer z kluczem ze zmiennej środowiskowej (przetestowane na codex-cli 0.157.1):
codex mcp add context7 --url https://mcp.context7.com/mcp --bearer-token-env-var CONTEXT7_API_KEYTo polecenie zapisuje w ~/.codex/config.toml poniższy blok, a codex mcp list pokazuje potem uwierzytelnianie jako „Bearer token”:
[mcp_servers.context7]url = "https://mcp.context7.com/mcp"bearer_token_env_var = "CONTEXT7_API_KEY"Alternatywy:
# Lokalny proces stdio# zapisuje klucz w ~/.codex/config.toml; lepiej użyć formy --url + --bearer-token-env-var powyżejcodex mcp add context7 --env CONTEXT7_API_KEY=YOUR_API_KEY -- npx -y @upstash/context7-mcp@4.1.1
# Tryb CLI + Skills, bez serwera MCPnpx ctx7 setup --cli --codexWpisz zdalny serwer do ~/.cursor/mcp.json (globalnie), żeby klucz nigdy nie trafił do repozytorium (kształt konfiguracji z README Upstash; nie testowano w samym Cursorze):
{ "mcpServers": { "context7": { "url": "https://mcp.context7.com/mcp", "headers": { "Authorization": "Bearer YOUR_API_KEY" } } }}Projektowy .cursor/mcp.json też zadziała; nie wpisuj do niego nagłówka i niech każdy programista doda klucz globalnie.
Możesz też zlecić zapis konfiguracji CLI:
npx ctx7 setup --cursor # zapyta o tryb MCP albo CLI + SkillsZastąp YOUR_API_KEY kluczem z panelu Context7 albo pomiń nagłówek, żeby działać anonimowo z niższymi limitami.
Sprawdź, czy agent widzi Context7
Dział zatytułowany „Sprawdź, czy agent widzi Context7”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".
Context7 domyślnie, a nie na hasło
Dział zatytułowany „Context7 domyślnie, a nie na hasło”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 zależności: Context7, codemod i testy
Dział zatytułowany „Aktualizacja zależności: Context7, codemod i testy”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.
-
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. -
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.
-
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. -
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. Pomocctx7 docsmówi to wprost: jedno pytanie o jeden temat na wywołanie i osobne zapytanie dla każdego odrębnego pojęcia. -
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.
-
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.
Jak udowodnić, że agent użył właściwego API?
Dział zatytułowany „Jak udowodnić, że agent użył właściwego API?”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.
| Kontrola | Co wyłapuje | Kto za nią odpowiada |
|---|---|---|
| Type check względem typów zainstalowanego pakietu | Wymyślone funkcje, usunięte opcje, złe sygnatury | CI, blokująca |
| Testy i build na zaktualizowanym lockfile’u | Zmiany zachowania, których typy nie widzą | CI, blokująca |
| Ostrzeżenia o wycofaniu API w wyjściu buildu i testów | Kod, który działa dziś na API zaplanowanym do usunięcia | CI, blokująca, gdy stan wyjściowy jest czysty |
| ID biblioteki i wersja, o które pytał agent, wypisane w PR | Dokumentacja pobrana dla złej biblioteki lub wersji | Autor (agent), weryfikuje recenzent |
| Nowe lub zmienione zależności w diffie lockfile’a | Pakiet dodany przez agenta, bo wspominała o nim dokumentacja | CI; 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.
Ile kontekstu zużywa Context7?
Dział zatytułowany „Ile kontekstu zużywa Context7?”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.
Jak popularny jest Context7?
Dział zatytułowany „Jak popularny jest Context7?”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ło | Do czego | Instalacja (pokazano Claude Code) | Uwierzytelnianie | Dowód |
|---|---|---|---|---|
| Microsoft Learn MCP | Dokumentacja 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 odpowiedzi | claude mcp add --transport http microsoft-learn https://learn.microsoft.com/api/mcp | Brak | Zweryfikowane; 1,9 tys. gwiazdek; plugin microsoft-docs |
| AWS Knowledge MCP | Dokumentacja i wytyczne AWS | claude mcp add --transport http aws-knowledge https://knowledge-mcp.global.api.aws | Brak; limitowane | Zweryfikowane |
| Hugging Face MCP | Modele, zbiory danych i Spaces na Hubie | claude mcp add hf-mcp-server -t http "https://huggingface.co/mcp?login" | Logowanie lub token HF | Zweryfikowane (README dostawcy) |
| DeepWiki MCP | Pytania o budowę publicznego repozytorium na GitHubie. Narzędzia: read_wiki_structure, read_wiki_contents, ask_question | claude mcp add --transport http deepwiki https://mcp.deepwiki.com/mcp | Brak; 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. changelog | claude mcp add fetch -- uvx mcp-server-fetch | Brak | Zweryfikowane; 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 doAGENTS.md/CLAUDE.mdgenerowanego przeznext dev. Na Next.js 16.1 lub starszymnpx @next/codemod@canary agents-mdpobiera dokumentację dopasowaną do wersji. Starsze repozytoriumvercel-labs/next-skillsjest wycofane. - Stripe:
npx skills add https://docs.stripe.cominstaluje skille Stripe prosto z jego strony z dokumentacją. - Skille z indeksu Context7:
npx ctx7 skills install /google-gemini/gemini-skills gemini-api-devinstaluje skill dostawcy przez CLIctx7.
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.
Gdy Context7 zwraca złą dokumentację albo żadnej
Dział zatytułowany „Gdy Context7 zwraca złą dokumentację albo żadnej”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.