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

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

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

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.