Mappy MCP サーバー新設
概要
| 項目 | 内容 |
|---|---|
| ステータス | 🔵 提案中 |
| Issue | #13 |
| GitLab Issue | Mappy #58 |
| 担当 | - |
| 想定工数（MVP） | 24.0人日 |
| 想定工数（全Phase） | 約44.0人日 |
| 実装スタック | Python (FastMCP) を推奨／TypeScript (公式SDK) も併記 |
業務改善系の追加機能を Mappy に直接 AI 統合する方針を転換し、MCP (Model Context Protocol) サーバー を新設する。顧客が自身の AI エージェント（Claude Desktop / Claude Code / ChatGPT Pro 等）から Mappy のデータ・操作にアクセスできるようにすることで、Mappy 側は「データと操作のインターフェース」に専念し、LLM 運用コストを抱えない構成へ移行する。
提案内容
背景・課題
- 個別実装の限界: AI 連携機能（#5 口コミ AI、#6 流入キーワード AI、#7 グループ分析、#8 #9 レポート AI など）を 1 案件ずつ個別実装する方式では、Mappy 本体が AI 機能を抱え続けることになり、保守範囲が膨張する
- LLM 運用コスト: Mappy 側で AI を動かす場合、トークン使用料・モデル更新追随・プロンプト保守をすべて自社負担となる
- 拡張性の問題: 顧客ごとに異なる分析ニーズに個別対応する形では、機能要望のたびに開発リソースが必要
- 顧客の AI 契約活用不可: 顧客が既に ChatGPT Pro / Claude Pro 等を契約していても、Mappy はその能力を活用できない
提案するソリューション
顧客の AI エージェント（クライアント）から Mappy の機能・データを呼び出せる MCP サーバーを新設する。
主な特徴：
- Streamable HTTP + OAuth 2.1 でリモート接続対応
- Claude Desktop / Claude Code / ChatGPT Connectors の主要 MCP クライアント全対応
- Mappy の全ドメイン（ロケーション・投稿・口コミ・順位・インサイト等）を網羅的に MCP tool として提供
- 顧客側で AI を持ち込めるため、Mappy 側で LLM 運用コストを負わない
- 既存案件 #5・#6 は MCP に完全吸収可能、独立案件としては縮退検討
切り分け方針（MCP vs API）
| 対象機能 | 方式 | 理由 |
|---|---|---|
| 業務改善系（B2B 契約店舗が利用） | MCP サーバー | 利用者が特定、認証・課金が明確 |
| オープン/BtoC AI 機能（口コミ自動返信等） | API | Web トリガー前提、不特定多数で MCP 公開はリスク |
想定スコープ（網羅対象ドメイン）
MCP サーバーで提供する tool の対象ドメインは以下の通り。詳細仕様は別途 ツールカタログ で定義する。
| ドメイン | 主な操作 |
|---|---|
| ロケーション | 一覧・取得・属性更新 |
| グループ | 一覧・店舗紐付け・グループ別操作 |
| メニュー / サービス | 取得・更新 |
| 商品（GBP products） | 取得・一括反映（新規実装） |
| 投稿 | 一覧・作成・予約 |
| メディア（写真） | 一覧・アップロード・削除 |
| 口コミ | 一覧・返信・テンプレート管理 |
| 返信テンプレート | CRUD |
| インサイト | 取得・集計 |
| 検索順位 | 取得・期間絞り込み |
| 流入キーワード | 取得・分析データ提供 |
| レポート | 生成リクエスト・ダウンロード |
| アンケート | 一覧・回答取得 |
| CTA / SMS | 一覧・送信ログ取得 |
| SNS 連携 | 設定取得・フィード取得 |
| 通知 | 一覧取得 |
機能一覧（フェーズ分け）
3 段階での段階的リリースを想定する。
| Phase | 名称 | 範囲 | 主な tool | 想定工数 |
|---|---|---|---|---|
| Phase 1（MVP） | 認証 + 読取系 | OAuth 2.1 基盤、読取系 5 tool、監査ログ | location.list / location.get / review.list / ranking.list / insight.summary | 24.0 日 |
| Phase 2 | 書込系拡張 | 投稿・口コミ返信・メディア、dry_run、idempotency、batchId ポーリング | post.create / review.reply / media.upload / location.update など | 11.5 日 |
| Phase 3 | レポート・分析 | レポート生成・分析データ提供・AI レポート機能との統合 | report.create / report.get / keyword.analyze / group.compare | 8.5 日 |
Phase 1 のスコープ判断
MVP は 「顧客 AI から Mappy の状態を読み取れる」 ことを最小目標とし、書込系は Phase 2 に分離。書込系には dry_run・確認トークン・idempotency key 等の安全装置が必須となるため、まず読取系で認証・監査・運用フローを確立する。
アーキテクチャ概要
全体構成図
責務分担:
| コンポーネント | 役割 |
|---|---|
| 顧客 AI | tool 呼び出し・結果の解釈・ユーザーへの応答 |
| MCP Server | tool 定義の公開、認証検証、Laravel API への中継、監査記録 |
| OAuth 2.1 認可サーバー | クライアント認証、scope 検証、トークン発行 |
| Laravel API | 既存ビジネスロジックの提供（MCP 用エンドポイントを追加） |
| Mappy DB | データ実体 |
| GBP API | Google Business Profile への中継 |
| 監査ログ DB | MCP 経由の全操作を記録（書込・読取・認可失敗を含む） |
実装スタック候補（両案併記）
決定タイミング
設計フェーズは両案併記で進める。実装スタックの最終確定は**製造フェーズ着手前（Issue 起票直前）**でよい。アーキ設計・ツールカタログ・認証・DB 設計はいずれも言語非依存。
案A：Python (FastMCP) — 推奨
| 項目 | 内容 |
|---|---|
| MCP 実装 | FastMCP (Python 3.10+) |
| HTTP サーバー | Starlette / Uvicorn (ASGI) |
| OAuth 2.1 | Authlib または独自実装 |
| ORM | SQLAlchemy または Laravel API 経由（DB 直参照しない） |
| デプロイ | コンテナ（Docker）、ECS Fargate or EC2 |
推奨理由:
- 既存 AI レポート機能（#9）が Python (FastAPI + Jinja2 + LangChain) で設計済み — 同居・共通基盤の流用が可能
- スクレイピング系コンポーネントが Python — 社内スキル蓄積を活かせる
- 将来的に MCP 内で PPTX 生成等の選択肢を残せる（python-pptx 等）
- FastMCP は型ヒントから自動で tool 定義を生成、Pydantic ベースで I/O バリデーションが容易
案B：TypeScript (公式 SDK)
| 項目 | 内容 |
|---|---|
| MCP 実装 | @modelcontextprotocol/sdk |
| HTTP サーバー | Express / Hono / Fastify |
| OAuth 2.1 | oauth4webapi など |
| ORM | Prisma または Laravel API 経由 |
| デプロイ | Node.js コンテナ |
採用検討理由:
- Mappy フロント（Vue + TS）開発者がそのままサーバー実装できる
@modelcontextprotocol/sdkは公式 SDK で長期サポート見込み- TypeScript の型システムにより JSON Schema との整合性確保が強い
- Laradock 内に Node.js コンテナが既存
認証方式
既存 Mappy 認証は MCP に流用不可
DB 確認の結果、Mappy には Laravel Passport が導入されていない（composer.json に依存はあるが oauth_* テーブル未作成）。Sanctum も未導入。実運用は Web セッション認証のみ。 MCP の OAuth 2.1 認可サーバーは完全新設となる。
- プロトコル: OAuth 2.1（PKCE 必須、Implicit Flow 廃止）
- トランスポート: Streamable HTTP
- 対応クライアント: ChatGPT Connectors / Claude Desktop / Claude Code
- scope 設計: Mappy 既存の
*_access_levelカラム群と 1:1 マッピング（詳細は 認証・テナンシ設計）
既存 Mappy との接続
- Laravel API 経由（推奨）: MCP サーバー → Laravel API → Mappy DB / GBP API の構成
- 既存ビジネスロジック・バリデーション・権限チェックを再利用
- MCP 専用の API エンドポイントを Laravel に追加
- DB 直参照は禁止: テナンシ判定・権限制御の重複実装を避ける
接続イメージ
Claude Desktop からの利用例
利用者は Claude Desktop の MCP 設定ファイルに以下を追加するだけで、Mappy が AI のツールとして使えるようになる。
json
{
"mcpServers": {
"mappy": {
"url": "https://mcp.mappy.example.com/sse",
"transport": "streamable-http",
"auth": {
"type": "oauth2",
"authorization_url": "https://mcp.mappy.example.com/oauth/authorize",
"token_url": "https://mcp.mappy.example.com/oauth/token"
}
}
}
}利用シーン例:
ユーザー: 「先月の渋谷店の検索順位の推移を教えて」
Claude: （MCP のranking.listtool を自動呼び出し → データ取得 → 自然言語で要約）
「渋谷店の先月の検索順位は平均 3.2 位で、前月比 1.5 位上昇しています。特に『美容室 渋谷』のキーワードで…」
ChatGPT Connectors からの利用例
ChatGPT 設定画面の「Connectors」に Mappy の MCP URL を追加し、OAuth 認証を完了させれば利用可能になる。
1. ChatGPT 設定 → Connectors → 「Add custom connector」
2. URL: https://mcp.mappy.example.com/sse
3. OAuth 認証画面で Mappy アカウントにログイン → スコープ承認
4. ChatGPT の会話中で「Mappy で先月の口コミを見せて」のように利用テナンシ・スコープ設計（概要）
詳細は 認証・テナンシ設計 を参照。
権限階層
admins.is_supervisor = 1（神権限）
└─ 全 mappy_users 代理可能（要厳格制限）
admins.is_supervisor = 0（一般 admin）
└─ 担当ユーザーのみ（preview_user_id Cookie 範囲）
mappy_users.user_type = 1（MAIN_USER）
└─ 自分 + parent_user_id 配下を操作
mappy_users.user_type = 3（MASTER_USER）
└─ parent_user_id 配下全部
mappy_users.user_type = 2（GROUP_USER）
└─ 自分のみscope と Mappy 権限カラムのマッピング
| MCP scope 例 | Mappy 側の権限カラム |
|---|---|
mappy:ranking:read | mappy_users.search_ranking_enabled = 1 |
mappy:ranking:write | mappy_users.search_ranking_access_level >= 2 |
mappy:gbp:write | mappy_users.gbp_connection_settings_access_level >= 2 |
mappy:antitamper:read | mappy_users.anti_tamper_screen_access_level >= 1 |
mappy:smartmeo:* | mappy_users.is_smart_meo = 1 |
mappy:kuchikomi:settings | mappy_users.show_kuchikomi_settings_link = 1 |
店舗境界の判定
- 通常ユーザー:
mappy_user_available_gbp_locationsに紐付く店舗のみ - グループ単位:
mappy_groups+mappy_group_location（単数形）で絞り込み - Admin 代理:
preview_user_idCookie の対象ユーザーで上記を絞り込み
既存案件との関係
MCP サーバー化により、既存案件のうち AI 連携部分は MCP に統合できる。 ただし画面・UI・既存機能改修部分は MCP と独立して必要。
| 案件 | MCP との関係 | 影響 |
|---|---|---|
| #2 レポート権限開放 | 独立 | 画面の権限制御 UI は MCP と無関係。スコープ設計を共有 |
| #3 写真の一括投稿・削除 | 部分統合 | 画面の確認ポップアップ・一括削除 UI は別。一括投稿 API は MCP tool 化可 |
| #5 口コミ AI 分析 | 完全統合 | 本案件は MCP で代替可能、独立案件としては縮退検討 |
| #6 流入キーワード AI 分析 | 完全統合 | 本案件は MCP で代替可能、独立案件としては縮退検討 |
| #7 グループ分析 | 部分統合 | データ取得 IF は MCP tool 化、画面・CSV ダウンロードは別 |
| #8 レポートインサイト追加 | 独立 | レポート本体改修。MCP と関係ない |
| #9 レポート AI アドバイス | 部分統合 | AI 生成部分のみ MCP で代替可、HTML テンプレート・画面フローは別 |
縮退検討の対象
#5・#6 は MCP に完全吸収可能なため、MCP 採用が決まれば独立案件として実装する必要はない。 #3・#7・#9 は MCP と並行で進行するため、機能設計フェーズで重複しない切り分けを確定する必要がある。
概算工数（AI前提）
体制
| 役割 | 人数 | 担当内容 |
|---|---|---|
| 設計者 | 1名 | 要件確認 → AI に設計書作成指示 → レビュー → 製造へ指示 |
| 製造者 | 1名 | ISSUE を元に AI に作成指示 → コードレビュー → テスト実施 → デプロイ |
工数内訳（Phase 1 — MVP）
工数の考え方
「人日」は人間のレビュー時間 です。実作業（設計書・コード生成）は AI が担当し、人間は AI の成果物のレビュー・指示出しに専念します。
公式: AI リテイク回数 × レビュー時間 (0.5日/回) = 工数 (人日)
例: AIリテイク 3回 × 0.5日/回 = 1.5 人日（人が 1.5 日分レビューに費やす）
| # | 作業項目 | AIリテイク | レビュー | 工数（人日） | 担当 |
|---|---|---|---|---|---|
| 1 | 要件確認・全体設計書作成 | 4回 | 0.5日/回 | 2.0 | 設計者 |
| 2 | アーキテクチャ設計（スタック確定） | 3回 | 0.5日/回 | 1.5 | 設計者 |
| 3 | OAuth 2.1 認証設計 | 3回 | 0.5日/回 | 1.5 | 設計者 |
| 4 | ツールカタログ設計（MVP範囲） | 3回 | 0.5日/回 | 1.5 | 設計者 |
| 5 | 監査ログ・DB 設計 | 2回 | 0.5日/回 | 1.0 | 設計者 |
| 6 | インフラ設計 | 2回 | 0.5日/回 | 1.0 | 設計者 |
| 7 | MCP サーバー基盤実装 | 5回 | 0.5日/回 | 2.5 | 製造者 |
| 8 | OAuth 2.1 認証実装 | 6回 | 0.5日/回 | 3.0 | 製造者 |
| 9 | 読取系 Tool 実装（5個） | 6回 | 0.5日/回 | 3.0 | 製造者 |
| 10 | 監査ログ実装 | 3回 | 0.5日/回 | 1.5 | 製造者 |
| 11 | インフラ構築（AWS/コンテナ） | 3回 | 0.5日/回 | 1.5 | 製造者 |
| 12 | 接続テスト（Claude Desktop / ChatGPT） | 3回 | 0.5日/回 | 1.5 | 製造者 |
| 13 | 結合テスト・品質調整 | 3回 | 0.5日/回 | 1.5 | 製造者 |
| 14 | 運用マニュアル作成 | 2回 | 0.5日/回 | 1.0 | 設計者 |
| 15 | デプロイ・動作確認 | 2回 | 0.5日/回 | 1.0 | 製造者 |
| Phase 1 合計 | 24.0 |
工数内訳（Phase 2 — 書込系拡張、概算）
| # | 作業項目 | AIリテイク | レビュー | 工数（人日） |
|---|---|---|---|---|
| 1 | 書込安全装置設計（dry_run / idempotency / 確認トークン） | 3回 | 0.5日/回 | 1.5 |
| 2 | 書込系 Tool 実装（5〜7 個） | 6回 | 0.5日/回 | 3.0 |
| 3 | dry_run / idempotency 実装 | 3回 | 0.5日/回 | 1.5 |
| 4 | 確認トークン実装 | 2回 | 0.5日/回 | 1.0 |
| 5 | batchId + ポーリング統合（既存 Jobs キュー連携） | 3回 | 0.5日/回 | 1.5 |
| 6 | レート制限 | 2回 | 0.5日/回 | 1.0 |
| 7 | テスト | 3回 | 0.5日/回 | 1.5 |
| 8 | デプロイ | 1回 | 0.5日/回 | 0.5 |
| Phase 2 合計 | 11.5 |
工数内訳（Phase 3 — レポート・分析、概算）
| # | 作業項目 | AIリテイク | レビュー | 工数（人日） |
|---|---|---|---|---|
| 1 | レポート tool 設計 | 3回 | 0.5日/回 | 1.5 |
| 2 | レポート tool 実装 | 4回 | 0.5日/回 | 2.0 |
| 3 | 分析系 tool 実装（順位・キーワード・グループ） | 4回 | 0.5日/回 | 2.0 |
| 4 | AI レポート機能（#9）との統合 | 3回 | 0.5日/回 | 1.5 |
| 5 | テスト | 2回 | 0.5日/回 | 1.0 |
| 6 | デプロイ | 1回 | 0.5日/回 | 0.5 |
| Phase 3 合計 | 8.5 |
前提条件・制約
- OAuth 2.1 認証基盤は新規構築: 既存 Passport は未稼働のため流用不可
- Laravel API への MCP 用エンドポイント追加: 既存ロジックを呼び出す薄い層を Laravel 側に作る
- DB 直参照は禁止: 全データアクセスは Laravel API 経由
- 顧客側 AI ツール契約は顧客負担: ChatGPT Pro / Claude Pro 等は顧客が用意
- MCP の最新仕様への追随: Streamable HTTP、OAuth 2.1、tool schema 仕様は進化中のため、リリース後も継続的な追随が必要
- DB 直接操作は厳禁、SELECT 系 SQL は都度提示してユーザーが実行（運用ルール）
スケジュール（Phase 1 — MVP）
| タスク | 担当 | 日数 | 6/2 | 6/3 | 6/4 | 6/5 | 6/6 | 6/7 | 6/8 | 6/9 | 6/10 | 6/11 | 6/12 | 6/13 | 6/14 | 6/15 | 6/16 | 6/17 | 6/18 | 6/19 | 6/20 | 6/21 | 6/22 | 6/23 | 6/24 | 6/25 | 6/26 | 6/27 | 6/28 | 6/29 |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 火 | 水 | 木 | 金 | 土 | 日 | 月 | 火 | 水 | 木 | 金 | 土 | 日 | 月 | 火 | 水 | 木 | 金 | 土 | 日 | 月 | 火 | 水 | 木 | 金 | 土 | 日 | 月 | |||
| 要件確認・全体設計書作成 | 設計者 | 2d | ||||||||||||||||||||||||||||
| アーキテクチャ設計 | 設計者 | 1.5d | ||||||||||||||||||||||||||||
| OAuth 2.1 認証設計 | 設計者 | 1.5d | ||||||||||||||||||||||||||||
| ツールカタログ設計 | 設計者 | 1.5d | ||||||||||||||||||||||||||||
| 監査ログ・DB 設計 | 設計者 | 1d | ||||||||||||||||||||||||||||
| インフラ設計 | 設計者 | 1d | ||||||||||||||||||||||||||||
| MCP サーバー基盤実装 | 製造者 | 2.5d | ||||||||||||||||||||||||||||
| OAuth 2.1 認証実装 | 製造者 | 3d | ||||||||||||||||||||||||||||
| 読取系 Tool 実装 | 製造者 | 3d | ||||||||||||||||||||||||||||
| 監査ログ実装 | 製造者 | 1.5d | ||||||||||||||||||||||||||||
| インフラ構築 | 製造者 | 1.5d | ||||||||||||||||||||||||||||
| 接続テスト | 製造者 | 1.5d | ||||||||||||||||||||||||||||
| 結合テスト | 製造者 | 1.5d | ||||||||||||||||||||||||||||
| 運用マニュアル作成 | 設計者 | 1d | ||||||||||||||||||||||||||||
| デプロイ・動作確認 | 製造者 | 1d |
Phase 2 / Phase 3 のスケジュール
Phase 2・3 は Phase 1 のリリース後、運用フィードバックを反映してから着手するため、本提案書ではスケジュールを確定しない。Phase 1 完了時点で改めて見積もり・スケジュールを策定する。
関連ドキュメント
設計の詳細は以下を参照：
- 機能設計: /design/mcp-server-overview
- ツールカタログ: /design/mcp-tools-catalog
- 認証・テナンシ設計: /design/mcp-auth-tenancy
- 書込安全装置: /design/mcp-write-safety
- DB 設計（監査ログ）: /data/mcp-audit-logs
- DB 設計（OAuth クライアント）: /data/mcp-oauth-clients
- インフラ設計: /infrastructure/mcp-hosting
- Issue 詳細: /issues/mcp-server