Repo del giorno: claude-context, tutto il codebase come contesto per Claude Code

💡 Cos'è: il codebase intero come contesto

claude-context è un plugin Model Context Protocol (MCP) che aggiunge la ricerca semantica del codice a Claude Code e agli altri agenti di coding. In pratica: dai in pasto il tuo progetto una volta, lui lo spezza in blocchi, li trasforma in embedding e li salva in un database vettoriale. Da lì, ogni volta che l'agente deve capire il codice, interroga l'indice in linguaggio naturale e riceve solo i frammenti pertinenti.

La differenza con l'approccio classico è netta. Senza uno strumento del genere, Claude Code scopre il codebase «a mano»: apre file, legge cartelle, segue gli import, e ogni lettura consuma spazio nel context window. Con claude-context quel lavoro di scoperta lo fa un indice: l'agente smette di sfogliare e inizia a cercare. Il progetto è open source con licenza MIT ed è distribuito come pacchetto npm ufficiale.

# aggiunge claude-context come server MCP
claude mcp add claude-context \
  -e OPENAI_API_KEY=sk-la-tua-chiave \
  -e MILVUS_ADDRESS=il-tuo-endpoint-zilliz \
  -e MILVUS_TOKEN=la-tua-api-key \
  -- npx @zilliz/claude-context-mcp@latest

🧠 Il problema: perché su progetti grandi si «bruciano» token

Il context window è una risorsa finita e costosa. Quando chiedi a Claude Code di modificare una funzione in un progetto grande, l'agente deve prima capire dove vive quella funzione e come si collega al resto: senza un indice, l'unico modo è leggere. Più file legge, più token spende, e più il contesto si riempie di codice che alla risposta finale non serve.

Ne derivano due effetti fastidiosi: sessioni che costano più del necessario e risposte meno precise, perché il modello si distrae con file irrilevanti caricati «per sicurezza». Su codebase da milioni di righe l'approccio a forza bruta semplicemente non scala. claude-context ribalta la logica: indicizza una volta, poi a ogni domanda recupera solo il minimo indispensabile.

⚙️ Come funziona sotto il cofano

Il cuore è una ricerca ibrida: claude-context combina BM25 (la ricerca per parole chiave, ottima quando conosci il nome esatto) con la ricerca densa a embedding (che trova codice per significato, anche quando usi parole diverse da quelle nel sorgente). Le due insieme recuperano meglio di ciascuna da sola.

A monte c'è un chunking intelligente: invece di tagliare il codice ogni N caratteri, claude-context lo analizza come Abstract Syntax Tree e lo spezza lungo i confini sintattici — funzioni, classi, metodi — così ogni blocco resta un'unità di senso. E per non re-indicizzare tutto a ogni salvataggio usa gli alberi di Merkle: rileva i file cambiati e aggiorna solo quelli. Indicizzazione incrementale, non da capo ogni volta.

• Ricerca ibrida: BM25 (parole chiave) + vettori densi (significato).
• Chunking AST: blocchi allineati a funzioni e classi, non tagli ciechi.
• Indicizzazione incrementale: alberi di Merkle, si aggiornano solo i file modificati.
• Multi-linguaggio: TypeScript, Python, Java, C#, Go, Rust, PHP, Ruby e altri.

🚀 Come si usa: dall'indicizzazione alla prima ricerca

Il flusso quotidiano è disarmante. Configurato il server MCP, apri Claude Code nella cartella del progetto e gli dici «Indicizza questo codebase». Parte l'indicizzazione — puoi chiedere «A che punto è l'indicizzazione?» per vedere la percentuale — e da quel momento cerchi in linguaggio naturale: «Trova le funzioni che gestiscono l'autenticazione utente».

Lato strumenti, il server espone quattro comandi essenziali all'agente: `index_codebase` per creare l'indice, `search_code` per interrogarlo con la ricerca ibrida, `get_indexing_status` per lo stato di avanzamento e `clear_index` per ripartire da zero. Non devi impararli a memoria: l'agente li invoca al posto tuo quando riconosce che la richiesta è una ricerca sul codice.

> Indicizza questo codebase
  …indicizzazione in corso (AST + embedding)…

> A che punto è l'indicizzazione?
  Completata al 100% · pronto per la ricerca

> Trova le funzioni che gestiscono l'autenticazione utente
  auth/session.ts:42 · login()  ·  score 91%
  auth/tokens.ts:17 · verifyJwt()  ·  score 88%

🔌 Non solo Claude Code: tanti client, un solo setup

Anche se il nome parla di Claude, claude-context è un server MCP standard e funziona con una lunga lista di agenti: oltre a Claude Code e Claude Desktop, sono documentati OpenAI Codex CLI, Gemini CLI, Cursor, Windsurf, Cline, Roo Code, Augment, Qwen Code e altri. Lo configuri una volta e lo riusi con l'editor che preferisci.

Per chi vive nell'IDE c'è anche un'estensione VS Code («Semantic Code Search») che usa lo stesso motore senza passare da un agente. La configurazione MCP è la solita manciata di righe — un comando `claude mcp add` oppure un blocco JSON/TOML: se hai già collegato un server MCP, qui non cambia nulla. Il meccanismo è identico a quello che abbiamo raccontato per Claude Code, Codex e VS Code.

# la chiave è mcp_servers (non mcpServers) su Codex
[mcp_servers.claude-context]
command = "npx"
args = ["@zilliz/claude-context-mcp@latest"]
env = { OPENAI_API_KEY = "la-tua-chiave", MILVUS_TOKEN = "la-tua-api-key" }
startup_timeout_ms = 20000

📊 Quanto fa risparmiare davvero

Il numero che gira è circa il 40% di token in meno a parità di qualità del recupero: è il risultato della valutazione controllata pubblicata dagli autori nella cartella `evaluation` del repo. Va letto per quello che è — una misura del team che sviluppa il progetto — ma non è isolata: recensioni indipendenti e i report degli utenti su Reddit parlano di riduzioni nell'ordine del 30-50% nelle sessioni lunghe.

La logica del risparmio è intuitiva: se all'agente arrivano tre snippet mirati invece di dieci file interi, il contesto resta snello e la stessa risposta costa meno. Su un progetto grande e su sessioni lunghe è lì che si sente la differenza, sia in bolletta sia in lucidità delle risposte. Su un file singolo, ovviamente, il vantaggio è trascurabile.

repo      zilliztech/claude-context
stelle    ~11.800 · licenza MIT · di Zilliz (team Milvus)
stack     TypeScript · Python · Node.js ≥ 20
motore    ricerca ibrida BM25 + vettori · chunking AST
storage   Milvus / Zilliz Cloud · embedding OpenAI/Voyage/Gemini/Ollama
risparmio ~40% token (valutazione degli autori)

⚠️ Cosa sapere prima di adottarlo

Non è privo di attriti. claude-context ha bisogno di due ingredienti esterni: un database vettoriale (Milvus in locale, oppure Zilliz Cloud che ha un piano gratuito) e un provider di embedding (OpenAI, VoyageAI, Gemini oppure Ollama in locale). Vanno configurate le relative chiavi, ed è il passaggio in più rispetto a un MCP «a costo zero».

C'è poi un tema di privacy da valutare con la testa: per default gli embedding del tuo codice vengono calcolati da un servizio esterno e archiviati in un database vettoriale. Su codice proprietario o sotto NDA conviene la strada tutta locale — Ollama per gli embedding e Milvus self-hosted — così il codice non lascia le tue macchine. È una scelta di setup, non un limite del progetto, ma va fatta consapevolmente prima di indicizzare repository sensibili.

🏢 Perché è interessante per sviluppatori e PMI

Per chi sviluppa, claude-context è un caso di studio di RAG applicato al codice: indicizzazione incrementale, chunking sintattico e ricerca ibrida sono esattamente i mattoni che useresti per costruire un motore di ricerca interno. Vederli impacchettati in un server MCP pronto all'uso è, di per sé, una piccola lezione di architettura.

Per una PMI che sta introducendo l'AI nello sviluppo il valore è doppio: da un lato contieni i costi delle sessioni con gli agenti su progetti reali (che raramente sono piccoli), dall'altro rendi l'assistente più affidabile, perché lavora sul codice giusto invece che su una selezione casuale. Meno token spesi e risposte più centrate sono due metriche che un responsabile tecnico capisce al volo. E la variante tutta locale mette d'accordo anche chi ha vincoli di riservatezza.

🗺️ Da dove partire

Il percorso a basso rischio: crea un account gratuito su Zilliz Cloud (o avvia un Milvus locale), procurati una chiave per gli embedding, aggiungi il server con `claude mcp add` e indicizza un progetto di prova, non subito il monorepo aziendale. Fai due o tre ricerche in linguaggio naturale e confronta le risposte con quelle che ottenevi senza indice: in dieci minuti capisci se il recupero ti serve.

Se il codice è sensibile, parti direttamente dalla configurazione locale con Ollama. E se vuoi inquadrare il meccanismo MCP prima di metterci le mani, gli approfondimenti qui sotto spiegano come si collega un server MCP a Claude Code, Codex e VS Code. Studiare come claude-context tiene insieme indice, embedding e ricerca vale quanto usarlo.

Altri articoli del blog