Data Nexus MCP

Una plataforma modular y segura para conectarse a bases de datos SQL y NoSQL a través de API REST, MCP (Protocolo de Contexto de Modelo) y una interfaz web en Vue.js.

Arquitectura

┌─────────────┐     ┌──────────────┐     ┌─────────────────┐
│   Web UI    │────▶│  REST API    │────▶│ core-db-command │
│  (Vue.js)   │     │  (FastAPI)   │     │  (Python lib)   │
└─────────────┘     └──────┬───────┘     └────────┬────────┘
                           │                       │
                    ┌──────▼───────┐               │
                    │  MCP Server  │───────────────┘
                    └──────┬───────┘
                           │
                    ┌──────▼───────┐
                    │  MCP Client  │──▶ AI Agents / LLMs
                    └──────────────┘

Módulos

Related MCP server: Database MCP Server

Tipos de Bases de Datos Compatibles

El registro de controladores soporta más de 50 tipos de bases de datos en 13 categorías:

• Relacionales: PostgreSQL, MySQL, MSSQL, Oracle, CockroachDB, TiDB, YugabyteDB, TimescaleDB, pgvector

• Documentales: MongoDB, DocumentDB, Firestore, Couchbase (esqueleto)

• Clave-Valor: Redis, DynamoDB, Memcached/etcd/RocksDB (esqueleto)

• Columnas Anchas: Cassandra, ScyllaDB, Bigtable/HBase (esqueleto)

• Grafos: Neo4j, Neptune/JanusGraph/ArangoDB (esqueleto)

• Series Temporales: InfluxDB, ClickHouse, Prometheus/QuestDB (esqueleto)

• Vectoriales: Qdrant, Weaviate, Milvus, Pinecone

• Búsqueda: Elasticsearch, OpenSearch, Splunk/Solr (esqueleto)

• Almacén: BigQuery, Snowflake, Redshift/Databricks (esqueleto)

• Multimodelo: Cosmos DB, OrientDB (esqueleto)

• Empotradas: SQLite, DuckDB, Realm/LMDB (esqueleto)

• Libro Mayor: QLDB/BigchainDB (esqueleto)

• NewSQL: Spanner (esqueleto)

Los controladores totalmente implementados incluyen PostgreSQL, MySQL, MSSQL, Oracle, MongoDB, Redis, SQLite, DuckDB, Elasticsearch, ClickHouse, Neo4j, InfluxDB, Cassandra, DynamoDB, BigQuery, Snowflake, Qdrant, Weaviate, Milvus, Pinecone, Cosmos DB y Firestore. Los controladores esqueleto están registrados y son extensibles.

Inicio Rápido

Prerrequisitos

• Python 3.11+

• Node.js 20+ (para desarrollo de la interfaz web)

• Docker & Docker Compose (opcional)

1. Instalar dependencias Python

cp .env.example .env
pip install -e ".[dev]"

2. Configurar conexiones

Editar config/connections.yaml y establecer secretos mediante variables de entorno:

connections:
  - name: postgres_prod
    type: postgresql
    host: localhost
    port: 5432
    database: mydb
    user: readonly_user
    password: ${PG_PASSWORD}

3. Iniciar la API REST

db-rest-api
# or: uvicorn rest_api_command.app:app --reload

Documentación de la API: http://localhost:8000/docs

4. Iniciar la interfaz web (desarrollo)

cd web-ui
cp .env.example .env
npm install
npm run dev

Abrir http://localhost:5173 — credenciales por defecto: admin / changeme

5. Ejecutar con Docker Compose

docker compose up -d

Servicios:

• API REST: http://localhost:8000

• Interfaz web: http://localhost:5173

• PostgreSQL, MySQL, MongoDB, Redis, Elasticsearch

Endpoints de la API REST

Servidor MCP

Configurar en .env o Cursor MCP env:

MCP_REST_API_URL=http://localhost:8000
# Option A: bearer token (when REST_API_AUTH_MODE=oauth2)
MCP_REST_API_TOKEN=<jwt-from-/api/auth/token>
# Option B: username/password (works with basic auth; auto-fetches JWT if oauth2)
MCP_REST_API_USER=admin
MCP_REST_API_PASSWORD=changeme

Ejecutar:

db-mcp-server

Agregar a la configuración MCP de Cursor/Claude:

{
  "mcpServers": {
    "data-nexus-mcp": {
      "command": "db-mcp-server",
      "cwd": "/path/to/data_nexus_mcp",
      "env": {
        "MCP_REST_API_URL": "http://localhost:8000",
        "MCP_REST_API_USER": "admin",
        "MCP_REST_API_PASSWORD": "changeme"
      }
    }
  }
}

Nota: Las variables REST_API_* pertenecen al proceso de la API REST (db-rest-api), no en la configuración del servidor MCP.

Cliente MCP

db-mcp-client                    # list available tools
db-mcp-client query local_sqlite "SELECT 1"

Autenticación

Establecer REST_API_AUTH_MODE en uno de estos valores:

• basic — Autenticación básica HTTP (por defecto en desarrollo)

• oauth2 — Tokens JWT bearer mediante /api/auth/token

• ldap — Enlace LDAP (requiere REST_API_LDAP_SERVER y REST_API_LDAP_BASE_DN)

Agregar un Nuevo Controlador

1. Crear core_db_commando/drivers/mydb.py2. Subclase de BaseDriver y estableer driver_type3. Decorar con @DriverRegistry.register4. Importar en core_db_command/drivers/registry_loader.py

from core_db_command.base import BaseDriver, DriverRegistry

@DriverRegistry.register
class MyDBDriver(BaseDriver):
    driver_type = "mydb"

    async def connect(self): ...
    async def disconnect(self): ...
    async def query(self, query, params=None): ...
    async def execute(self, command, params=None): ...
    async def list_tables(self, schema=None): ...
    async def describe_table(self, table, schema=None): ...

Pruebas

pytest tests/ -v

Notas de Seguridad

• Las credenciales nunca son devueltas por la API REST o el servidor MCP

• Los secretos deben usar placeholders ${ENV_VAR} en el archivo de configuración YAML

• Todos los endpoints de la API requieren autenticación

• La entrada de consultas es validada y limitada en longitud

Estructura del Proyecto

data-nexus-mcp/
├── core_db_command/       # Core library + drivers
├── rest_api_command/      # FastAPI REST API
├── mcp_server/            # MCP server
├── mcp_client/            # MCP client
├── web-ui/                # Vue.js frontend
├── config/                # YAML connection config
├── tests/                 # Unit tests
├── docker-compose.yml
├── Dockerfile
└── pyproject.toml

Licencia

MIT