#13 Mappy MCP サーバー新設
概要
| 項目 | 内容 |
|---|---|
| 課題ID | ISS-013 |
| 課題名 | MCP サーバーを新設し、顧客 AI から Mappy を操作可能にする |
| カテゴリ | 機能拡張・AI 統合・認証基盤 |
| 優先度 | 高 |
| ステータス | 🔵 提案中 |
| GitLab Issue | Mappy #58 |
| 関連案件 | #13 MCP サーバー新設 |
| 親設計 | 機能設計（全体像） |
現状の課題
- 業務改善系 AI 機能（#5 口コミ AI 分析、#6 流入キーワード AI、#7 グループ分析、#8 #9 レポート AI 等）を個別実装すると保守範囲が膨張する
- Mappy 側で LLM 運用コスト（トークン使用料・モデル更新追随・プロンプト保守）を抱える設計は持続性が低い
- 顧客が既に契約している ChatGPT Pro / Claude Pro 等の AI 能力を Mappy が活用できない
- 新規 AI 連携要望のたびに開発リソースが必要
解決アプローチ
業務改善系を MCP（Model Context Protocol）サーバー化し、顧客 AI から Mappy を操作可能にする。
- Mappy は「データと操作のインターフェース」に専念
- LLM 運用は顧客側 AI（Claude Desktop / Claude Code / ChatGPT Pro）に委譲
- AI 機能の追加 = MCP tool の追加で実現
- 既存案件 #5・#6 は MCP に完全吸収可能
詳細は 案件提案書 を参照。
要件
機能要件
| No | 要件 | 詳細 |
|---|---|---|
| 1 | MCP プロトコル準拠 | Streamable HTTP トランスポート、tools/call、tools/list |
| 2 | OAuth 2.1 認証基盤 | PKCE 必須、認可コード + リフレッシュトークン、動的クライアント登録 |
| 3 | 主要 MCP クライアント対応 | Claude Desktop / Claude Code / ChatGPT Connectors |
| 4 | テナンシ制御 | mappy_users 階層 × *_access_level × mappy_user_available_gbp_locations |
| 5 | scope 設計 | mappy:<domain>:<action> 体系、Mappy 既存権限と 1:1 マッピング |
| 6 | 読取系 tool（Phase 1） | location / review / ranking / insight / keyword 等 5 tool 以上 |
| 7 | 書込系 tool（Phase 2） | post / review.reply / media / location.update |
| 8 | 書込安全装置（Phase 2） | dry_run / idempotency_key / confirm_token / batch.status |
| 9 | レポート tool（Phase 3） | report.create / report.get、AI レポート機能と統合 |
| 10 | 監査ログ | 全 tool 呼び出し・OAuth イベント・拒否・dry_run を記録 |
| 11 | レート制限 | アクセストークン / クライアント / ユーザー / idempotency 単位 |
非機能要件
| No | 要件 | 詳細 |
|---|---|---|
| 1 | 可用性 | ECS Fargate 複数タスク、ALB ヘルスチェック |
| 2 | スケーラビリティ | Auto Scaling（CPU + リクエスト数） |
| 3 | レスポンス時間 | 読取系 p95 < 1 秒、書込同期 p95 < 3 秒 |
| 4 | セキュリティ | OAuth 2.1 ベストプラクティス準拠、PKCE 必須、refresh_token rotation、family_id 監視 |
| 5 | 監査可能性 | 全イベントを mappy_mcp_audit_logs に記録、1 年保持 |
| 6 | データ保護 | トークン・パスワード・PII はログに残さない |
| 7 | 既存システムへの影響最小化 | DB 直参照禁止、Laravel API 経由のみ |
フェーズ構成
| Phase | 名称 | 工数 | 主成果物 |
|---|---|---|---|
| Phase 1（MVP） | 認証 + 読取系 | 24.0 人日 | OAuth 2.1 基盤、読取系 5 tool、監査ログ |
| Phase 2 | 書込系拡張 | 11.5 人日 | 投稿・口コミ返信・メディア、dry_run、idempotency |
| Phase 3 | レポート・分析 | 8.5 人日 | レポート tool、グループ分析、AI レポート機能との統合 |
| 合計 | 44.0 人日 |
Phase 1 詳細タスク
設計フェーズ
| No | タスク | 担当 | 工数 | 完了条件 |
|---|---|---|---|---|
| 1.1 | 要件確認・全体設計書作成 | 設計者 | 2.0 | 全体像設計書 完成、レビュー OK |
| 1.2 | アーキテクチャ設計（スタック確定） | 設計者 | 1.5 | Python / TypeScript の最終確定 |
| 1.3 | OAuth 2.1 認証設計 | 設計者 | 1.5 | 認証・テナンシ設計 完成 |
| 1.4 | ツールカタログ設計（MVP 範囲） | 設計者 | 1.5 | ツールカタログ の Phase 1 部分完成 |
| 1.5 | 監査ログ・DB 設計 | 設計者 | 1.0 | DB（監査ログ） + DB（OAuth） 完成 |
| 1.6 | インフラ設計 | 設計者 | 1.0 | インフラ設計 完成 |
| 設計小計 | 8.5 |
製造フェーズ
| No | タスク | 担当 | 工数 | 完了条件 |
|---|---|---|---|---|
| 1.7 | MCP サーバー基盤実装 | 製造者 | 2.5 | Streamable HTTP 接続、tools/list 応答、ヘルスチェック |
| 1.8 | OAuth 2.1 認証実装 | 製造者 | 3.0 | 認可コード + PKCE フロー、refresh rotation、動的登録、/.well-known/oauth-authorization-server |
| 1.9 | 読取系 Tool 実装（5 個） | 製造者 | 3.0 | location.list / location.get / review.list / ranking.list / insight.summary 動作 |
| 1.10 | 監査ログ実装 | 製造者 | 1.5 | 全 tool 呼び出し・OAuth イベントを mappy_mcp_audit_logs に記録 |
| 1.11 | インフラ構築（AWS/コンテナ） | 製造者 | 1.5 | ECS / ALB / Redis / Secrets Manager 設定完了 |
| 1.12 | 接続テスト（Claude Desktop / ChatGPT） | 製造者 | 1.5 | 両クライアントから tool 呼び出し成功 |
| 1.13 | 結合テスト・品質調整 | 製造者 | 1.5 | 認可拒否・テナンシ違反・レート制限の各シナリオ動作確認 |
| 1.14 | 運用マニュアル作成 | 設計者 | 1.0 | 障害対応・トークン失効・新規クライアント追加手順 |
| 1.15 | デプロイ・動作確認 | 製造者 | 1.0 | ステージング→本番、動作確認 |
| 製造小計 | 15.5 |
Phase 1 合計: 24.0 人日
Phase 2 詳細タスク（概要）
| No | タスク | 工数 |
|---|---|---|
| 2.1 | 書込安全装置設計（書込安全装置） | 1.5 |
| 2.2 | 書込系 Tool 実装（post.create / review.reply / media.upload 等 5〜7 個） | 3.0 |
| 2.3 | dry_run / idempotency 実装 | 1.5 |
| 2.4 | 確認トークン実装 | 1.0 |
| 2.5 | batchId + ポーリング統合（既存 jobs テーブル連携） | 1.5 |
| 2.6 | レート制限 | 1.0 |
| 2.7 | テスト | 1.5 |
| 2.8 | デプロイ | 0.5 |
| Phase 2 合計 | 11.5 |
Phase 3 詳細タスク（概要）
| No | タスク | 工数 |
|---|---|---|
| 3.1 | レポート tool 設計 | 1.5 |
| 3.2 | レポート tool 実装（report.create / report.get） | 2.0 |
| 3.3 | 分析系 tool 実装（keyword / group.compare 等） | 2.0 |
| 3.4 | AI レポート機能（#9）との統合 | 1.5 |
| 3.5 | テスト | 1.0 |
| 3.6 | デプロイ | 0.5 |
| Phase 3 合計 | 8.5 |
検収条件（Phase 1）
機能検収
- [ ] Claude Desktop に MCP サーバー追加 → ログイン → tool 一覧取得成功
- [ ] ChatGPT Connectors からの接続 → OAuth 認証 → tool 呼び出し成功
- [ ] 5 つの読取系 tool が仕様通りの入出力で動作
- [ ] scope 不足リクエストが 403 (FORBIDDEN_SCOPE) を返す
- [ ] テナンシ外のリソース要求が 403 (FORBIDDEN_LOCATION/USER) を返す
- [ ] レート制限超過が 429 を返す
- [ ] refresh_token rotation が機能（再使用検出で family 全失効）
- [ ] アクセストークン失効後の呼び出しが 401 を返す
- [ ] 全 tool 呼び出しが
mappy_mcp_audit_logsに記録される
非機能検収
- [ ] 読取系 tool p95 レスポンス時間 < 1 秒
- [ ] ECS タスク 1 台落としても全機能継続動作
- [ ] CloudWatch アラーム発火・Slack 通知
- [ ] ステージング → 本番のデプロイがゼロダウンタイム
ドキュメント検収
依存関係
前提タスク（Phase 1 着手前）
- [ ] 実装スタック確定（Python / TypeScript）
- [ ] MCP 用ドメイン確定（
mcp.mappy.example.com等） - [ ] AWS リソース申請（Redis ElastiCache、ACM 証明書）
- [ ] 公式 MCP クライアント（Claude / ChatGPT）の redirect_uri 確認
Phase 1 完了後の前提（Phase 2 着手）
- [ ] Phase 1 の本番運用 2 週間（安定性確認）
- [ ] 顧客 AI 経由のアクセスログから tool 利用傾向把握
- [ ] 書込系の優先 tool 確定（顧客要望ヒアリング）
Phase 2 完了後の前提（Phase 3 着手）
- [ ] #9 レポート AI アドバイス の AI レポート機能（Python FastAPI + LangChain）が稼働
関連案件・統合方針
| 関連案件 | MCP との関係 |
|---|---|
| #2 レポート権限開放 | 独立。MCP scope と権限カラムを共有 |
| #3 写真の一括投稿・削除 | 部分統合。MCP の media.upload / post.create で API 提供 |
| #5 口コミ AI 分析 | 完全統合。Mappy 側 AI 実装は不要、MCP で代替 |
| #6 流入キーワード AI 分析 | 完全統合。同上 |
| #7 グループ分析 | 部分統合。MCP の group.compare で API 提供 |
| #8 レポートインサイト追加 | 独立。レポート本体改修 |
| #9 レポート AI アドバイス | 部分統合。MCP の report.create から呼び出し可 |
リスク・課題
| # | リスク | 影響 | 対策 |
|---|---|---|---|
| 1 | MCP 仕様の変更 | プロトコル互換性 | 公式 SDK / FastMCP の最新版追随、CI で互換性テスト |
| 2 | OAuth 2.1 実装の脆弱性 | セキュリティ事故 | 専門ライブラリ採用、ペネトレーションテスト |
| 3 | 顧客 AI 側の暴走（誤実行・大量呼び出し） | データ破壊・コスト膨張 | dry_run / confirm_token / レート制限の徹底 |
| 4 | refresh_token 盗難 | アカウント乗っ取り | family_id 監視、token reuse 検出時の即時失効 |
| 5 | GBP API クォータ消費 | 書込失敗・コスト | Mappy 側既存レート制限の流用、MCP 側でさらに制限 |
| 6 | Phase 2 以降の書込系誤実行 | 顧客データ破損 | dry_run 必須化、監査ログ全件記録 |
| 7 | 実装スタック決定の遅延 | 着手遅れ | 設計フェーズ後半で確定、両案で進められる設計を優先 |