#13 Mappy MCP Server (Thiết lập mới)
Tổng quan
| Mục | Nội dung |
|---|---|
| Issue ID | ISS-013 |
| Tên Issue | Thiết lập MCP Server, cho phép AI khách thao tác Mappy |
| Phân loại | Mở rộng tính năng・Tích hợp AI・Base xác thực |
| Ưu tiên | Cao |
| Trạng thái | 🔵 Đề xuất |
| GitLab Issue | Mappy #58 |
| Case liên quan | #13 MCP Server (Thiết lập mới) |
| Design cha | Thiết kế chức năng (tổng thể) |
Vấn đề hiện tại
- Nếu các tính năng AI cải thiện nghiệp vụ (#5 phân tích đánh giá AI, #6 phân tích từ khóa AI, #7 phân tích group, #8 #9 AI report v.v.) được implement riêng, phạm vi bảo trì sẽ phình to
- Phía Mappy gánh chi phí vận hành LLM (token, theo dõi update model, bảo trì prompt) là thiết kế không bền vững
- Không tận dụng được năng lực AI mà khách đã có hợp đồng (ChatGPT Pro / Claude Pro)
- Mỗi yêu cầu tích hợp AI mới đều cần resource dev
Phương pháp giải quyết
MCP hóa (Model Context Protocol) các tính năng cải thiện nghiệp vụ, cho phép AI khách thao tác Mappy.
- Mappy chỉ tập trung vào "interface dữ liệu và thao tác"
- Vận hành LLM ủy thác cho AI phía khách (Claude Desktop / Claude Code / ChatGPT Pro)
- Thêm tính năng AI = thêm MCP tool
- Các case #5・#6 hiện có có thể được hấp thụ hoàn toàn vào MCP
Chi tiết xem Đề xuất case.
Yêu cầu
Yêu cầu chức năng
| No | Yêu cầu | Chi tiết |
|---|---|---|
| 1 | Tuân thủ protocol MCP | Transport Streamable HTTP, tools/call, tools/list |
| 2 | Base auth OAuth 2.1 | Bắt buộc PKCE, authorization code + refresh token, dynamic client registration |
| 3 | Tương thích MCP client chính | Claude Desktop / Claude Code / ChatGPT Connectors |
| 4 | Kiểm soát tenancy | Phân tầng mappy_users × *_access_level × mappy_user_available_gbp_locations |
| 5 | Thiết kế scope | Hệ thống mappy:<domain>:<action>, mapping 1:1 với quyền hiện có của Mappy |
| 6 | Read tool (Phase 1) | 5 tool trở lên: location / review / ranking / insight / keyword v.v. |
| 7 | Write tool (Phase 2) | post / review.reply / media / location.update |
| 8 | Cơ chế an toàn write (Phase 2) | dry_run / idempotency_key / confirm_token / batch.status |
| 9 | Report tool (Phase 3) | report.create / report.get, tích hợp với AI report |
| 10 | Audit log | Ghi toàn bộ tool call・OAuth event・từ chối・dry_run |
| 11 | Rate limit | Theo đơn vị access token / client / user / idempotency |
Yêu cầu phi chức năng
| No | Yêu cầu | Chi tiết |
|---|---|---|
| 1 | Tính sẵn sàng | Nhiều ECS Fargate task, ALB health check |
| 2 | Khả năng scale | Auto Scaling (CPU + số request) |
| 3 | Thời gian response | Read tool p95 < 1 giây, write đồng bộ p95 < 3 giây |
| 4 | Bảo mật | Tuân thủ best practice OAuth 2.1, bắt buộc PKCE, refresh token rotation, giám sát family_id |
| 5 | Tính có thể audit | Ghi toàn bộ event vào mappy_mcp_audit_logs, giữ 1 năm |
| 6 | Bảo vệ dữ liệu | Không lưu log token, password, PII |
| 7 | Tối thiểu hóa ảnh hưởng hệ thống hiện có | Cấm truy cập DB trực tiếp, chỉ qua Laravel API |
Cấu trúc Phase
| Phase | Tên | Công sức | Sản phẩm chính |
|---|---|---|---|
| Phase 1 (MVP) | Auth + Read-only | 24.0 ngày-người | OAuth 2.1 base, 5 read tool, audit log |
| Phase 2 | Mở rộng write | 11.5 ngày-người | Post / trả lời review / media, dry_run, idempotency |
| Phase 3 | Báo cáo・Phân tích | 8.5 ngày-người | Report tool, phân tích group, tích hợp với AI report |
| Tổng | 44.0 ngày-người |
Chi tiết task Phase 1
Giai đoạn thiết kế
| No | Task | Phụ trách | Công sức | Tiêu chí hoàn thành |
|---|---|---|---|---|
| 1.1 | Xác nhận yêu cầu, tạo tài liệu design tổng thể | Thiết kế | 2.0 | Tài liệu tổng thể hoàn thành, review OK |
| 1.2 | Thiết kế kiến trúc (chốt stack) | Thiết kế | 1.5 | Chốt Python / TypeScript cuối cùng |
| 1.3 | Thiết kế auth OAuth 2.1 | Thiết kế | 1.5 | Auth & Tenancy hoàn thành |
| 1.4 | Thiết kế tool catalog (phạm vi MVP) | Thiết kế | 1.5 | Phần Phase 1 của Tool Catalog hoàn thành |
| 1.5 | Thiết kế audit log・DB | Thiết kế | 1.0 | DB (audit log) + DB (OAuth) hoàn thành |
| 1.6 | Thiết kế hạ tầng | Thiết kế | 1.0 | Hạ tầng hoàn thành |
| Tổng phụ design | 8.5 |
Giai đoạn manufacture
| No | Task | Phụ trách | Công sức | Tiêu chí hoàn thành |
|---|---|---|---|---|
| 1.7 | Implement base MCP server | Manufacture | 2.5 | Kết nối Streamable HTTP, response tools/list, health check |
| 1.8 | Implement auth OAuth 2.1 | Manufacture | 3.0 | Flow auth code + PKCE, refresh rotation, dynamic registration, /.well-known/oauth-authorization-server |
| 1.9 | Implement 5 read tool | Manufacture | 3.0 | location.list / location.get / review.list / ranking.list / insight.summary hoạt động |
| 1.10 | Implement audit log | Manufacture | 1.5 | Ghi toàn bộ tool call・OAuth event vào mappy_mcp_audit_logs |
| 1.11 | Xây hạ tầng (AWS/container) | Manufacture | 1.5 | Cấu hình ECS / ALB / Redis / Secrets Manager hoàn tất |
| 1.12 | Test kết nối (Claude Desktop / ChatGPT) | Manufacture | 1.5 | Gọi tool thành công từ cả 2 client |
| 1.13 | Test tích hợp, điều chỉnh chất lượng | Manufacture | 1.5 | Verify các kịch bản từ chối auth, vi phạm tenancy, rate limit |
| 1.14 | Tạo manual vận hành | Thiết kế | 1.0 | Quy trình xử lý sự cố, revoke token, thêm client mới |
| 1.15 | Deploy, kiểm tra hoạt động | Manufacture | 1.0 | Staging → production, kiểm tra hoạt động |
| Tổng phụ manufacture | 15.5 |
Tổng Phase 1: 24.0 ngày-người
Chi tiết task Phase 2 (tóm tắt)
| No | Task | Công sức |
|---|---|---|
| 2.1 | Thiết kế cơ chế an toàn write (write safety) | 1.5 |
| 2.2 | Implement write tool (post.create / review.reply / media.upload v.v. 5〜7 tool) | 3.0 |
| 2.3 | Implement dry_run / idempotency | 1.5 |
| 2.4 | Implement confirm token | 1.0 |
| 2.5 | Tích hợp batchId + polling (liên kết với bảng jobs hiện có) | 1.5 |
| 2.6 | Rate limit | 1.0 |
| 2.7 | Test | 1.5 |
| 2.8 | Deploy | 0.5 |
| Tổng Phase 2 | 11.5 |
Chi tiết task Phase 3 (tóm tắt)
| No | Task | Công sức |
|---|---|---|
| 3.1 | Thiết kế report tool | 1.5 |
| 3.2 | Implement report tool (report.create / report.get) | 2.0 |
| 3.3 | Implement analytics tool (keyword / group.compare v.v.) | 2.0 |
| 3.4 | Tích hợp với AI report (#9) | 1.5 |
| 3.5 | Test | 1.0 |
| 3.6 | Deploy | 0.5 |
| Tổng Phase 3 | 8.5 |
Tiêu chí nghiệm thu (Phase 1)
Nghiệm thu chức năng
- [ ] Thêm MCP server vào Claude Desktop → Login → Lấy danh sách tool thành công
- [ ] Kết nối từ ChatGPT Connectors → OAuth → Gọi tool thành công
- [ ] 5 read tool hoạt động đúng spec input/output
- [ ] Request thiếu scope trả về 403 (FORBIDDEN_SCOPE)
- [ ] Request resource ngoài tenancy trả về 403 (FORBIDDEN_LOCATION/USER)
- [ ] Vượt rate limit trả về 429
- [ ] Refresh token rotation hoạt động (phát hiện token reuse → revoke toàn family)
- [ ] Call sau khi access token revoked trả về 401
- [ ] Toàn bộ tool call được ghi vào
mappy_mcp_audit_logs
Nghiệm thu phi chức năng
- [ ] Read tool p95 response < 1 giây
- [ ] Hỏng 1 ECS task vẫn duy trì hoạt động đầy đủ
- [ ] CloudWatch alarm phát hỏa, thông báo Slack
- [ ] Deploy staging → production zero downtime
Nghiệm thu tài liệu
- [ ] Thiết kế chức năng (tổng thể)
- [ ] Thiết kế auth・tenancy
- [ ] Tool catalog
- [ ] DB (audit log)
- [ ] DB (OAuth)
- [ ] Thiết kế hạ tầng
- [ ] Manual vận hành
Quan hệ phụ thuộc
Task tiên quyết (trước khi vào Phase 1)
- [ ] Chốt stack triển khai (Python / TypeScript)
- [ ] Chốt domain MCP (
mcp.mappy.example.comv.v.) - [ ] Apply AWS resource (Redis ElastiCache, ACM certificate)
- [ ] Xác nhận redirect_uri của MCP client chính thức (Claude / ChatGPT)
Tiên quyết sau khi xong Phase 1 (trước khi vào Phase 2)
- [ ] Phase 1 chạy production 2 tuần (verify ổn định)
- [ ] Từ access log AI khách, nắm xu hướng sử dụng tool
- [ ] Chốt tool write ưu tiên (hỏi ý kiến khách)
Tiên quyết sau khi xong Phase 2 (trước khi vào Phase 3)
- [ ] Tính năng AI report (#9 AI advice cho report) đã chạy (Python FastAPI + LangChain)
Quan hệ và phương châm tích hợp với các case liên quan
| Case liên quan | Quan hệ với MCP |
|---|---|
| #2 Mở quyền report | Độc lập. Chia sẻ scope MCP và cột quyền |
| #3 Đăng ảnh hàng loạt / xóa | Tích hợp một phần. Cung cấp API qua media.upload / post.create của MCP |
| #5 Phân tích đánh giá AI | Tích hợp hoàn toàn. Không cần implement AI phía Mappy, MCP thay thế |
| #6 Phân tích từ khóa AI | Tích hợp hoàn toàn. Tương tự |
| #7 Phân tích group | Tích hợp một phần. Cung cấp API qua group.compare của MCP |
| #8 Thêm số liệu insight vào report | Độc lập. Cải tạo body report |
| #9 AI advice cho report | Tích hợp một phần. report.create của MCP có thể gọi |
Rủi ro・Vấn đề
| # | Rủi ro | Tác động | Đối phó |
|---|---|---|---|
| 1 | Spec MCP thay đổi | Tính tương thích protocol | Cập nhật SDK chính thức / FastMCP, CI test tương thích |
| 2 | Lỗ hổng trong implement OAuth 2.1 | Sự cố bảo mật | Dùng thư viện chuyên dụng, pen test |
| 3 | AI khách hoạt động bất thường (lệnh sai / gọi đại số lượng) | Phá hủy dữ liệu, chi phí phình to | Áp dụng triệt để dry_run / confirm_token / rate limit |
| 4 | Bị trộm refresh token | Chiếm tài khoản | Giám sát family_id, revoke ngay khi phát hiện token reuse |
| 5 | Tiêu quota GBP API | Thất bại ghi, chi phí | Tận dụng rate limit hiện có của Mappy, thêm hạn chế phía MCP |
| 6 | Lệnh sai write tool sau Phase 2 | Hỏng dữ liệu khách | Bắt buộc dry_run, ghi toàn bộ audit log |
| 7 | Chậm chốt stack triển khai | Trễ deadline | Chốt cuối giai đoạn design, ưu tiên design có thể tiến với cả 2 phương án |