# schema-engram-mcp

Servidor **MCP** (Model Context Protocol) que guarda la **estructura de bases de datos** (esquema: tablas, columnas, claves, índices, etc.) en un fichero **SQLite** local. Está pensado como memoria persistente **similar en espíritu a [Engrams](https://engrams.sh)** (contexto estructurado para el asistente), pero **específico para esquemas de BD**.

## Herramientas MCP

| Herramienta | Descripción |
|-------------|-------------|
| `db_schema_save` | Guarda una instantánea JSON del esquema (`workspace_id`, `connection_name`, …). |
| `db_schema_get` | Recupera la última instantánea o una por `snapshot_id`. |
| `db_schema_list` | Lista metadatos de instantáneas (sin volcar todo el JSON). |
| `db_schema_update` | Actualiza por `snapshot_id` (esquema, metadatos o renombre de workspace/conexión). |
| `db_schema_delete` | Borra una instantánea por id. |

### Forma sugerida de `schema` (JSON)

No hay un esquema obligatorio: puedes guardar lo que saques de `information_schema`, Prisma, SQLAlchemy, etc. Un ejemplo razonable:

```json
{
  "tables": [
    {
      "name": "users",
      "columns": [
        {"name": "id", "type": "uuid", "nullable": false, "primary_key": true},
        {"name": "email", "type": "text", "nullable": false}
      ],
      "foreign_keys": [],
      "indexes": [{"name": "users_email_key", "columns": ["email"], "unique": true}]
    }
  ]
}
```

## Instalación

```bash
cd /ruta/al/proyecto
python3 -m venv .venv
source .venv/bin/activate
pip install -e .
```

## Configurar en Cursor

El servidor MCP **no usa puerto**: Cursor arranca un proceso y habla por **stdin/stdout**.

### 1. Dónde pones la configuración

| Ámbito | Fichero | Cuándo usarlo |
|--------|---------|----------------|
| **Todo Cursor** | `~/.cursor/mcp.json` | Quieres el mismo MCP en todos los proyectos. |
| **Solo este repo** | `.cursor/mcp.json` en la raíz del proyecto que abres en Cursor | Quieres dejar la config versionada o por proyecto. |

Si ya existe `mcpServers` con otros servidores, **añade** la clave `"schema-engram"` dentro de ese mismo objeto; no borres los demás.

### 2. Desde la interfaz

1. **Cursor** → **Settings** (⚙️) → busca **MCP** o **Model Context Protocol**.  
2. Ahí suele haber un enlace para editar el JSON o añadir servidores.  
3. Tras guardar, **reinicia** el MCP o Cursor si no aparece el servidor.

(El menú exacto puede variar según la versión; el fichero JSON es lo importante.)

### 3. Opción A — Python local (sin Docker)

En la máquina donde está clonado este repo:

```bash
cd /ruta/al/schema-engram-mcp
python3 -m venv .venv && source .venv/bin/activate && pip install -e .
```

En `mcp.json` (rutas **absolutas**):

```json
{
  "mcpServers": {
    "schema-engram": {
      "command": "/ruta/absoluta/schema-engram-mcp/.venv/bin/python",
      "args": [
        "-m",
        "schema_engram_mcp",
        "--sqlite",
        "/ruta/absoluta/schema-engram-mcp/data/schemas.sqlite"
      ]
    }
  }
}
```

Si no pasas `--sqlite`, el valor por defecto del programa es  
`~/.local/share/schema-engram-mcp/schemas.sqlite` (fuera de `./data`).

### 4. Opción B — Docker Compose (recomendado si ya usas Docker)

Antes: `docker compose build` en la carpeta del repo.  
En `mcp.json`, la ruta del `-f` debe ser la del **`docker-compose.yml` de este repo** (absoluta):

```json
{
  "mcpServers": {
    "schema-engram": {
      "command": "docker",
      "args": [
        "compose",
        "-f",
        "/ruta/absoluta/schema-engram-mcp/docker-compose.yml",
        "run",
        "--rm",
        "-i",
        "mcp"
      ]
    }
  }
}
```

Hay una plantilla en [`.cursor/mcp.json.example`](.cursor/mcp.json.example): cópiala a `.cursor/mcp.json` (en el proyecto que quieras) y sustituye la ruta.

### 5. Otro proyecto distinto al del MCP

Si tu app está en `/proyecto/mi-api` pero el MCP vive en `/herramientas/schema-engram-mcp`, abres **`mi-api`** en Cursor y en `mi-api/.cursor/mcp.json` pones las rutas **absolutas** al clon `schema-engram-mcp` (Python o Docker como arriba). El SQLite puede quedarse en `schema-engram-mcp/data/schemas.sqlite`.

## Variables de entorno

| Variable | Significado |
|----------|-------------|
| `SCHEMA_ENGRAM_SQLITE` | Ruta al fichero SQLite (tiene prioridad si no pasas `--sqlite`). |

## Docker Compose (recomendado)

Desde la raíz del proyecto:

```bash
docker compose build
docker compose run --rm -i mcp
```

El SQLite se guarda en **`./data/schemas.sqlite`** en tu máquina (carpeta montada en el contenedor).

La parte de Cursor + Docker detallada está en **[Configurar en Cursor](#configurar-en-cursor)**. No uses `docker compose up` para MCP: hace falta **`run ... -i`**.

### Solo Docker (sin Compose)

```bash
docker build -t schema-engram-mcp:local .
docker run -i --rm -v "$(pwd)/data:/data" schema-engram-mcp:local
```

## Limitación

Este paquete **no** conecta solo a tu PostgreSQL/MySQL: el cliente MCP (o tú) debe **obtener el esquema** con las herramientas que ya uses y llamar a `db_schema_save` con ese objeto JSON.