Agente de Análisis de Datos MCP

Analítica local-primero y gobernada para clientes MCP sobre SQLite y PostgreSQL.

mcp-data-analysis-agent proporciona a un cliente MCP una pequeña capa de acceso a datos auditable en lugar de acceso directo a la base de datos. Valida SQL antes de la ejecución, utiliza conexiones de solo lectura, limita los resultados y el tiempo de ejecución, escribe registros de observabilidad respaldados por recibos y mantiene las credenciales en la máquina del operador.

Por qué existe

Los clientes MCP pueden razonar sobre datos, pero no deberían recibir credenciales de base de datos sin restricciones ni ejecutar silenciosamente declaraciones arbitrarias. Este proyecto proporciona un punto de control local para ese límite:

• Mantener rutas de base de datos, URLs, contraseñas y tokens en un archivo .env ignorado.

• Permitir solo una declaración SELECT o WITH parametrizada.

• Bloquear mutaciones, DDL, comandos, adjuntos, múltiples declaraciones, funciones inseguras, campos restringidos y rutas de artefactos inseguras.

• Requerir acceso de solo lectura a nivel de base de datos además de la política de la aplicación.

• Preservar SQL normalizado, tiempos, vinculación de tareas, recibos, hashes y líneas de tiempo de eventos para auditoría posterior.

El servidor usa solo stdio. No aloja una API pública, no sube datos fuente, no almacena credenciales remotas ni crea usuarios de base de datos de producción.

Related MCP server: sql-explorer-mcp

Capacidades

• Acceso a SQLite y PostgreSQL a través de SQLAlchemy Core con validación de política SQLGlot.

• Descubrimiento de fuente, esquema, relaciones, perfil, calidad/frescura y deriva de esquema.

• Validación, planes de explicación, ejecución acotada, paginación con desplazamiento no negativo, cancelación, tiempos de espera y límites de concurrencia.

• Clasificaciones para campos/fuentes públicos, internos, confidenciales y restringidos.

• Métricas semánticas aprobadas, recetas nativas de Git, comparación de períodos, detección de cambios y recomendaciones de gráficos.

• Paneles HTML sin conexión, CSV, Parquet, PDF Typst, metadatos de recibos y directorios de salida atómicos seguros.

• Carga de contexto ClineFlow, diarios de tareas, registros de consultas/ejecuciones inmutables, líneas de tiempo de eventos y verificación de integridad.

• Fixtures deterministas de retail, SaaS y soporte, incluidos fixtures de paridad local SQLite-a-PostgreSQL.

Requisitos previos

• Python 3.11 o más reciente y uv.

• Typst para la instalación de renderizado de informes compatible.

• Herramientas de línea de comandos de PostgreSQL, incluido createdb para fixtures de paridad locales.

• Un bundle ClineFlow/OKF saludable en el proyecto objetivo.

Ejecute mcp-data-cli preflight para instalar o informar sobre las herramientas locales requeridas a través de un administrador de paquetes de ámbito de usuario disponible. Nunca contacta con una fuente configurada. mcp-data-cli doctor valida la instalación local; ninguna fuente configurada se informa como configuration_pending, no como un fallo de instalación.

Instalar

Instalar este repositorio en el proyecto actual

Cuando se le pida a un agente u operador que instale este repositorio de GitHub en un proyecto, use el instalador de repositorio—no un comando uv tool install simple:

cd /path/to/your-project
curl -fsSL https://raw.githubusercontent.com/hassanvfx/mcp-data-analysis-agent/main/install.sh | bash

El instalador instala la herramienta de línea de comandos e inicializa el directorio desde el que se ejecutó. Crea el playground de retail determinista ignorado, escribe el único valor privado MCP_DATA_SOURCE_URL en .env, escribe la política de fuente y fusiona el servidor MCP en cada cliente compatible detectado. No copia el paquete en el proyecto y nunca pone una URL de base de datos o credencial en una configuración de cliente. Los avisos de habilitación/confianza del cliente y reinicio permanecen bajo el control de cada aplicación cliente.

uv tool install instala intencionalmente ejecutables a nivel de usuario y no ejecuta ganchos post-instalación que muten el proyecto. Úselo solo cuando quiera instalar el ejecutable por separado, luego ejecute mcp-data-cli init usted mismo.

Flujo de trabajo compatible con PyPI

uv tool install mcp-data-analysis-agent
cd /path/to/your-project
mcp-data-cli preflight
mcp-data-cli init
mcp-data-cli doctor

Para instalar la versión actual del repositorio antes de un lanzamiento de paquete, reemplace el comando de instalación con:

uv tool install git+https://github.com/hassanvfx/mcp-data-analysis-agent.git

En el primer uso del servidor en cualquier cliente MCP compatible, el agente crea y abre un playground SQLite de retail determinista solo para desarrollo en .mcp-data/playground.sqlite. La herramienta MCP compartida welcome explica cómo explorarlo y cómo cambiar a una fuente real. init materializa el mismo playground en la política de proyecto explícita y en el .env privado, luego fusiona entradas de cliente MCP seguras después de una confirmación. El instalador de repositorio explícito usa init --yes porque ejecutar ese instalador es la única autorización para esas escrituras con ámbito.

Use setup --all para previsualizar solo la configuración del cliente, o setup --all --apply para fusionar solo la entrada stdio mcp-data-analysis después de una confirmación explícita. Preserva servidores y configuraciones no relacionados. Use setup --status para inspeccionar la detección y el estado de configuración actual.

Setup configura solo definiciones MCP. No puede omitir el aviso de confianza/habilitación de un cliente ni lanzar/reiniciar un IDE. Los detalles de configuración de VS Code están documentados por VS Code y GitHub Copilot en VS Code; Continue documenta fragmentos MCP de proyecto en su guía MCP.

Bootstrap de lanzamiento verificado por checksum

Para un wheel versionado y su checksum SHA-256 publicado:

MCP_DATA_RELEASE_URL='https://example.invalid/mcp_data_analysis_agent-0.1.0-py3-none-any.whl' \
MCP_DATA_RELEASE_SHA256='published-sha256' \
./install.sh

El bootstrap requiere curl y uv, verifica el artefacto con sha256sum o shasum, e instala solo después de que el checksum coincida. Luego inicializa el proyecto actual exactamente como lo hace el instalador de repositorio. No usa sudo ni contacta con una base de datos de producción; crea solo datos de demostración deterministas locales.

Configurar una fuente activa

La instalación estándar usa exactamente una fuente activa, llamada data, y exactamente un valor privado en .env: MCP_DATA_SOURCE_URL. No es una constante de paquete ni un valor de prueba—es el único valor que el operador cambia para apuntar a su propia base de datos de solo lectura. Mantenga .env privado; está ignorado por Git.

En el primer uso, data apunta automáticamente al playground de retail generado. Ejecute mcp-data-cli init cuando esté listo para materializar esa elección en el .env del proyecto; escribe:

MCP_DATA_SOURCE_URL='/absolute/path/to/your-project/.mcp-data/playground.sqlite'

El playground son datos sintéticos solo para desarrollo. Permite que una nueva instalación ejecute descubrimiento de esquema, consultas gobernadas, recibos e informes inmediatamente; nunca son datos de producción y nunca se sobrescriben con una ejecución posterior de init. Todos los clientes compatibles reciben las mismas instrucciones de bienvenida del servidor stdio y la herramienta MCP welcome.

# .mcp-data-agent.toml
[agent]
default_row_limit = 500
max_row_limit = 5000
query_timeout_seconds = 30

# The database dialect is inferred from MCP_DATA_SOURCE_URL.
[source]
env = "MCP_DATA_SOURCE_URL"
allowed_schemas = ["analytics"]
classification = "internal"

[classification.columns]
email = "restricted"

# .env — never commit this file. Change this single value for your own source.
MCP_DATA_SOURCE_URL='postgresql://readonly_user:password@localhost:5432/analytics'

Para SQLite, haga que la misma variable única sea una ruta de archivo absoluta o una URL SQLite. Para PostgreSQL, use una URL postgres:// o postgresql://. No se necesita configuración manual de dialecto:

MCP_DATA_SOURCE_URL=/absolute/path/to/your.sqlite
# or: MCP_DATA_SOURCE_URL='postgresql://readonly_user:password@localhost:5432/analytics'

Use data como argumento de fuente en llamadas CLI, por ejemplo mcp-data-cli schema data. El agente rechaza esquemas de URL no compatibles, rutas SQLite relativas y un dialecto declarado heredado que entre en conflicto con la URL. Las políticas multi-fuente establecidas siguen siendo legibles, pero init se niega deliberadamente a reescribirlas; migre manualmente o comience un nuevo proyecto simplificado.

Para PostgreSQL, use una cuenta dedicada de privilegios mínimos sin privilegios de escritura o DDL. El agente también habilita una sesión de solo lectura y aplica la ruta de búsqueda de esquema configurada, pero el control de acceso del lado de la base de datos sigue siendo obligatorio.

Flujo de trabajo típico

Valide antes de ejecutar, luego inspeccione el plan y ejecute una consulta acotada:

mcp-data-cli sql data 'SELECT id, name, stock FROM products WHERE id = :id' --params '{"id": 1}'
mcp-data-cli explain data 'SELECT id, name, stock FROM products WHERE id = :id' --params '{"id": 1}'
mcp-data-cli query data 'SELECT id, name, stock FROM products ORDER BY id' --limit 25 --offset 0

Cree una tarea explícita cuando varias operaciones pertenezcan a un análisis:

mcp-data-cli task-begin 'Inventory review' 'Identify stockout risk.'
mcp-data-cli observe <task-id>
mcp-data-cli task-complete <task-id> 'Findings recorded.'
mcp-data-cli evaluate-task <task-id>

Genere informes en un directorio nuevo seleccionado por el llamador. Se rechazan directorios existentes y el recorrido de enlaces simbólicos.

mcp-data-cli report data 'SELECT id, name, stock FROM products' outputs/inventory --pdf --parquet

Cada informe contiene HTML sin conexión, CSV, artefactos opcionales Parquet/PDF, metadatos de recibos, rutas y hashes de contenido. Los artefactos generados, fuentes y credenciales no deben ser confirmados.

Fixtures de desarrollo y paridad PostgreSQL

init crea solo el pequeño playground de retail descrito anteriormente. Los contribuyentes pueden generar fixtures sintéticos deterministas adicionales explícitamente:

mcp-data-cli dataset retail /tmp/retail.sqlite --tier unit --seed 1
mcp-data-cli dataset-postgres retail mcp_data_parity --tier unit --seed 1
# Seed an already-created disposable test database; creates only mcp_seed_<domain>.
MCP_DATA_TEST_POSTGRES_URL='postgresql://mcp_data_test@localhost:5432/mcp_data_parity' \
  mcp-data-cli seed-postgres retail --seed 1

dataset-postgres usa createdb local, rechaza un nombre de base de datos existente, crea datos SQLite solo en un directorio temporal, luego los copia a la nueva base de datos PostgreSQL bajo el esquema mcp_parity. No requiere una URL PostgreSQL desechable proporcionada manualmente.

seed-postgres es para una base de datos de prueba aislada ya aprovisionada. Lee la URL de prueba privada del entorno y reemplaza solo sus esquemas reservados mcp_seed_retail, mcp_seed_saas o mcp_seed_support. Nunca toca esquemas públicos/de aplicación.

Ejecute la suite de calidad local completa con una instancia PostgreSQL aislada al desarrollar el comportamiento del adaptador. CI cubre linting, tipado, pruebas, puertas de cobertura, renderizado real de Typst, paridad SQLite/PostgreSQL, escaneo de secretos, auditoría de dependencias, generación de SBOM y automatización de lanzamiento de publicación confiable.

uv run ruff check src tests scripts
uv run mypy src
uv run pytest --cov=mcp_data_agent --cov-branch
uv run python scripts/check_coverage.py coverage.json
./validate-okf

Los módulos de configuración crítica de seguridad, contexto, libro mayor y política SQL requieren 100% de cobertura de líneas y ramas. Las puertas generales requieren al menos 90% de cobertura de líneas y 85% de cobertura de ramas.

Contrato de seguridad y operación

• Las consultas deben estar parametrizadas y se validan antes de la conexión/ejecución de la base de datos.

• Los límites de resultados y desplazamientos están gobernados por la política del proyecto; el SQL del llamador no puede omitirlos.

• Las columnas restringidas se rechazan antes de la ejecución y los parámetros similares a secretos se redactan en los registros de observabilidad.

• Los diarios de tareas, recibos de consultas, ejecuciones y eventos se almacenan bajo knowledge/ y observability/; las URLs de base de datos, secretos sin procesar, bases de datos fuente, cachés de resultados y binarios de informes están excluidos.

• Los conjuntos de datos sintéticos locales son solo infraestructura de desarrollo y no son incorporación de producción.

Consulte guía de operaciones, la política de seguridad y la licencia MIT para el contrato completo de operación y divulgación.

Contribuciones y lanzamientos

Use commits enfocados y preserve las etiquetas anotadas checkpoint-*: son puntos de reversión explícitos para hitos de entrega. Actualice el diario de ingeniería ClineFlow activo y el registro de conocimiento con cambios materiales, ejecute la validación OKF, luego confirme la implementación y la evidencia de conocimiento juntas.

GitHub Actions construye y verifica distribuciones en la publicación del lanzamiento. Los endpoints de lanzamiento y las credenciales de publicación son configuración del repositorio; nunca se almacenan en este código.