MCP BigQuery Server

Acesse conjuntos de dados do BigQuery com segurança, utilizando cache inteligente, rastreamento de esquemas e análise de consultas por meio da integração com Supabase.

GitHub

Documentação

MCP BigQuery Server

Um servidor FastMCP para acesso seguro a conjuntos de dados do BigQuery, com cache inteligente, rastreamento de evolução de esquemas e análises de consultas via integração com Supabase.

Recursos

  • Múltiplos Métodos de Transporte: HTTP, Stdio e SSE (Server-Sent Events)
  • Integração com BigQuery: Acesso seguro a conjuntos de dados e tabelas do BigQuery
  • Cache Inteligente: Cache de resultados de consultas com gerenciamento de TTL e rastreamento de dependências
  • Base de Conhecimento Supabase: Armazenamento aprimorado de metadados e contexto de negócio
  • Análise de Consultas: Análise de desempenho e recomendações de otimização
  • Rastreamento de Evolução de Esquemas: Monitore alterações de esquema de tabelas ao longo do tempo
  • Sugestões com IA: Recomendações de consultas baseadas em padrões de uso
  • Eventos em Tempo Real: Server-Sent Events para monitoramento de consultas e status do sistema
  • Consultas Somente Leitura: Abordagem de segurança em primeiro lugar com execução de SQL somente leitura
  • Segurança em Nível de Linha: Controle de acesso baseado em usuário e isolamento de cache
  • API Abrangente: Endpoints RESTful e suporte ao protocolo MCP

Instalação

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]"

Configuração

  1. Copie o arquivo de ambiente de exemplo:
cp .env.example .env
  1. Edite o .env com os detalhes do seu BigQuery e 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

Configuração do Supabase

Para recursos aprimorados de cache e análise, você precisará de um projeto Supabase com as seguintes tabelas e políticas.

  • query_cache - Armazena resultados de consultas em cache
  • table_dependencies - Rastreia dependências de tabelas para invalidação de cache
  • query_history - Padrões históricos de execução de consultas
  • query_templates - Modelos de consulta reutilizáveis
  • column_documentation - Contexto de negócio para colunas de tabelas
  • event_log - Rastreamento de eventos do sistema

Execute estas consultas SQL no editor SQL do seu Supabase para configurar o 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 tabelas permitem:

  • Cache de resultados de consultas e rastreamento de dependências
  • Evolução de esquemas e documentação
  • Análise de consultas e reconhecimento de padrões
  • Registro de eventos em tempo real
  • Preferências e configurações do usuário

Segurança em Nível de Linha (RLS) está habilitada para todas as tabelas. Você pode escolher entre várias opções de políticas de RLS:

  • Opção 1: Permitir todas as operações (para desenvolvimento/testes)
  • Opção 2: Políticas baseadas em usuário (recomendado para produção com autenticação)
  • Opção 3: Políticas de papel de serviço (para serviços de backend)

Personalize as políticas de RLS conforme necessário para o seu ambiente.

O servidor funcionará sem o Supabase, mas com funcionalidade limitada.

Uso

Linha de Comando

# 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 Python

from mcp_bigquery.main import main
import sys

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

Uso com Claude Desktop

Para usar este servidor MCP BigQuery com o Claude Desktop, você precisa configurá-lo no arquivo de configuração do Claude Desktop.

1. Instalar e Configurar o Servidor

Primeiro, certifique-se de que o servidor está instalado e 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 o Claude Desktop

Adicione o servidor ao arquivo de configuração do Claude Desktop:

Localizações do arquivo de configuração:

  • 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. Configuração de Autenticação

Autenticação do BigQuery - Escolha um dos dois métodos de autenticação:

Opção A: Arquivo de Chave de Conta de Serviço

  1. Crie uma conta de serviço no Google Cloud Console
  2. Baixe o arquivo de chave JSON
  3. Defina a variável de ambiente KEY_FILE com o caminho deste arquivo

Opção B: Credenciais Padrão

  1. Instale e configure o Google Cloud SDK: gcloud auth application-default login
  2. Remova o KEY_FILE das variáveis de ambiente

Autenticação do Supabase (Opcional, mas recomendado):

  1. Crie um projeto Supabase
  2. Obtenha a URL do projeto e a chave de papel de serviço no painel do Supabase
  3. Configure o esquema de banco de dados necessário (veja a seção Configuração do Supabase)

4. Reiniciar o Claude Desktop

Após salvar o arquivo de configuração, reinicie o Claude Desktop completamente para que as alterações tenham efeito.

5. Usando o Servidor

Depois de configurado, você pode interagir com seus dados do BigQuery através do Claude Desktop com recursos aprimorados:

Operações Básicas:

  • "Quais conjuntos de dados eu tenho disponíveis no BigQuery?"
  • "Mostre-me o esquema da tabela [dataset].[table]"
  • "Execute uma consulta para obter as primeiras 10 linhas de [dataset].[table]"

Recursos Aprimorados (com Supabase):

  • "Analise o desempenho das minhas consultas recentes"
  • "Quais sugestões de consulta você tem para a tabela de vendas?"
  • "Mostre-me as alterações de esquema de [dataset].[table] no último mês"
  • "Explique para que serve a tabela customer_events"
  • "Quais são as estatísticas de cache?"

Aplicativo Streamlit AI Analyst

O repositório inclui um front-end Streamlit (streamlit_app/app.py) que encapsula o servidor MCP BigQuery em uma experiência interativa de "analista de dados com IA". Ele usa um modelo OpenAI para traduzir perguntas em linguagem natural em SQL seguro do BigQuery somente leitura, executa a consulta através do servidor MCP e resume os resultados em tempo real.

Pré-requisitos

  • Uma instância em execução do servidor MCP BigQuery (transporte HTTP).
  • Dependências Python instaladas (uv pip install -e .).
  • Uma chave de API OpenAI disponível como variável de ambiente (OPENAI_API_KEY) ou inserida na interface.

Executando o aplicativo Streamlit

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

A barra lateral permite configurar a URL base do MCP, identificadores de usuário/sessão, controles de custo de consulta e o modelo OpenAI. Selecionar um conjunto de dados e tabelas opcionais compartilha informações de esquema com o agente para melhorar a geração de SQL. Faça perguntas na interface de chat e o assistente irá:

  1. Propor um plano de consulta BigQuery usando os metadados fornecidos e as melhores práticas.
  2. Executar o SQL através do servidor MCP, respeitando o cache e o limite máximo de bytes cobrados.
  3. Retornar um resumo em Markdown, tabela de pré-visualização, CSV para download e o SQL executado para transparência.

Endpoints da API

Recursos

  • GET /resources/list - Listar todos os conjuntos de dados e tabelas disponíveis
  • GET /bigquery/{project_id}/{dataset_id}/{table_id} - Obter metadados de tabela

Ferramentas

  • POST /tools/execute_bigquery_sql - Executar consultas SQL somente leitura com cache
  • POST /tools/get_datasets - Obter lista de conjuntos de dados com metadados
  • POST /tools/get_tables - Obter tabelas em um conjunto de dados com documentação
  • POST /tools/get_table_schema - Obter esquema de tabela com contexto de negócio
  • POST /tools/get_query_suggestions - Obter recomendações de consulta com IA
  • POST /tools/explain_table - Obter documentação abrangente de tabela
  • POST /tools/analyze_query_performance - Analisar padrões de desempenho de consultas
  • POST /tools/get_schema_changes - Rastrear evolução de esquemas ao longo do tempo
  • POST /tools/manage_cache - Operações de gerenciamento de cache
  • POST /tools/health_check - Verificação de saúde do sistema

Eventos (SSE)

  • GET /events/system - Eventos de status do sistema
  • GET /events/queries - Eventos de execução de consultas
  • GET /events/resources - Eventos de atualização de recursos

Saúde

  • GET /health - Endpoint de verificação de saúde

Ferramentas e Recursos MCP

Recursos

  • resources://list - Listar todos os recursos do BigQuery
  • bigquery://{project}/{dataset}/{table} - Acessar metadados de tabela específica

Ferramentas

Ferramentas Principais do BigQuery

  • execute_bigquery_sql - Executar uma consulta SQL somente leitura com cache inteligente
    • Parâmetros: sql, maximum_bytes_billed, use_cache, user_id, force_refresh
  • get_datasets - Obter lista de conjuntos de dados com metadados
  • get_tables - Obter tabelas em um conjunto de dados com documentação de colunas
  • get_table_schema - Obter detalhes abrangentes do esquema de tabela
    • Parâmetros: dataset_id, table_id, include_samples, include_documentation

Ferramentas Aprimoradas de Análise (requer Supabase)

  • get_query_suggestions - Obter recomendações de consulta com IA
    • Parâmetros: tables_mentioned, query_context, limit, user_id
  • explain_table - Obter documentação abrangente de tabela e contexto de negócio
    • Parâmetros: project_id, dataset_id, table_id, include_usage_stats, user_id
  • analyze_query_performance - Analisar padrões históricos de desempenho de consultas
    • Parâmetros: sql, tables_accessed, time_range_hours, user_id, include_recommendations
  • get_schema_changes - Rastrear evolução e alterações de esquema ao longo do tempo
    • Parâmetros: project_id, dataset_id, table_id, limit, include_impact_analysis, user_id

Ferramentas de Gerenciamento do Sistema

  • manage_cache - Operações abrangentes de gerenciamento de cache
    • Parâmetros: action, target, project_id, dataset_id, table_id, user_id
  • health_check - Verificação de saúde do sistema incluindo status do BigQuery, Supabase e cache
    • Parâmetros: user_id

Sistema de Cache Inteligente

O servidor inclui um sistema de cache sofisticado alimentado pelo Supabase:

Recursos

  • Cache de Resultados de Consultas: Cache automático de resultados de consultas com TTL configurável
  • Rastreamento de Dependências de Tabelas: Invalidação de cache baseada em modificações de tabelas
  • Estatísticas de Cache: Taxas de acerto, métricas de desempenho e análises de uso
  • Isolamento Baseado em Usuário: Segurança em Nível de Linha para ambientes multi-tenant
  • Limpeza Automática: Remoção de entradas de cache expiradas

Gerenciamento de Cache

# 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")

Desenvolvimento

Configurar Ambiente de Desenvolvimento

# 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/

Estrutura do Projeto

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

Autenticação

Autenticação do BigQuery

O servidor suporta dois métodos de autenticação:

  1. Arquivo de Chave de Conta de Serviço: Especifique o caminho na variável de ambiente KEY_FILE
  2. Credenciais Padrão: Usa as credenciais padrão do Google Cloud SDK se nenhum arquivo de chave for fornecido

Autenticação do Supabase

  • Chave de Papel de Serviço: Acesso total a todas as tabelas (recomendado para implantação de servidor)
  • Chave Anônima: Acesso limitado com políticas de Segurança em Nível de Linha (RLS)

Segurança

  • Todas as consultas SQL são restritas a operações somente leitura
  • Palavras-chave proibidas (INSERT, UPDATE, DELETE, CREATE, DROP, ALTER) são bloqueadas
  • A validação do ID do projeto garante que as consultas sejam executadas apenas contra o projeto configurado
  • Limites de custo de consulta configuráveis via parâmetro maximum_bytes_billed
  • Suporte a Segurança em Nível de Linha (RLS) para implantações multi-tenant
  • Isolamento de cache e controle de acesso baseados em usuário

Streaming de Eventos

O servidor fornece eventos em tempo real via Server-Sent Events (SSE):

  • Eventos do Sistema: Saúde do servidor, status de conexão, conectividade do Supabase
  • Eventos de Consulta: Início de consulta, progresso, conclusão, erros, acertos/erros de cache
  • Eventos de Recursos: Atualizações de conjuntos de dados e tabelas, alterações de esquema
  • Eventos de Análise: Insights de desempenho, padrões de uso

Considerações de Desempenho

  • Cache de Consultas: Reduz significativamente os custos do BigQuery e melhora os tempos de resposta
  • Pooling de Conexões: Gerenciamento eficiente do cliente BigQuery
  • Operações Assíncronas: I/O sem bloqueio para melhor concorrência
  • Carregamento Preguiçoso: Conexões Supabase inicializadas apenas quando necessário
  • Otimização de Cache: Geração inteligente de chaves de cache e rastreamento de dependências

Monitoramento e Observabilidade

O servidor fornece recursos abrangentes de monitoramento:

  • Verificações de Saúde: Status de conectividade do BigQuery e Supabase
  • Métricas de Cache: Taxas de acerto, uso de armazenamento, estatísticas de desempenho
  • Análise de Consultas: Padrões de execução, análise de custos, recomendações de otimização
  • Registro de Eventos: Trilhas de auditoria detalhadas para todas as operações
  • Rastreamento de Erros: Registro e relatórios abrangentes de erros

Contribuindo

  1. Faça um fork do repositório
  2. Crie um branch de recurso
  3. Faça suas alterações
  4. Adicione testes para a nova funcionalidade
  5. Execute a suíte de testes
  6. Envie um pull request

Licença

[Adicione suas informações de licença aqui]

Changelog

v0.2.0

  • Adicionada integração com Supabase para cache e análise aprimorados
  • Implementado cache inteligente de consultas com rastreamento de dependências de tabelas
  • Adicionadas sugestões de consulta e explicações de tabelas com IA
  • Aprimorados os recursos de rastreamento de evolução de esquemas
  • Melhoradas as recomendações de análise de desempenho e otimização
  • Adicionados registros abrangentes de eventos e trilhas de auditoria
  • Implementado suporte a Segurança em Nível de Linha (RLS) para implantações multi-tenant