# O Copilot vê seu workspace. O Maguyva mapeia o repo.

Canonical source: https://maguyva.ai/pt-br/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).

O agente do VS Code lê os arquivos que você anexa e os que ele mesmo encontra. O Maguyva indexa o repo inteiro e o entrega via MCP, então, antes de editar, o agente pergunta onde um símbolo fica e quem o chama.

> Uma entrada servers no .vscode/mcp.json: uma URL e um cabeçalho Authorization.

## O que o VS Code precisa saber

Quatro fatos específicos do VS Code.

### .vscode/mcp.json

Os servidores ficam em `servers`, não em `mcpServers`. Para valer em todos os workspaces, rode `MCP: Open User Configuration` e adicione a mesma entrada ao `mcp.json` do seu perfil.

### type: http

O VS Code se conecta ao endpoint do Maguyva por Streamable HTTP e só recorre a SSE quando um servidor não oferece suporte. Nada roda localmente.

### Uma referência a variável de ambiente

O cabeçalho é `Bearer ${env:MAGUYVA_API_KEY}`, que o VS Code resolve a partir do ambiente em que foi iniciado, então a chave fica fora do arquivo que você commita. Prefere ser perguntado? Uma variável de entrada pede a chave uma vez e a guarda.

### Workspace Trust

Os servidores do `.vscode/mcp.json` iniciam sem um aviso à parte assim que você confia no workspace, e nunca no modo restrito. O Configure Tools, na entrada do chat, liga ou desliga cada ferramenta.

## Instruções personalizadas são um acordo de trabalho. Use-as.

```text
# .github/copilot-instructions.md
- Rode npm test antes de dar uma mudança por concluída.
- Nunca edite arquivos gerados em src/gen/.
```

O VS Code lê instruções do projeto todo em `.github/copilot-instructions.md` ou `AGENTS.md`, e instruções direcionadas em arquivos `.github/instructions/*.instructions.md` com um padrão `applyTo`. Use-as para:

- Comandos de build, teste e lint.
- Convenções que o agente insiste em errar.
- Pastas que o agente não deve tocar.

Instruções dizem ao agente como trabalhar. Não dizem quais de quatro mil arquivos importam o tipo que ele está prestes a renomear.

## Onde a visão do workspace acaba

Três coisas que o agente não aprende com os arquivos que tem abertos.

### // anexado não é tudo

O agente trabalha com o que você anexa e com o que as buscas dele retornam. O chamador em outro pacote que quebra depois da mudança não estava em nenhuma das duas listas.

### // um match de texto não é uma referência

A busca do workspace encontra a string. Ela não distingue uma chamada real de um comentário, um mock ou um método de mesmo nome em outra classe.

### // cada leitura custa contexto

Cada arquivo que o agente abre para se orientar gasta o contexto de que ele precisa para a mudança. Uma resposta ranqueada com file:line custa menos que dez leituras exploratórias.

## Maguyva como servidor MCP no VS Code

Uma entrada servers dá ao agente:

- **11 ferramentas sobre o seu repositório indexado**: busca semântica, estrutural (AST), de grafo e de texto, além de busca de símbolos, dependentes e recuperação de arquivos.
- **Respostas com caminhos de arquivo e números de linha**: em mais de 285 linguagens, para o agente abrir o arquivo certo logo de primeira.
- **Ferramentas que só leem**: As ferramentas do Maguyva consultam o índice. Nenhuma edita seus arquivos, então cada aprovação é de leitura, não de escrita.

> O VS Code dá ao agente *seu workspace*.
> O Maguyva dá ao agente *um mapa do repo*.

## Dois fluxos de trabalho

Pergunte ao mapa primeiro, depois edite.

### 01. Achar os testes antes de mudar um parser

```text
vscode agent> quais testes passam por parseConfig?

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

→ Depois da edição, o agente roda esses dois arquivos, não a suíte inteira.
[exit 0]
```

A resposta aponta os dois arquivos de teste que chegam ao parser, então o agente confere a mudança onde ela pode quebrar.

### 02. Dimensionar uma renomeação antes da primeira edição

```text
vscode agent> renomeie OrderStatus.PENDING para OrderStatus.QUEUED

find_symbol("OrderStatus", references)
  23 referências em 9 arquivos

→ O agente planeja uma única passada por nove arquivos.
[exit 0]
```

A contagem de referências chega antes da edição, não depois que o verificador de tipos falha.

## Configuração no VS Code

Três passos. Plano Free: 3 repositórios, Até 50 mil linhas de repositório indexadas, sem cartão.

### 01. Indexe um repositório em maguyva.ai

Escolha um que você já conheça, para poder avaliar as respostas.

### 02. Adicione o Maguyva ao .vscode/mcp.json

`.vscode/mcp.json`

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

### 03. Defina sua chave e inicie o servidor

Defina `MAGUYVA_API_KEY` no ambiente de onde você abre o VS Code e inicie o servidor pelo code lens acima da entrada. Faça ao agente uma pergunta cuja resposta você já saiba.

A [documentação de MCP](https://code.visualstudio.com/docs/agent-customization/mcp-servers) do VS Code cobre variáveis de entrada, o formato portátil .mcp.json e a confiança em servidores.

## Indexe um repositório que você já conhece.

Conecte o VS Code via MCP e faça uma pergunta que você consiga conferir.