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.
┌─────────────┐ ┌──────────────┐ ┌─────────────────┐
│ Web UI │────▶│ REST API │────▶│ core-db-command │
│ (Vue.js) │ │ (FastAPI) │ │ (Python lib) │
└─────────────┘ └──────┬───────┘ └────────┬────────┘
│ │
┌──────▼───────┐ │
│ MCP Server │───────────────┘
└──────┬───────┘
│
┌──────▼───────┐
│ MCP Client │──▶ AI Agents / LLMs
└──────────────┘Módulo | Paquete | Descripción |
core-db-command |
| Librería Python basada en plugins para todos los controladores de bases de datos |
rest-api-command |
| Capa REST de FastAPI con autenticación OAuth2/LDAP/básica |
mcp-server |
| Herramientas MCP: |
mcp-client |
| Puente cliente MCP para integración con agentes |
web-ui |
| Editor de consultas con Vue 3 + Pinia + Monaco Editor |
config |
| Definiciones de conexión en YAML con sustitución de |
Related MCP server: Database MCP Server
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.
Python 3.11+
Node.js 20+ (para desarrollo de la interfaz web)
Docker & Docker Compose (opcional)
cp .env.example .env
pip install -e ".[dev]"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}db-rest-api
# or: uvicorn rest_api_command.app:app --reloadDocumentación de la API: http://localhost:8000/docs
cd web-ui
cp .env.example .env
npm install
npm run devAbrir http://localhost:5173 — credenciales por defecto: admin / changeme
docker compose up -dServicios:
API REST: http://localhost:8000
Interfaz web: http://localhost:5173
PostgreSQL, MySQL, MongoDB, Redis, Elasticsearch
Método | Ruta | Descripción |
GET |
| Listar conexiones (sin credenciales) |
POST |
| Consulta parametrizada |
POST |
| SQL sin procesar / comando nativo |
GET |
| Esquema de la base de datos |
GET |
| Listar tablas/colecciones |
GET |
| Estructura de la tabla |
GET/POST |
| Historial de consultas |
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=changemeEjecutar:
db-mcp-serverAgregar 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.
db-mcp-client # list available tools
db-mcp-client query local_sqlite "SELECT 1"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)
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): ...pytest tests/ -vLas 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
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.tomlMIT
Describe the structure of a specific table or collection.
| Name | Required | Description | Default |
|---|---|---|---|
| table | Yes | ||
| schema | No | ||
| connection_name | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description's verb 'describe' implies a read-only, non-destructive operation, which is basic transparency. However, it doesn't disclose any additional behaviors (e.g., permission requirements, response shape, or limitations) beyond that.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence that is direct and front-loaded with the core action and target. Every word earns its place, with zero waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple and has an output schema to document return values, but the description lacks context about relationships to sibling tools and does not mention the need for connection_name or that schema is optional. It is complete for a trivial description but not for a comprehensive agent-facing tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% and the description adds no meaning to the parameters. The schema titles (table, schema, connection_name) are self-explanatory, but the description doesn't explain their roles or any requirements beyond the schema's 'required' fields.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Describe') and resource ('structure of a specific table or collection'), clearly distinguishing it from siblings like query_database and execute_sql, which run queries. It precisely communicates what the tool does.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when you need the structure of one specific table, but does not explicitly mention when to avoid it or compare with get_schema or list_tables. No exclusions or alternatives are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Execute raw SQL or native database command on a named connection.
| Name | Required | Description | Default |
|---|---|---|---|
| params | No | ||
| command | Yes | ||
| connection_name | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Since no annotations are provided, the description carries the full burden of behavioral disclosure. It mentions 'raw SQL or native database command', implying potential write operations and risks, but fails to explicitly state that commands can modify data, require admin privileges, or that results may vary by connection type. The output schema exists but is not referenced.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence of 11 words, making it very concise. It includes the essential elements (execute, raw SQL, named connection) without fluff. However, the brevity leaves out important contextual details that could be added without significant lengthening.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (3 parameters, no annotations, 0% schema coverage, output schema present), the description is incomplete. It omits the role of 'params', fails to explain what 'native command' means, and does not address security or error behavior. The output schema exists but is not mentioned, so the agent cannot infer what will be returned.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It defines 'connection_name' and 'command' but provides no additional meaning beyond the schema fields. The 'params' parameter is an optional object described only as 'anyOf object or null', with no explanation of its role (e.g., parameterized queries). The description adds minimal value over the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool executes raw SQL or native database commands on a named connection. This distinguishes it from siblings like 'query_database' and 'describe_table' by emphasizing raw execution and the need for a named connection.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not specify when to use this tool versus siblings like 'query_database' or 'list_tables'. It lacks guidance on prerequisites (e.g., connection setup, permissions) and when not to use it (e.g., for read-only queries or exploratory analysis).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieve schema information for a named database connection.
| Name | Required | Description | Default |
|---|---|---|---|
| connection_name | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description carries the full burden of behavioral disclosure. It does not mention whether the operation is read-only, requires permissions, or what happens if the connection_name is invalid. The minimal phrasing 'Retrieve schema information' provides no insight into side effects, errors, or performance implications.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that is front-loaded and contains no unnecessary words. It is concise and easy to parse. However, it could be slightly more informative without losing conciseness, such as noting the output schema or the nature of the schema information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has an output schema, the description does not need to explain return values, but it still lacks context about how to use the connection_name parameter, what the tool returns (beyond schema info), and how it relates to sibling tools. The presence of siblings like 'list_tables' and 'describe_table' makes the lack of differentiation a significant gap. The description is too minimal to be fully actionable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has a single parameter 'connection_name' with type string, but the description adds no meaning beyond the schema. With 0% schema description coverage, the description should explain what constitutes a valid connection name or how to obtain it. It does not, so it provides no added value for parameter understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves schema information for a named database connection. It uses a specific verb-resource pair ('Retrieve schema information') and implies a scope of a connection, which distinguishes it from sibling tools like 'describe_table' that focus on individual tables. However, it does not specify what 'schema information' includes (e.g., tables, columns, types), which slightly reduces precision.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives such as 'list_tables' or 'describe_table'. There are no prerequisites, exclusions, or context about valid connection names. The description lacks any advisory information to help an agent decide between siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all tables or collections in a named database connection.
| Name | Required | Description | Default |
|---|---|---|---|
| schema | No | ||
| connection_name | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description must fully disclose behavioral traits. It states the tool 'list[s]' tables, implying a read-only operation, but does not explicitly confirm non-destructiveness, error conditions (e.g., invalid connection_name), rate limits, or behavior when 'schema' is null vs. specified. These are important gaps for a database connection tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence with no wasted words. However, it is so brief that it sacrifices information needed for tool selection and correct invocation. Slightly more detail (e.g., about the schema parameter) could be added without sacrificing conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having an output schema (which helps with return values), the description lacks essential context about input semantics (especially the schema parameter), error handling, and behavioral guarantees. For a tool with 0% schema description coverage and no annotations, this description is insufficiently complete for correct agent invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, meaning the description must compensate entirely. While 'connection_name' is mentioned in the description ('named database connection'), the 'schema' parameter (which is optional and can be null) is not explained at all. The description does not clarify how 'schema' affects the listing (e.g., filter by schema, ignored if null). This is a significant gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('List') and resource ('tables or collections') and context ('in a named database connection'), clearly distinguishing this tool from siblings like 'describe_table' (which describes a single table) and 'get_schema' (which retrieves schema-level metadata). It leaves no ambiguity about what this tool returns.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides minimal usage guidance. It does not specify when to use this tool versus 'get_schema' or 'describe_table', nor does it mention any prerequisites (e.g., connection must exist). It lacks exclusion criteria or alternative suggestions, relying on the user/agent to infer context from sibling names.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Run a parameterized query on a named database connection.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | ||
| params | No | ||
| connection_name | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description carries full burden for behavioral disclosure. It fails to indicate whether the tool is read-only, whether it modifies data, what permissions are needed, or any side effects. The agent cannot determine safety or appropriateness from the description alone.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely short (one sentence), but this brevity comes at the cost of completeness. It is under-specified rather than concise. Every sentence should earn its place; here, it leaves critical gaps.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having an output schema (not shown), the description is incomplete. It does not explain return values, error handling, connection requirements, or the role of 'params'. For a tool with 3 parameters and zero annotations, much more context is needed to be minimally viable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, meaning the schema provides no parameter descriptions. The description adds no value: it does not explain the purpose of 'query', 'params', or 'connection_name', nor how to structure the 'params' object. The agent is left guessing parameter semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Run a parameterized query on a named database connection' clearly states the verb and resource, but it does not differentiate itself from the sibling tool 'execute_sql', which likely performs a similar function. The term 'parameterized query' hints at safety but is not explicit enough to distinguish usage.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus siblings like 'get_schema' or 'execute_sql'. There is no mention of prerequisites, when-not-to-use, or alternatives. The agent must rely on the tool name alone to infer context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0describe_tableexecute_sqlget_schemalist_tablesquery_databaseScored across 5 tools
Tools are mostly distinct: query_database and execute_sql both run queries but one is parameterized and the other raw; get_schema, list_tables, describe_table each target different metadata. Minor potential for confusion between the two query tools, but descriptions clarify the difference.
All tool names follow a consistent verb_noun pattern with lowercase and underscores: query_database, get_schema, list_tables, describe_table, execute_sql. No mixed conventions or irregularities.
5 tools are well-scoped for a database MCP server. The set covers core operations—querying, schema retrieval, table listing, structure description, raw execution—without being overwhelming or too sparse.
The tool surface covers essential query and schema exploration operations. The execute_sql tool can handle DDL, but there are no dedicated create/alter/drop tools; transaction commands are also missing. Overall, it's nearly complete for a typical read-heavy interaction pattern.
Let AI agents query data and act across all your business apps via MCP.
PostgreSQL, MySQL, and SQL Server in one session. 26 read-only MCP tools for AI agents.
An agent-native database over MCP: shared, validated, structured records in every AI chat.
Governed app access for AI agents: 1,000+ apps & 12,000+ tools via Code Mode MCP.
