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 conexión, 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 ni nombre de propiedad de HubSpot. Verificado por diff — las únicas líneas diferentes en 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 llevan 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 cambio de nombre de propiedad de HubSpot debe aplicarse manualmente en ambos lugares. Nada lo impone. Presupuesta eso, o planea retirar uno de los lados.

Related MCP server: hubspot-mcp-server

Por qué esto vive fuera del mono-repo

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

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

Biblioteca: 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. Aquí no se importa MCPServer.

Dos consecuencias que vale la pena conocer:

• Los nombres de los transportes difieren. El transporte HTTP de FastMCP es "http" (se acepta "streamable-http" como alias) y el argumento de la 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 en 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. Ahora esa es una segunda divergencia entre los dos códigos, además del fork.

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 eso proviene 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 contiene 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 solo registra la longitud y los últimos cuatro caracteres) y se almacena en caché durante 900 s para que la rotación no requiera un nuevo despliegue.

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

LQABR_SECRET_BACKEND=env existe como último recurso para trabajo sin conexión o CI. secrets.py lo limita a "desarrollo local, CI y pruebas únicamente" y no hay una alternativa automática a él — debes escribirlo. Coloca una credencial real en un archivo en el 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 coloca hubspot-crm-mcp-server/ en la ruta para que import hubspot_mcp se resuelva — la carpeta en sí no puede ser un paquete debido al guión.

El contrato son DIEZ campos, no nueve

LeadProfile lleva diez: los nueve que todos documentan, más contact_name (agregado para el mapeo de nombre/apellido). El test_wrapper_shape_is_the_nine_fields_plus_ids del mono-repo aún 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 desactualizado. La prueba se renombra a test_wrapper_shape_is_the_contract_fields_plus_ids y ahora afirma los nombres de los campos en lugar de un recuento, por lo que la próxima adición falla 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 de ID es la URL base del servicio sin /mcp. El script lo elimina por ti.

El cliente usa fastmcp.Client, que maneja el apretón de manos de inicialización, por lo que no hay plomería de sesión en este archivo. Los encabezados viajan en un StreamableHttpTransport. Esto ahora coincide con la biblioteca de la muestra de referencia.

Desplegando en Cloud Run

Compilación uv en dos etapas, usuario mcp no root, PID 1 es Python para que SIGTERM se drene limpiamente. Autónomo: 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, concede secretmanager.secretAccessor en lqabr-hubspot-access-token, despliega --no-allow-unauthenticated, concede 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 conexión — resuélvelo antes de que cualquier cliente se conecte.

Credenciales

Dos, nunca se confunden:

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

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

Este servicio es el único titular 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 pasaron, 0 fallaron

• 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 — PASÓ contra el servidor en ejecución, salida 0

• test_server.py bajo pytest — 3 pasaron con servidor, 3 omitidos sin

• 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á probado de extremo a extremo.

No verificado: la imagen de 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 un simulacro.