# MCP PostgreSQL Server

Un servidor MCP (Model Context Protocol) para PostgreSQL que permite a Cursor y otras herramientas interactuar con bases de datos PostgreSQL a través de HTTP.

## Características

- ✅ Protocolo MCP completo implementado
- ✅ Conexión a PostgreSQL
- ✅ Servidor HTTP con Express
- ✅ Endpoints REST para pruebas directas
- ✅ Herramientas MCP para consultas SQL
- ✅ Soporte para esquemas y metadatos
- ✅ Manejo de errores robusto

## Instalación

1. Clona o descarga este proyecto.
2. Instala las dependencias:

```bash
npm install
```

3. Copia el archivo de configuración:

```bash
cp .env.example .env
```

4. Configura las variables de entorno en `.env`:

```env
PORT=3000
DB_HOST=localhost
DB_PORT=5432
DB_NAME=tu_base_de_datos
DB_USER=tu_usuario
DB_PASSWORD=tu_contraseña
DB_SSL=false
```

## Uso

### Iniciar el servidor

```bash
# Modo desarrollo (con auto-reload)
npm run dev

# Modo producción
npm start
```

El servidor estará disponible en `http://localhost:3000`

### Endpoints disponibles

#### Health Check
```
GET /health
```

#### MCP Protocol
```
POST /mcp
```
Endpoint principal para comunicación MCP.

#### Consulta directa
```
POST /query
Content-Type: application/json

{
  "query": "SELECT * FROM users LIMIT 10",
  "params": []
}
```

#### Listar tablas
```
GET /tables
```

#### Describir tabla
```
GET /tables/:tableName
```

## Configuración en Cursor

Para usar este servidor MCP en Cursor, agrega la siguiente configuración:

### Configuración MCP en Cursor

Crea o edita el archivo de configuración de Cursor (ubicación depende del OS):

**macOS**: `~/Library/Application Support/Cursor/User/globalStorage/cursor.mcp/config.json`
**Windows**: `%APPDATA%\Cursor\User\globalStorage\cursor.mcp\config.json`
**Linux**: `~/.config/Cursor/User/globalStorage/cursor.mcp/config.json`

```json
{
  "mcpServers": {
    "postgres": {
      "url": "http://localhost:3000/mcp"
    }
  }
}
```

También se incluye un archivo `cursor-mcp-config.json` en el proyecto como ejemplo de configuración.

## Herramientas MCP disponibles

### postgres_query
Ejecuta consultas SQL en la base de datos.

```json
{
  "name": "postgres_query",
  "arguments": {
    "query": "SELECT * FROM users WHERE id = $1",
    "params": ["123"]
  }
}
```

### postgres_tables
Lista todas las tablas en la base de datos.

```json
{
  "name": "postgres_tables",
  "arguments": {}
}
```

### postgres_schema
Obtiene información del esquema de la base de datos.

```json
{
  "name": "postgres_schema",
  "arguments": {
    "table_name": "users"
  }
}
```

### postgres_describe_table
Describe la estructura de una tabla específica.

```json
{
  "name": "postgres_describe_table",
  "arguments": {
    "table_name": "users"
  }
}
```

## Ejemplos de uso

### Consulta simple
```bash
curl -X POST http://localhost:3000/query \
  -H "Content-Type: application/json" \
  -d '{"query": "SELECT version()"}'
```

### Consulta con parámetros
```bash
curl -X POST http://localhost:3000/query \
  -H "Content-Type: application/json" \
  -d '{"query": "SELECT * FROM users WHERE age > $1", "params": ["25"]}'
```

### Solicitud MCP
```bash
curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "postgres_tables",
      "arguments": {}
    }
  }'
```

## Desarrollo

### Estructura del proyecto

```
src/
├── server.js          # Servidor HTTP principal
├── mcp-protocol.js    # Implementación del protocolo MCP
└── database.js        # Conexión y utilidades de PostgreSQL

test/
└── test.js           # Tests básicos

.env.example          # Ejemplo de variables de entorno
package.json          # Dependencias y scripts
README.md            # Este archivo
```

### Agregar nuevas herramientas

1. Edita `src/mcp-protocol.js`
2. Registra la nueva herramienta en `initialize()`
3. Implementa el manejador en `handleToolCall()`

## Requisitos

- Node.js 18+
- PostgreSQL 12+
- npm o yarn

## Solución de problemas

### Error de conexión a la base de datos
- Verifica que PostgreSQL esté ejecutándose
- Comprueba las credenciales en `.env`
- Asegúrate de que la base de datos existe

### Puerto en uso
- Cambia el puerto en `.env` con `PORT=otro_puerto`

### Permisos insuficientes
- Verifica que el usuario de la base de datos tenga permisos de lectura/escritura

## Contribuir

1. Fork del proyecto
2. Crea una rama para tu feature
3. Commit tus cambios
4. Push a la rama
5. Abre un Pull Request

## Licencia

MIT