Installazione

Contextia può essere installato come strumento CLI standalone, come pacchetto Python, o eseguito direttamente con uvx senza installazione permanente. Questa guida copre tutti i metodi e mostra come configurare il server MCP per il tuo editor.

Prerequisiti

• Python 3.12 o successivo — Contextia utilizza funzionalità moderne di Python, inclusa la sintassi dei parametri di tipo e i miglioramenti a typing introdotti nella versione 3.12
• uv (raccomandato) — un gestore di pacchetti Python veloce. Installalo da docs.astral.sh/uv

Consiglio

Se non hai uv installato, puoi ottenerlo con un singolo comando:

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

Su macOS, puoi anche usare Homebrew:

brew install uv

Installare la CLI

Con uv (raccomandato)

Il modo più veloce per usare Contextia è con uvx, che esegue lo strumento direttamente senza installarlo nel tuo ambiente:

uvx contextia --version

Questo scarica Contextia alla prima esecuzione e lo mette in cache. Nessuna gestione di ambienti virtuali necessaria.

Per installarlo in modo permanente così che il comando contextia sia sempre disponibile:

uv tool install contextia

Con pip

Se preferisci l’installazione tradizionale con pip:

pip install contextia

Attenzione

Quando installi con pip, assicurati di usare Python 3.12 o successivo. Puoi verificare con python --version. Considera l’uso di un ambiente virtuale per evitare conflitti con altri pacchetti.

Con supporto per le grammatiche dei linguaggi

Contextia può analizzare le annotazioni nel codice (@spec, @decision, ecc.) usando regex per impostazione predefinita. Per un’analisi più accurata con le grammatiche tree-sitter, installa con l’extra languages:

pip install contextia[languages]

Oppure con uv:

uv tool install contextia[languages]

Questo installa le grammatiche tree-sitter per Python, TypeScript, JavaScript, Go, Rust e Java. Tree-sitter fornisce un’analisi a livello di AST, il che significa che Contextia può rilevare in modo affidabile la funzione o la classe che contiene un’annotazione, non solo la riga in cui appare.

Nota

Il supporto per le grammatiche dei linguaggi è opzionale. Lo scanner basato su regex funziona bene per la maggior parte dei progetti. Hai bisogno di tree-sitter solo se vuoi un contesto più ricco dalla scansione delle annotazioni (ad esempio, sapere che @spec SPEC-001 appare all’interno di class PaymentProcessor.process_payment()).

Verifica dell’installazione

Dopo l’installazione, verifica che Contextia sia disponibile:

contextia --version

Dovresti vedere un output simile a:

contextia 0.1.0

Puoi anche verificare che la CLI funzioni eseguendo il comando di aiuto:

contextia --help

Questo mostra tutti i comandi disponibili con brevi descrizioni.

Configurazione del server MCP

Il server MCP (contextia-mcp) consente agli agenti AI di accedere all’architettura del contesto del tuo progetto direttamente tramite il Model Context Protocol. Il server viene eseguito come processo locale stdio — niente HTTP, niente autenticazione, niente accesso alla rete esterna.

Il server scopre automaticamente il tuo progetto risalendo dalla directory di lavoro alla ricerca di .contextia/config.yaml, proprio come git scopre .git/. Non è necessaria alcuna configurazione specifica per progetto nel tuo editor.

Claude Code

Registra il server MCP con Claude Code usando un singolo comando:

claude mcp add contextia -- uvx contextia-mcp

Questo dice a Claude Code di avviare il server MCP di Contextia quando necessario. Il server eredita la directory di lavoro da Claude Code, quindi trova automaticamente la root del progetto.

Per verificare che il server sia registrato:

claude mcp list

Dovresti vedere contextia nella lista dei server configurati.

Cursor

Crea o modifica .cursor/mcp.json nella root del tuo progetto:

.cursor/mcp.json

{
  "mcpServers": {
    "contextia": {
      "command": "uvx",
      "args": ["contextia-mcp"]
    }
  }
}

Riavvia Cursor dopo aver aggiunto questa configurazione. Il server MCP sarà disponibile per l’agente AI in tutti i file del progetto.

VS Code

Crea o modifica .vscode/mcp.json nella root del tuo progetto:

.vscode/mcp.json

{
  "servers": {
    "contextia": {
      "type": "stdio",
      "command": "uvx",
      "args": ["contextia-mcp"]
    }
  }
}

Nota

Il supporto MCP in VS Code richiede l’estensione appropriata per il tuo provider AI (ad esempio, l’estensione Claude o GitHub Copilot con supporto MCP). Consulta la documentazione della tua estensione per il formato esatto di configurazione MCP, poiché potrebbe variare.

Verifica del server MCP

Puoi testare il server MCP direttamente dalla riga di comando:

uvx contextia-mcp

Il server si avvia e attende messaggi JSON-RPC su stdin. Nell’uso normale, il tuo editor gestisce questo processo automaticamente. Premi Ctrl+C per fermare.

Per verificare che funzioni con il tuo progetto, naviga in una directory che contiene una cartella .contextia/ e controlla che il server si avvii senza errori.

Configurazione a livello di progetto

Contextia non richiede alcuna configurazione specifica per l’editor oltre alla configurazione del server MCP descritta sopra. Tutte le impostazioni del progetto risiedono in .contextia/config.yaml, che viene creato quando esegui contextia init.

Una configurazione minimale si presenta così:

.contextia/config.yaml

version: "1.0"
project:
  name: my-project
  languages:
    - python
annotations:
  prefix: "@"
  comment_syntax:
    python: "#"

Consulta la Guida rapida per una guida passo-passo sull’inizializzazione del tuo primo progetto.

Aggiornamento

Con uv

uv tool upgrade contextia

Con pip

pip install --upgrade contextia

Verificare la disponibilità di aggiornamenti

contextia --version

Confronta l’output con l’ultima versione pubblicata su PyPI.

Consiglio

Contextia segue il versionamento semantico. Le release di patch (0.1.x) contengono correzioni di bug. Le release minori (0.x.0) aggiungono funzionalità senza modifiche incompatibili. Le release maggiori (x.0.0) possono modificare il formato della directory .contextia/, ma includeranno sempre un comando di migrazione.

Prossimi passi

Con Contextia installato e il server MCP configurato, vai al tutorial di avvio rapido per inizializzare il tuo primo progetto e creare la tua prima specifica.