amitzore71/bigquery-mcp-server

Purpose and entry points

BigQuery SaaS is a multi-tenant natural-language analytics platform over Google BigQuery. It exposes a FastAPI REST API and HTMX chat UI, plus a separate stdio MCP server for AI-tool clients. Main entry points are src/bqsaas/api/app.py (uvicorn API/UI), main.py and src/bqsaas/__main__.py (MCP process); client/app.py is a thin app export.

Resource taxonomy and tenancy

The typed Kind system defines platform resources—tenants, users, workspaces, connections, API keys, sessions, subscriptions, and usage—and registry-backed schema metadata. Tenant ID is the primary isolation boundary across persisted resources.

• src/bqsaas/kinds/base.py

• src/bqsaas/kinds/registry.py

• src/bqsaas/models/tenant.py

Storage and service layer

The current persistence implementation is an in-memory, tenant-isolated store behind a storage abstraction. Services coordinate bootstrap/demo provisioning, tenant lifecycle, connection handling, and chat behavior rather than placing this logic directly in route handlers.

• src/bqsaas/storage/base.py

• src/bqsaas/storage/memory.py

• src/bqsaas/services/bootstrap.py

• src/bqsaas/services/chat_service.py

API boundary and web delivery

FastAPI composes versioned HTTP routes for authentication, tenant/workspace/session operations, query execution, kind discovery, and health checks. The same server serves the chat web experience; templates and static assets are a presentation layer over API/chat functionality.

• src/bqsaas/api/app.py

• src/bqsaas/api/routes/chat.py

• src/bqsaas/api/routes/query.py

• src/bqsaas/api/web.py

Authentication, authorization, and billing gates

Requests authenticate through bearer or API-key headers. Key hashing, scope enforcement, and request dependencies establish an auth context before protected operations. Plan definitions and the usage meter enforce daily query and resource limits, making quota checks a cross-cutting gate around query and provisioning flows.

• src/bqsaas/auth/security.py

• src/bqsaas/auth/dependencies.py

• src/bqsaas/billing/plans.py

• src/bqsaas/billing/meter.py

AI and BigQuery execution pipeline

A chat turn is handled by the chat service and Gemini integration, which uses prompts and tool-calling to select data actions. BigQuery operations are encapsulated as MCP-compatible tools and a client, keeping external SQL execution distinct from API orchestration. Connections supply per-tenant BigQuery context; validation and execution limits protect query paths.

• src/bqsaas/ai/gemini.py

• src/bqsaas/ai/prompts.py

• src/bqsaas/mcp/tools.py

• src/bqsaas/mcp/bigquery_client.py

MCP integration and external runtime

The MCP server exposes the BigQuery tool set over stdio independently of the FastAPI runtime, allowing other MCP-capable agents to invoke table discovery, description, and queries. External dependencies are Gemini API and Google BigQuery, using environment-provided API/project/dataset settings and optionally a service-account file.

• src/bqsaas/mcp/server.py

• src/bqsaas/config.py

• .env.example