LQABR_MCP

El servidor MCP central de HubSpot de LQABR. Construido sobre FastMCP, y autónomo — sin dependencia del mono-repo de LQABR.

RUNNING.md — cómo ejecutarlo: configuración, credenciales, ambos transportes, agentgateway, solución de problemas. CONSUMING.md — cómo lo llaman los agentes de correo electrónico / voz / programación: ADK McpToolset, autenticación, el contrato de red, alcance de herramientas. Este archivo es la justificación del diseño; esos dos son los procedimientos.

LQABR_MCP/
├── hubspot-crm-mcp-server/
│   ├── __init__.py              (empty, per mcp.odt Step 4)
│   ├── hubspot_crm_server.py    the launcher — mcp.odt Step 5
│   ├── test_server.py           remote smoke test — handoff S8
│   ├── hubspot_mcp/             THE IMPLEMENTATION (vendored)
│   │   ├── __init__.py          provenance + drift warning — read this
│   │   ├── server.py            the FastMCP object + the two tools
│   │   ├── secrets.py           Secret Manager access
│   │   ├── obs/                 the four logs: system/process/audit/tokens
│   │   │   ├── __init__.py
│   │   │   ├── context.py       RunContext, run_id, lead_ref_id
│   │   │   └── loggers.py
│   │   └── hubspot/
│   │       ├── __init__.py
│   │       ├── crm.py           upsert_lead_profiles / get_lead_profile
│   │       ├── auth.py          get_hubspot_token(), short-lived M2M
│   │       ├── schema.py        LeadProfile, PushResult, property mapping
│   │       └── failures.py      failure taxonomy + CircuitBreaker
│   └── tests/                   61 tests ported from the mono-repo
├── .vscode/hubspot_mcp.json     stdio config — mcp.odt Steps 7–8
├── Dockerfile                   Cloud Run image — handoff S4
├── .dockerignore
├── pytest.ini
├── .python-version              3.12, matching the Dockerfile
├── .env.example                 mode switches + secret IDs (no values)
├── pyproject.toml
├── RUNNING.md                   step-by-step runbook — start here
├── CONSUMING.md                 client integration guide for other agents
└── README.md

Esto es un fork, no un traslado

hubspot_mcp/ es una copia de la implementación del mono-repo. Solo se reescribieron las líneas de importación; no cambió ninguna lógica, nombre de campo o propiedad de HubSpot. Verificado por diff — las únicas líneas que difieren entre los nueve archivos son:

- from lqabr_core.obs import get_obs, utc_now_iso
+ from ..obs import get_obs, utc_now_iso
- from lqabr_core.leadgen.secrets import ...
+ from ..secrets import ...

El mono-repo aún necesita su copia. No la elimines.

La consecuencia: ahora hay dos rutas de escritura hacia HubSpot que transportan los mismos nombres de campo y los mismos nombres de propiedad de HubSpot — y el contrato de datos dice que esos nombres son el contrato. Cualquier corrección en crm.py, cualquier cambio de autenticación, cualquier renombre de propiedad de HubSpot debe aplicarse en ambos lugares a mano. Nada lo impone. Presupuesta eso, o planea retirar un lado.

Related MCP server: HubSpot MCP Server

Por qué esto vive fuera del mono-repo

El repositorio LQABR tiene un paquete de nivel superior literalmente llamado mcp en su raíz, que oculta el SDK mcp del que depende FastMCP. Ejecutar desde dentro del repositorio rompe las importaciones propias de FastMCP.

No agregues la raíz del repositorio LQABR a PYTHONPATH.

Librería: FastMCP, no el SDK oficial

La dependencia es fastmcp>=3.4.7. No agregues mcp>=2.0 — los dos son mutuamente excluyentes:

• fastmcp 3.4.7 fija mcp<2.0,>=1.24.0 transitivamente (instala mcp 1.29).

• MCPServer, la clase de servidor del SDK oficial, solo existe en mcp>=2.0.

Por lo tanto, un proyecto puede usar FastMCP o MCPServer, nunca ambos. Este usa FastMCP. Nada aquí importa MCPServer.

Dos consecuencias que vale la pena conocer:

• Los nombres de transporte difieren. El transporte HTTP de FastMCP es "http" ("streamable-http" se acepta como alias) y el argumento de ruta del endpoint es path=. El SDK oficial lo escribe como streamable_http_path=.

• Los campos de tipo difieren. Debido a que mcp está fijado a 1.x, los tipos incluidos usan camelCase: Tool.inputSchema, no input_schema.

El lqabr_core/leadgen/server.py del mono-repo aún usa MCPServer. Eso es ahora una segunda divergencia entre los dos códigos, además del fork.

Cómo ejecutarlo

uv sync

# stdio — local ADK MCPToolset, or the VSCode config in .vscode/
uv run python hubspot-crm-mcp-server/hubspot_crm_server.py

# HTTP — what Cloud Run runs
uv run python hubspot-crm-mcp-server/hubspot_crm_server.py \
    --transport http --host 0.0.0.0 --port 8080

Credenciales

tools/list no necesita nada. Una llamada a una herramienta necesita el token de HubSpot, y ese viene de Secret Manager — contexto §7.6 / CLAUDE.md §5: los secretos nunca se codifican y nunca se confirman.

cp .env.example .env                    # holds mode switches + secret IDs only
gcloud auth application-default login
uv sync --extra gcp --extra test        # both extras; --extra gcp alone drops pytest
export UV_ENV_FILE=.env

uv sync --extra <x> sincroniza exactamente ese conjunto extra, por lo que --extra gcp por sí solo desinstala pytest. test_server.py se ejecuta como CLI sin pytest, pero uv run pytest obviamente lo necesita.

.env no lleva valores secretos — solo HUBSPOT_AUTH_MODE, LQABR_SECRET_PROJECT y el ID del secreto. El token en sí se obtiene a través de la API de Secret Manager en tiempo de ejecución, se mantiene en memoria, nunca se registra (la línea de auditoría registra solo la longitud y los últimos cuatro caracteres) y se almacena en caché durante 900 s para que la rotación no necesite redespliegue.

auth.py y secrets.py fallan cerrados — no estar establecido significa un error explícito, nunca un valor predeterminado silencioso.

LQABR_SECRET_BACKEND=env existe como último recurso para trabajo fuera de línea o CI. secrets.py lo limita a "desarrollo local, CI y pruebas únicamente" y no hay una caída automática hacia él — debes escribirlo. Coloca una credencial real en un archivo en disco. Nunca lo establezcas en Cloud Run.

Cada indicador tiene un valor predeterminado de variable de entorno (MCP_TRANSPORT, MCP_HOST, PORT, MCP_PATH), por lo que el contenedor se inicia sin argumentos — Cloud Run inyecta PORT.

Pruebas

uv run pytest              # 61 tests, all passing, none touch real HubSpot

pytest.ini añade hubspot-crm-mcp-server/ a la ruta para que import hubspot_mcp se resuelva — la carpeta en sí no puede ser un paquete debido al guion.

El contrato tiene DIEZ campos, no nueve

LeadProfile lleva diez: los nueve que todos documentan, más contact_name (agregado para el mapeo de nombre/apellido). La prueba test_wrapper_shape_is_the_nine_fields_plus_ids del mono-repo todavía afirmaba 9 y había estado fallando allí — schema.py es idéntico byte a byte, por lo que este proyecto lo heredó.

Resuelto el 2026-08-18: el código era correcto, el número estaba obsoleto. La prueba se renombró a test_wrapper_shape_is_the_contract_fields_plus_ids y ahora afirma los nombres de los campos en lugar de un conteo, por lo que la próxima adición fallará con algo legible.

La misma corrección aún se debe al mono-repo — esa afirmación no ha cambiado allí y sigue en rojo. Los documentos que dicen "9 campos" también deberían corregirse.

Probando un servidor desplegado

# local
uv run python hubspot-crm-mcp-server/test_server.py

# Cloud Run — mints a Google ID token via ADC
uv run python hubspot-crm-mcp-server/test_server.py \
    --url https://lqabr-mcp-server-xxxx.a.run.app/mcp --auth google

# one real read against HubSpot — writes nothing
... --auth google --employee-id EMP-00042

Solo lectura por diseño: nunca llama a upsert_lead_profile. Envía X-LQABR-Run-Id para que los registros de auditoría del servidor atribuyan la llamada (la corrección B10).

La audiencia del token ID es la URL base del servicio sin /mcp. El script la elimina por ti.

El cliente usa fastmcp.Client, que maneja el handshake de inicialización, por lo que no hay configuración de sesión en este archivo. Los encabezados viajan sobre un StreamableHttpTransport. Ahora esto coincide con la biblioteca de la muestra de referencia.

Desplegando en Cloud Run

Construcción uv de dos etapas, usuario mcp no root, PID 1 es Python para que SIGTERM se descargue limpiamente. Autocontenido: sin carpeta hermana, sin dependencia de git.

docker build -t lqabr-mcp-server .

Confirma un uv.lock y cambia la sincronización a --frozen antes de producción.

Luego S5–S8: crea mcp-server-sa, otorga secretmanager.secretAccessor en lqabr-hubspot-access-token, despliega --no-allow-unauthenticated, otorga a las tres cuentas de servicio de agente roles/run.invoker, apunta test_server.py hacia él.

Herramientas expuestas

Deduplicación: Contacto por employee_id, Empresa por company_id. El correo electrónico vive en la propiedad personalizada email_id.

Pendiente. El nombre de la herramienta registrada es upsert_lead_profile (singular), pero los documentos de diseño, la transferencia de sesión y las instrucciones del proyecto dicen upsert_lead_profiles (plural), y la función subyacente es plural. Esto es un contrato de red — resuélvelo antes de que cualquier cliente se conecte.

Credenciales

Dos, nunca confundidas:

• Token ID de Google prueba agente → este servidor (Cloud Run servicio a servicio).

• Token M2M de HubSpot prueba este servidor → HubSpot, acuñado por llamada dentro del servidor. Quienes llaman nunca lo ven.

Este servicio es el único poseedor de la credencial de HubSpot.

Verificado

En un entorno virtual limpio que contiene solo fastmcp 3.4.7 (que trajo mcp 1.29), requests y pytest — con lqabr_core ausente (confirmado ModuleNotFoundError) y MCPServer ausente (confirmado ImportError):

• cero importaciones de lqabr_core en cualquier parte del proyecto

• suite de pruebas migrada: 61 pasadas, 0 falladas

• stdio — tools/list devuelve ambas herramientas, PYTHONPATH eliminado por completo

• --transport http — vincula host/puerto/ruta, sesión completa de fastmcp.Client

• --transport streamable-http — alias aceptado, sirve el mismo endpoint

• test_server.py — PASS contra el servidor en ejecución, salida 0

• test_server.py bajo pytest — 3 pasadas con servidor, 3 omitidas sin él

• call_tool en vivo alcanzó la cadena real: transporte → herramienta → crm.py → auth.py → secrets.py, fallando solo en las protecciones deliberadas de AuthConfigError / SecretConfigError (sin configuración de GCP en el entorno de prueba). El cableado está comprobado de extremo a extremo.

No verificado: la imagen Docker nunca se ha construido — no había un demonio de Docker disponible donde se ensamblaron estos archivos. Nada ha tocado HubSpot real; cada prueba usa simulaciones.