bricks and context

---

✨ O que é isso?

Bricks and Context permite que assistentes de IA (Cursor, Claude Desktop, etc.) conversem diretamente com seus workspaces Databricks por meio do Model Context Protocol.

Pense nisso como uma ponte: sua IA faz perguntas, este servidor as traduz em chamadas de API do Databricks e retorna respostas estruturadas e amigáveis para IA.

Por que usar isso?

Ponto de Dor	Como resolvemos
A IA fica sobrecarregada com resultados de consulta enormes	Saídas limitadas — limites configuráveis de linhas/bytes/células
Conexões instáveis causam falhas aleatórias	Tentativas + circuit breakers — tolerância a falhas automática
Gerenciar múltiplos ambientes é tedioso	Multi-workspace — alterne entre dev/prod com um parâmetro
Respostas brutas da API confundem modelos de IA	Tabelas Markdown — saída estruturada e otimizada para LLM

---

🔧 Ferramentas Disponíveis

Descoberta de SQL e Schemas

Ferramenta	O que faz
execute_sql_query	Executa SQL com saída limitada e segura para IA
discover_schemas	Lista todos os schemas no workspace
discover_tables	Lista tabelas em um schema com metadados
describe_table	Obtém tipos de coluna, nulidade, estrutura
get_table_sample	Pré-visualiza linhas para exploração de dados
connection_health	Verifica a conectividade com Databricks

Gerenciamento de Jobs

Ferramenta	O que faz
list_jobs	Lista jobs com filtro opcional por nome
get_job_details	Configuração completa do job: agendamento, cluster, tarefas
get_job_runs	Histórico de execuções com estado e duração
trigger_job	Inicia um job com parâmetros opcionais
cancel_job_run	Para um job em execução
get_job_run_output	Recupera logs, erros, saída do notebook

Observabilidade

Ferramenta	O que faz
cache_stats	Taxas de acerto, uso de memória, detalhamento por categoria
performance_stats	Latências de operação, taxas de erro, saúde

---

🚀 Início Rápido

1. Clone e Instale

git clone https://github.com/laraib-sidd/bricks-and-context.git
cd bricks-and-context
uv sync  # or: pip install -e .

2. Configure os Workspaces

Copie o modelo e adicione suas credenciais:

cp auth.template.yaml auth.yaml

Edite auth.yaml:

default_workspace: dev

workspaces:
  - name: dev
    host: your-dev.cloud.databricks.com
    token: dapi...
    http_path: /sql/1.0/warehouses/...

  - name: prod
    host: your-prod.cloud.databricks.com
    token: dapi...
    http_path: /sql/1.0/warehouses/...

💡 auth.yaml está no gitignore. Seus segredos permanecem locais.

3. Execute

python run_mcp_server.py

---

🎯 Integração com Cursor

O Cursor usa transporte stdio e não herda o ambiente do seu shell. Você precisa de caminhos explícitos.

Passo 1: Garanta que as dependências estejam instaladas

cd /path/to/bricks-and-context
uv sync

Passo 2: Abra as configurações de MCP no Cursor

Cmd+Shift+P → "Abrir Configurações de MCP" → Abre ~/.cursor/mcp.json

Passo 3: Adicione esta configuração

Usando uv run (recomendado):

{
  "mcpServers": {
    "databricks": {
      "command": "uv",
      "args": [
        "--directory", "/path/to/bricks-and-context",
        "run", "python", "run_mcp_server.py"
      ],
      "env": {
        "MCP_AUTH_PATH": "/path/to/bricks-and-context/auth.yaml",
        "MCP_CONFIG_PATH": "/path/to/bricks-and-context/config.json"
      }
    }
  }
}

Ou usando venv diretamente:

{
  "mcpServers": {
    "databricks": {
      "command": "/path/to/bricks-and-context/.venv/bin/python",
      "args": ["/path/to/bricks-and-context/run_mcp_server.py"],
      "env": {
        "MCP_AUTH_PATH": "/path/to/bricks-and-context/auth.yaml",
        "MCP_CONFIG_PATH": "/path/to/bricks-and-context/config.json"
      }
    }
  }
}

Passo 4: Reinicie o Cursor

Recarregue a janela para ativar o servidor MCP.

Teste

Pergunte à sua IA:

• "Liste meus jobs do Databricks"
• "Execute SELECT 1 no Databricks"
• "Descreva a tabela catalog.schema.my_table"

---

🌐 Multi-Workspace

Defina vários workspaces em auth.yaml e selecione por chamada:

execute_sql_query(sql="SELECT 1", workspace="prod")
list_jobs(limit=10, workspace="dev")

Quando workspace for omitido, o servidor usa default_workspace.

---

⚙️ Configuração

config.json — Configurações ajustáveis (commitadas)

Configuração	Padrão	Descrição
max_connections	10	Tamanho do pool de conexões
max_result_rows	200	Máximo de linhas retornadas por consulta
max_result_bytes	262144	Tamanho máximo da resposta (256KB)
max_cell_chars	200	Trunca valores longos de células
allow_write_queries	false	Habilita INSERT/UPDATE/DELETE
enable_sql_retries	true	Repete falhas transitórias de SQL
enable_query_cache	false	Armazena em cache consultas repetidas
query_cache_ttl_seconds	300	TTL do cache
databricks_api_timeout_seconds	30	Timeout da API de Jobs

Qualquer configuração pode ser substituída por variável de ambiente (em maiúsculas, ex.: MAX_RESULT_ROWS=500).

---

🏗️ Arquitetura

┌─────────────────────────────────────────────────────────────────┐
│                   MCP Client (Cursor / Claude)                  │
└─────────────────────────────────────────────────────────────────┘
                                │ stdio
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                     FastMCP Server                              │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────────┐  │
│  │ SQL Tools   │  │ Job Tools   │  │ Observability           │  │
│  └──────┬──────┘  └──────┬──────┘  └───────────┬─────────────┘  │
└─────────┼────────────────┼─────────────────────┼────────────────┘
          │                │                     │
          ▼                ▼                     ▼
┌──────────────────┐ ┌──────────────────┐ ┌──────────────────────┐
│ Connection Pool  │ │  Job Manager     │ │ Cache / Perf Monitor │
│  (SQL Connector) │ │  (REST API 2.1)  │ │                      │
└────────┬─────────┘ └────────┬─────────┘ └──────────────────────┘
         │                    │
         └────────┬───────────┘
                  ▼
┌─────────────────────────────────────────────────────────────────┐
│                   Databricks Workspace(s)                       │
│              SQL Warehouse        Jobs Service                  │
└─────────────────────────────────────────────────────────────────┘

---

🛡️ Recursos de Confiabilidade

Recurso	Descrição
Saídas limitadas	Limites de linhas, bytes e caracteres por célula evitam estouro de memória
Pool de conexões	Thread-safe com validação de saúde por conexão
Tentativas com backoff	Backoff exponencial + jitter para falhas transitórias
Circuit breakers	Isolamento automático de falhas, evita falhas em cascata
Cache de consultas	Cache opcional baseado em TTL para consultas repetidas

---

🧑‍💻 Desenvolvimento

uv sync --dev        # Install dev dependencies
uv run pytest        # Run tests
uv run black .       # Format code
uv run mypy src/     # Type check

---

📄 Licença

MIT — veja LICENSE