Stellaris MCP: la ricerca semantica nella tua codebase

Se sviluppi con l’aiuto di Claude, Cursor o un altro agente IA, probabilmente hai già vissuto questa frustrazione: l’IA commette errori che non hanno nulla a che fare con le sue capacità. Propone codice che duplica una funzione già esistente. Allucinazione negli import. Corregge un bug creandone altri tre, perché non ha visto che la logica era già gestita altrove.

Non è un problema di intelligenza — è un problema di contesto.

Un agente IA, per quanto potente, non può leggere l’intero progetto a ogni scambio. Sarebbe troppo lento, e soprattutto troppo costoso in token. Quindi lavora con ciò che gli fornisci esplicitamente, e indovina il resto. Ciò che funziona bene su file piccoli e isolati diventa rapidamente un problema su un progetto reale con decine di file, centinaia di funzioni e un’architettura che si è evoluta nel corso di mesi.

La soluzione è dare all’IA un modo per cercare nel tuo codice su richiesta — offrirle una sorta di motore di ricerca interno che capisce cosa stai cercando, anche se non conosci il nome esatto della funzione o del file.

È esattamente quello che fa Stellaris MCP: uno strumento open source che ho sviluppato e pubblicato su GitHub, progettato per integrarsi direttamente con Claude Desktop (e qualsiasi client compatibile con MCP).

Permette all’IA di localizzare con precisione il frammento di codice giusto al momento giusto, senza dover caricare l’intero progetto in memoria.

Risultato: meno errori, meno token consumati e un assistente che comprende davvero la tua codebase.

Non è necessario essere uno sviluppatore esperto per trarne vantaggio — se usi Claude per aiutarti a programmare, anche occasionalmente, Stellaris MCP ti farà risparmiare tempo fin dalla prima sessione.

Cos’è un server MCP?

Immagina che Claude possa premere pulsanti al posto tuo: aprire un file, cercare nel tuo database, chiamare un’API esterna. È esattamente ciò che permette il Model Context Protocol (MCP) — uno standard aperto sviluppato da Anthropic che dà agli agenti IA la capacità di interagire con strumenti di terze parti in modo strutturato e sicuro.

In pratica, un server MCP espone dei “tools” — funzioni che l’IA può invocare durante una conversazione, secondo le sue necessità. Claude non li usa in modo continuo: li chiama solo quando è pertinente, come chiederesti a un collega un’informazione specifica piuttosto che inviargli l’intero dossier all’inizio.

È questa logica “su richiesta” che rende i server MCP così efficaci nel risparmiare token e ridurre i costi di inferenza. Invece di caricare 50 file nel contesto per precauzione, Claude può chiedere esattamente ciò di cui ha bisogno, nel momento in cui ne ha bisogno.

Stellaris MCP espone sei strumenti di questo tipo, suddivisi in due categorie complementari: la ricerca semantica (che comprende le tue intenzioni) e l’esplorazione strutturale (che analizza la sintassi del tuo codice).

Come funziona: due approcci complementari

Stellaris MCP ha due modalità di funzionamento, a seconda di ciò che vuoi fare.

Cercare per intenzione, non per parola chiave

La prima modalità è la ricerca semantica. In concreto, Stellaris analizza il tuo progetto e crea una sorta di impronta digitale per ogni funzione, componente o classe. Queste impronte vengono archiviate localmente sulla tua macchina in una piccola cartella nascosta.

Il vantaggio? Quando Claude ha bisogno di qualcosa, può cercare per intenzione — “la funzione che gestisce il login dell’utente” — senza conoscere il nome esatto del file o del metodo. È come Google per il tuo codice: descrivi cosa stai cercando, e il motore trova la corrispondenza più rilevante.

Questa indicizzazione utilizza l’API di OpenAI (è necessaria una chiave), ma il costo è minimo — pochi centesimi per un intero progetto — e l’indice viene aggiornato in modo incrementale: solo i file modificati vengono rianalizzati a ogni avvio.

Tre strumenti coprono questa modalità:

• Ricerca nel codice — in linguaggio naturale, in tutti i tuoi file sorgente
• Ricerca nella documentazione — nei tuoi file Markdown
• Reindicizzazione — per forzare un aggiornamento dell’indice

Esplorare la struttura, senza spendere un solo token

La seconda modalità è completamente gratuita: nessuna chiave API, nessuna chiamata di rete. Analizza semplicemente la sintassi del tuo codice per estrarne la struttura — esattamente come farebbe un IDE.

Tre strumenti in questa categoria:

• Vista ad albero — l’elenco completo di tutti i tuoi file, con statistiche per linguaggio
• Schema di un file — tutte le funzioni e le classi di un file, con i relativi numeri di riga
• Codice sorgente di un simbolo — il codice esatto di una funzione specifica, con il suo contesto (vedi sotto)

Questa modalità è particolarmente utile per consentire a Claude di “scoprire” il tuo progetto all’inizio di una sessione, senza dover caricare tutto in memoria.

Il vero valore aggiunto: il contesto automatico

Ecco un dettaglio che cambia davvero la qualità del risultato. Quando uno strumento di ricerca restituisce una funzione, ti dà semplicemente… la funzione. Il che sembra logico, ma pone un problema pratico: Claude non sa da dove provengono le variabili utilizzate, né se funzioni simili esistono già nello stesso file.

Stellaris fa qualcosa di più intelligente: quando recupera una funzione per Claude, allega automaticamente ciò che la circonda — l’elenco degli import del file, i nomi delle funzioni vicine e i possibili commenti di avviso (TODO, FIXME, ecc.) presenti nel file.

È un piccolo surplus di informazioni (circa un centinaio di token), ma evita gli errori più frequenti: refactoring cieco, duplicazione del codice, correzioni che rompono qualcos’altro senza accorgersene. Un ottimo rapporto qualità/costo.

Compatibile con i tuoi linguaggi abituali

Stellaris MCP supporta nativamente TypeScript, JavaScript, React (TSX/JSX), Python, Go, Rust, PHP, HTML e CSS — oltre ai file Markdown per la documentazione. Copre la stragrande maggioranza dei progetti web e backend attuali.

Come appare nella pratica?

Una volta installato, il workflow naturale con Claude diventa:

1. All’inizio di una sessione, Claude chiede di vedere la struttura del tuo progetto — in una sola chiamata, sa cosa esiste e dove
2. Quando cerca qualcosa di preciso, effettua una ricerca per intenzione anziché chiederti di incollare del codice
3. Quando modifica una funzione, recupera il contesto completo prima di scrivere qualsiasi cosa

La maggior parte di queste operazioni è completamente gratuita — solo la ricerca semantica usa l’API di OpenAI, e soltanto durante l’indicizzazione iniziale o gli aggiornamenti. Nell’uso corrente, spendi quasi nulla.

Installazione e integrazione con Claude Desktop

git clone https://github.com/GDM-Pixel/stellaris-code-search.git
cd stellaris-code-search
npm install
npm run build

Poi nel tuo claude_desktop_config.json:

{
  "mcpServers": {
    "stellaris-mcp": {
      "command": "node",
      "args": ["/percorso/verso/stellaris-code-search/dist/index.js"],
      "env": {
        "OPENAI_API_KEY": "sk-..."
      }
    }
  }
}

Senza una chiave OpenAI, il server si avvia normalmente — i tre strumenti AST rimangono disponibili.

Open source, davvero

Il progetto è pubblicato sotto licenza MIT su GitHub: github.com/GDM-Pixel/stellaris-code-search

Contributi benvenuti — issue, pull request, suggerimenti di linguaggi aggiuntivi. Se lo usi sui tuoi progetti e trovi casi limite, apri una issue.

È uno strumento che ho costruito per i miei flussi di sviluppo personali in GDM-Pixel e su Nova-Mind. Lo condivido perché il problema del contesto del codice per gli agenti IA è universale — e una soluzione aperta vale più di una proprietaria rinchiusa in un SaaS.