Servidor MCP BigQuery RAG

Un servicio privado del Protocolo de Contexto de Modelo (MCP) que convierte una pregunta en lenguaje natural en un embedding, realiza una recuperación semántica sobre fragmentos de documentos almacenados en BigQuery y devuelve pasajes estructurados con metadatos de fuente y página.

Este repositorio posee la capa de recuperación de un chatbot más grande basado en documentos. El repositorio de la aplicación complementaria posee la orquestación de Google ADK, la generación de respuestas de Gemini, Firebase Authentication, la API /chat y la interfaz React.

Aplicación complementaria: shrprabh/atomic-habits-adk-rag

Despliegue en vivo

La URL del servicio no es intencionadamente pública en el navegador. Un llamante debe tener roles/run.invoker en el servicio y enviar un token de identidad firmado por Google cuyo público sea la URL base de MCP.

Arquitectura integral

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

Qué hace este servicio

• Expone una herramienta MCP de solo lectura llamada semantic_search.

• Valida query y top_k usando esquemas MCP generados por Pydantic.

• Crea un embedding de consulta con AI.GENERATE_EMBEDDING usando RETRIEVAL_QUERY.

• Realiza VECTOR_SEARCH de distancia coseno sobre los embeddings de documentos almacenados.

• Utiliza un valor de consulta parametrizado en lugar de insertar la entrada del usuario en SQL.

• Devuelve campos estructurados de fuente, página, capítulo, sección, distancia y similitud.

• Se ejecuta como un servidor MCP HTTP Streamable sin estado.

• Mantiene el servicio de recuperación privado con IAM de Cloud Run.

• No llama a Gemini para componer una respuesta; la generación pertenece al servicio ADK complementario.

Recursos de BigQuery utilizados por este proyecto

La tabla actual es pequeña, por lo que esta implementación utiliza deliberadamente la búsqueda vectorial por fuerza bruta. Un índice vectorial se vuelve útil después de que el corpus crezca lo suficiente como para justificar la búsqueda aproximada del vecino más cercano y el mantenimiento del índice.

Contrato de la herramienta MCP

semantic_search

Entrada:

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

Validación:

Salida simplificada:

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

Estructura del repositorio

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 importa mcp de server.py, por lo que ejecuta la herramienta en el mismo proceso de Python. Es útil como cliente de referencia o regresión local, pero no forma parte de la ruta de solicitud de producción desplegada. La aplicación ADK complementaria llama a este servicio de forma remota a través de /mcp.

Requisitos previos

• Python 3.12+

• CLI de Google Cloud

• Un proyecto de Google Cloud con facturación habilitada

• APIs de BigQuery, BigQuery Connection, Vertex AI, Cloud Run, Cloud Build y Artifact Registry

• Conjunto de datos, modelo de embedding y tabla de embeddings existentes en BigQuery que coincidan con el esquema configurado

• Permiso para crear cuentas de servicio y administrar IAM de Cloud Run y BigQuery

1. Clonar e instalar

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

Para desarrollo local fuera de Cloud Shell:

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

Nunca confirmar Credenciales predeterminadas de la aplicación o archivos de clave de cuenta de servicio.

2. Configurar el entorno

cp .env.example .env

Valores esperados:

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

server.py lee estos valores del entorno del proceso. El archivo .env.example verificado es solo documentación; usar exportaciones explícitas localmente o variables de entorno de Cloud Run en el despliegue.

3. Verificar los activos de BigQuery

Ejecutar en el editor de BigQuery:

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

Esperado para el conjunto de datos actual:

dimensions  row_count
1536        1222

Confirmar que el modelo existe:

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

4. Configurar IAM en tiempo de ejecución

Establecer variables:

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"

Habilitar APIs:

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

Crear la cuenta de servicio de tiempo de ejecución si aún no existe:

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"

Conceder permiso a la cuenta de servicio para ejecutar consultas y leer el conjunto de datos/modelo:

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"

Permiso de conexión requerido

Debido a que AI.GENERATE_EMBEDDING utiliza la conexión de recursos en la nube de BigQuery, la identidad en tiempo de ejecución de MCP también debe tener permiso para usar vertex_ai_connection.

En la consola de Google Cloud:

1. Abrir BigQuery → tu proyecto → Conexiones.

2. Seleccionar vertex_ai_connection en us-central1.

3. Seleccionar Compartir.

4. Agregar bigquery-rag-mcp-sa@bigquery-semantic-search.iam.gserviceaccount.com.

5. Conceder Usuario de conexión de BigQuery (roles/bigquery.connectionUser).

No usar bq add-iam-policy-binding --connection_type=...; esa bandera no comparte una conexión y es rechazada por las versiones actuales de bq. Se debe usar la consola de Cloud o la API de conexiones de BigQuery para compartir a nivel de conexión.

La conexión en sí tiene una cuenta de servicio administrada por Google. Esa cuenta de servicio de conexión debe tener el rol de usuario de Vertex AI/Agent Platform apropiado en el proyecto para que el modelo de embedding remoto pueda llamar a su endpoint.

Sin estos permisos de conexión, el registro de MCP contiene un error similar a:

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

5. Probar localmente

Compilar los archivos:

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

Ejecutar la prueba de regresión MCP directa:

python test_mcp.py

Iniciar el servidor HTTP:

python server.py

Endpoints:

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

Desde otro terminal:

curl http://localhost:8000/health

Esperado:

{"status":"healthy"}

Opcionalmente, ejecutar el cliente de referencia de generación fundamentada local:

python rag_client.py

6. Desplegar el servicio MCP privado

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 suministra PORT; server.py se vincula a 0.0.0.0 y usa ese puerto.

Obtener la URL canónica del servicio:

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

echo "$MCP_URL"

Probar la ruta de salud autenticada:

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

Esperado: HTTP 200 y {"status":"healthy"}.

7. Probar la herramienta MCP desplegada

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

Preguntar:

What is the two-minute rule?

El cliente de prueba debe inicializar una sesión MCP, llamar a semantic_search e imprimir resultados de recuperación estructurados. Un estado HTTP exitoso por sí solo es insuficiente; verificar que result_count sea mayor que cero y el resultado contenga metadatos de página.

8. Autorizar el servicio ADK complementario

Después de crear la cuenta de servicio del agente en el repositorio complementario, permitirle invocar este servicio privado:

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"

Verificar:

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

La cuenta de servicio de ADK necesita run.invoker en este servicio. No necesita los roles de BigQuery del servicio MCP porque cada servicio de Cloud Run tiene su propia identidad y responsabilidad.

Continuar con la guía de despliegue de ADK + React.

Observabilidad

Leer registros recientes:

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

Mensaje de registro exitoso útil:

Running semantic search with top_k=5

Las métricas de Cloud Run están disponibles en:

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

El historial de consultas de BigQuery y los bytes procesados están disponibles en el historial de trabajos de BigQuery o en INFORMATION_SCHEMA.JOBS_BY_PROJECT.

Solución de problemas

Seguridad y manejo de datos

• El servicio MCP de Cloud Run permanece privado.

• No se despliegan ni confirman archivos JSON de clave de cuenta de servicio.

• Se utilizan la identidad del servicio de Cloud Run y tokens de ID de Google de corta duración.

• El texto de la consulta del usuario se pasa a BigQuery como un parámetro.

• La herramienta está marcada como de solo lectura y devuelve solo evidencia de recuperación.

• .env, archivos ADC, PDFs, fragmentos JSONL, registros y bases de datos locales son ignorados por Git.

• El documento fuente y los fragmentos extraídos no se redistribuyen en este repositorio.

• No exponer tokens de autenticación en capturas de pantalla o registros.

Limitaciones actuales

• El corpus contiene 1,222 fragmentos de un documento.

• La búsqueda es por fuerza bruta y no tiene un índice vectorial.

• Aún no hay un reordenador o un conjunto de evaluación de recuperación.

• La herramienta MCP devuelve pasajes; la calidad de la respuesta y las citas dependen del agente complementario.

• La implementación actual del portafolio público es específica del documento en lugar de una plataforma de ingesta multiinquilino.

Próximas mejoras recomendadas

1. Agregar evaluación de recuperación con un conjunto de datos de preguntas/fuentes esperadas.

2. Agregar umbrales de similitud y pruebas de abstención.

3. Soportar la ingesta de documentos y la validación de metadatos como un pipeline separado.

4. Agregar filtros de inquilino/documento antes de la recuperación.

5. Agregar un índice vectorial después de que el conjunto de datos sea lo suficientemente grande.

6. Agregar campos estructurados de Cloud Logging para latencia y recuento de resultados sin registrar el contenido de los pasajes.

7. Agregar pruebas unitarias que simulen BigQuery y pruebas de integración para el servicio MCP desplegado.

Publicación en GitHub

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

Si origin ya existe, no agregarlo de nuevo. Verificar con git remote -v, luego ejecutar solo git push.

Referencias oficiales

• MCP Python SDK

• AI.GENERATE_EMBEDDING de BigQuery

• Búsqueda vectorial de BigQuery

• Acceso a conexiones de BigQuery

• Autenticación de servicio a servicio en Cloud Run

• Identidad de servicio en Cloud Run

Autor

Shreyas Prabhakar

• GitHub: @shrprabh

• LinkedIn: linkedin.com/in/shreyasprabhakar

• Medium: @pshreyasgowda1997