> 🇧🇷 Tradução em Português. [English version](../../guides/code-graph-mcp-setup.md)

# Code Graph MCP — Guia de Configuração

Guia de configuração para instalação, configuração e validação do Code Graph MCP como provider de code intelligence no LMAS.

---

## Pré-requisitos

| Requisito | Versão Mínima | Verificar |
|-----------|---------------|-----------|
| Python | 3.12+ | `python --version` |
| pip | 24+ | `pip --version` |
| Node.js | 18+ | `node --version` |
| Claude Code | latest | `claude --version` |

---

## 1. Instalação

### 1.1 Instalar Package e Dependências

```bash
pip install code-graph-mcp ast-grep-py rustworkx
```

**Packages instalados:**
- `code-graph-mcp` (v1.2.4+) — MCP server principal
- `ast-grep-py` — Engine de parsing AST (baseado em tree-sitter)
- `rustworkx` — Biblioteca de análise de grafos

### 1.2 Verificar Instalação

```bash
code-graph-mcp --help
```

Output esperado:
```
Usage: code-graph-mcp [OPTIONS]

  Code Graph Intelligence MCP Server.

Options:
  --project-root TEXT  Root directory of the project to analyze
  -v, --verbose        Enable verbose logging
  --help               Show this message and exit.
```

---

## 2. Configuração como MCP Server

### 2.1 Adicionar ao Projeto (Recomendado)

Editar `.mcp.json` na raiz do projeto:

```json
{
  "mcpServers": {
    "code-graph": {
      "command": "code-graph-mcp",
      "args": ["--project-root", "C:\\Users\\<USER>\\path\\to\\project"]
    }
  }
}
```

Ou via CLI (fora de uma sessão Claude Code ativa):

```bash
claude mcp add code-graph -s project -- code-graph-mcp --project-root /path/to/project
```

### 2.2 Verificação Pós-Configuração

1. Reiniciar Claude Code para carregar o novo MCP
2. Verificar que as tools estão disponíveis na sessão

**9 tools esperadas:**
| Tool | Descrição |
|------|-----------|
| `get_usage_guide` | Guia de uso e workflows |
| `analyze_codebase` | Análise completa da estrutura |
| `find_definition` | Localizar definições de symbols |
| `find_references` | Rastrear usos de symbols |
| `find_callers` | Funções que chamam um alvo |
| `find_callees` | Funções chamadas por um alvo |
| `complexity_analysis` | Análise de complexidade |
| `dependency_analysis` | Grafos de dependência |
| `project_statistics` | Métricas e estatísticas |

---

## 3. Health Check

Execute o script de health check para validar que tudo está funcionando:

```bash
node scripts/code-intel-health-check.js
```

Output esperado (provider ativo):
```json
{
  "status": "available",
  "provider": "code-graph-mcp",
  "tools": [
    { "name": "find_definition", "available": true },
    { "name": "find_references", "available": true },
    ...
  ],
  "responseTimeMs": 1234,
  "errors": []
}
```

---

## 4. Solução de Problemas

### Cenário 1: `code-graph-mcp: command not found`

**Causa:** Package não instalado ou não está no PATH.

**Solução:**
```bash
# Verificar instalação
pip show code-graph-mcp

# Se não instalado
pip install code-graph-mcp ast-grep-py rustworkx

# Verificar PATH (Windows)
python -c "import shutil; print(shutil.which('code-graph-mcp'))"
```

### Cenário 2: MCP server não aparece no Claude Code

**Causa:** `.mcp.json` com sintaxe incorreta ou Claude Code não reiniciado.

**Solução:**
1. Validar JSON: `python -m json.tool .mcp.json`
2. Reiniciar Claude Code completamente
3. Verificar que o path no `--project-root` existe

### Cenário 3: Timeout ao executar tools

**Causa:** Codebase muito grande, primeira execução faz indexação.

**Solução:**
1. Primeira execução pode levar 10-30s em codebases grandes
2. Execuções subsequentes usam cache LRU
3. Se persistir, use `--verbose` para diagnóstico:
   ```bash
   code-graph-mcp --project-root /path/to/project --verbose
   ```

### Cenário 4: Tool específica retorna erro

**Causa:** Symbol não encontrado ou linguagem não suportada.

**Solução:**
1. Verificar que o arquivo alvo usa linguagem suportada (25+ linguagens)
2. Verificar nome exato do symbol (case-sensitive)
3. Executar `analyze_codebase` primeiro para confirmar que o provider reconhece o projeto

### Cenário 5: Conflito de dependências (httpx)

**Causa:** `code-graph-mcp` requer httpx >= 0.27.1 que pode conflitar com supabase.

**Solução:**
- Conflito não afeta funcionalidade do Code Graph MCP
- Se necessário, use virtualenv isolado:
  ```bash
  python -m venv .venv-codegraph
  .venv-codegraph\Scripts\activate
  pip install code-graph-mcp ast-grep-py rustworkx
  ```
- Atualizar `.mcp.json` com path completo do executável no venv

---

## Referência

- **Repositório:** [entrepeneur4lyf/code-graph-mcp](https://github.com/entrepeneur4lyf/code-graph-mcp)
- **PyPI:** [code-graph-mcp](https://pypi.org/project/code-graph-mcp/)
- **Versão instalada:** 1.2.4
- **Linguagens suportadas:** 25+ (JavaScript, TypeScript, Python, Rust, Go, Java, C, C++, etc.)
- **Pesquisa:** `docs/research/2026-02-15-code-intelligence-alternatives/03-recommendations.md`

---

*NOG-0 — Guia de Configuração do Code Graph MCP v1.0*
*@devops (Operator) — 2026-02-15*