BigQuery RAG MCP Server

Ein privater Model Context Protocol (MCP)-Dienst, der eine natürlichsprachliche Frage in ein Embedding umwandelt, eine semantische Suche über in BigQuery gespeicherten Dokumentabschnitten durchführt und strukturierte Passagen mit Quellen- und Seitenmetadaten zurückgibt.

Dieses Repository besitzt die Retrieval-Schicht eines größeren dokumentengestützten Chatbots. Das begleitende Anwendungsrepository besitzt die Google ADK-Orchestrierung, die Gemini-Antwortgenerierung, die Firebase-Authentifizierung, die /chat-API und die React-Oberfläche.

Begleitende Anwendung: shrprabh/atomic-habits-adk-rag

Live-Bereitstellung

Die Dienst-URL ist absichtlich nicht öffentlich im Browser zugänglich. Ein Aufrufer muss roles/run.invoker auf dem Dienst haben und ein von Google signiertes Identitätstoken senden, dessen Zielgruppe die MCP-Basis-URL ist.

End-to-End-Architektur

React application on Firebase Hosting
        │ Firebase ID token
        ▼
ADK Agent API on Cloud Run
        │ Google service identity token
        ▼
Private MCP service on Cloud Run  ◀── this repository
        │ parameterized BigQuery SQL
        ▼
AI.GENERATE_EMBEDDING
        │ 1,536-dimensional query vector
        ▼
BigQuery VECTOR_SEARCH (COSINE)
        │
        ▼
Top document passages + page metadata

Was dieser Dienst tut

• Stellt ein schreibgeschütztes MCP-Tool namens semantic_search bereit.

• Validiert query und top_k mit Pydantic-generierten MCP-Schemas.

• Erstellt ein Query-Embedding mit AI.GENERATE_EMBEDDING unter Verwendung von RETRIEVAL_QUERY.

• Führt eine Kosinus-Distanz VECTOR_SEARCH über gespeicherte Dokument-Embeddings durch.

• Verwendet einen parametrisierten Abfragewert anstatt Benutzereingaben in SQL einzufügen.

• Gibt strukturierte Quellen-, Seiten-, Kapitel-, Abschnitts-, Distanz- und Ähnlichkeitsfelder zurück.

• Läuft als zustandsloser Streamable HTTP MCP-Server.

• Hält den Retrieval-Dienst mit Cloud Run IAM privat.

• Ruft Gemini nicht auf, um eine Antwort zu verfassen; die Generierung gehört zum begleitenden ADK-Dienst.

Von diesem Projekt verwendete BigQuery-Ressourcen

Die aktuelle Tabelle ist klein, daher verwendet diese Implementierung bewusst eine Brute-Force-Vektorsuche. Ein Vektorindex wird nützlich, sobald der Korpus groß genug ist, um eine approximative Nächste-Nachbarn-Suche und Indexwartung zu rechtfertigen.

MCP-Tool-Vertrag

semantic_search

Eingabe:

{
  "query": "What is the two-minute rule?",
  "top_k": 5
}

Validierung:

Vereinfachte Ausgabe:

{
  "query": "What is the two-minute rule?",
  "result_count": 5,
  "results": [
    {
      "chunk_id": 480,
      "document_id": "atomic_habits",
      "content": "Retrieved passage text...",
      "title": "Atomic Habits",
      "author": "James Clear",
      "source": "atomic-habits.pdf",
      "page_start": 96,
      "page_end": 96,
      "chapter": "...",
      "section": "...",
      "distance": 0.18,
      "similarity": 0.82
    }
  ]
}

Repository-Struktur

bigquery-rag-mcp/
├── server.py                 # MCP tool, BigQuery query, health route
├── test_mcp.py               # In-process MCP regression test
├── test_deployed_mcp.py      # Authenticated test against Cloud Run
├── rag_client.py             # Local in-process RAG reference client
├── requirements.txt
├── Dockerfile
├── .env.example
└── .gitignore

rag_client.py importiert mcp aus server.py, sodass es das Tool im selben Python-Prozess ausführt. Es ist als lokaler Referenz- oder Regressionstest-Client nützlich, aber nicht Teil des bereitgestellten Produktionsanforderungspfads. Die begleitende ADK-Anwendung ruft diesen Dienst remote über /mcp auf.

Voraussetzungen

• Python 3.12+

• Google Cloud CLI

• Ein Google Cloud-Projekt mit aktivierter Abrechnung

• BigQuery-, BigQuery Connection-, Vertex AI-, Cloud Run-, Cloud Build- und Artifact Registry-APIs

• Vorhandenes BigQuery-Dataset, Embedding-Modell und Embedding-Tabelle, die dem konfigurierten Schema entsprechen

• Berechtigung zum Erstellen von Dienstkonten und Verwalten von Cloud Run- und BigQuery-IAM

1. Klonen und installieren

git clone https://github.com/shrprabh/bigquery-rag-mcp.git
cd bigquery-rag-mcp

python3 -m venv .venv
source .venv/bin/activate

python -m pip install --upgrade pip
pip install -r requirements.txt

Für lokale Entwicklung außerhalb von Cloud Shell:

gcloud auth login
gcloud auth application-default login
gcloud config set project bigquery-semantic-search

Committen Sie niemals Anwendungsstandard-Anmeldedaten oder Dienstkontoschlüsseldateien.

2. Umgebung konfigurieren

cp .env.example .env

Erwartete Werte:

GOOGLE_CLOUD_PROJECT=bigquery-semantic-search
BQ_DATASET=atomic_habits_rag
BQ_LOCATION=us-central1
EMBEDDING_DIM=1536

server.py liest diese Werte aus der Prozessumgebung. Die eingecheckte .env.example dient nur als Dokumentation; verwenden Sie explizite Exports lokal oder Cloud Run-Umgebungsvariablen bei der Bereitstellung.

3. BigQuery-Assets überprüfen

Führen Sie im BigQuery-Editor aus:

SELECT
  ARRAY_LENGTH(embedding) AS dimensions,
  COUNT(*) AS row_count
FROM `bigquery-semantic-search.atomic_habits_rag.article_embeddings`
GROUP BY dimensions;

Erwartet für das aktuelle Dataset:

dimensions  row_count
1536        1222

Bestätigen Sie, dass das Modell existiert:

SELECT
  model_name,
  model_type
FROM `bigquery-semantic-search.atomic_habits_rag.INFORMATION_SCHEMA.MODELS`
WHERE model_name = 'embedding_model';

4. Laufzeit-IAM konfigurieren

Variablen setzen:

export PROJECT_ID="bigquery-semantic-search"
export REGION="us-central1"
export CONNECTION_ID="vertex_ai_connection"
export MCP_SERVICE="bigquery-rag-mcp"
export MCP_SA_NAME="bigquery-rag-mcp-sa"
export MCP_SA="${MCP_SA_NAME}@${PROJECT_ID}.iam.gserviceaccount.com"

gcloud config set project "$PROJECT_ID"

APIs aktivieren:

gcloud services enable \
  bigquery.googleapis.com \
  bigqueryconnection.googleapis.com \
  aiplatform.googleapis.com \
  run.googleapis.com \
  cloudbuild.googleapis.com \
  artifactregistry.googleapis.com \
  --project="$PROJECT_ID"

Erstellen Sie das Laufzeit-Dienstkonto, falls es noch nicht existiert:

gcloud iam service-accounts describe "$MCP_SA" \
  --project="$PROJECT_ID" >/dev/null 2>&1 || \
gcloud iam service-accounts create "$MCP_SA_NAME" \
  --project="$PROJECT_ID" \
  --display-name="BigQuery RAG MCP Server"

Gewähren Sie dem Dienstkonto die Berechtigung, Abfragen auszuführen und das Dataset/Modell zu lesen:

gcloud projects add-iam-policy-binding "$PROJECT_ID" \
  --member="serviceAccount:${MCP_SA}" \
  --role="roles/bigquery.jobUser"

gcloud projects add-iam-policy-binding "$PROJECT_ID" \
  --member="serviceAccount:${MCP_SA}" \
  --role="roles/bigquery.dataViewer"

Erforderliche Verbindungsberechtigung

Da AI.GENERATE_EMBEDDING die BigQuery Cloud-Ressourcenverbindung verwendet, muss die MCP-Laufzeitidentität auch die Berechtigung zur Nutzung von vertex_ai_connection haben.

In der Google Cloud-Konsole:

1. Öffnen Sie BigQuery → Ihr Projekt → Verbindungen.

2. Wählen Sie vertex_ai_connection in us-central1.

3. Wählen Sie Freigeben.

4. Fügen Sie bigquery-rag-mcp-sa@bigquery-semantic-search.iam.gserviceaccount.com hinzu.

5. Gewähren Sie BigQuery Connection User (roles/bigquery.connectionUser).

Verwenden Sie nicht bq add-iam-policy-binding --connection_type=...; dieses Flag teilt keine Verbindung und wird von aktuellen bq-Versionen abgelehnt. Verwenden Sie die Cloud-Konsole oder die BigQuery Connections-API für die Freigabe auf Verbindungsebene.

Die Verbindung selbst hat ein von Google verwaltetes Dienstkonto. Dieses Verbindungsdienstkonto muss die entsprechende Vertex AI/Agent Platform-Benutzerrolle im Projekt haben, damit das Remote-Embedding-Modell seinen Endpunkt aufrufen kann.

Ohne diese Verbindungsberechtigungen enthält das MCP-Protokoll einen Fehler ähnlich wie:

403 Access Denied: User does not have bigquery.connections.use permission

5. Lokal testen

Kompilieren Sie die Dateien:

python -m py_compile server.py test_mcp.py rag_client.py

Führen Sie den direkten MCP-Regressionstest aus:

python test_mcp.py

Starten Sie den HTTP-Server:

python server.py

Endpunkte:

http://localhost:8000/health
http://localhost:8000/mcp

Von einem anderen Terminal:

curl http://localhost:8000/health

Erwartet:

{"status":"healthy"}

Optional den lokalen Grounded-Generation-Referenzclient ausführen:

python rag_client.py

6. Privaten MCP-Dienst bereitstellen

gcloud run deploy "$MCP_SERVICE" \
  --source=. \
  --project="$PROJECT_ID" \
  --region="$REGION" \
  --service-account="$MCP_SA" \
  --no-allow-unauthenticated \
  --memory="1Gi" \
  --timeout="300" \
  --set-env-vars="GOOGLE_CLOUD_PROJECT=$PROJECT_ID,BQ_DATASET=atomic_habits_rag,BQ_LOCATION=$REGION,EMBEDDING_DIM=1536"

Cloud Run stellt PORT bereit; server.py bindet an 0.0.0.0 und verwendet diesen Port.

Die kanonische Dienst-URL abrufen:

export MCP_URL="$(
  gcloud run services describe "$MCP_SERVICE" \
    --project="$PROJECT_ID" \
    --region="$REGION" \
    --format='value(status.url)'
)"

echo "$MCP_URL"

Die authentifizierte Health-Route testen:

curl -i \
  -H "Authorization: Bearer $(gcloud auth print-identity-token)" \
  "$MCP_URL/health"

Erwartet: HTTP 200 und {"status":"healthy"}.

7. Bereitgestelltes MCP-Tool testen

export MCP_URL="https://bigquery-rag-mcp-nfp4nl2vna-uc.a.run.app"
python test_deployed_mcp.py

Fragen:

What is the two-minute rule?

Der Testclient sollte eine MCP-Sitzung initialisieren, semantic_search aufrufen und strukturierte Retrieval-Ergebnisse ausgeben. Ein erfolgreicher HTTP-Status allein reicht nicht aus; überprüfen Sie, ob result_count größer als Null ist und das Ergebnis Seitenmetadaten enthält.

8. Begleitenden ADK-Dienst autorisieren

Nachdem Sie das Agent-Dienstkonto im begleitenden Repository erstellt haben, erlauben Sie ihm, diesen privaten Dienst aufzurufen:

export AGENT_SA="bigquery-rag-agent-sa@bigquery-semantic-search.iam.gserviceaccount.com"

gcloud run services add-iam-policy-binding "$MCP_SERVICE" \
  --project="$PROJECT_ID" \
  --region="$REGION" \
  --member="serviceAccount:${AGENT_SA}" \
  --role="roles/run.invoker"

Überprüfen:

gcloud run services get-iam-policy "$MCP_SERVICE" \
  --project="$PROJECT_ID" \
  --region="$REGION" \
  --flatten="bindings[].members" \
  --filter="bindings.members:serviceAccount:${AGENT_SA}" \
  --format="table(bindings.role,bindings.members)"

Das ADK-Dienstkonto benötigt run.invoker auf diesem Dienst. Es benötigt nicht die BigQuery-Rollen des MCP-Dienstes, da jeder Cloud Run-Dienst seine eigene Identität und Verantwortung hat.

Fahren Sie fort mit der ADK + React-Bereitstellungsanleitung.

Beobachtbarkeit

Aktuelle Protokolle lesen:

gcloud run services logs read "$MCP_SERVICE" \
  --project="$PROJECT_ID" \
  --region="$REGION" \
  --limit=100

Nützliche erfolgreiche Protokollnachricht:

Running semantic search with top_k=5

Cloud Run-Metriken sind verfügbar unter:

Google Cloud Console → Cloud Run → bigquery-rag-mcp → Metrics

BigQuery-Abfrageverlauf und verarbeitete Bytes sind im BigQuery-Jobverlauf oder in INFORMATION_SCHEMA.JOBS_BY_PROJECT verfügbar.

Fehlerbehebung

Sicherheit und Datenverarbeitung

• Der MCP Cloud Run-Dienst bleibt privat.

• Es werden keine Dienstkontoschlüssel-JSONs bereitgestellt oder committet.

• Es werden Cloud Run-Dienstidentität und kurzlebige Google-ID-Token verwendet.

• Der Benutzerabfragetext wird als Parameter an BigQuery übergeben.

• Das Tool ist als schreibgeschützt markiert und gibt nur Retrieval-Nachweise zurück.

• .env, ADC-Dateien, PDFs, JSONL-Chunks, Protokolle und lokale Datenbanken werden von Git ignoriert.

• Das Quelldokument und die extrahierten Abschnitte werden in diesem Repository nicht weiterverteilt.

• Setzen Sie Authentifizierungstoken nicht in Screenshots oder Protokollen offen.

Aktuelle Einschränkungen

• Der Korpus enthält 1.222 Abschnitte aus einem Dokument.

• Die Suche ist Brute-Force und hat keinen Vektorindex.

• Es gibt noch kein Reranking oder Retrieval-Evaluierungssuite.

• Das MCP-Tool gibt Passagen zurück; Antwortqualität und Zitate hängen vom begleitenden Agenten ab.

• Die aktuelle öffentliche Portfolio-Implementierung ist dokumentspezifisch und keine Multi-Tenant-Ingestionsplattform.

Empfohlene nächste Verbesserungen

1. Retrieval-Evaluierung mit einem Frage-/Erwartete-Quelle-Datensatz hinzufügen.

2. Ähnlichkeitsschwellenwerte und Enthaltungstests hinzufügen.

3. Dokumenten-Ingestion und Metadatenvalidierung als separate Pipeline unterstützen.

4. Mandanten-/Dokumentenfilter vor dem Retrieval hinzufügen.

5. Einen Vektorindex hinzufügen, nachdem das Dataset groß genug ist.

6. Strukturierte Cloud Logging-Felder für Latenz und Ergebnisanzahl hinzufügen, ohne Passageninhalte zu protokollieren.

7. Unit-Tests, die BigQuery mocken, und Integrationstests für den bereitgestellten MCP-Dienst hinzufügen.

GitHub-Veröffentlichung

git add README.md
git commit -m "Add end-to-end MCP deployment documentation"

git remote add origin https://github.com/shrprabh/bigquery-rag-mcp.git
git push -u origin main

Wenn origin bereits existiert, fügen Sie es nicht erneut hinzu. Überprüfen Sie mit git remote -v, führen Sie dann nur git push aus.

Offizielle Referenzen

• MCP Python SDK

• BigQuery AI.GENERATE_EMBEDDING

• BigQuery Vektorsuche

• BigQuery Verbindungszugriff

• Cloud Run Dienst-zu-Dienst-Authentifizierung

• Cloud Run Dienstidentität

Autor

Shreyas Prabhakar

• GitHub: @shrprabh

• LinkedIn: linkedin.com/in/shreyasprabhakar

• Medium: @pshreyasgowda1997