# SQL Server MCP Server (Python)

Um servidor [Model Context Protocol (MCP)](https://modelcontextprotocol.io) em Python para integração com bancos de dados **Microsoft SQL Server**.

O servidor disponibiliza ferramentas completas de inspeção de schema e operações CRUD (Create, Read, Update, Delete), além de recursos MCP para consulta rápida de dados e schemas.

## Ferramentas Disponíveis (Tools)

### Schema & Inspeção

- `list_schemas()`: Lista todos os schemas de usuário presentes no banco de dados.
- `list_tables(schema_name=None)`: Lista tabelas e views do banco de dados com opção de filtro por schema.
- `get_table_schema(table_name, schema_name="dbo")`: Retorna detalhes estruturais da tabela (colunas, tipos de dados, chaves primárias, chaves estrangeiras e identidades).
- `get_database_schema(schema_name=None, table_name=None)`: Retorna o schema completo do banco de dados ou filtrado.

### Operações CRUD

- `read_records(table_name, schema_name="dbo", columns=None, where_clause=None, params=None, order_by=None, limit=100, offset=0)`: Consulta registros de uma tabela com colunas personalizadas, filtros `WHERE` parametrizados, ordenação e paginação.
- `read_query(sql_query, params=None)`: Executa uma query `SELECT` personalizada em T-SQL com suporte a parâmetros posicionais (`?`).
- `insert_record(table_name, data, schema_name="dbo")`: Insere um único registro (dicionário chave/valor) em uma tabela.
- `bulk_insert_records(table_name, records, schema_name="dbo")`: Insere múltiplos registros em lote dentro de uma transação.
- `update_records(table_name, data, where_clause, where_params=None, schema_name="dbo")`: Atualiza registros correspondentes a uma cláusula `WHERE` parametrizada.
- `delete_records(table_name, where_clause, params=None, schema_name="dbo")`: Remove registros correspondentes a uma cláusula `WHERE` de forma segura.
- `execute_sql(sql_statement, params=None)`: Executa comandos DDL/DML arbitrários (CREATE, ALTER, DROP, INSERT, UPDATE, DELETE).

## Recursos MCP (Resources)

- `sqlserver://schema`: Retorna o schema completo do banco de dados em formato JSON.
- `sqlserver://tables`: Retorna a lista de tabelas e views disponíveis.

## Instalação e Configuração

### 1. Requisitos

- Python >= 3.10
- Driver SQL Server (Suporta `pyodbc` com ODBC Driver do SQL Server e `pymssql` para conexões puras em Python).

### 2. Configuração do Ambiente (`.env`)

Crie um arquivo `.env` na raiz do projeto ou defina as variáveis de ambiente:

```env
SQLSERVER_HOST=localhost
SQLSERVER_PORT=1433
SQLSERVER_DATABASE=MeuBanco
SQLSERVER_USER=sa
SQLSERVER_PASSWORD=SuaSenha123!
SQLSERVER_DRIVER_TYPE=auto
SQLSERVER_TRUST_SERVER_CERTIFICATE=true
```

#### Uso com SQL Server Express LocalDB

O servidor possui suporte nativo ao **SQL Server LocalDB** (com suporte a anexar arquivos `.mdf` diretamente):

**Via variáveis de ambiente (`.env`):**
```env
SQLSERVER_USE_LOCALDB=true
SQLSERVER_LOCALDB_INSTANCE=MSSQLLOCALDB
SQLSERVER_DATABASE=MeuBanco
# Opcional: Caminho para anexar um arquivo .mdf diretamente
# SQLSERVER_ATTACH_DB_FILENAME=C:\Caminho\Para\Banco.mdf
```

Ou configurando `SQLSERVER_HOST=(localdb)\MSSQLLOCALDB`.

**Via linha de comando:**
```bash
python -m sql_server_mcp.server --localdb --database MeuBanco
# Ou anexando um arquivo MDF:
python -m sql_server_mcp.server --localdb --attach-db-filename C:\Data\MeuBanco.mdf
```

### 3. Instalação

```bash
python -m venv .venv
# Windows
.\.venv\Scripts\activate
# Linux/macOS
source .venv/bin/activate

pip install -e .
```

## Configuração em Clientes MCP

### Exemplo de `mcp.json` / Configuração de Cliente

```json
{
  "mcpServers": {
    "sql-server": {
      "command": "python",
      "args": [
        "-m",
        "sql_server_mcp.server"
      ],
      "env": {
        "SQLSERVER_HOST": "localhost",
        "SQLSERVER_PORT": "1433",
        "SQLSERVER_DATABASE": "MeuBanco",
        "SQLSERVER_USER": "sa",
        "SQLSERVER_PASSWORD": "SuaSenha123!",
        "SQLSERVER_TRUST_SERVER_CERTIFICATE": "true"
      }
    },
    "sql-server-localdb": {
      "command": "python",
      "args": [
        "-m",
        "sql_server_mcp.server",
        "--localdb",
        "--database", "MeuBanco"
      ]
    }
  }
}
```

## 🐳 Docker & Makefile

Você pode usar o `Makefile` para facilitar a compilação e execução via Docker:

```bash
# Compilar a imagem Docker
make build

# Executar o servidor MCP em container utilizando as variáveis do .env
make run

# Rodar os testes unitários dentro do container Docker
make docker-test

# Exibir ajuda dos comandos Makefile
make help
```

---

## 🧪 Testes

Para rodar os testes unitários da aplicação:
```bash
pytest
```