bricks and context

---

✨ ¿Qué es esto?

Bricks and Context permite a los asistentes de IA (Cursor, Claude Desktop, etc.) hablar directamente con tus espacios de trabajo de Databricks a través del Model Context Protocol.

Piénsalo como un puente: tu IA hace preguntas, este servidor las traduce en llamadas a la API de Databricks y devuelve respuestas estructuradas y amigables para la IA.

¿Por qué usar esto?

Problema	Cómo lo resolvemos
La IA se abruma con resultados de consultas enormes	Salidas limitadas — límites configurables de filas/bytes/celdas
Conexiones inestables causan fallos aleatorios	Reintentos + interruptores de circuito — tolerancia a fallos automática
Gestionar múltiples entornos es tedioso	Multi-Workspace — cambia entre dev/prod con un parámetro
Las respuestas crudas de la API confunden a los modelos de IA	Tablas Markdown — salida estructurada y optimizada para LLM

---

🔧 Herramientas disponibles

Descubrimiento de SQL y esquemas

Herramienta	Qué hace
execute_sql_query	Ejecuta SQL con salida limitada y segura para IA
discover_schemas	Lista todos los esquemas en el espacio de trabajo
discover_tables	Lista tablas en un esquema con metadatos
describe_table	Obtén tipos de columna, nulabilidad, estructura
get_table_sample	Previsualiza filas para exploración de datos
connection_health	Verifica la conectividad con Databricks

Gestión de trabajos

Herramienta	Qué hace
list_jobs	Lista trabajos con filtro opcional por nombre
get_job_details	Configuración completa del trabajo: programación, clúster, tareas
get_job_runs	Historial de ejecuciones con estado y duración
trigger_job	Inicia un trabajo con parámetros opcionales
cancel_job_run	Detiene un trabajo en ejecución
get_job_run_output	Recupera registros, errores, salida de notebooks

Observabilidad

Herramienta	Qué hace
cache_stats	Tasas de acierto, uso de memoria, desglose por categoría
performance_stats	Latencias de operación, tasas de error, salud

---

🚀 Inicio rápido

1. Clonar e instalar

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

2. Configurar espacios de trabajo

Copia la plantilla y añade tus credenciales:

cp auth.template.yaml auth.yaml

Edita 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á en gitignore. Tus secretos permanecen locales.

3. Ejecutar

python run_mcp_server.py

---

🎯 Integración con Cursor

Cursor usa transporte stdio y no hereda el entorno de tu shell. Necesitas rutas explícitas.

Paso 1: Asegúrate de que las dependencias estén instaladas

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

Paso 2: Abre la configuración de MCP en Cursor

Cmd+Shift+P → "Abrir configuración de MCP" → Abre ~/.cursor/mcp.json

Paso 3: Añade esta configuración

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

O usando venv directamente:

{
  "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"
      }
    }
  }
}

Paso 4: Reinicia Cursor

Recarga la ventana para activar el servidor MCP.

Pruébalo

Pregunta a tu IA:

• "Lista mis trabajos de Databricks"
• "Ejecuta SELECT 1 en Databricks"
• "Describe la tabla catalog.schema.my_table"

---

🌐 Multi-espacio de trabajo

Define múltiples espacios de trabajo en auth.yaml, luego selecciona por llamada:

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

Cuando se omite workspace, el servidor usa default_workspace.

---

⚙️ Configuración

config.json — Ajustes configurables (confirmados)

Ajuste	Predeterminado	Descripción
max_connections	10	Tamaño del grupo de conexiones
max_result_rows	200	Máximo de filas devueltas por consulta
max_result_bytes	262144	Tamaño máximo de respuesta (256KB)
max_cell_chars	200	Truncar valores de celda largos
allow_write_queries	false	Habilitar INSERT/UPDATE/DELETE
enable_sql_retries	true	Reintentar fallos transitorios de SQL
enable_query_cache	false	Almacenar en caché consultas repetidas
query_cache_ttl_seconds	300	TTL de caché
databricks_api_timeout_seconds	30	Tiempo de espera de la API de Jobs

Cualquier ajuste se puede sobrescribir mediante variable de entorno (en mayúsculas, p. ej., MAX_RESULT_ROWS=500).

---

🏗️ Arquitectura

┌─────────────────────────────────────────────────────────────────┐
│                   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                  │
└─────────────────────────────────────────────────────────────────┘

---

🛡️ Características de fiabilidad

Característica	Descripción
Salidas limitadas	Los límites de filas, bytes y caracteres por celda evitan OOM
Agrupación de conexiones	Seguro para subprocesos con validación de salud por conexión
Reintento con retroceso	Retroceso exponencial + jitter para fallos transitorios
Interruptores de circuito	Aislamiento automático de fallos, previene fallos en cascada
Caché de consultas	Caché opcional basada en TTL para consultas repetidas

---

🧑‍💻 Desarrollo

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

---

📄 Licencia

MIT — consulta LICENSE