LQABR_MCP

Центральный HubSpot MCP-сервер LQABR. Построен на FastMCP и является автономным — без зависимости от моно-репозитория LQABR.

RUNNING.md — как запустить: настройка, учётные данные, оба транспорта, agentgateway, устранение неполадок. CONSUMING.md — как его вызывают агенты электронной почты, голосовые и планирования: ADK McpToolset, аутентификация, контракт взаимодействия, область действия инструментов. Этот файл — обоснование дизайна; те два — процедуры.

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

Это форк, а не перенос

hubspot_mcp/ — это копия реализации из моно-репозитория. Были переписаны только строки импорта; никакая логика, имена полей или свойства HubSpot не изменялись. Проверено с помощью diff — единственные различающиеся строки во всех девяти файлах:

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

Моно-репозиторий по-прежнему нуждается в своей копии. Не удаляйте её.

Следствие: теперь существует два пути записи в HubSpot с одинаковыми именами полей и одинаковыми именами свойств HubSpot — и контракт данных гласит, что эти имена являются контрактом. Любое исправление в crm.py, любое изменение аутентификации, любое переименование свойства HubSpot должно применяться в обоих местах вручную. Ничто это не обеспечивает. Закладывайте бюджет на это или планируйте отказаться от одной из сторон.

Related MCP server: HubSpot MCP Server

Почему это находится вне моно-репозитория

В репозитории LQABR есть пакет верхнего уровня, буквально названный mcp в корне, который затеняет SDK mcp, от которого зависит FastMCP. Запуск изнутри репозитория нарушает собственные импорты FastMCP.

Не добавляйте корень репозитория LQABR в PYTHONPATH.

Библиотека: FastMCP, а не официальный SDK

Зависимость — fastmcp>=3.4.7. Не добавляйте mcp>=2.0 — они взаимоисключающие:

• fastmcp 3.4.7 транзитивно фиксирует mcp<2.0,>=1.24.0 (он устанавливает mcp 1.29).

• MCPServer, класс сервера официального SDK, существует только в mcp>=2.0.

Таким образом, проект может использовать либо FastMCP, либо MCPServer, но не оба. Этот использует FastMCP. Ничто здесь не импортирует MCPServer.

Два следствия, о которых стоит знать:

• Названия транспортов различаются. HTTP-транспорт FastMCP называется "http" ("streamable-http" принимается как псевдоним), а аргумент пути конечной точки — path=. Официальный SDK использует streamable_http_path=.

• Поля типов различаются. Поскольку mcp зафиксирован на версии 1.x, встроенные типы используют camelCase: Tool.inputSchema, а не input_schema.

В моно-репозитории lqabr_core/leadgen/server.py по-прежнему использует MCPServer. Теперь это второе расхождение между двумя кодовыми базами, в дополнение к форку.

Запуск

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

Учётные данные

tools/list ничего не требует. Вызов инструмента требует токен HubSpot, который поступает из Secret Manager — контекст §7.6 / CLAUDE.md §5: секреты никогда не жёстко кодируются и никогда не фиксируются.

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> синхронизирует именно этот дополнительный набор, так что --extra gcp сам по себе удаляет pytest. test_server.py запускается как CLI без pytest, но uv run pytest, очевидно, требует его.

.env не содержит секретных значений — только HUBSPOT_AUTH_MODE, LQABR_SECRET_PROJECT и ID секрета. Сам токен извлекается через API Secret Manager во время выполнения, хранится в памяти, никогда не логируется (строка аудита записывает только длину и последние четыре символа) и кэшируется на 900 секунд, поэтому ротация не требует повторного развёртывания.

auth.py и secrets.py оба завершаются с ошибкой — отсутствие значения означает явную ошибку, никогда не молчаливое значение по умолчанию.

LQABR_SECRET_BACKEND=env существует как крайнее средство для офлайн-работы или CI. secrets.py ограничивает его «локальной разработкой, CI и тестами», и нет автоматического перехода на него — вы должны ввести его вручную. Он помещает действующие учётные данные в файл на диске. Никогда не устанавливайте его в Cloud Run.

Каждый флаг имеет значение по умолчанию из переменной окружения (MCP_TRANSPORT, MCP_HOST, PORT, MCP_PATH), поэтому контейнер запускается без аргументов — Cloud Run вводит PORT.

Тесты

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

pytest.ini добавляет hubspot-crm-mcp-server/ в путь, чтобы import hubspot_mcp разрешался — сама папка не может быть пакетом из-за дефиса.

Контракт состоит из ДЕСЯТИ полей, а не девяти

LeadProfile содержит десять: девять, которые все документируют, плюс contact_name (добавлено для отображения firstname/lastname). В моно-репозитории test_wrapper_shape_is_the_nine_fields_plus_ids по-прежнему утверждал 9 и терпел неудачу — schema.py идентичен побайтово, поэтому этот проект унаследовал его.

Исправлено 2026-08-18: код был правильным, число устарело. Тест переименован в test_wrapper_shape_is_the_contract_fields_plus_ids и теперь проверяет имена полей, а не количество, так что следующее дополнение завершится с читаемой ошибкой.

То же исправление всё ещё необходимо в моно-репозитории — это утверждение там не изменено и всё ещё красное. Документы, в которых говорится «9 полей», также следует исправить.

Тестирование развёрнутого сервера

# 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

Только для чтения по дизайну: он никогда не вызывает upsert_lead_profile. Отправляет X-LQABR-Run-Id, чтобы журналы аудита сервера атрибутировали вызов (исправление B10).

Аудитория токена ID — это базовый URL сервиса без /mcp. Скрипт удаляет его за вас.

Клиент использует fastmcp.Client, который обрабатывает рукопожатие инициализации, поэтому в этом файле нет служебного кода сессии. Заголовки передаются через StreamableHttpTransport. Теперь это соответствует библиотеке эталонного образца.

Развёртывание в Cloud Run

Двухэтапная сборка uv, пользователь mcp без прав root, PID 1 — Python, поэтому SIGTERM корректно завершает работу. Самодостаточно: нет соседней папки, нет зависимости от git.

docker build -t lqabr-mcp-server .

Зафиксируйте uv.lock и переключите синхронизацию на --frozen перед продакшеном.

Затем S5–S8: создайте mcp-server-sa, предоставьте secretmanager.secretAccessor на lqabr-hubspot-access-token, разверните с --no-allow-unauthenticated, предоставьте трём сервисным аккаунтам агентов roles/run.invoker, укажите test_server.py на него.

Предоставленные инструменты

Дедупликация: Контакт по employee_id, Компания по company_id. Электронная почта находится в пользовательском свойстве email_id.

Открытый вопрос. Зарегистрированное имя инструмента — upsert_lead_profile (единственное число), но дизайн-документы, передача сессии и инструкции проекта — все говорят upsert_lead_profiles (множественное число), и базовая функция — множественное число. Это контракт взаимодействия — урегулируйте это до того, как какой-либо клиент подключится.

Учётные данные

Два, никогда не путаются:

• Токен ID Google подтверждает агент → этот сервер (Cloud Run service-to-service).

• M2M-токен HubSpot подтверждает этот сервер → HubSpot, создаётся за вызов внутри сервера. Вызывающие его никогда его не видят.

Этот сервис является единственным держателем учётных данных HubSpot.

Проверено

В чистом venv, содержащем только fastmcp 3.4.7 (который принёс mcp 1.29), requests и pytest — с отсутствующим lqabr_core (подтверждено ModuleNotFoundError) и отсутствующим MCPServer (подтверждено ImportError):

• нулевое количество импортов lqabr_core в проекте

• перенесённый набор тестов: 61 пройдено, 0 не пройдено

• stdio — tools/list возвращает оба инструмента, PYTHONPATH полностью удалён

• --transport http — привязывается к host/port/path, полная сессия fastmcp.Client

• --transport streamable-http — псевдоним принят, обслуживает ту же конечную точку

• test_server.py — PASS против работающего сервера, выход 0

• test_server.py под pytest — 3 пройдено с сервером, 3 пропущено без

• живой call_tool достиг реальной цепочки: transport → tool → crm.py → auth.py → secrets.py, завершившись только на преднамеренных защитах AuthConfigError / SecretConfigError (нет конфигурации GCP в тестовой среде). Соединение проверено от начала до конца.

Не проверено: образ Docker никогда не собирался — не было доступно Docker-демона, где собирались эти файлы. Ничто не касалось реального HubSpot; каждый тест использует фиктивный объект.