H2T プロダクト群 MCP サーバー新設（v2）
概要
| 項目 | 内容 |
|---|---|
| ステータス | 🔵 提案中 |
| GitLab Issue | Mappy #58 |
| 対象プロダクト | GMAC / GCOR / PIPIT (KingMeo) / 口コミONE の 4 製品 |
| 想定工数（Phase 1 MVP） | 約 11.5 人日（AI 前提 — 人間のレビュー時間） |
| 想定工数（全 Phase） | 約 24.5 人日 |
| 想定月額コスト（追加分） | 約 $5〜30 USD/月（Phase 1〜2、リクエスト数に比例） |
| 実装スタック | Python 3.13 + 公式 MCP Python SDK + AWS Lambda + API Gateway HTTP API + DynamoDB |
H2T が提供する MEO 系 4 プロダクト（GMAC / GCOR / PIPIT / 口コミONE）に対し、顧客が利用している ChatGPT / Claude などの AI クライアントから MCP (Model Context Protocol) 経由でデータ参照・操作できるサーバーを新設する。
既存の本番 AWS インフラ（Account: 881980194724）に乗せる形で、新規 EC2 / ALB / Redis などは追加しない。既存 Lambda 群と同じ運用パターン（Python 3.13 zip パッケージ）に揃え、運用ノウハウを完全に流用する。
背景・目的
解決したい課題
- 顧客は自分が契約している ChatGPT Pro / Claude Pro 等の AI 能力を持っているが、現状その AI から各プロダクトのデータにアクセスできない
- 各プロダクト（GMAC / GCOR / PIPIT / 口コミONE）に AI 連携機能を個別実装する方式は、保守範囲が膨張する
- プロダクト側に AI を内蔵する場合、トークン使用料・モデル更新追随を H2T（および保守ベンダー）側で負担することになる
- 「ロケーション一覧を見たい」「先月の口コミに返信文を考えて欲しい」「月次レポートを作りたい」といったニーズに、AI からプログラマブルに DB を参照・操作する手段が必要
MCP を採用する理由（REST API ではない理由）
| 観点 | REST API | MCP |
|---|---|---|
| ChatGPT Connectors / Claude Desktop / Claude Code との互換性 | 顧客がカスタム API クライアントを作る必要 | 公式 MCP クライアントが既に対応、設定のみで連携可 |
| tool 定義の自動配信 | OpenAPI スキーマを別途用意・配布 | MCP プロトコルが標準化、AI が自動で tool 一覧を取得 |
| 認可フロー | API キー or 自前 OAuth | OAuth 2.1 + PKCE が MCP 仕様で必須化、AI クライアント側が対応 |
| 顧客側の AI 環境のセットアップ | クライアント実装の指示 | MCP URL を貼るだけで接続完了 |
→ 顧客が「自分の AI ツールから H2T プロダクトを使う」という用途に対しては、MCP プロトコル一択。REST API では顧客側のクライアント実装が必要になり、ハードルが高い。
スコープ
対象プロダクト（4 製品）
すべて同一の Laravel コードベース（mappy リポジトリ）から env を切り替えて動いている マルチテナント構成 であることが本番調査で確認されている。
| 製品 | 公開ドメイン | EC2 | Aurora クラスター |
|---|---|---|---|
| GMAC | gmac-g.com | gmac-app-production (18.181.95.36) | gmac-db-production-cluster-1 |
| GCOR | g-cor-m.com | gcor-app-production (43.207.35.103) | gcor-db-production-cluster |
| PIPIT (KingMeo) | king-meo.com | kingmeo-app-production (3.112.192.246) | kingmeo-db-production-cluster |
| 口コミONE | kuchikomione.com | Kuchikomi One (18.183.15.203) | kuchikomi-one-db-production-cluster |
4 製品で DB スキーマが同一であるため、MCP の tool は プロダクト非依存の単一名前空間（例: location.list）で実装可能。リクエストの裏で「認証ユーザー → どのプロダクトの Aurora に接続するか」を自動判定する。
対象外
| 製品 | 対象外の理由 |
|---|---|
| Places API | 別案件として進行中（MEOSCRAPING-14） |
| MEO Times | 今回スコープ外 |
| SmartMEO Listing+ | 今回スコープ外 |
| Sumasapo | 停止中 |
Phase 区切り
リスクと工数を抑えるため、3 段階での段階リリースとする。
| Phase | 範囲 | 想定工数 |
|---|---|---|
| Phase 1（MVP） | GMAC のみ、読取系 4 tool、OAuth 2.1 基盤、Lambda 基盤、API Gateway 構築 | 約 11.5 人日 |
| Phase 2 | GCOR / PIPIT / 口コミONE への横展開、書込系基盤の準備、location.get 追加 | 約 8 人日 |
| Phase 3 | 4 製品の書込系（投稿・口コミ返信・写真等）、レポート用集計データ tool | 約 5 人日 |
Phase 1 を GMAC のみに絞る理由
4 プロダクトは同一 Laravel コードベースで DB スキーマも同一だが、テナンシ判定・user テーブル参照・access_level 制御は MCP 側で組む必要がある。Phase 1 で GMAC を雛形に作っておけば、Phase 2 では「env と DB 接続先の切替設定を追加するだけ」で残り 3 製品をカバーできる。
Phase 1 で実装する tool（4 個）
| # | tool 名 | できること | AI からの典型的な使われ方 |
|---|---|---|---|
| 1 | location.list | 自分の店舗（ロケーション）一覧を取得 | 「うちの店舗一覧見せて」「グループ A の店だけ」 |
| 2 | review.list | 口コミ一覧を取得（期間・評価で絞り込み可） | 「先月の口コミ全部見せて」「☆1〜2 の口コミだけ」 |
| 3 | ranking.list | 検索順位データを取得 | 「『美容室 渋谷』で順位の推移は？」 |
| 4 | insight.summary | アクセス数・電話発信・経路検索などの集計データ | 「先月のアクセス数どうだった？」「電話の件数の前月比は？」 |
location.get を Phase 2 に回した理由
Phase 1 を 5 個 → 4 個に絞った差分は location.get（特定店舗の詳細情報）。location.list で取得できる店舗一覧に基本属性（名前・住所・カテゴリ等）は含まれるため、Phase 1 では大半のユースケースをまかなえる。営業時間・電話番号などの詳細属性が必要になった時点で Phase 2 で追加する。
insight.summary を Phase 1 に残している理由：「先月のレポートを作って」という主要ユースケース（AI がローカル PPTX テンプレートに集計値を流し込んで生成）が、これ抜きでは成立しないため。
想定アーキ概要
コンポーネント構成
| コンポーネント | 役割 | 配置 |
|---|---|---|
| API Gateway HTTP API | MCP プロトコルの HTTP 受付、TLS 終端 | 新規 |
| Lambda Authorizer | OAuth 2.1 トークン検証、scope 確認、認証ユーザー解決 | VPC 外 Lambda（コールドスタート高速化） |
| Lambda MCP Dispatcher | tool ルーティング、入力バリデーション、レスポンス整形、監査記録 | VPC 外 Lambda |
| Lambda Data Fetcher | Aurora への実 SQL クエリ実行、4 プロダクト振り分け | VPC 内 Lambda（Aurora 接続） |
| DynamoDB | OAuth state / refresh token / 認可同意 / 監査ログ / idempotency キャッシュ | 新規（VPC 不要、IAM 経由） |
| RDS Proxy | Lambda → Aurora の接続プーリング | Phase 1 は GMAC 1 本のみ |
| Aurora MySQL | 各プロダクトの DB（既存リソース、変更なし） | 既存 |
4 プロダクトの振り分け方式
- 顧客はログイン時にどのプロダクトのアカウントで認証するかを選ぶ
- access_token に
productクレームが含まれ、以降のリクエストはそのプロダクトの DB に振り分けられる - 1 顧客が複数プロダクトを使う場合、プロダクトごとに別 OAuth クライアントとして登録する
レポート生成の動き方（ローカル PPTX 生成）
MCP サーバー側で PPTX を組み立てることはしない。データ提供のみを行い、PPTX 化はクライアント AI のローカル環境で実行する。
→ MCP サーバーは集計データの取得 tool だけ用意する。テンプレートと組み立てはクライアント側責任。サーバーに python-pptx などのレンダリングライブラリを抱えなくて済む。
想定工数とコスト
工数の試算方式（AI 前提）
工数の考え方
「人日」は人間のレビュー時間 です。実作業（設計書・コード生成）は AI が担当し、人間は AI の成果物のレビュー・指示出しに専念します。
公式: AI リテイク回数 × レビュー時間 (0.5日/回) = 工数 (人日)
例: AI リテイク 3 回 × 0.5日/回 = 1.5 人日（人が 1.5 日分レビューに費やす）
工数内訳（Phase 1 — MVP）
| # | 作業項目 | AIリテイク | レビュー | 工数（人日） | 担当 |
|---|---|---|---|---|---|
| 1 | 設計書 5 本作成（提案書 / アーキ / 認証 / ツール / インフラ） | 各 2〜3 回 | 0.5日/回 | 3.0 | 設計者 |
| 2 | Lambda 基盤実装（Authorizer + Dispatcher + Data Fetcher 雛形） | 3 回 | 0.5日/回 | 1.5 | 製造者 |
| 3 | OAuth 2.1 認証実装（PKCE + refresh rotation + 動的登録） | 4 回 | 0.5日/回 | 2.0 | 製造者 |
| 4 | 読取 tool 4 個実装（1 個目で雛形、残り 3 個は流用） | 計 3 回 | 0.5日/回 | 1.5 | 製造者 |
| 5 | DynamoDB スキーマ + 監査ログ実装 | 2 回 | 0.5日/回 | 1.0 | 製造者 |
| 6 | インフラ構築（API Gateway / IAM / Secrets / RDS Proxy） | 2 回 | 0.5日/回 | 1.0 | 製造者 |
| 7 | 接続テスト（Claude Desktop + ChatGPT Connectors） | 2 回 | 0.5日/回 | 1.0 | 製造者 |
| 8 | デプロイ・動作確認 | 1 回 | 0.5日/回 | 0.5 | 製造者 |
| Phase 1 合計 | 11.5 人日 |
コスト試算（月額、Phase 1）
既存リソースは変更しないため、追加分のみ計上。
| リソース | 月額 | 課金基準 |
|---|---|---|
| API Gateway HTTP API（〜10 万 req/月） | $0.1 | リクエスト数 |
| Lambda 実行（〜10 万 req） | $0.5 | 実行時間 × メモリ |
| DynamoDB on-demand（〜10 万 write/月） | $1.5 | 読み書きユニット + ストレージ |
| CloudWatch Logs（5 GB/月） | $2.0 | ログ取り込み量 + ストレージ |
| Secrets Manager（5 secret × $0.40） | $2.0 | シークレット数 |
| Route 53 / データ転送 | $2.0 | hosted zone + アウトバウンド通信 |
| Phase 1 合計 | 約 $8 USD/月 |
Phase 1 では RDS Proxy を導入しない
Lambda の reserved concurrency = 10〜20 に絞ることで Aurora 接続数を制御し、RDS Proxy（本番調査結果より $25.92/月）を省く。Phase 1 は GMAC 1 クラスターのみ・顧客数も少ない時期なので、これで十分。利用が増えてきて接続数が問題になりそうな段階で後から Proxy を追加できる（コード側変更は接続先 endpoint の切替のみ）。
現在のコストはゼロ
上記の試算は MCP 実装後に追加発生するコスト であり、未実装の現時点では追加コスト $0。既存の EC2 / Aurora 等の料金は MCP とは関係なく従来通り発生している。
リクエスト数別のコスト試算
リクエスト数が増えれば、API Gateway / Lambda / DynamoDB / CloudWatch Logs はそれに比例して料金が上がる。一方、Secrets Manager / Route 53 はリクエスト数と無関係の固定費。
| 月間リクエスト数 | API GW | Lambda | DynamoDB | CW Logs | 固定費 | 合計/月 | 想定ユースケース |
|---|---|---|---|---|---|---|---|
| 1 万 | $0.01 | $0.05 | $0.15 | $1 | $4 | 約 $5 | Phase 1 α 公開、20〜30 顧客 |
| 10 万 | $0.1 | $0.5 | $1.5 | $2 | $4 | 約 $8 | Phase 1 標準（本提案の基準） |
| 100 万 | $1 | $5 | $15 | $5 | $4 | 約 $30 | Phase 2、4 製品 × 数百顧客の日常利用 |
| 1000 万 | $10 | $50 | $150 | $20 | $7 | 約 $237 | 大規模化、要モニタリング |
リクエスト数の感覚値
顧客 1 人が 1 日 5〜10 回 MCP 呼び出し（店舗一覧確認・口コミチェック・順位確認等）と仮定すると、1 ユーザー = 月 150〜300 req。
- Phase 1（GMAC のみ、α 公開 50 ユーザー）→ 約 1〜2 万 req/月 → $5〜8/月
- Phase 2（4 製品 × 100 ユーザーずつ）→ 約 6〜12 万 req/月 → $8〜15/月
レポート生成・口コミ一括返信のような重い操作を多用すると、1 ユーザーあたり数倍に増える可能性がある。
データ通信料の影響はほぼ無視できる
本案件で発生する通信のうち課金対象は「Lambda → 顧客 AI への JSON レスポンス送信」のみで、10 万 req × 5KB = 500MB ≒ $0.045/月。同一 VPC 内（Lambda ↔ Aurora）と AWS インバウンド（顧客 AI → API Gateway）は無料。データ通信料はリクエスト数増の主因ではない。
Phase 2 / 3 の工数（概算）
| Phase | 主な作業 | 想定工数 |
|---|---|---|
| Phase 2 | GCOR/PIPIT/口コミONE 横展開、書込安全装置基盤、location.get 追加、書込 tool 5〜7 個 | 約 8 人日 |
| Phase 3 | 4 製品書込系完備、レポート用集計 tool 追加、AI ローカル PPTX 連携テスト | 約 5 人日 |
関連設計書
詳細設計は以下に分割する（すべて新規作成、既存設計書は参照しない）。
| ドキュメント | パス | 内容 |
|---|---|---|
| アーキ全体像 | /design/mcp-architecture-v2 | 構成図・コンポーネント責務・リクエストフロー・4 プロダクト振り分け方式 |
| 認証・テナンシ設計 | /design/mcp-auth-v2 | OAuth 2.1 フロー・scope 設計・ユーザー基盤統合・テナンシ判定 |
| ツール一覧 | /design/mcp-tools-v2 | Phase 1 の 4 tool 詳細スキーマ |
| インフラ・実装計画 | /infrastructure/mcp-infra-v2 | AWS リソース構成・デプロイ手順・実装タスク・検収条件 |
前提条件・制約
- 既存設計書（mcp-server.md / mcp-server-overview.md ほか 7 本）は参照しない。アーキ・構成・テーブル設計・命名はすべて本提案でゼロから定義する
- AWS リソースは既存運用パターンに完全準拠：Lambda zip パッケージ、CloudWatch Logs、IAM ロール命名（既存
Lambda_scraper等に倣う） - 4 プロダクトは同一 Laravel コードベース、DB スキーマ同一、users テーブル構造同一（要 Phase 1 開始前検証）
- PPTX / レポート生成はクライアント AI のローカル環境で実施、MCP サーバーには持たない
- 書込系は Phase 2 以降、Phase 1 は読取専用
- 工数は AI 前提（設計書・コード生成は AI、人間はレビューのみ）
未確定事項（設計レビュー or 追加調査で決定）
| # | 項目 | 状態 |
|---|---|---|
| 1 | Cognito User Pool の本番有無 | dev.user 権限不足で未確認、etj.admin での確認待ち。仮になければ自前実装で進める |
| 2 | 既存 API Gateway の有無 | 同上 |
| 3 | EventBridge / Step Functions の活用余地 | 同上、Phase 1 では使わない方針なので判断保留可 |
| 4 | 4 製品の mappy_users テーブル構造の差異 | ✅ GMAC で本番調査完了（30 カラム、user_type / parent_user_id / is_enabled / search_ranking_enabled / 各種 access_level 等を確認）。4 製品同一 Laravel コードベース前提のため同一スキーマと判断、Phase 2 横展開時に抜き打ち確認 |
| 5 | レポート用集計 tool の具体仕様 | Phase 3 の設計時に確定、ユーザーがどんなレポートを AI 経由で作りたいかのユースケース整理が前提 |
| 6 | 公式 MCP クライアントの動的クライアント登録互換性 | Phase 1 製造前に接続検証で確定 |
| 7 | レート制限の閾値 | Phase 1 リリース後の運用フィードバックで調整 |
| 8 | 監査ログの保持期間 | CloudWatch Logs デフォルト 30 日でスタート、必要に応じ延長 |
リスクと対策
| # | リスク | 対策 |
|---|---|---|
| 1 | MCP プロトコルの仕様変更 | 公式 MCP SDK を採用、CI で互換性テスト、リリース後も最新版に追随 |
| 2 | OAuth 2.1 の実装ミス | ペネトレーションテストを Phase 1 リリース前に実施、refresh rotation の動作確認を検収項目に含める |
| 3 | AI 経由の意図しない書込（Phase 2+） | dry_run / confirm_token / idempotency_key を書込 tool 必須化、Phase 2 設計で詳細化 |
| 4 | 各プロダクトのテーブル差異 | Phase 1 開始前に 4 製品の主要テーブル（users / locations / reviews 等）を実 DB で確認、差異があれば Phase 2 で吸収層を設ける |
| 5 | env に AWS access key 平文コミット（既存問題） | MCP 案件とは別タスクで対応、MCP Lambda は IAM ロールベースの認証のみ使用 |