Mappy MCP Server (Thiết lập mới)

Tổng quan

Mục	Nội dung
Trạng thái	🔵 Đề xuất
Issue	#13
GitLab Issue	Mappy #58
Phụ trách	-
Ước lượng công sức (MVP)	24.0 ngày-người
Ước lượng công sức (toàn Phase)	khoảng 44.0 ngày-người
Stack triển khai	Đề xuất Python (FastMCP) / TypeScript (SDK chính thức) liệt kê song song

Chuyển đổi hướng tiếp cận: thay vì tích hợp AI trực tiếp vào Mappy cho các tính năng cải thiện nghiệp vụ, ta thiết lập MCP (Model Context Protocol) Server để khách hàng có thể truy cập dữ liệu và thao tác Mappy thông qua AI agent của chính họ (Claude Desktop / Claude Code / ChatGPT Pro v.v.). Nhờ vậy Mappy chỉ tập trung vào "interface dữ liệu và thao tác", không phải gánh chi phí vận hành LLM.

Nội dung đề xuất

Bối cảnh và vấn đề

Giới hạn của cách triển khai từng case riêng lẻ: Nếu mỗi tính năng AI (#5 phân tích đánh giá AI, #6 phân tích từ khóa thu hút AI, #7 phân tích nhóm, #8 #9 báo cáo AI) được implement riêng, Mappy sẽ phải gánh tất cả AI feature và phạm vi bảo trì sẽ phình to
Chi phí vận hành LLM: Khi chạy AI ở phía Mappy, toàn bộ chi phí token, theo dõi cập nhật model, bảo trì prompt đều do Mappy gánh
Vấn đề khả năng mở rộng: Đáp ứng từng yêu cầu phân tích khác nhau của khách bằng cách implement riêng đòi hỏi nhiều resource dev mỗi khi có yêu cầu mới
Không tận dụng được hợp đồng AI sẵn có của khách: Khách hàng đã có ChatGPT Pro / Claude Pro nhưng Mappy không cách nào tận dụng được năng lực đó

Giải pháp đề xuất

Thiết lập MCP Server mới để AI agent (client) của khách hàng có thể gọi các tính năng và dữ liệu của Mappy.

Đặc điểm chính:

Hỗ trợ kết nối remote qua Streamable HTTP + OAuth 2.1
Tương thích đầy đủ các MCP client chính: Claude Desktop / Claude Code / ChatGPT Connectors
Cung cấp toàn bộ domain của Mappy (location, post, review, ranking, insight v.v.) dưới dạng MCP tool
Khách hàng tự mang AI vào, Mappy không phải gánh chi phí vận hành LLM
Các case #5・#6 hiện có có thể được hấp thụ hoàn toàn vào MCP, có thể xem xét thu hẹp lại thành case độc lập

Phương châm phân chia (MCP vs API)

Đối tượng	Phương thức	Lý do
Tính năng cải thiện nghiệp vụ (cửa hàng hợp đồng B2B sử dụng)	MCP Server	Người dùng xác định rõ, xác thực và tính phí rõ ràng
Tính năng AI open/BtoC (tự động trả lời đánh giá v.v.)	API	Tiền đề là Web trigger, rủi ro khi public MCP cho không giới hạn người

Phạm vi đối tượng (các domain bao phủ)

Domain mà MCP Server cung cấp tool. Chi tiết spec được định nghĩa riêng trong Tool Catalog.

Domain	Thao tác chính
Location	List / Get / Update thuộc tính
Group	List / Liên kết cửa hàng / Thao tác theo group
Menu / Service	Get / Update
Sản phẩm (GBP products)	Get / Áp dụng hàng loạt (mới triển khai)
Post	List / Tạo / Lên lịch
Media (ảnh)	List / Upload / Xóa
Review (đánh giá)	List / Trả lời / Quản lý template
Template trả lời	CRUD
Insight	Get / Tổng hợp
Xếp hạng tìm kiếm	Get / Lọc theo kỳ
Từ khóa thu hút	Get / Cung cấp dữ liệu phân tích
Báo cáo	Yêu cầu tạo / Download
Khảo sát	List / Get câu trả lời
CTA / SMS	List / Get log gửi
SNS liên kết	Get cài đặt / Get feed
Notification	List

Danh sách tính năng (theo Phase)

Dự kiến release theo 3 giai đoạn.

Phase	Tên	Phạm vi	Tool chính	Ước lượng công sức
Phase 1 (MVP)	Auth + Read-only	OAuth 2.1 base, 5 read tool, audit log	location.list / location.get / review.list / ranking.list / insight.summary	24.0 ngày
Phase 2	Mở rộng Write	Post / trả lời review / media, dry_run, idempotency, polling batchId	post.create / review.reply / media.upload / location.update v.v.	11.5 ngày
Phase 3	Báo cáo・Phân tích	Tạo báo cáo / cung cấp dữ liệu phân tích / tích hợp với AI report	report.create / report.get / keyword.analyze / group.compare	8.5 ngày

Quyết định scope cho Phase 1

MVP đặt mục tiêu tối thiểu là "AI khách có thể đọc trạng thái của Mappy", write tool tách sang Phase 2. Write tool yêu cầu các cơ chế an toàn như dry_run / confirm token / idempotency key, do đó trước hết thiết lập auth, audit, flow vận hành qua read-only.

Tổng quan kiến trúc

Sơ đồ tổng thể

Phân chia trách nhiệm:

Component	Vai trò
AI khách	Gọi tool, diễn giải kết quả, trả lời người dùng
MCP Server	Công bố định nghĩa tool, xác thực, chuyển tiếp tới Laravel API, ghi audit
OAuth 2.1 Authz Server	Xác thực client, kiểm tra scope, phát hành token
Laravel API	Cung cấp business logic hiện có (thêm endpoint dành cho MCP)
Mappy DB	Dữ liệu thực
GBP API	Trung gian tới Google Business Profile
Audit Log DB	Ghi toàn bộ thao tác qua MCP (read/write/auth failure đều ghi)

Stack triển khai (đề xuất song song 2 phương án)

Thời điểm quyết định

Giai đoạn thiết kế đi song song cả hai phương án. Việc chốt cuối cùng stack triển khai có thể thực hiện ngay trước khi bắt đầu giai đoạn manufacturing (tức trước khi raise Issue). Architecture, tool catalog, auth, DB design đều language-independent.

Phương án A: Python (FastMCP) — đề xuất

Mục	Nội dung
MCP library	FastMCP (Python 3.10+)
HTTP server	Starlette / Uvicorn (ASGI)
OAuth 2.1	Authlib hoặc tự implement
ORM	SQLAlchemy hoặc qua Laravel API (không truy cập DB trực tiếp)
Deploy	Container (Docker), ECS Fargate hoặc EC2

Lý do đề xuất:

Tính năng AI report (#9) đã thiết kế bằng Python (FastAPI + Jinja2 + LangChain) — có thể đồng cư, dùng chung base
Component scraping cũng là Python — tận dụng được kỹ năng tích lũy trong công ty
Trong tương lai có thể giữ option tạo PPTX trực tiếp trong MCP (python-pptx v.v.)
FastMCP tự sinh định nghĩa tool từ type hint, validate input/output dễ dàng nhờ Pydantic

Phương án B: TypeScript (SDK chính thức)

Mục	Nội dung
MCP library	@modelcontextprotocol/sdk
HTTP server	Express / Hono / Fastify
OAuth 2.1	`oauth4webapi` v.v.
ORM	Prisma hoặc qua Laravel API
Deploy	Container Node.js

Lý do xem xét chọn:

Dev frontend Mappy (Vue + TS) có thể implement server luôn
@modelcontextprotocol/sdk là SDK chính thức, hứa hẹn long-term support
Type system của TypeScript đảm bảo tính nhất quán với JSON Schema mạnh
Đã có container Node.js trong Laradock

Authentication

Auth hiện có của Mappy không thể tái sử dụng cho MCP

Kết quả kiểm tra DB cho thấy Mappy chưa cài đặt Laravel Passport (composer.json có dependency nhưng bảng oauth_* chưa được tạo). Sanctum cũng chưa cài. Thực tế chỉ chạy session-based authentication. OAuth 2.1 authz server cho MCP sẽ phải tạo mới hoàn toàn.

Protocol: OAuth 2.1 (bắt buộc PKCE, bỏ Implicit Flow)
Transport: Streamable HTTP
Client tương thích: ChatGPT Connectors / Claude Desktop / Claude Code
Thiết kế scope: Mapping 1:1 với các cột *_access_level hiện có của Mappy (xem chi tiết tại Auth & Tenancy)

Kết nối với Mappy hiện có

Qua Laravel API (đề xuất): Cấu trúc MCP Server → Laravel API → Mappy DB / GBP API
- Tái sử dụng business logic, validation, kiểm tra quyền hiện có
- Thêm endpoint dành riêng cho MCP vào Laravel
Cấm truy cập DB trực tiếp: Tránh duplicate logic xác định tenant và quyền

Hình ảnh kết nối

Ví dụ sử dụng từ Claude Desktop

Người dùng chỉ cần thêm cấu hình sau vào file MCP setting của Claude Desktop, Mappy sẽ sẵn sàng làm tool cho 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"
      }
    }
  }
}

Ví dụ kịch bản sử dụng:

Người dùng: "Cho tôi xem biến động xếp hạng tìm kiếm của cửa hàng Shibuya tháng trước"
Claude: (Tự động gọi tool ranking.list của MCP → Lấy dữ liệu → Tóm tắt bằng ngôn ngữ tự nhiên)
"Xếp hạng tìm kiếm trung bình của cửa hàng Shibuya tháng trước là 3.2, tăng 1.5 vị trí so với tháng trước. Đặc biệt với từ khóa 'tiệm tóc Shibuya'..."

Ví dụ sử dụng từ ChatGPT Connectors

Thêm MCP URL của Mappy vào mục "Connectors" trong cài đặt ChatGPT, hoàn tất OAuth là dùng được.

1. Cài đặt ChatGPT → Connectors → "Add custom connector"
2. URL: https://mcp.mappy.example.com/sse
3. Đăng nhập Mappy trong màn hình OAuth → Đồng ý scope
4. Sử dụng trong hội thoại ChatGPT như "Xem đánh giá của Mappy tháng trước"

Thiết kế tenancy & scope (tổng quan)

Chi tiết xem Auth & Tenancy.

Phân tầng quyền

admins.is_supervisor = 1 (quyền tối cao)
  └─ Có thể thay mặt toàn bộ mappy_users (cần giới hạn nghiêm ngặt)

admins.is_supervisor = 0 (admin thông thường)
  └─ Chỉ user phụ trách (phạm vi cookie preview_user_id)

mappy_users.user_type = 1 (MAIN_USER)
  └─ Thao tác bản thân + group dưới parent_user_id

mappy_users.user_type = 3 (MASTER_USER)
  └─ Toàn bộ group dưới parent_user_id

mappy_users.user_type = 2 (GROUP_USER)
  └─ Chỉ bản thân

Mapping scope với cột quyền của Mappy

Ví dụ scope MCP	Cột quyền phía 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`

Xác định ranh giới cửa hàng

User thông thường: chỉ cửa hàng có liên kết trong mappy_user_available_gbp_locations
Theo group: lọc qua mappy_groups + mappy_group_location (dạng số ít)
Admin thay mặt: thu hẹp bằng user đối tượng của cookie preview_user_id

Quan hệ với các case hiện có

Việc MCP hóa cho phép hấp thụ phần AI của các case hiện có vào MCP. Tuy nhiên phần UI / cải tạo tính năng hiện có vẫn cần độc lập với MCP.

Case	Quan hệ với MCP	Ảnh hưởng
#2 Mở quyền report cho main account	Độc lập	UI kiểm soát quyền không liên quan MCP. Chia sẻ thiết kế scope
#3 Đăng ảnh hàng loạt và xóa hàng loạt	Tích hợp một phần	Popup xác nhận / UI xóa hàng loạt vẫn riêng. API đăng hàng loạt có thể MCP tool hóa
#5 Phân tích đánh giá AI	Tích hợp hoàn toàn	Case này có thể được thay thế bằng MCP, xem xét thu hẹp thành case độc lập
#6 Phân tích AI từ khóa thu hút	Tích hợp hoàn toàn	Tương tự trên
#7 Phân tích group	Tích hợp một phần	Lấy dữ liệu thành tool, UI / CSV vẫn riêng
#8 Thêm số liệu insight vào report	Độc lập	Cải tạo body report. Không liên quan MCP
#9 Tự động sinh AI advice cho report	Tích hợp một phần	Phần sinh AI có thể thay bằng MCP, HTML template / flow màn hình vẫn riêng

Đối tượng xem xét thu hẹp

#5・#6 có thể hấp thụ hoàn toàn vào MCP, nên nếu chốt áp dụng MCP thì không cần implement riêng. #3・#7・#9 chạy song song với MCP, cần xác định ranh giới không trùng lặp trong giai đoạn thiết kế tính năng.

Ước lượng công sức (giả định có AI)

Cơ cấu

Vai trò	Số người	Phụ trách
Thiết kế	1 người	Xác nhận yêu cầu → ra lệnh AI tạo design → review → chỉ đạo manufacture
Manufacture	1 người	Dựa Issue ra lệnh AI tạo code → code review → test → deploy

Chi tiết công sức (Phase 1 — MVP)

Cách hiểu ngày-người

"Ngày-người" = thời gian review của người. Việc thực tế (tạo design document, code) do AI làm, người chỉ tập trung review và ra chỉ thị.

Công thức: Số lần retake của AI × thời gian review (0.5 ngày/lần) = ngày-người

Ví dụ: AI retake 3 lần × 0.5 ngày/lần = 1.5 ngày-người (người dùng 1.5 ngày để review)

#	Hạng mục	AI retake	Review	Ngày-người	Phụ trách
1	Xác nhận yêu cầu, tạo tài liệu design tổng thể	4 lần	0.5 ngày/lần	2.0	Thiết kế
2	Thiết kế kiến trúc (chốt stack)	3 lần	0.5 ngày/lần	1.5	Thiết kế
3	Thiết kế auth OAuth 2.1	3 lần	0.5 ngày/lần	1.5	Thiết kế
4	Thiết kế tool catalog (phạm vi MVP)	3 lần	0.5 ngày/lần	1.5	Thiết kế
5	Thiết kế audit log・DB	2 lần	0.5 ngày/lần	1.0	Thiết kế
6	Thiết kế hạ tầng	2 lần	0.5 ngày/lần	1.0	Thiết kế
7	Implement base MCP server	5 lần	0.5 ngày/lần	2.5	Manufacture
8	Implement auth OAuth 2.1	6 lần	0.5 ngày/lần	3.0	Manufacture
9	Implement 5 read tool	6 lần	0.5 ngày/lần	3.0	Manufacture
10	Implement audit log	3 lần	0.5 ngày/lần	1.5	Manufacture
11	Xây hạ tầng (AWS/container)	3 lần	0.5 ngày/lần	1.5	Manufacture
12	Test kết nối (Claude Desktop / ChatGPT)	3 lần	0.5 ngày/lần	1.5	Manufacture
13	Test tích hợp, điều chỉnh chất lượng	3 lần	0.5 ngày/lần	1.5	Manufacture
14	Tạo manual vận hành	2 lần	0.5 ngày/lần	1.0	Thiết kế
15	Deploy, kiểm tra hoạt động	2 lần	0.5 ngày/lần	1.0	Manufacture
	Tổng Phase 1			24.0

Chi tiết công sức (Phase 2 — Mở rộng Write, ước lượng)

#	Hạng mục	AI retake	Review	Ngày-người
1	Thiết kế cơ chế an toàn write (dry_run / idempotency / confirm token)	3 lần	0.5 ngày/lần	1.5
2	Implement write tool (5〜7 tool)	6 lần	0.5 ngày/lần	3.0
3	Implement dry_run / idempotency	3 lần	0.5 ngày/lần	1.5
4	Implement confirm token	2 lần	0.5 ngày/lần	1.0
5	Tích hợp batchId + polling (liên kết với queue Jobs hiện có)	3 lần	0.5 ngày/lần	1.5
6	Rate limit	2 lần	0.5 ngày/lần	1.0
7	Test	3 lần	0.5 ngày/lần	1.5
8	Deploy	1 lần	0.5 ngày/lần	0.5
	Tổng Phase 2			11.5

Chi tiết công sức (Phase 3 — Báo cáo・Phân tích, ước lượng)

#	Hạng mục	AI retake	Review	Ngày-người
1	Thiết kế report tool	3 lần	0.5 ngày/lần	1.5
2	Implement report tool	4 lần	0.5 ngày/lần	2.0
3	Implement analytics tool (xếp hạng / từ khóa / group)	4 lần	0.5 ngày/lần	2.0
4	Tích hợp với tính năng AI report (#9)	3 lần	0.5 ngày/lần	1.5
5	Test	2 lần	0.5 ngày/lần	1.0
6	Deploy	1 lần	0.5 ngày/lần	0.5
	Tổng Phase 3			8.5

Điều kiện tiên quyết và ràng buộc

OAuth 2.1 authz server xây mới: không tái sử dụng được Passport hiện có
Thêm endpoint MCP vào Laravel API: tạo lớp thin gọi logic hiện có
Cấm truy cập DB trực tiếp: mọi data access qua Laravel API
Hợp đồng AI tool phía khách hàng do khách chịu: ChatGPT Pro / Claude Pro v.v.
Theo kịp spec MCP mới nhất: Streamable HTTP, OAuth 2.1, tool schema đang phát triển, sau release vẫn cần cập nhật liên tục
Tuyệt đối cấm thao tác DB trực tiếp, SQL SELECT phải xuất từng lần để user thực thi (rule vận hành)

Lịch trình (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
			火	水	木	金	土	日	月	火	水	木	金	土	日	月	火	水	木	金	土	日	月	火	水	木	金	土	日	月
Xác nhận yêu cầu / tài liệu thiết kế tổng thể	Thiết kế	2d
Thiết kế kiến trúc	Thiết kế	1.5d
Thiết kế auth OAuth 2.1	Thiết kế	1.5d
Thiết kế tool catalog	Thiết kế	1.5d
Thiết kế audit log・DB	Thiết kế	1d
Thiết kế hạ tầng	Thiết kế	1d
Implement base MCP server	Manufacture	2.5d
Implement auth OAuth 2.1	Manufacture	3d
Implement read tool	Manufacture	3d
Implement audit log	Manufacture	1.5d
Xây hạ tầng	Manufacture	1.5d
Test kết nối	Manufacture	1.5d
Test tích hợp	Manufacture	1.5d
Tạo manual vận hành	Thiết kế	1d
Deploy / kiểm tra hoạt động	Manufacture	1d

Lịch Phase 2 / Phase 3

Phase 2・3 sẽ được lên kế hoạch lại sau khi release Phase 1 và phản ánh feedback vận hành. Tài liệu đề xuất này không cố định lịch cho 2 phase đó. Sau khi Phase 1 hoàn tất sẽ thực hiện ước lượng và lập lịch riêng.

Tài liệu liên quan

Chi tiết thiết kế xem các tài liệu sau:

Thiết kế chức năng: /vi/design/mcp-server-overview
Tool catalog: /vi/design/mcp-tools-catalog
Thiết kế auth・tenancy: /vi/design/mcp-auth-tenancy
Cơ chế an toàn write: /vi/design/mcp-write-safety
Thiết kế DB (audit log): /vi/data/mcp-audit-logs
Thiết kế DB (OAuth client): /vi/data/mcp-oauth-clients
Thiết kế hạ tầng: /vi/infrastructure/mcp-hosting
Chi tiết Issue: /vi/issues/mcp-server

Mappy MCP Server (Thiết lập mới) ​

Tổng quan ​

Nội dung đề xuất ​

Bối cảnh và vấn đề ​

Giải pháp đề xuất ​

Phương châm phân chia (MCP vs API) ​

Phạm vi đối tượng (các domain bao phủ) ​

Danh sách tính năng (theo Phase) ​

Tổng quan kiến trúc ​

Sơ đồ tổng thể ​

Stack triển khai (đề xuất song song 2 phương án) ​

Phương án A: Python (FastMCP) — đề xuất ​

Phương án B: TypeScript (SDK chính thức) ​

Authentication ​

Kết nối với Mappy hiện có ​

Hình ảnh kết nối ​

Ví dụ sử dụng từ Claude Desktop ​

Ví dụ sử dụng từ ChatGPT Connectors ​

Thiết kế tenancy & scope (tổng quan) ​

Phân tầng quyền ​

Mapping scope với cột quyền của Mappy ​

Xác định ranh giới cửa hàng ​

Quan hệ với các case hiện có ​

Ước lượng công sức (giả định có AI) ​

Cơ cấu ​

Chi tiết công sức (Phase 1 — MVP) ​

Chi tiết công sức (Phase 2 — Mở rộng Write, ước lượng) ​

Chi tiết công sức (Phase 3 — Báo cáo・Phân tích, ước lượng) ​

Điều kiện tiên quyết và ràng buộc ​

Lịch trình (Phase 1 — MVP) ​

Tài liệu liên quan ​