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 (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:

{
  "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

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:

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

En mcp.json (rutas absolutas):

{
  "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):

{
  "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: 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:

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. No uses docker compose up para MCP: hace falta run ... -i.

Solo Docker (sin Compose)

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.