# mssql-mcp

Servidor MCP de **solo lectura** para explorar y analizar objetos de SQL Server
(tablas, vistas, triggers, stored procedures) desde Claude Code.

## Tools expuestas

| Tool | Qué hace |
|---|---|
| `list_tables` | Lista tablas (filtro opcional por esquema / patrón de nombre) |
| `get_table_definition` | Columnas, tipos, PK, FK e índices de una tabla |
| `list_views` | Lista vistas |
| `list_triggers` | Lista triggers, tabla dueña y eventos que disparan |
| `list_stored_procedures` | Lista SPs |
| `get_object_definition` | Código T-SQL completo de un SP/vista/trigger + parámetros |
| `get_object_dependencies` | Objetos referenciados por un SP/vista/trigger (impacto de cambios) |
| `run_select_query` | Ejecuta un `SELECT` (bloquea DML/DDL/EXEC, tope de 500 filas) |

## 1. Crear un usuario SQL de solo lectura

**No uses tu usuario de aplicación ni `sa`.** Crea un login dedicado con permisos mínimos:

```sql
CREATE LOGIN mcp_readonly WITH PASSWORD = 'una_password_fuerte';
USE NombreBaseDatos;
CREATE USER mcp_readonly FOR LOGIN mcp_readonly;
ALTER ROLE db_datareader ADD MEMBER mcp_readonly;
GRANT VIEW DEFINITION TO mcp_readonly; -- necesario para leer el texto de SPs/vistas/triggers
```

Esto le permite leer datos y definiciones, pero **no** puede insertar, modificar,
borrar ni ejecutar procedimientos. La capa de validación en `db.ts` es una
segunda barrera, no la principal — la principal es este usuario.

## 2. Instalar y compilar

```bash
cd mssql-mcp
npm install
cp .env.example .env
# edita .env con tus datos de conexión (server, database, user, password)
npm run build
```

## 3. Probar en local (opcional)

```bash
npm start
```

Deberías ver `mssql-mcp: servidor MCP corriendo por stdio` en stderr. Ctrl+C para salir.

## 4. Registrar el servidor en Claude Code

Desde la raíz de tu proyecto (o global con `-g`):

```bash
claude mcp add mssql-mcp -- node /ruta/absoluta/mssql-mcp/dist/index.js
```

Verifica que quedó registrado:

```bash
claude mcp list
```

Las variables de entorno del `.env` las carga el propio proceso (via `dotenv`),
así que no necesitas pasarlas en el comando `claude mcp add`. Si prefieres no
usar `.env`, puedes pasarlas inline:

```bash
claude mcp add mssql-mcp \
  -e DB_SERVER=127.0.0.1 -e DB_DATABASE=NombreBD \
  -e DB_USER=mcp_readonly -e DB_PASSWORD=xxx \
  -- node /ruta/absoluta/mssql-mcp/dist/index.js
```

## 5. Flujo típico para analizar un SP

En Claude Code, dentro de tu proyecto:

```
Usa mssql-mcp para traer la definición del SP dbo.sp_ActualizarSaldo,
revisa sus dependencias y dime qué ajustes de performance o buenas
prácticas recomendarías (índices, SARGability, manejo de transacciones,
try/catch, etc.)
```

Claude Code llamará `get_object_definition`, opcionalmente
`get_object_dependencies` y `get_table_definition` de las tablas involucradas,
y con eso arma el análisis. Como tiene también `run_select_query`, puede
validar hipótesis (ej. cardinalidad de una tabla, existencia de un índice)
contra la base real.

## Seguridad

- El usuario SQL debe ser de solo lectura (paso 1) — es la protección real.
- `run_select_query` rechaza cualquier cosa que no empiece con `SELECT`/`WITH`
  y bloquea palabras clave de escritura/DDL como segunda barrera.
- No apuntes este MCP a una base de producción con datos sensibles sin
  revisar antes qué columnas expone `db_datareader` (considera vistas o
  máscaras si hay PII).
- `.env` está en `.gitignore` — nunca subas credenciales al repo.