# LQABR_MCP

The LQABR central HubSpot MCP server. Built on **FastMCP**, and **standalone** —
no dependency on the LQABR mono-repo.

> **[RUNNING.md](RUNNING.md)** — how to run it: setup, credentials, both
> transports, agentgateway, troubleshooting.
> **[CONSUMING.md](CONSUMING.md)** — how the email / voice / scheduling agents
> call it: ADK `McpToolset`, auth, the wire contract, tool scoping.
> This file is the design rationale; those two are the procedures.

```
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
```

## This is a fork, not a move

`hubspot_mcp/` is a **copy** of the mono-repo's implementation. Only the import
lines were rewritten; no logic, field name or HubSpot property name changed.
Verified by diff — the only differing lines across all nine files are:

```
- 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 ...
```

**The mono-repo still needs its copy. Do not delete it.**

| Module | Also used by |
|---|---|
| `lqabr_core.obs` | 8 files in lead_profile/src, 2 in text_voice/src, `lqabr_core/crm` |
| `lqabr_core.leadgen.*` | 12 lead_profile files incl. `call_mcp.py`, plus `evals/run_eval.py` |
| `lqabr_core.leadgen.secrets` | lead_profile `model.py`, 2 test files |

**The consequence:** there are now two write paths to HubSpot carrying the same
field names and the same HubSpot property names — and the data contract says
those names *are* the contract. Any fix to `crm.py`, any auth change, any
HubSpot property rename must be applied in both places by hand. Nothing enforces
it. Budget for that, or plan to retire one side.

## Why this lives outside the mono-repo

The LQABR repo has a top-level package literally named `mcp` at its root, which
shadows the `mcp` SDK that FastMCP depends on. Running from inside the repo
breaks FastMCP's own imports.

**Do not** add the LQABR repo root to `PYTHONPATH`.

## Library: FastMCP, not the official SDK

The dependency is `fastmcp>=3.4.7`. **Do not add `mcp>=2.0`** — the two are
mutually exclusive:

- `fastmcp` 3.4.7 pins `mcp<2.0,>=1.24.0` transitively (it installs mcp 1.29).
- `MCPServer`, the official SDK's server class, exists only in `mcp>=2.0`.

So a project can use `FastMCP` or `MCPServer`, never both. This one uses
`FastMCP`. Nothing here imports `MCPServer`.

Two consequences worth knowing:

- **Transport names differ.** FastMCP's HTTP transport is `"http"`
  (`"streamable-http"` is accepted as an alias) and the endpoint path kwarg is
  `path=`. The official SDK spells that `streamable_http_path=`.
- **Type fields differ.** Because mcp is pinned to 1.x, the bundled types use
  camelCase: `Tool.inputSchema`, not `input_schema`.

The mono-repo's `lqabr_core/leadgen/server.py` still uses `MCPServer`. That is
now a second divergence between the two codebases, on top of the fork.

## Running it

```bash
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
```

### Credentials

`tools/list` needs nothing. A tool *call* needs the HubSpot token, and that
comes from **Secret Manager** — context §7.6 / CLAUDE.md §5: secrets are never
hard-coded and never committed.

```bash
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>` syncs *exactly* that extra set, so `--extra gcp` on its
> own uninstalls pytest. `test_server.py` runs as a CLI without pytest, but
> `uv run pytest` obviously needs it.

`.env` carries no secret values — just `HUBSPOT_AUTH_MODE`,
`LQABR_SECRET_PROJECT` and the secret's *ID*. The token itself is fetched over
the Secret Manager API at runtime, held in memory, never logged (the audit line
records only length and last four characters), and cached for 900s so rotation
needs no redeploy.

`auth.py` and `secrets.py` both fail closed — unset means an explicit error,
never a silent default.

> `LQABR_SECRET_BACKEND=env` exists as a last resort for offline work or CI.
> `secrets.py` scopes it to "local development, CI and tests only" and there is
> no automatic fallback to it — you must type it. It puts a live credential in
> a file on disk. Never set it in Cloud Run.

Every flag has an env-var default (`MCP_TRANSPORT`, `MCP_HOST`, `PORT`,
`MCP_PATH`), so the container starts with no arguments — Cloud Run injects
`PORT`.

## Tests

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

`pytest.ini` puts `hubspot-crm-mcp-server/` on the path so `import hubspot_mcp`
resolves — the folder itself can't be a package because of the hyphen.

### The contract is TEN fields, not nine

`LeadProfile` carries ten: the nine everyone documents, plus `contact_name`
(added for the firstname/lastname mapping). The mono-repo's
`test_wrapper_shape_is_the_nine_fields_plus_ids` still asserted 9 and had been
failing there — `schema.py` is byte-identical, so this project inherited it.

Resolved 2026-08-18: the code was right, the number was stale. The test is
renamed `test_wrapper_shape_is_the_contract_fields_plus_ids` and now asserts
the field *names* rather than a count, so the next addition fails with
something readable.

**The same fix is still owed to the mono-repo** — that assertion is unchanged
there and still red. The docs that say "9 fields" should be corrected too.

## Testing a deployed server

```bash
# 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
```

Read-only by design: it never calls `upsert_lead_profile`. Sends
`X-LQABR-Run-Id` so the server's audit logs attribute the call (the B10 fix).

> The ID token audience is the service base URL **without** `/mcp`. The script
> strips it for you.

The client uses `fastmcp.Client`, which handles the initialize handshake, so
there is no session plumbing in this file. Headers ride on a
`StreamableHttpTransport`. This now matches the reference sample's library.

## Deploying to Cloud Run

Two-stage uv build, non-root `mcp` user, PID 1 is Python so SIGTERM drains
cleanly. Self-contained: no sibling folder, no git dependency.

```bash
docker build -t lqabr-mcp-server .
```

Commit a `uv.lock` and switch the sync to `--frozen` before production.

Then S5–S8: create `mcp-server-sa`, grant `secretmanager.secretAccessor` on
`lqabr-hubspot-access-token`, deploy `--no-allow-unauthenticated`, grant the
three agent service accounts `roles/run.invoker`, point `test_server.py` at it.

## Tools exposed

| Tool | Direction | Notes |
|---|---|---|
| `upsert_lead_profile` | write | Company upsert → Contact upsert → association. Idempotent. |
| `get_lead_profile` | read | contract fields + `contact_hs_id` + `company_hs_id`. |

Dedup: Contact on `employee_id`, Company on `company_id`. Email lives in the
custom `email_id` property.

> **Open item.** The registered tool name is `upsert_lead_profile` (singular),
> but the design docs, session handoff and project instructions all say
> `upsert_lead_profiles` (plural), and the underlying function is plural.
> This is a wire contract — settle it before any client wires up.

## Credentials

Two, never confused:

- **Google ID token** proves *agent → this server* (Cloud Run service-to-service).
- **HubSpot M2M token** proves *this server → HubSpot*, minted per call inside
  the server. Callers never see it.

This service is the sole holder of the HubSpot credential.

## Verified

In a clean venv containing **only** `fastmcp` 3.4.7 (which brought `mcp` 1.29),
`requests` and `pytest` — with `lqabr_core` absent (confirmed
`ModuleNotFoundError`) and `MCPServer` absent (confirmed `ImportError`):

- zero `lqabr_core` imports anywhere in the project
- ported test suite: **61 passed, 0 failed**
- stdio — `tools/list` returns both tools, `PYTHONPATH` stripped entirely
- `--transport http` — binds host/port/path, full `fastmcp.Client` session
- `--transport streamable-http` — alias accepted, serves the same endpoint
- `test_server.py` — PASS against the running server, exit 0
- `test_server.py` under pytest — 3 passed with a server, 3 skipped without
- **live `call_tool` reached the real chain**: transport → tool → `crm.py` →
  `auth.py` → `secrets.py`, failing only at the deliberate
  `AuthConfigError` / `SecretConfigError` guards (no GCP config in the test
  environment). The wiring is proven end to end.

**Not verified:** the Docker image has never been built — no Docker daemon was
available where these files were assembled. Nothing has touched real HubSpot;
every test uses a fake.