Ciao a tutti, quante volte sviluppiamo codice attraverso i nostri agenti per poi ritrovarci metodi che non esistono, sintassi di due versioni fa o configurazioni ormai deprecate? Il problema è noto: i modelli ragionano sui dati di addestramento, che invecchiano in fretta rispetto al ritmo con cui escono le release di framework e librerie.
Nell’articolo di oggi voglio parlarvi di Context7,un progetto che risolve questo problema in modo semplice: recupera la documentazione aggiornata e specifica per versione delle librerie e iniettarla direttamente nel contesto del modello.
Sto provando ad inserire questo strumento nell’harness dei miei agenti da ormai qualche tempo e posso dire che in alcuni contesti la qualità del codice prodotta è migliorata molto. Il vantaggio principale è che Context7 fornisce agli agenti una documentazione già ottimizzata e pulita, cosa che non avremmo con un agente che si documenta tramite web.
Scendiamo ora più nel dettaglio e cerchiamo di vedere come funziona.
A cosa serve Context7
Context7 è una piattaforma che indicizza la documentazione di linguaggi, librerie e altro, per poi esporla agli agenti AI tramite protocollo mcp o skill. Quando chiediamo al nostro agente qualcosa su una libreria, invece di rispondere “a memoria”, l’agente interroga Context7 e riceve estratti di documentazione e snippet di codice presi dalle fonti ufficiali.
Il progetto è open source (repository GitHub) e può lavorare in due modalità:
- MCP: registriamo il server MCP di Context7 e l’agente chiama i tool di documentazione in modo nativo
- CLI + skill: installiamo una skill che guida l’agente ad usare i comandi della CLI
ctx7, senza bisogno di MCP
In questo articolo vedremo come installarlo con entrambe le modalità, io personalmente mi trovo molto bene ad utilizzare l’approccio MCP.
Collegare Context7 via MCP
Partiamo dalla strada che preferisco, il server MCP. Il modo più veloce per configurare tutto è il comando di setup (richiede Node.js 18+):
npx ctx7 setupIl comando autentica via OAuth (con il device flow: ci mostra un link e un codice da aprire su qualsiasi dispositivo, quindi funziona anche su macchine remote via SSH), genera una API key e installa la configurazione. Durante il setup possiamo scegliamo la modalità MCP e con i flag --claude (o il provider che preferite), per installarlo direttamente nella directory dell’agente che ci interessa.
Se preferite la configurazione manuale, il server remoto risponde all’indirizzo https://mcp.context7.com/mcp e accetta la API key nell’header Authorization: Bearer <API_KEY>. Ogni client ha il suo formato di configurazione: la guida ufficiale copre più di 30 client. In alternativa esiste anche il pacchetto @upstash/context7-mcp per eseguire il server in locale via npx.
Una volta collegato, il server espone due tool:
| Tool | Cosa fa |
|---|---|
resolve-library-id | trasforma il nome di una libreria (es. “next.js”) in un ID compatibile con Context7 (es. /vercel/next.js) |
query-docs | recupera la documentazione di una libreria a partire dall’ID e dalla domanda |
Nota: per chi usa Claude Code esiste anche un plugin dedicato che oltre al server MCP installa skill, agenti e comandi:
/plugin marketplace add upstash/context7
/plugin install context7@context7-marketplaceIl plugin legge la API key dalla variabile d’ambiente CONTEXT7_API_KEY; se non la impostiamo funziona comunque, ma passa dal tier anonimo che ha limiti più bassi. Se non avete ancora installato Claude Code, ne ho parlato in questo articolo.
Usarlo con CLI e skill
La modalità CLI + skill è la novità più interessante: non serve nessun server MCP attivo. Il setup installa una skill che spiega all’agente quando e come usare la CLI ctx7, che offre due comandi speculari ai tool MCP:
# cerca una libreria nell'indice e restituisce gli ID
ctx7 library next.js "middleware"
# recupera la documentazione a partire dall'ID
ctx7 docs /vercel/next.js "app router setup"La parte comoda è che la skill si attiva da sola: quando facciamo una domanda su un linguaggio, un framework o una libreria, l’agente riconosce che la documentazione può aiutare e chiama Context7 senza che dobbiamo chiederglielo.
Con il plugin per Claude Code arrivano anche due strumenti in più:
- il comando
/context7:docs <libreria> [domanda]per interrogare la documentazione manualmente (es./context7:docs prisma relations) - l’agente
docs-researcher: un subagente che esegue la ricerca di documentazione in un contesto separato e ritorna solo la risposta. Utile quando siamo nel mezzo di un task lungo e non vogliamo sporcare il contesto principale con le chiamate ai tool
Come sfruttarlo al meglio
Per quanto possa essere molto utile anche solo per il fatto che produciamo codice aggiornato all’ultima versione, ci sono alcuni accorgimenti che ci possono aiutare a migliorare l’utilizzo di context7:
- Versione nel prompt: citando la versione (“Come configuro il middleware in Next.js 14?”) Context7 abbina la documentazione della versione corrispondente ed evita di doverla ricavare dal progetto.
- Una regola nel progetto: dopo l’installazione aggiungo sempre una regola nel file AGENT.md o CLAUDE.md con scritto “Usa sempre Context7 quando serve documentazione di librerie o API”, in modo tale che l’agente lo faccia in autonomia senza doverlo specificare
Un aspetto che apprezzo molto legato alla privacy (e per nulla scontato) è che verso i server di Context7 viaggiano solo la query di ricerca e il nome della libreria, non il nostro codice né la conversazione.
È gratuito oppure no?
Sì, per l’uso individuale su librerie pubbliche è gratuito, seppur con dei limiti legati al numero di chiamate al mese. Per ulteriori dettagli vi rimando alla pagina con i dettagli di pricing.
Possiamo usare Context7 anche senza API key, in forma anonima, ma con rate limit più bassi: la key è gratuita (si genera dalla dashboard) e conviene sempre averla
Il limite di 1.000 chiamate al mese (limite attivo quando ho scritto questo articolo) è più che sufficiente per un uso personale e personalmente non ho mai sforato: ogni domanda dell’agente consuma in genere una o due chiamate (risoluzione + query). Raggiunto il limite si viene bloccati, ma vengono concesse 20 chiamate bonus al giorno fino al reset del mese
I repository privati restano l’esclusiva dei piani a pagamento (e questo diventa molto interessante in contesti aziendali): se volete indicizzare la documentazione delle vostre librerie interne servirà il piano Pro. Tutti i dettagli sono sulla pagina dei piani.
Io solitamente configuro due account (api key): uno personale e uno che utilizzo in contesti lavorativi.
Conclusioni
E’ sempre più evidente che la qualità dell’output generato da un agente non dipende solo dal modello, ma anche dall’harness e dagli strumenti che ha a disposizione: context7 è uno strumento molto utile e che migliora il codice prodotto, fornendo una documentazione sempre aggiornata.
Il mio consiglio è di partire dal piano gratuito con la modalità che preferite (MCP se avete già altri server configurati, CLI + skill se volete la strada più leggera) e aggiungete una regola nel progetto: da lì in poi ci si dimentica che esista e contribuirà a migliorare la qualità dell’ouput.
Personalmente ho potuto notare una enorme differenza su modelli open source o meno “capaci”, mentre modelli come Sonnet5, Opus, Fable, Gpt Sole/Terra il codice generato è nella maggiorparte delle volte allineato alle ultime versioni: probabilmente questi modelli così capaci hanno già un meccanismo simile dietro alle quinte.
Grazie per aver letto, alla prossima!
