# MCP SQL Server

Servidor MCP (Model Context Protocol) para Microsoft SQL Server.
Permite que Claude Code, Codex, Cursor, Windsurf, Cline, Continue e outras ferramentas MCP explorem schema, relacionamentos e executem consultas SQL com foco em seguranca.

## O que ele faz

- Explora schemas, tabelas, colunas, indices, procedures e foreign keys
- Monta ranking por intencao com `find_entities`
- Sugere caminhos de join com `suggest_join_path`
- Gera plano de consulta com `plan_query`
- Valida SQL antes de executar com `validate_query`
- Executa `SELECT` e, opcionalmente, escrita controlada por permissoes
- Mantem catalogo em memoria com cache e refresh
- Permite trocar o banco ativo em runtime com `switch_database`
- Permite trocar a porta ativa em runtime com `switch_port`
- Permite trocar porta, usuario, senha e banco em uma unica acao com `switch_connection`
- Lista bancos acessiveis no servidor com `list_databases`
- Mostra a conexao ativa com `current_connection`
- Retorna respostas em formato visual com box-drawing ASCII/Unicode durante a execucao das tools

## Ferramentas disponiveis

| Ferramenta | Descricao |
|------------|-----------|
| `current_connection` | Mostra servidor, porta, banco ativo, permissao e cache |
| `list_databases` | Lista bancos acessiveis no SQL Server atual |
| `list_schemas` | Lista todos os schemas do banco |
| `list_tables` | Lista tabelas e views agrupadas por schema |
| `find_tables` | Busca tabelas e views por nome |
| `describe_table` | Mostra colunas, PK, FK, checks, identity e computed |
| `list_indexes` | Lista indices, key columns e included columns |
| `table_stats` | Mostra rows, tamanho e datas da tabela |
| `find_columns` | Busca colunas por nome em todas as tabelas |
| `relationship_map` | Mostra o mapa de relacionamentos de um schema |
| `list_procedures` | Lista procedures e functions |
| `query` | Executa SQL respeitando as regras de permissao |
| `permissions` | Mostra o modo atual e operacoes permitidas/bloqueadas |
| `sample_values` | Retorna amostras distintas de valores por coluna |
| `query_with_explanation` | Executa query de leitura e adiciona interpretacao curta |
| `switch_database` | Troca o banco ativo da sessao atual sem reiniciar o MCP |
| `switch_port` | Troca a porta SQL Server da sessao atual sem reiniciar o MCP |
| `switch_connection` | Troca porta, usuario, senha e banco juntos com uma unica reconexao |
| `refresh_metadata` | Recarrega o catalogo em cache |
| `health` | Mostra estado da conexao e metricas do cache |
| `find_entities` | Busca entidades por linguagem natural |
| `schema_summary` | Resume schemas e tabelas mais conectadas |
| `explain_table` | Explica o papel provavel de uma tabela |
| `suggest_join_path` | Sugere joins a partir do grafo de FKs |
| `plan_query` | Gera um plano de consulta a partir de um objetivo |
| `validate_query` | Analisa SQL antes da execucao |

## Sobre este README

Este arquivo fica em Markdown normal para leitura no GitHub e nas IDEs.
O visual com box-drawing ASCII/Unicode aparece apenas na execucao das tools do MCP, nas respostas retornadas para Claude, Codex, Cursor e clientes compativeis.

## Requisitos

- Node.js 18 ou superior
- Acesso a um SQL Server local ou remoto

## Instalacao

```bash
git clone https://github.com/WendellOttoni/mcp-sqlserver.git
cd mcp-sqlserver
npm install
```

## Configuracao MCP

Exemplo de `.mcp.json`:

```json
{
  "mcpServers": {
    "sqlserver": {
      "command": "node",
      "args": ["C:/MCP/mcp-sqlserver/src/index.js"],
      "env": {
        "DB_SERVER": "localhost",
        "DB_DATABASE": "MeuBanco",
        "DB_USER": "sa",
        "DB_PASSWORD": "MinhaSenha"
      }
    }
  }
}
```

Voce tambem pode usar o template em `.mcp.json.example`.

## Variaveis de ambiente

| Variavel | Obrigatoria | Padrao | Descricao |
|----------|-------------|--------|-----------|
| `DB_SERVER` | Nao | `localhost` | Host do SQL Server |
| `DB_DATABASE` | Sim | - | Banco inicial da sessao |
| `DB_USER` | Nao | - | Usuario SQL; se omitido usa Windows Auth |
| `DB_PASSWORD` | Nao | - | Senha SQL |
| `DB_PORT` | Nao | `1433` | Porta do SQL Server; ignorada em instancia nomeada |
| `DB_ENCRYPT` | Nao | `false` | Habilita criptografia na conexao com SQL Server |
| `DB_TRUST_SERVER_CERTIFICATE` | Nao | `true` | Confia no certificado do servidor sem validacao completa |
| `DB_ALLOW_WRITE` | Nao | - | Operacoes de escrita permitidas |
| `DB_ALLOW_TABLES` | Nao | - | Restringe escrita a tabelas especificas |
| `DB_ALLOW_SCHEMAS` | Nao | - | Restringe escrita a schemas especificos |
| `DB_ALLOW_DATABASE_SWITCH` | Nao | - | Allowlist opcional de bancos permitidos para `switch_database` |
| `DB_METADATA_TTL_MS` | Nao | `300000` | TTL do cache de metadata em ms |
| `DB_QUERY_TIMEOUT_MS` | Nao | `30000` | Timeout das queries em ms |
| `DB_DEFAULT_MAX_ROWS` | Nao | `100` | Limite padrao de linhas para leitura |
| `DB_SAMPLE_SIZE` | Nao | `5` | Quantidade padrao do `sample_values` |

## Formatos de `DB_SERVER`

| Formato | Exemplo |
|---------|---------|
| Host local | `localhost` |
| IP | `192.168.1.100` |
| Nome da maquina | `SERVIDOR-SQL` |
| Instancia nomeada com `\\` | `LAPTOP-ABC\\SQLEXPRESS` |
| Instancia nomeada com `/` | `LAPTOP-ABC/SQLEXPRESS` |

Se usar `/`, o MCP converte automaticamente para o formato de instancia nomeada.

## Modo de permissao

Por padrao o servidor sobe em modo `READ-ONLY`.
Sem `DB_ALLOW_WRITE`, apenas consultas de leitura sao permitidas.

Exemplo:

```json
{
  "DB_ALLOW_WRITE": "INSERT,UPDATE",
  "DB_ALLOW_TABLES": "dbo.Produto,dbo.Pedido"
}
```

Operacoes permanentemente bloqueadas:

`EXEC`, `EXECUTE`, `GRANT`, `REVOKE`, `DENY`, `BACKUP`, `RESTORE`, `SHUTDOWN`, `DBCC`, `BULK`, `OPENROWSET`, `OPENDATASOURCE`, `xp_*`, `sp_*`

## Troca de banco em runtime

Agora nao e mais necessario reiniciar o processo MCP para apontar para outro banco no mesmo servidor.

Fluxo recomendado:

1. Rode `current_connection` para confirmar onde a sessao esta conectada.
2. Rode `list_databases` para ver os bancos acessiveis.
3. Rode `switch_database` para trocar o banco ativo.
4. Rode `schema_summary` ou `list_schemas` para explorar o novo banco.

Use:

```text
switch_database { "database": "OutroBanco" }
```

Comportamento:

- valida a nova conexao antes de trocar
- carrega o catalogo do novo banco antes de assumir a sessao
- fecha o pool antigo apenas depois da validacao
- se a troca falhar, a conexao atual continua ativa

Observacao:

- `switch_database` troca apenas o banco ativo
- `server`, `user`, `password` e outras configuracoes permanecem as mesmas
- `list_databases` oculta `master`, `model`, `msdb` e `tempdb` por padrao
- use `include_system_databases: true` para incluir bancos de sistema

Para limitar quais bancos podem ser usados em `switch_database`, configure:

```json
{
  "DB_ALLOW_DATABASE_SWITCH": "ReqPlay,Homologacao,Teste"
}
```

Se `DB_ALLOW_DATABASE_SWITCH` nao for definida, qualquer banco acessivel pelo login atual pode ser usado.

## Troca de porta em runtime

Use `switch_port` para apontar a sessao atual para outra porta TCP do mesmo servidor sem reiniciar o chat ou perder o contexto da IA.

Fluxo recomendado:

1. Rode `current_connection` para ver servidor, porta e banco atuais.
2. Rode `switch_port` com a nova porta.
3. Rode `current_connection`, `schema_summary` ou `list_schemas` para confirmar a nova conexao.

Use:

```text
switch_port { "port": 1450 }
```

Comportamento:

- valida a nova conexao antes de trocar
- carrega o catalogo usando a nova porta antes de assumir a sessao
- fecha o pool antigo apenas depois da validacao
- se a troca falhar, a conexao atual continua ativa

Observacao:

- `switch_port` troca apenas a porta
- `server`, `database`, `user`, `password` e outras configuracoes permanecem as mesmas
- em `DB_SERVER` com instancia nomeada, a porta e gerenciada pela instancia e `switch_port` nao e aplicado

## Troca completa de conexao em runtime

Use `switch_connection` quando precisar trocar porta, usuario, senha e banco de uma vez so, com apenas uma validacao e uma reconexao ao final.

Use:

```text
switch_connection {
  "port": 51218,
  "user": "sa",
  "password": "Docker@Test123",
  "database": "master"
}
```

Comportamento:

- todos os parametros sao opcionais
- qualquer campo omitido mantem o valor atual
- a troca so e assumida depois que a nova conexao completa for validada
- o pool antigo so e fechado no final, apos validar e carregar o catalogo

## Exemplos de configuracao

Somente leitura:

```json
{
  "DB_SERVER": "localhost",
  "DB_DATABASE": "MeuBanco"
}
```

SQL Auth:

```json
{
  "DB_SERVER": "localhost",
  "DB_DATABASE": "MeuBanco",
  "DB_USER": "sa",
  "DB_PASSWORD": "MinhaSenha"
}
```

Instancia nomeada:

```json
{
  "DB_SERVER": "LAPTOP-ABC/SQLEXPRESS",
  "DB_DATABASE": "MeuBanco"
}
```

Escrita restrita por tabela:

```json
{
  "DB_SERVER": "localhost",
  "DB_DATABASE": "MeuBanco",
  "DB_ALLOW_WRITE": "INSERT,UPDATE",
  "DB_ALLOW_TABLES": "dbo.Produto,dbo.Pedido"
}
```

Escrita restrita por schema:

```json
{
  "DB_SERVER": "localhost",
  "DB_DATABASE": "MeuBanco",
  "DB_ALLOW_WRITE": "INSERT,UPDATE,DELETE",
  "DB_ALLOW_SCHEMAS": "staging"
}
```

Servidor remoto com porta customizada:

```json
{
  "DB_SERVER": "192.168.1.100",
  "DB_PORT": "1450",
  "DB_DATABASE": "Producao",
  "DB_USER": "app_user",
  "DB_PASSWORD": "SenhaSegura"
}
```

Servidor remoto com TLS validado:

```json
{
  "DB_SERVER": "sql.empresa.local",
  "DB_PORT": "1433",
  "DB_DATABASE": "Producao",
  "DB_USER": "app_user",
  "DB_PASSWORD": "SenhaSegura",
  "DB_ENCRYPT": "true",
  "DB_TRUST_SERVER_CERTIFICATE": "false"
}
```

## Ferramentas de analise

As ferramentas abaixo usam metadata carregada em memoria para responder mais rapido:

- `find_entities`
- `schema_summary`
- `explain_table`
- `suggest_join_path`
- `plan_query`
- `refresh_metadata`
- `health`

## Seguranca

- `READ-ONLY` por padrao
- Escrita controlada por operacao, schema e tabela
- Validacao de SQL antes da execucao
- Limite maximo de 1000 linhas no fluxo de leitura
- Cache de metadata com TTL configuravel
- Validacao de conexao logo no startup
- Troca de banco em runtime com validacao antes do cutover

## Estrutura do projeto

```text
mcp-sqlserver/
|-- .mcp.json.example
|-- README.md
|-- package.json
|-- src/
|   |-- config/
|   |   `-- env.js
|   |-- db/
|   |   |-- catalog-cache.js
|   |   |-- catalog-loader.js
|   |   `-- connection.js
|   |-- graph/
|   |   `-- relationship-graph.js
|   |-- search/
|   |   |-- aliases.js
|   |   `-- ranker.js
|   |-- security/
|   |   |-- permissions.js
|   |   `-- sql-validator.js
|   |-- tools/
|   |   |-- core.js
|   |   `-- intelligence.js
|   |-- utils/
|   |   |-- formatting.js
|   |   `-- text.js
|   `-- index.js
`-- test/
    |-- sample-values.test.js
    `-- security.test.js
```

## Desenvolvimento

Executar o servidor:

```bash
npm start
```

Rodar os testes:

```bash
npm test
```