LQABR_MCP

LQABR の中央 HubSpot MCP サーバーです。FastMCP 上に構築されており、スタンドアロン で動作します — LQABR モノレポへの依存はありません。

RUNNING.md — 実行方法: セットアップ、認証情報、両方のトランスポート、agentgateway、トラブルシューティング。 CONSUMING.md — メール / 音声 / スケジューリングエージェントがこれを呼び出す方法: ADK McpToolset、認証、ワイヤーコントラクト、ツールスコープ。 このファイルは設計の根拠です。上記の2つは手順書です。

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 で確認済み — 9 ファイルすべてで差があるのは以下の行のみです:

- 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 への書き込みパスが 2 つ存在することになり、データコントラクトはそれらの名前がコントラクトであると定義しています。crm.py への修正、認証の変更、HubSpot プロパティの名称変更はすべて、手動で両方の場所に適用する必要があります。それを強制するものは何もありません。そのための予算を組むか、どちらか片方を廃止する計画を立ててください。

Related MCP server: HubSpot MCP Server

なぜこれがモノレポの外に存在するのか

LQABR リポジトリのルートには、文字通り mcp という名前のトップレベルパッケージがあり、これが FastMCP が依存する mcp SDK を隠蔽（シャドウ）します。リポジトリ内から実行すると FastMCP 自身のインポートが壊れます。

LQABR リポジトリルートを PYTHONPATH に追加しないでください。

ライブラリ: FastMCP（公式 SDK ではありません）

依存関係は fastmcp>=3.4.7 です。mcp>=2.0 は追加しないでください — この2つは互いに排他的です:

• fastmcp 3.4.7 は推移的に mcp<2.0,>=1.24.0 を固定します（mcp 1.29 をインストールします）。

• 公式 SDK のサーバークラスである MCPServer は mcp>=2.0 にのみ存在します。

したがって、プロジェクトは FastMCP または MCPServer のどちらか一方のみを使用でき、両方は使用できません。こちらは FastMCP を使用します。ここでは MCPServer をインポートしません。

知っておくべき2つの結果:

• トランスポート名が異なります。 FastMCP の HTTP トランスポートは "http" です（"streamable-http" はエイリアスとして受け入れられます）。エンドポイントパスのキーワード引数は path= です。公式 SDK では streamable_http_path= と記述します。

• 型のフィールドが異なります。 mcp が 1.x に固定されているため、バンドルされた型は camelCase を使用します: Tool.inputSchema、input_schema ではありません。

モノレポの lqabr_core/leadgen/server.py は依然として MCPServer を使用しています。これは、フォークに加えて、2 つのコードベース間の2つ目の乖離点となっています。

実行方法

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 は pytest なしで CLI として実行できますが、uv run pytest では明らかに pytest が必要です。

.env はシークレットの値を一切保持しません — HUBSPOT_AUTH_MODE、LQABR_SECRET_PROJECT、およびシークレットの ID だけです。トークン自体は実行時に Secret Manager API 経由で取得され、メモリ内に保持され、決してログに記録されず（監査行には長さと最後の4文字のみが記録されます）、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 が解決されます — フォルダ自体はハイフンが含まれているためパッケージにできません。

コントラクトは9フィールドではなく10フィールド

LeadProfile は10個持ちます: 全員が文書化する9つに加えて、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 へのデプロイ

2段階の uv ビルド、非rootの mcp ユーザー、PID1 は Python なので SIGTERM はきれいにドレインされます。自己完結型: 兄弟フォルダーや git 依存関係はありません。

docker build -t lqabr-mcp-server .

uv.lock をコミットし、本番環境の前に同期を --frozen に切り替えてください。

次に S5–S8: mcp-server-sa を作成し、lqabr-hubspot-access-token に secretmanager.secretAccessor を付与し、--no-allow-unauthenticated でデプロイし、3つのエージェントサービスアカウントに roles/run.invoker を付与し、test_server.py をそのサーバーに向けます。

公開されるツール

重複排除: 連絡先は employee_id、会社は company_id で行います。メールはカスタム email_id プロパティに格納されます。

未解決項目。 登録されたツール名は upsert_lead_profile（単数形）ですが、設計ドキュメント、セッションハンドオフ、プロジェクトの指示はすべて upsert_lead_profiles（複数形）と言っており、基盤となる関数も複数形です。これはワイヤーコントラクトです — クライアントが配線する前に解決してください。

認証情報

2種類あり、決して混同されません:

• Google ID トークン は、エージェント → このサーバー（Cloud Run サービス間）を証明します。

• HubSpot M2M トークン は、このサーバー → HubSpot を証明し、サーバー内部で呼び出しごとに発行されます。呼び出し元はこれを見ることはありません。

このサービスは HubSpot 認証情報の唯一の保持者です。

検証済み

fastmcp 3.4.7（これにより mcp 1.29 が導入された）、requests、pytest のみを含むクリーンな venv で — lqabr_core が存在せず（ModuleNotFoundError 確認済み）、MCPServer が存在せず（ImportError 確認済み）:

• プロジェクト内のどこにも lqabr_core のインポートはゼロ

• 移植されたテストスイート: 61 パス、0 失敗

• stdio — tools/list が両方のツールを返し、PYTHONPATH は完全に除去

• --transport http — ホスト/ポート/パスにバインド、完全な fastmcp.Client セッション

• --transport streamable-http — エイリアス受け入れ、同じエンドポイントを提供

• test_server.py — 実行中のサーバーに対して PASS、終了コード 0

• pytest 下の test_server.py — サーバーありで3パス、サーバーなしで3スキップ

• 実際の call_tool が本番チェーンに到達: トランスポート → ツール → crm.py → auth.py → secrets.py、意図的な AuthConfigError / SecretConfigError ガードでのみ失敗（テスト環境に GCP 設定がない）。配線はエンドツーエンドで証明されました。

未検証: Docker イメージは一度もビルドされていません — これらのファイルが組み立てられた場所で Docker デーモンは利用できませんでした。実際の HubSpot に触れたものは何もなく、すべてのテストは偽の環境を使用しています。