# Copilot vede il tuo workspace. Maguyva mappa il repo.

Canonical source: https://maguyva.ai/it/for-vscode

License: text under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/); code samples under [MIT-0](https://opensource.org/license/mit-0); the Maguyva name, logos, brand assets and other code are not covered. Details: [maguyva.ai/license](https://maguyva.ai/license).

L’agente di VS Code legge i file che alleghi e quelli che trova da solo. Maguyva indicizza l’intero repo e lo serve via MCP, così prima di modificare l’agente chiede dove si trova un simbolo e chi lo chiama.

> Una voce servers in .vscode/mcp.json: un URL e un header Authorization.

## Cosa deve sapere VS Code

Quattro fatti specifici di VS Code.

### .vscode/mcp.json

I server vanno sotto `servers`, non sotto `mcpServers`. Per usarli in ogni workspace, esegui `MCP: Open User Configuration` e aggiungi la stessa voce al `mcp.json` del tuo profilo.

### type: http

VS Code si collega all’endpoint di Maguyva in Streamable HTTP e ripiega su SSE solo se un server non lo supporta. In locale non gira nulla.

### Un riferimento a variabile d’ambiente

L’header è `Bearer ${env:MAGUYVA_API_KEY}`, che VS Code risolve dall’ambiente in cui è stato avviato, così la chiave resta fuori dal file che committi. Preferisci un prompt? Una variabile di input chiede la chiave una volta e la conserva.

### Workspace Trust

I server in `.vscode/mcp.json` si avviano senza un prompt separato appena ti fidi del workspace, e mai in modalità con restrizioni. Configure Tools, nell’input della chat, attiva o disattiva i singoli strumenti.

## Le istruzioni personalizzate sono un accordo di lavoro. Usale.

```text
# .github/copilot-instructions.md
- Esegui npm test prima di dichiarare conclusa una modifica.
- Non modificare mai i file generati in src/gen/.
```

VS Code legge le istruzioni di progetto da `.github/copilot-instructions.md` o `AGENTS.md`, e quelle mirate da file `.github/instructions/*.instructions.md` con un pattern `applyTo`. Usale per:

- Comandi di build, test e lint.
- Convenzioni che l’agente continua a sbagliare.
- Cartelle che l’agente non deve toccare.

Le istruzioni dicono all’agente come lavorare. Non possono dirgli quali di quattromila file importano il tipo che sta per rinominare.

## Dove finisce la vista del workspace

Tre cose che l’agente non può imparare dai file che ha aperti.

### // allegato non vuol dire tutto

L’agente lavora con ciò che alleghi e con ciò che restituiscono le sue ricerche. Il chiamante in un altro pacchetto che si rompe dopo la modifica non era in nessuna delle due liste.

### // una corrispondenza testuale non è un riferimento

La ricerca del workspace trova la stringa. Non distingue una chiamata vera da un commento, un mock o un metodo omonimo di un’altra classe.

### // ogni lettura costa contesto

Ogni file che l’agente apre per orientarsi consuma il contesto che gli serve per la modifica. Una risposta classificata con file:line costa meno di dieci letture esplorative.

## Maguyva come server MCP in VS Code

Una voce servers dà all’agente:

- **11 strumenti sul tuo repo indicizzato**: ricerca semantica, strutturale (AST), a grafo e testuale, più ricerca dei simboli, dipendenti e recupero file.
- **Risposte con percorsi file e numeri di riga**: su oltre 285 linguaggi, così l’agente apre subito il file giusto.
- **Strumenti che leggono e basta**: Gli strumenti di Maguyva interrogano l’indice. Nessuno modifica i tuoi file, quindi ogni approvazione riguarda una lettura, non una scrittura.

> VS Code dà all’agente *il tuo workspace*.
> Maguyva dà all’agente *una mappa del repo*.

## Due flussi di lavoro

Prima chiedi alla mappa, poi modifica.

### 01. Trovare i test prima di cambiare un parser

```text
vscode agent> quali test passano da parseConfig?

dependency_search("parseConfig", dependents)
  tests/config/parse.test.ts:12
  tests/cli/flags.test.ts:88

→ Dopo la modifica l’agente esegue questi due file, non l’intera suite.
[exit 0]
```

La risposta indica i due file di test che raggiungono il parser, così l’agente verifica la modifica dove può rompersi.

### 02. Misurare una rinomina prima della prima modifica

```text
vscode agent> rinomina OrderStatus.PENDING in OrderStatus.QUEUED

find_symbol("OrderStatus", references)
  23 riferimenti in 9 file

→ L’agente pianifica un solo passaggio su nove file.
[exit 0]
```

Il numero di riferimenti arriva prima della modifica, non dopo che il type checker fallisce.

## Configurazione in VS Code

Tre passaggi. Piano Free: 3 repository, Fino a 50K righe di repository indicizzate, senza carta di credito.

### 01. Indicizza un repo su maguyva.ai

Scegline uno che già conosci, così puoi valutare le risposte.

### 02. Aggiungi Maguyva a .vscode/mcp.json

`.vscode/mcp.json`

```json
{
  "servers": {
    "maguyva": {
      "type": "http",
      "url": "https://maguyva.tools/mcp",
      "headers": {
        "Authorization": "Bearer ${env:MAGUYVA_API_KEY}"
      }
    }
  }
}
```

### 03. Imposta la chiave e avvia il server

Imposta `MAGUYVA_API_KEY` nell’ambiente da cui avvii VS Code, poi avvia il server dal code lens sopra la sua voce. Fai all’agente una domanda di cui conosci già la risposta.

La [documentazione MCP](https://code.visualstudio.com/docs/agent-customization/mcp-servers) di VS Code copre le variabili di input, il formato portabile .mcp.json e la fiducia nei server.

## Indicizza un repo che già conosci.

Collega VS Code via MCP, poi fai una domanda che puoi verificare.