MCP BigQuery Server

Accede de forma segura a conjuntos de datos de BigQuery con almacenamiento en caché inteligente, seguimiento de esquemas y análisis de consultas mediante la integración con Supabase.

GitHubPrueba este MCPPatrocinado

Documentación

MCP BigQuery Server

Un servidor FastMCP para acceder de forma segura a conjuntos de datos de BigQuery con caché inteligente, seguimiento de evolución de esquemas y analítica de consultas mediante la integración con Supabase.

Características

  • Múltiples métodos de transporte: HTTP, Stdio y SSE (Server-Sent Events)
  • Integración con BigQuery: Acceso seguro a conjuntos de datos y tablas de BigQuery
  • Caché inteligente: Caché de resultados de consultas con gestión de TTL y seguimiento de dependencias
  • Base de conocimiento de Supabase: Almacenamiento mejorado de metadatos y contexto empresarial
  • Analítica de consultas: Análisis de rendimiento y recomendaciones de optimización
  • Seguimiento de evolución de esquemas: Monitorización de cambios en el esquema de tablas a lo largo del tiempo
  • Sugerencias impulsadas por IA: Recomendaciones de consultas basadas en patrones de uso
  • Eventos en tiempo real: Server-Sent Events para monitorización de consultas y estado del sistema
  • Consultas de solo lectura: Enfoque de seguridad primero con ejecución de SQL de solo lectura
  • Seguridad a nivel de fila: Control de acceso basado en usuario y aislamiento de caché
  • API integral: Endpoints RESTful y soporte del protocolo MCP

Instalación

Usando uv (recomendado):

# Clone the repository
git clone <repository-url>
cd mcp-bigquery-server

# Create virtual environment and install dependencies
uv venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
uv pip install -e ".[dev]"

Configuración

  1. Copia el archivo de entorno de ejemplo:
cp .env.example .env
  1. Edita .env con los detalles de tu BigQuery y Supabase:
# BigQuery Configuration
PROJECT_ID=your-project-id
LOCATION=US
KEY_FILE=/path/to/your/service-account-key.json  # Optional
DEFAULT_USER_ID=your-default-user-id  # Optional

# Supabase Configuration (for enhanced features)
SUPABASE_URL=https://your-project.supabase.co
SUPABASE_SERVICE_KEY=your-service-role-key  # Recommended for full access
SUPABASE_ANON_KEY=your-anon-key  # Alternative with RLS

Configuración de Supabase

Para las funciones mejoradas de caché y analítica, necesitarás un proyecto de Supabase con las siguientes tablas y políticas.

  • query_cache - Almacena resultados de consultas en caché
  • table_dependencies - Realiza seguimiento de dependencias de tablas para la invalidación de caché
  • query_history - Patrones históricos de ejecución de consultas
  • query_templates - Plantillas de consultas reutilizables
  • column_documentation - Contexto empresarial para columnas de tablas
  • event_log - Seguimiento de eventos del sistema

Ejecuta estas consultas SQL en el editor SQL de Supabase para configurar el esquema:

-- Enable UUID extension
CREATE EXTENSION IF NOT EXISTS "uuid-ossp";

-- 1. Query Result Caching Tables
CREATE TABLE query_cache (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  query_hash TEXT UNIQUE NOT NULL,
  sql_query TEXT NOT NULL,
  result_data JSONB NOT NULL,
  metadata JSONB NOT NULL, -- bytes processed, execution time, etc.
  created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
  expires_at TIMESTAMP WITH TIME ZONE NOT NULL,
  hit_count INTEGER DEFAULT 0
);

-- Indexes for query_cache
CREATE INDEX idx_query_cache_hash ON query_cache(query_hash);
CREATE INDEX idx_query_cache_expires ON query_cache(expires_at);
CREATE INDEX idx_query_cache_created ON query_cache(created_at);

CREATE TABLE table_dependencies (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  query_cache_id UUID REFERENCES query_cache(id) ON DELETE CASCADE,
  project_id TEXT NOT NULL,
  dataset_id TEXT NOT NULL,
  table_id TEXT NOT NULL,
  created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
);

-- Indexes for table_dependencies
CREATE INDEX idx_table_deps_lookup ON table_dependencies(project_id, dataset_id, table_id);
CREATE INDEX idx_table_deps_cache ON table_dependencies(query_cache_id);

-- 2. Schema Evolution & Knowledge Base Tables
CREATE TABLE schema_snapshots (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  project_id TEXT NOT NULL,
  dataset_id TEXT NOT NULL,
  table_id TEXT NOT NULL,
  schema_version INTEGER NOT NULL DEFAULT 1,
  schema_data JSONB NOT NULL,
  row_count BIGINT,
  size_bytes BIGINT,
  created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
);

-- Indexes for schema_snapshots
CREATE UNIQUE INDEX idx_schema_version ON schema_snapshots(project_id, dataset_id, table_id, schema_version);
CREATE INDEX idx_schema_table ON schema_snapshots(project_id, dataset_id, table_id);

CREATE TABLE column_documentation (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  project_id TEXT NOT NULL,
  dataset_id TEXT NOT NULL,
  table_id TEXT NOT NULL,
  column_name TEXT NOT NULL,
  description TEXT,
  business_rules TEXT[],
  sample_values JSONB,
  data_quality_notes TEXT,
  updated_by TEXT,
  updated_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
);

-- Indexes for column_documentation
CREATE UNIQUE INDEX idx_column_docs_unique ON column_documentation(project_id, dataset_id, table_id, column_name);
CREATE INDEX idx_column_docs_table ON column_documentation(project_id, dataset_id, table_id);

-- 3. Query Analytics & Pattern Recognition Tables
CREATE TABLE query_history (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  user_id TEXT,
  sql_query TEXT NOT NULL,
  execution_time_ms INTEGER,
  bytes_processed BIGINT,
  success BOOLEAN NOT NULL,
  error_message TEXT,
  tables_accessed TEXT[],
  created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
);

-- Indexes for query_history
CREATE INDEX idx_query_history_user ON query_history(user_id);
CREATE INDEX idx_query_history_success ON query_history(success);
CREATE INDEX idx_query_history_created ON query_history(created_at);
CREATE INDEX idx_query_history_tables ON query_history USING GIN(tables_accessed);

CREATE TABLE query_templates (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  name TEXT NOT NULL,
  description TEXT,
  template_sql TEXT NOT NULL,
  parameters JSONB NOT NULL DEFAULT '{}',
  usage_count INTEGER DEFAULT 0,
  tags TEXT[],
  created_by TEXT,
  created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
  updated_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
);

-- Indexes for query_templates
CREATE INDEX idx_query_templates_usage ON query_templates(usage_count DESC);
CREATE INDEX idx_query_templates_tags ON query_templates USING GIN(tags);

-- 4. Real-time Event Tracking
CREATE TABLE event_log (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  event_type TEXT NOT NULL,
  event_data JSONB NOT NULL,
  user_id TEXT,
  session_id TEXT,
  created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
);

-- Indexes for event_log
CREATE INDEX idx_event_log_type ON event_log(event_type);
CREATE INDEX idx_event_log_user ON event_log(user_id);
CREATE INDEX idx_event_log_session ON event_log(session_id);
CREATE INDEX idx_event_log_created ON event_log(created_at);

-- 5. User Preferences & Settings
CREATE TABLE user_preferences (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  user_id TEXT UNIQUE NOT NULL,
  preferences JSONB NOT NULL DEFAULT '{}',
  query_defaults JSONB NOT NULL DEFAULT '{}',
  favorite_queries UUID[] DEFAULT '{}',
  created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
  updated_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
);

-- Row Level Security (RLS) Policies for BigQuery Cache Tables

-- First, ensure RLS is enabled on the tables
ALTER TABLE query_cache ENABLE ROW LEVEL SECURITY;
ALTER TABLE query_history ENABLE ROW LEVEL SECURITY;
ALTER TABLE table_dependencies ENABLE ROW LEVEL SECURITY;
ALTER TABLE schema_snapshots ENABLE ROW LEVEL SECURITY;
ALTER TABLE column_documentation ENABLE ROW LEVEL SECURITY;
ALTER TABLE query_templates ENABLE ROW LEVEL SECURITY;
ALTER TABLE event_log ENABLE ROW LEVEL SECURITY;

-- Option 1: Allow all operations (least secure, but simplest for development)
-- Use this during development/testing phases

-- Allow all operations on query_cache
CREATE POLICY "Allow all operations on query_cache" ON query_cache
FOR ALL USING (true) WITH CHECK (true);

-- Allow all operations on query_history
CREATE POLICY "Allow all operations on query_history" ON query_history
FOR ALL USING (true) WITH CHECK (true);

-- Allow all operations on table_dependencies
CREATE POLICY "Allow all operations on table_dependencies" ON table_dependencies
FOR ALL USING (true) WITH CHECK (true);

-- Allow all operations on schema_snapshots
CREATE POLICY "Allow all operations on schema_snapshots" ON schema_snapshots
FOR ALL USING (true) WITH CHECK (true);

-- Allow all operations on column_documentation
CREATE POLICY "Allow all operations on column_documentation" ON column_documentation
FOR ALL USING (true) WITH CHECK (true);

-- Allow all operations on query_templates
CREATE POLICY "Allow all operations on query_templates" ON query_templates
FOR ALL USING (true) WITH CHECK (true);

-- Allow all operations on event_log
CREATE POLICY "Allow all operations on event_log" ON event_log
FOR ALL USING (true) WITH CHECK (true);

-- Option 2: User-based policies (more secure)
-- Uncomment and use these instead if you have user authentication

/*
-- Allow users to manage their own cache entries
CREATE POLICY "Users can manage own cache entries" ON query_cache
FOR ALL USING (auth.uid()::text = user_id OR user_id IS NULL);

-- Allow users to manage their own query history
CREATE POLICY "Users can manage own query history" ON query_history
FOR ALL USING (auth.uid()::text = user_id OR user_id IS NULL);

-- Allow all operations on system tables (no user-specific data)
CREATE POLICY "Allow system operations" ON table_dependencies
FOR ALL USING (true) WITH CHECK (true);

CREATE POLICY "Allow system operations" ON schema_snapshots
FOR ALL USING (true) WITH CHECK (true);

CREATE POLICY "Allow system operations" ON column_documentation
FOR ALL USING (true) WITH CHECK (true);

CREATE POLICY "Allow system operations" ON query_templates
FOR ALL USING (true) WITH CHECK (true);

-- Allow users to create their own event log entries
CREATE POLICY "Users can create event logs" ON event_log
FOR INSERT WITH CHECK (auth.uid()::text = user_id OR user_id IS NULL);

CREATE POLICY "Users can read event logs" ON event_log
FOR SELECT USING (auth.uid()::text = user_id OR user_id IS NULL);
*/

-- Option 3: Service role policies (for backend services)
-- If your application uses a service role key, you might want to create
-- policies that allow the service role to perform all operations

/*
-- Create a function to check if the current role is the service role
CREATE OR REPLACE FUNCTION is_service_role()
RETURNS BOOLEAN AS $$
BEGIN
  RETURN current_setting('role') = 'service_role';
EXCEPTION
  WHEN others THEN
    RETURN false;
END;
$$ LANGUAGE plpgsql SECURITY DEFINER;

-- Service role policies
CREATE POLICY "Service role can manage query_cache" ON query_cache
FOR ALL USING (is_service_role()) WITH CHECK (is_service_role());

CREATE POLICY "Service role can manage query_history" ON query_history
FOR ALL USING (is_service_role()) WITH CHECK (is_service_role());
*/

-- Triggers for automatic timestamp updates
CREATE OR REPLACE FUNCTION update_updated_at_column()
RETURNS TRIGGER AS $$
BEGIN
    NEW.updated_at = NOW();
    RETURN NEW;
END;
$$ LANGUAGE plpgsql;

CREATE TRIGGER update_column_documentation_updated_at
    BEFORE UPDATE ON column_documentation
    FOR EACH ROW EXECUTE FUNCTION update_updated_at_column();

CREATE TRIGGER update_query_templates_updated_at
    BEFORE UPDATE ON query_templates
    FOR EACH ROW EXECUTE FUNCTION update_updated_at_column();

CREATE TRIGGER update_user_preferences_updated_at
    BEFORE UPDATE ON user_preferences
    FOR EACH ROW EXECUTE FUNCTION update_updated_at_column();

-- Cache Cleanup Function
CREATE OR REPLACE FUNCTION cleanup_expired_cache()
RETURNS INTEGER AS $$
DECLARE
    deleted_count INTEGER;
BEGIN
    DELETE FROM query_cache WHERE expires_at < NOW();
    GET DIAGNOSTICS deleted_count = ROW_COUNT;
    RETURN deleted_count;
END;
$$ LANGUAGE plpgsql;

Estas tablas permiten:

  • Caché de resultados de consultas y seguimiento de dependencias
  • Evolución de esquemas y documentación
  • Analítica de consultas y reconocimiento de patrones
  • Registro de eventos en tiempo real
  • Preferencias y ajustes de usuario

La seguridad a nivel de fila (RLS) está habilitada para todas las tablas. Puedes elegir entre varias opciones de políticas RLS:

  • Opción 1: Permitir todas las operaciones (para desarrollo/pruebas)
  • Opción 2: Políticas basadas en usuario (recomendado para producción con autenticación)
  • Opción 3: Políticas de rol de servicio (para servicios backend)

Personaliza las políticas RLS según sea necesario para tu entorno.

El servidor funcionará sin Supabase pero con funcionalidad limitada.

Uso

Línea de comandos

# HTTP mode (default)
mcp-bigquery --transport http --host 0.0.0.0 --port 8000

# Stdio mode (for MCP clients)
mcp-bigquery --transport stdio

# SSE mode
mcp-bigquery --transport sse --host 0.0.0.0 --port 8000

API de Python

from mcp_bigquery.main import main
import sys

# Set command line arguments
sys.argv = ['mcp-bigquery', '--transport', 'http', '--port', '8000']
main()

Uso con Claude Desktop

Para usar este servidor MCP BigQuery con Claude Desktop, debes configurarlo en tu archivo de configuración de Claude Desktop.

1. Instalar y configurar el servidor

Primero, asegúrate de que el servidor esté instalado y configurado:

# Clone and install the server
git clone <repository-url>
cd mcp-bigquery-server
uv venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
uv pip install -e ".[dev]"

# Set up environment variables
cp .env.example .env
# Edit .env with your BigQuery and Supabase project details

2. Configurar Claude Desktop

Añade el servidor a tu archivo de configuración de Claude Desktop:

Ubicaciones del archivo de configuración:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows: %APPDATA%\Claude\claude_desktop_config.json

Para macOS/Linux:

{
  "mcpServers": {
    "mcp-bigquery": {
      "command": "/path/to/your/project/.venv/bin/mcp-bigquery",
      "args": ["--transport", "stdio"],
      "env": {
        "PROJECT_ID": "your-project-id",
        "LOCATION": "US",
        "KEY_FILE": "/path/to/your/service-account-key.json",
        "SUPABASE_URL": "https://your-project.supabase.co",
        "SUPABASE_SERVICE_KEY": "your-service-role-key",
        "DEFAULT_USER_ID": "your-user-id"
      }
    }
  }
}

Para Windows:

{
  "mcpServers": {
    "mcp-bigquery": {
      "command": "C:\\path\\to\\your\\project\\.venv\\Scripts\\mcp-bigquery.exe",
      "args": ["--transport", "stdio"],
      "env": {
        "PROJECT_ID": "your-project-id",
        "LOCATION": "US",
        "KEY_FILE": "C:\\path\\to\\your\\service-account-key.json",
        "SUPABASE_URL": "https://your-project.supabase.co",
        "SUPABASE_SERVICE_KEY": "your-service-role-key",
        "DEFAULT_USER_ID": "your-user-id"
      }
    }
  }
}

3. Configuración de autenticación

Autenticación de BigQuery - Elige uno de dos métodos de autenticación:

Opción A: Archivo de clave de cuenta de servicio

  1. Crea una cuenta de servicio en Google Cloud Console
  2. Descarga el archivo de clave JSON
  3. Establece la variable de entorno KEY_FILE en la ruta de este archivo

Opción B: Credenciales predeterminadas

  1. Instala y configura Google Cloud SDK: gcloud auth application-default login
  2. Elimina KEY_FILE de las variables de entorno

Autenticación de Supabase (Opcional pero recomendada):

  1. Crea un proyecto de Supabase
  2. Obtén la URL de tu proyecto y la clave de rol de servicio desde el panel de Supabase
  3. Configura el esquema de base de datos requerido (consulta la sección Configuración de Supabase)

4. Reiniciar Claude Desktop

Después de guardar el archivo de configuración, reinicia Claude Desktop por completo para que los cambios surtan efecto.

5. Uso del servidor

Una vez configurado, puedes interactuar con tus datos de BigQuery a través de Claude Desktop con capacidades mejoradas:

Operaciones básicas:

  • "¿Qué conjuntos de datos tengo disponibles en BigQuery?"
  • "Muéstrame el esquema de la tabla [dataset].[table]"
  • "Ejecuta una consulta para obtener las primeras 10 filas de [dataset].[table]"

Funciones mejoradas (con Supabase):

  • "Analiza el rendimiento de mis consultas recientes"
  • "¿Qué sugerencias de consultas tienes para la tabla de ventas?"
  • "Muéstrame los cambios de esquema de [dataset].[table] durante el último mes"
  • "Explica para qué se utiliza la tabla customer_events"
  • "¿Cuáles son las estadísticas de caché?"

Aplicación Streamlit AI Analyst

El repositorio incluye un front-end de Streamlit (streamlit_app/app.py) que envuelve el servidor MCP BigQuery en una experiencia interactiva de "analista de datos con IA". Utiliza un modelo de OpenAI para traducir preguntas en lenguaje natural a SQL de BigQuery seguro y de solo lectura, ejecuta la consulta a través del servidor MCP y resume los resultados en tiempo real.

Requisitos previos

  • Una instancia en ejecución del servidor MCP BigQuery (transporte HTTP).
  • Dependencias de Python instaladas (uv pip install -e .).
  • Una clave de API de OpenAI disponible como variable de entorno (OPENAI_API_KEY) o introducida en la interfaz.

Ejecutar la aplicación Streamlit

# Ensure the MCP server is running locally (default assumes http://localhost:8005)
export OPENAI_API_KEY="sk-..."
streamlit run streamlit_app/app.py

La barra lateral te permite configurar la URL base de MCP, los identificadores de usuario/sesión, los controles de coste de consultas y el modelo de OpenAI. Seleccionar un conjunto de datos y tablas opcionales comparte información del esquema con el agente para mejorar la generación de SQL. Haz preguntas en la interfaz de chat y el asistente:

  1. Propondrá un plan de consulta de BigQuery utilizando los metadatos proporcionados y las mejores prácticas.
  2. Ejecutará el SQL a través del servidor MCP, respetando la caché y el máximo de bytes facturados.
  3. Devolverá un resumen en Markdown, una tabla de vista previa, un CSV descargable y el SQL ejecutado para mayor transparencia.

Endpoints de API

Recursos

  • GET /resources/list - Lista todos los conjuntos de datos y tablas disponibles
  • GET /bigquery/{project_id}/{dataset_id}/{table_id} - Obtiene metadatos de tablas

Herramientas

  • POST /tools/execute_bigquery_sql - Ejecuta consultas SQL de solo lectura con caché
  • POST /tools/get_datasets - Obtiene la lista de conjuntos de datos con metadatos
  • POST /tools/get_tables - Obtiene las tablas de un conjunto de datos con documentación
  • POST /tools/get_table_schema - Obtiene el esquema de tablas con contexto empresarial
  • POST /tools/get_query_suggestions - Obtiene recomendaciones de consultas impulsadas por IA
  • POST /tools/explain_table - Obtiene documentación completa de tablas
  • POST /tools/analyze_query_performance - Analiza patrones de rendimiento de consultas
  • POST /tools/get_schema_changes - Realiza seguimiento de la evolución de esquemas a lo largo del tiempo
  • POST /tools/manage_cache - Operaciones de gestión de caché
  • POST /tools/health_check - Verificación de estado del sistema

Eventos (SSE)

  • GET /events/system - Eventos de estado del sistema
  • GET /events/queries - Eventos de ejecución de consultas
  • GET /events/resources - Eventos de actualización de recursos

Salud

  • GET /health - Endpoint de verificación de estado

Herramientas y recursos de MCP

Recursos

  • resources://list - Lista todos los recursos de BigQuery
  • bigquery://{project}/{dataset}/{table} - Accede a metadatos específicos de tablas

Herramientas

Herramientas principales de BigQuery

  • execute_bigquery_sql - Ejecuta una consulta SQL de solo lectura con caché inteligente
    • Parámetros: sql, maximum_bytes_billed, use_cache, user_id, force_refresh
  • get_datasets - Obtiene la lista de conjuntos de datos con metadatos
  • get_tables - Obtiene las tablas de un conjunto de datos con documentación de columnas
  • get_table_schema - Obtiene detalles completos del esquema de tablas
    • Parámetros: dataset_id, table_id, include_samples, include_documentation

Herramientas de analítica mejorada (requieren Supabase)

  • get_query_suggestions - Obtiene recomendaciones de consultas impulsadas por IA
    • Parámetros: tables_mentioned, query_context, limit, user_id
  • explain_table - Obtiene documentación completa de tablas y contexto empresarial
    • Parámetros: project_id, dataset_id, table_id, include_usage_stats, user_id
  • analyze_query_performance - Analiza patrones históricos de rendimiento de consultas
    • Parámetros: sql, tables_accessed, time_range_hours, user_id, include_recommendations
  • get_schema_changes - Realiza seguimiento de la evolución y los cambios de esquema a lo largo del tiempo
    • Parámetros: project_id, dataset_id, table_id, limit, include_impact_analysis, user_id

Herramientas de gestión del sistema

  • manage_cache - Operaciones integrales de gestión de caché
    • Parámetros: action, target, project_id, dataset_id, table_id, user_id
  • health_check - Verificación de estado del sistema que incluye BigQuery, Supabase y estado de caché
    • Parámetros: user_id

Sistema de caché inteligente

El servidor incluye un sistema de caché sofisticado impulsado por Supabase:

Características

  • Caché de resultados de consultas: Caché automática de resultados de consultas con TTL configurable
  • Seguimiento de dependencias de tablas: Invalidación de caché basada en modificaciones de tablas
  • Estadísticas de caché: Tasas de acierto, métricas de rendimiento y analítica de uso
  • Aislamiento basado en usuario: Seguridad a nivel de fila para entornos multi-tenant
  • Limpieza automática: Eliminación de entradas de caché caducadas

Gestión de caché

# Cache a query result (automatic)
result = await execute_bigquery_sql(sql="SELECT * FROM dataset.table", use_cache=True)

# Force cache refresh
result = await execute_bigquery_sql(sql="SELECT * FROM dataset.table", force_refresh=True)

# Get cache statistics
stats = await manage_cache(action="stats")

# Clean up expired entries
cleanup = await manage_cache(action="cleanup")

Desarrollo

Configurar el entorno de desarrollo

# Install with development dependencies
uv pip install -e ".[dev]"

# Run tests
pytest

# Run with coverage
pytest --cov=src/mcp_bigquery --cov-report=html

# Format code
black src/ tests/
isort src/ tests/

# Type checking
mypy src/

Estructura del proyecto

mcp-bigquery-server/
├── src/mcp_bigquery/          # Main package
│   ├── config/                # Configuration management
│   ├── core/                  # Core utilities (BigQuery client, Supabase client, JSON encoder)
│   ├── events/                # Event management system
│   ├── handlers/              # Business logic handlers
│   │   ├── resources.py       # Resource handlers
│   │   └── tools.py          # Tool handlers (query execution, analytics)
│   ├── api/                   # FastAPI and FastMCP applications
│   ├── routes/                # FastAPI route definitions
│   └── main.py                # Entry point
├── tests/                     # Test suite
├── pyproject.toml            # Project configuration
└── README.md                 # This file

Autenticación

Autenticación de BigQuery

El servidor admite dos métodos de autenticación:

  1. Archivo de clave de cuenta de servicio: Especifica la ruta en la variable de entorno KEY_FILE
  2. Credenciales predeterminadas: Utiliza las credenciales predeterminadas de Google Cloud SDK si no se proporciona un archivo de clave

Autenticación de Supabase

  • Clave de rol de servicio: Acceso completo a todas las tablas (recomendado para despliegue de servidor)
  • Clave anónima: Acceso limitado con políticas de seguridad a nivel de fila (RLS)

Seguridad

  • Todas las consultas SQL están restringidas a operaciones de solo lectura
  • Las palabras clave prohibidas (INSERT, UPDATE, DELETE, CREATE, DROP, ALTER) están bloqueadas
  • La validación del ID de proyecto garantiza que las consultas solo se ejecuten contra el proyecto configurado
  • Límites de coste de consultas configurables mediante el parámetro maximum_bytes_billed
  • Soporte de seguridad a nivel de fila (RLS) para despliegues multi-tenant
  • Aislamiento de caché y control de acceso basados en usuario

Transmisión de eventos

El servidor proporciona eventos en tiempo real mediante Server-Sent Events (SSE):

  • Eventos del sistema: Salud del servidor, estado de conexión, conectividad con Supabase
  • Eventos de consulta: Inicio, progreso, finalización, errores, aciertos/fallos de caché
  • Eventos de recursos: Actualizaciones de conjuntos de datos y tablas, cambios de esquema
  • Eventos de analítica: Información de rendimiento, patrones de uso

Consideraciones de rendimiento

  • Caché de consultas: Reduce significativamente los costes de BigQuery y mejora los tiempos de respuesta
  • Agrupación de conexiones: Gestión eficiente del cliente de BigQuery
  • Operaciones asíncronas: E/S sin bloqueo para mejor concurrencia
  • Carga diferida: Las conexiones de Supabase se inicializan solo cuando es necesario
  • Optimización de caché: Generación inteligente de claves de caché y seguimiento de dependencias

Monitorización y observabilidad

El servidor proporciona capacidades integrales de monitorización:

  • Verificaciones de estado: Estado de conectividad de BigQuery y Supabase
  • Métricas de caché: Tasas de acierto, uso de almacenamiento, estadísticas de rendimiento
  • Analítica de consultas: Patrones de ejecución, análisis de costes, recomendaciones de optimización
  • Registro de eventos: Trazas de auditoría detalladas para todas las operaciones
  • Seguimiento de errores: Registro y notificación integral de errores

Contribuciones

  1. Haz un fork del repositorio
  2. Crea una rama de funcionalidad
  3. Realiza tus cambios
  4. Añade pruebas para la nueva funcionalidad
  5. Ejecuta el conjunto de pruebas
  6. Envía un pull request

Licencia

[Añade aquí la información de tu licencia]

Registro de cambios

v0.2.0

  • Se añadió la integración con Supabase para caché y analítica mejoradas
  • Se implementó caché inteligente de consultas con seguimiento de dependencias de tablas
  • Se añadieron sugerencias de consultas y explicaciones de tablas impulsadas por IA
  • Se mejoraron las capacidades de seguimiento de evolución de esquemas
  • Se mejoraron el análisis de rendimiento y las recomendaciones de optimización
  • Se añadió registro integral de eventos y trazas de auditoría
  • Se implementó soporte de seguridad a nivel de fila (RLS) para despliegues multi-tenant