# MCP de PostgreSQL (Python)

Servidor MCP local para PostgreSQL usando `psycopg` y `FastMCP`.

Es el equivalente operativo del proyecto `C:\Users\PCBYRON\mssql-python-mcp`,
adaptado a catalogos y semantica de PostgreSQL. Mantiene el contrato de
respuesta uniforme:

```json
{
  "success": true,
  "data": {},
  "warnings": []
}
```

En error:

```json
{
  "success": false,
  "error": {
    "code": "SQL_ERROR",
    "sql_state": "42601",
    "message": "...",
    "hint": "..."
  }
}
```

## Configuracion default

La conexion `default` usa:

```python
HOST = "localhost"
PORT = 5432
USER = "postgres"
PASSWORD = "pgSQL"
DEFAULT_DATABASE = "postgres"
DEFAULT_SCHEMA = "public"
```

## Instalacion

Con el Python global de este equipo:

```cmd
cd C:\Users\PCBYRON\Documents\mcp-pgSQL
C:\Python310\python.exe -m pip install --user -r requirements.txt --trusted-host pypi.org --trusted-host files.pythonhosted.org
C:\Python310\python.exe -m py_compile server.py
```

Para ejecutar como MCP por stdio:

```cmd
C:\Python310\python.exe C:\Users\PCBYRON\Documents\mcp-pgSQL\server.py
```

Tambien puedes usar:

```cmd
run.bat
```

## Configuracion en Codex/Claude Desktop

Ejemplo:

```json
{
  "mcpServers": {
    "pgsql": {
      "command": "C:\\Python310\\python.exe",
      "args": ["C:\\Users\\PCBYRON\\Documents\\mcp-pgSQL\\server.py"]
    }
  }
}
```

## Parametros

Las tools SQL aceptan parametros por nombre estilo `@nombre`; internamente se
convierten a placeholders seguros de `psycopg`.

```json
{
  "sql": "select * from public.clientes where id = @id",
  "params": [
    {"name": "id", "type": "int", "value": 123}
  ]
}
```

Tambien acepta `params` como objeto:

```json
{
  "sql": "select @x::int + 1 as y",
  "params": {"x": 41}
}
```

## Tools incluidas

El servidor registra 165 tools: las 106 tools nominales del MCP MSSQL original
mas utilidades propias de PostgreSQL para observabilidad, MVCC, indices,
JSONB, particiones, RLS, extensiones, replicacion, FDW y desarrollo. Grupos
principales:

- Conexion: `connect_server`, `disconnect_server`, `list_connections`,
  `is_connected`, `use_database`, `set_default_schema`, `current_context`.
- Metadata: `list_databases`, `list_schemas`, `list_objects`,
  `get_table_schema`, `get_indexes`, `get_foreign_keys`, `get_constraints`,
  `get_triggers`, `get_dependencies`, `get_object_definition`,
  `search_in_definitions`, `get_table_dependencies_graph`,
  `find_identity_columns`.
- Ejecucion SQL: `execute_query`, `execute_query_paged`, `execute_scalar`,
  `execute_nonquery`, `execute_script`, `execute_dry_run`, `stream_query`,
  `call_procedure`, `call_function`, `call_tvf`.
- Compatibilidad: `query`, `execute`, `describe`.
- Transacciones: `begin_transaction`, `commit_transaction`,
  `rollback_transaction`, `savepoint`, `rollback_to_savepoint`,
  `get_open_transactions`.
- DDL: `create_or_alter`, `drop_object`, `rename_object`, `alter_column`,
  `clone_table`, `truncate_table`.
- Locks/performance: `list_sessions`, `get_active_requests`,
  `get_blocking_chains`, `kill_session`, `get_locks`, `get_wait_stats`,
  `get_query_plan`, `explain_query`, `get_query_stats`, `analyze_table`.
- Seguridad: `list_logins`, `list_users`, `list_roles`, `list_permissions`,
  `grant_permission`, `revoke_permission`, `check_effective_permissions`.
- Schema repo/db: `export_schema`, `import_schema`, `diff_schema`,
  `sync_schema`.
- Datos: `count_rows`, `sample_data`, `column_stats`, `find_duplicates`,
  `check_referential_integrity`, `find_identity_gaps`, `bulk_insert`,
  `bulk_upsert`.
- Diagnostico: `server_info`, `database_files`, `tempdb_usage`,
  `memory_usage`, `get_mcp_logs`, `get_connection_pool_stats`,
  `clear_plan_cache`, `table_sizes`, `vacuum_analyze`, `list_extensions`,
  `create_extension`.
- PostgreSQL-first: `get_database_health`, `get_table_bloat`,
  `get_autovacuum_status`, `get_slow_queries`, `recommend_indexes`,
  `index_usage_report`, `find_missing_foreign_key_indexes`,
  `inspect_jsonb_column`, `list_partitions`, `rls_status`, `role_audit`,
  `extension_recommendations`, `replication_slot_risk`, `fdw_health_check`,
  `generate_table_ddl_full`, `export_pg_dump_schema`.

## Seguridad operacional

- `execute_query` solo acepta consultas read-only (`SELECT`, `WITH`, `SHOW`,
  `EXPLAIN`, `VALUES`, `TABLE`).
- `execute_nonquery` bloquea DDL.
- Operaciones DDL/destructivas requieren `confirm=true`.
- `statement_timeout` default: 30 s.
- `lock_timeout` default: 5000 ms.
- Resultsets se limitan a 1000 filas por default y 10000 como hard limit.

## Equivalencia contra SQL Server

Cobertura nominal: **106/106 tools MSSQL presentes**.

Equivalencia funcional estimada: **90-93%**. Las areas core estan portadas
con implementacion PostgreSQL real. Algunas tools conservan el nombre y
contrato, pero devuelven advertencias o equivalentes aproximados cuando el
motor no tiene una funcion 1:1.

Expansion PostgreSQL-first: **52 tools nuevas** agregadas en 5 bloques,
orientadas a capacidades donde PostgreSQL tiene ventajas o necesidades propias.

## Diferencias contra SQL Server

Algunas tools del MCP MSSQL eran intrinsecamente de SQL Server. En PostgreSQL:

- `recompile_procedure` y `recompile_all_procedures` devuelven advertencia
  `NOT_APPLICABLE`.
- `clear_plan_cache` devuelve advertencia `NOT_APPLICABLE`.
- `database_files` reporta tamanos de bases, no archivos MDF/LDF.
- `tempdb_usage` usa `pg_stat_database.temp_files/temp_bytes`.
- `create_or_alter` usa `CREATE OR REPLACE` cuando aplica.
- `get_sql_agent_jobs`, `start_job` y `job_history` usan `pg_cron` si esta
  instalado; sin esa extension devuelven advertencia.
- `list_linked_servers` lista foreign servers/FDW. `execute_on_linked` no
  tiene pass-through generico equivalente a SQL Server linked servers.
- `cdc_status` y `replication_status` reportan logical replication,
  publications, slots, subscriptions y senders.
- `snapshot_database`/`restore_snapshot` usan `CREATE DATABASE ... WITH
  TEMPLATE`; no son snapshots copy-on-write como SQL Server.

## Pruebas realizadas

Validado localmente contra PostgreSQL 17.10 en `localhost` con usuario
`postgres`:

```cmd
C:\Python310\python.exe -m py_compile server.py
```

Y pruebas directas de:

- conexion `postgres/pgSQL`
- `current_context`
- `list_databases`
- `execute_query` con parametro `@x`
- `list_schemas`
- `server_info`
- DDL/DML sobre tabla descartable: create, schema, bulk insert, count, upsert,
  sample, indexes y drop.