From 059597346db292f01611550cc42e9f7513f70f29 Mon Sep 17 00:00:00 2001 From: Cristian Felipe Cruz Buitron Date: Mon, 21 Sep 2026 04:16:05 +0000 Subject: [PATCH] docs(adr-0012): documentar pivot de Fase 1 a Connectors nativos de claude.ai El MCP self-hosted (taylorwilsdon/google_workspace_mcp) quedo abandonado: limite real en FastMCP's OAuthProxy, no error de configuracion - redirect_uri se arma desde base_url (no desde GOOGLE_OAUTH_REDIRECT_URI), y base_url tambien alimenta issuer_url, que mcp/server/auth/routes.py exige HTTPS-o-localhost sin bypass. Documenta la causa raiz confirmada leyendo el codigo fuente instalado, la decision del usuario de usar Connectors nativos en su lugar, y la verificacion en vivo (3 calendarios reales, razonamiento de fechas correcto). Co-Authored-By: Claude Sonnet 5 Claude-Session: https://claude.ai/code/session_01QMP7ULbxbsB5g1vELNAT3D --- .../0012-practica-multicloud-gcp-azure.md | 80 ++++++++++++++----- 1 file changed, 62 insertions(+), 18 deletions(-) diff --git a/workloads/docs-portal/docs/decisiones/0012-practica-multicloud-gcp-azure.md b/workloads/docs-portal/docs/decisiones/0012-practica-multicloud-gcp-azure.md index 2a0820f..c6b4c1e 100644 --- a/workloads/docs-portal/docs/decisiones/0012-practica-multicloud-gcp-azure.md +++ b/workloads/docs-portal/docs/decisiones/0012-practica-multicloud-gcp-azure.md @@ -1,9 +1,13 @@ # ADR 0012 — Práctica multi-cloud: GCP y Azure DevOps en paralelo al lab ZimaOS -**Estado:** aceptada — Fase 1 (Google Workspace) en ejecución en esta -misma sesión; Fases 2-4 quedan documentadas como roadmap, explícitamente -no implementadas hasta que se pidan en una sesión futura. -**Fecha:** 2026-09-20 +**Estado:** aceptada — Fase 1 (Google Workspace) completa y verificada +en vivo, con un giro real: el MCP self-hosted planeado +(`taylorwilsdon/google_workspace_mcp`) quedó abandonado por un límite +real de esa librería (ver §Fase 1), reemplazado por los Connectors +nativos de claude.ai. Fases 2-4 quedan documentadas como roadmap, +explícitamente no implementadas hasta que se pidan en una sesión +futura. +**Fecha:** 2026-09-20 (Fase 1 cerrada 2026-09-21) ## Contexto @@ -36,7 +40,7 @@ empujan a abrir una segunda línea de práctica en paralelo: arquitectónica real, diagramas Mermaid, cifras verificadas en vivo o contra fuente primaria (no contra un blog de terceros sin corroborar — ver el caso del supuesto MCP "oficial" de Google - Workspace en la [Fase 1](#fase-1-ejecutar-en-esta-sesion-google-workspace)). + Workspace en la [Fase 1](#fase-1-ejecutada-google-workspace-con-un-giro-real-en-la-implementacion)). ## Diagrama del lab actual (ZimaOS) @@ -194,20 +198,60 @@ Todas documentadas acá; **solo la Fase 1 se ejecuta en esta sesión.** Las Fases 2-4 no se implementan sin pedido explícito en una sesión futura — quedan como roadmap, no como trabajo en curso. -### Fase 1 (ejecutar en esta sesión) — Google Workspace +### Fase 1 (ejecutada) — Google Workspace, con un giro real en la implementación -MCP de Google Workspace vía cuenta personal, para las iniciativas ya -en curso. Detalle de la investigación previa a implementar (qué MCP -usar, oficial vs comunitario) en la Parte 3 de esta conversación — -resumen: **no existe un MCP oficial de Google Workspace** publicado -por Google (se verificó explícitamente buscando en los GitHub -`google`/`googleworkspace` oficiales — no aparece ninguno; un solo -blog de terceros afirma que "ya existe uno oficial" sin que ninguna -otra fuente lo corrobore, así que se descarta esa afirmación por no -verificable). `taylorwilsdon/google_workspace_mcp` es la opción -comunitaria más completa y activamente mantenida (120+ herramientas, -OAuth 2.1, +2500 estrellas) — es la que se usa, etiquetada como -comunitaria, no oficial. +**Objetivo cumplido — acceso real a Google Calendar desde Claude, +verificado en vivo — pero por un camino distinto al planeado +originalmente.** Detalle de la investigación previa (qué MCP usar, +oficial vs comunitario) — resumen: **no existe un MCP oficial de +Google Workspace** publicado por Google (se verificó explícitamente +buscando en los GitHub `google`/`googleworkspace` oficiales — no +aparece ninguno; un solo blog de terceros afirma que "ya existe uno +oficial" sin que ninguna otra fuente lo corrobore, así que se descarta +esa afirmación por no verificable). Se optó por +`taylorwilsdon/google_workspace_mcp` (comunitario, el más completo y +activamente mantenido: 120+ herramientas, OAuth 2.1, +2500 estrellas) +como primer intento, self-hosted dentro de `tmux-host`. + +**Ese self-hosted quedó abandonado — límite real encontrado en la +librería, no un error de configuración.** El servidor usa FastMCP's +`GoogleProvider`/`OAuthProxy`, que construye el `redirect_uri` +enviado a Google directamente desde su propio `base_url` — **no** +desde la variable `GOOGLE_OAUTH_REDIRECT_URI` que el proyecto expone +(esa variable solo valida entradas, no arma la salida real; hallazgo +confirmado leyendo el código fuente instalado, no la documentación +pública). Y `base_url` es la misma variable de la que depende por +default `issuer_url`, que el SDK de MCP exige sea HTTPS salvo que sea +literalmente `localhost`/`127.0.0.1` (chequeo hardcodeado en +`mcp/server/auth/routes.py:validate_issuer_url`, sin variable de +entorno que lo salte). Resultado: **no hay combinación de variables +de entorno que satisfaga a la vez** "el navegador del usuario debe +poder llegar al callback" (necesita un dominio real, no `localhost`) +y "el issuer debe ser HTTPS o `localhost`" — `workspace-mcp` no +expone `issuer_url` por separado de `base_url` en su capa de +configuración (confirmado en `core/server.py`: solo pasa `base_url` a +`GoogleProvider(...)`). + +**Decisión del usuario ante ese límite:** en vez de armar un proxy +HTTPS con certificado autofirmado (infraestructura extra, fricción de +certificado no confiable en cada uso) o parchear el paquete instalado +a mano (frágil, se pierde en cualquier reinstalación), se usaron los +**Connectors nativos de claude.ai** (Google Calendar, vía el +directorio de conectores de la cuenta, fuera de Claude Code por +completo) — mismo resultado práctico (Claude con acceso real al +calendario personal), infraestructura cero de nuestro lado, sin +tocar código de terceros. Contrapartida real: es una integración de +cuenta de claude.ai, no un MCP configurado dentro del proyecto +`platform-multicloud` — no aparece como herramienta en sesiones de +Claude Code (`lab`/`cloud-practice`), solo en el chat normal de +claude.ai. + +**Verificado en vivo:** pregunta real en claude.ai normal ("¿qué +tengo en el calendario esta semana?") devolvió una respuesta correcta +revisando 3 calendarios reales de la cuenta (principal, Familia, +festivos de Colombia) vía la herramienta `Google Calendar: Lists +calendar events`, con razonamiento correcto sobre qué cuenta como +"esta semana" dado el día/hora real de la consulta. ### Fase 2 (documentar, no ejecutar) — Terraform aislado