Serena MCP — Come Dare al Tuo AI una Comprensione Reale del Codice

Chi usa Claude Code per scrivere codice lo sa: c'è un momento in cui smetti di spiegargli cosa fare e inizi a spiegargli dove farlo. "No, non quella funzione — quella sotto, nella classe ArticleService, riga 140". "Leggi anche il file db.php, ti serve il contesto". "Hai modificato il metodo sbagliato, quello era un altro".

Claude è potente, ma naviga il codice come un cieco in una stanza sconosciuta. Legge file interi per trovare dieci righe. Non sa che getArticleBySlug è chiamato in tre punti diversi. Non distingue una funzione da una costante con lo stesso nome. Ragiona sul testo, non sulla struttura.

Serena cambia radicalmente questo scenario.

Il problema: Claude legge testo, non codice

Facciamo un esempio concreto. Ho un progetto PHP — il mio portfolio, niente di complesso: un front controller, un file con le funzioni del database, un pannello admin. Circa quindici file in tutto.

Quando chiedo a Claude "aggiungi una funzione per contare gli articoli per mese dopo countArticles in db.php", succede questo:

1. Claude legge tutto db.php — 180 righe caricate nel contesto
2. Cerca countArticles scorrendo il testo
3. Individua (si spera) il punto giusto
4. Scrive la nuova funzione
5. Riscrive il file intero

Funziona? Sì, quasi sempre. Ma è inefficiente. Quelle 180 righe consumano token che potevano servire ad altro. E su un progetto da centinaia di file, il problema si moltiplica.

Il vero limite, però, è concettuale. Claude non sa che countArticles è una funzione di primo livello nel file. Non sa che getArticleBySlug è usata nel router principale. Non capisce la gerarchia dei simboli — vede solo stringhe di testo.

Serena: strumenti da IDE per un LLM

Serena è un server MCP open-source che dà a Claude le stesse capacità di navigazione di un IDE. Lo fa attraverso il Language Server Protocol (LSP) — lo stesso protocollo che alimenta l'autocompletamento in VS Code, la navigazione in PhpStorm, il "Go to Definition" in qualsiasi editor moderno.

Quando Serena è attiva, Claude non legge più file interi. Fa cose come queste:

• Chiede la panoramica dei simboli di un file → riceve la lista di classi, funzioni, costanti — senza caricare il codice
• Cerca un simbolo specifico per nome → trova countArticles direttamente, in qualsiasi file del progetto
• Chiede chi referenzia quel simbolo → scopre che è usato in blog.php e admin/views/list.php
• Legge solo il corpo della funzione che gli interessa → 10 righe invece di 180
• Inserisce codice dopo un simbolo → mette la nuova funzione esattamente dopo countArticles, senza riscrivere il file

La differenza è la stessa che c'è tra cercare una parola in un libro sfogliando pagina per pagina e cercarla nell'indice analitico.

Cosa cambia nel flusso di lavoro

Riprendiamo l'esempio di prima. Con Serena attiva, lo stesso task diventa:

1. Claude chiama find_symbol("countArticles") → trova la funzione, riga 45 di db.php
2. Chiama insert_after_symbol("countArticles") con il codice della nuova funzione
3. Fine. Nessun file letto per intero, nessuna riscrittura, nessun token sprecato.

Ma la cosa più utile è quando la richiesta è meno precisa. "Dove viene usata la paginazione nel blog?" — Claude chiama find_referencing_symbols su getArticles e countArticles, incrocia i risultati e mostra i punti del codice coinvolti. Con il grep testuale avrebbe trovato le stringhe, ma non le relazioni semantiche.

Le tre categorie di tool

Serena espone una trentina di strumenti, raggruppabili in tre aree:

Navigazione — get_symbols_overview, find_symbol, find_referencing_symbols, search_for_pattern. Sono i tool che Claude usa per orientarsi nel codice senza leggere tutto.

Editing — replace_symbol_body, insert_after_symbol, insert_before_symbol, replace_content. Modifiche chirurgiche: sostituire una funzione, inserire codice in un punto preciso, fare replace con regex.

Progetto — list_dir, find_file, read_file, execute_shell_command, write_memory. Gestione del filesystem e un sistema di memorie persistenti (ne parlo tra poco).

Il sistema di memorie

Questa è la feature che mi ha convinto a tenere Serena attiva su tutti i miei progetti.

Al primo utilizzo, Serena propone un onboarding: analizza la struttura del progetto e salva in file .md le informazioni chiave — architettura, convenzioni di codice, comandi utili, checklist di completamento task.

Sul mio portfolio ha generato quattro memorie:

• project_overview — Struttura delle directory, schema del database, routing
• code_style — camelCase per le funzioni, UPPER_SNAKE per le costanti, prepared statements per le query
• suggested_commands — composer install, php setup.php, i comandi git
• task_completion_checklist — Verificare XSS, SQL injection, responsive, encoding UTF-8

Queste memorie persistono tra le conversazioni. La prossima volta che apro Claude Code su quel progetto, non devo spiegare nulla. Claude carica le memorie rilevanti e sa già come è fatto il progetto, quali convenzioni seguire, dove mettere le mani.

Si possono anche scrivere memorie a mano — per esempio annotare una decisione architetturale o un workaround specifico da ricordare nelle sessioni future.

Quanto costa

Zero. Serena è completamente gratuito, open-source con licenza MIT. Oltre 17.000 stelle su GitHub, più di 2.000 commit, supporto per oltre 30 linguaggi di programmazione (PHP, Python, JavaScript, TypeScript, Java, Go, Rust, C/C++, Ruby, Swift, Kotlin e molti altri).

Non ci sono piani a pagamento, limiti di utilizzo o feature bloccate. L'unico costo è quello dell'LLM che usi — Claude, nel mio caso.

Come configurarlo

Prerequisito

Serve uv, il package manager Python:

curl -LsSf https://astral.sh/uv/install.sh | sh

Claude Code

Per un progetto specifico, dalla sua directory:

claude mcp add serena -- \
  uvx --from git+https://github.com/oraios/serena \
  serena start-mcp-server \
  --context claude-code \
  --project "$(pwd)"

Il flag --context claude-code è importante: disabilita i tool che duplicherebbero quelli già integrati in Claude Code (lettura file, editing base), lasciando solo quelli semantici.

Per una configurazione globale che funziona su tutti i progetti:

claude mcp add --scope user serena -- \
  uvx --from git+https://github.com/oraios/serena \
  serena start-mcp-server \
  --context=claude-code \
  --project-from-cwd

Con --project-from-cwd, Serena cerca automaticamente un .serena/project.yml o un .git risalendo dalla directory corrente.

Claude Desktop

Apri File → Impostazioni → Sviluppatore → MCP Servers → Modifica Configurazione e aggiungi:

{
  "mcpServers": {
    "serena": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/oraios/serena",
        "serena",
        "start-mcp-server"
      ]
    }
  }
}

Chiudi completamente Claude Desktop (File → Esci, non solo la X) e riaprilo. I tool Serena appariranno con l'icona del martello nella chat.

Configurazione del progetto

Al primo avvio Serena crea una directory .serena/ con un file project.yml:

project_name: "mio-progetto"
languages:
  - php
  - typescript
encoding: "utf-8"
ignored_paths:
  - "vendor/**"
  - "node_modules/**"
  - "db/**"

I linguaggi determinano quali language server vengono avviati. I path ignorati escludono directory che non serve analizzare — vendored code, database, build artifacts.

Cose da sapere

Non sostituisce Claude Code, lo potenzia. I tool base di Claude Code (lettura file, editing, bash) restano attivi. Serena aggiunge il livello semantico che manca.

Il primo avvio è lento. Il language server deve indicizzare il progetto. Il primo find_symbol può richiedere qualche secondo; poi la cache velocizza tutto.

Funziona offline. Serena gira interamente in locale. Nessun dato del tuo codice lascia la macchina (a parte quello che invii a Claude, ovviamente).

In sviluppo attivo. Il progetto è molto attivo, con nuove feature e linguaggi aggiunti regolarmente. La community è reattiva — bug fix e miglioramenti arrivano velocemente.

Se lavori con Claude Code e vuoi che smetta di navigare il codice a tentoni, Serena è probabilmente il miglior investimento (gratuito) che puoi fare sul tuo setup.

Il repository è su GitHub: github.com/oraios/serena