Quản lý App Store Connect và Google Play với Mağaza MCP

Mağaza MCP là gì?

Mağaza MCP là một máy chủ Model Context Protocol mã nguồn mở, cho phép trợ lý AI truy cập cả App Store Connect và Google Play từ một lần cài đặt duy nhất. Công cụ này dành cho các nhà phát triển và đơn vị vận hành ứng dụng cần kiểm tra, so sánh và quản lý dữ liệu trên các cửa hàng iOS và Android mà không phải chuyển đổi giữa những tích hợp riêng biệt.

Máy chủ chạy cục bộ trên máy của bạn và giao tiếp trực tiếp với Apple và Google. Không có dịch vụ trung gian. Các công cụ Apple sử dụng tiền tố appstore__, công cụ Google Play sử dụng play__, còn các công cụ liên cửa hàng hoặc API chung sử dụng magaza__.

Tính năng nổi bật là khả năng trả lời các câu hỏi liên quan đến nhiều cửa hàng trong một thao tác. Ví dụ, trợ lý có thể so sánh giá bằng đồng lira Thổ Nhĩ Kỳ của cùng một gói đăng ký trên App Store và Google Play, ghép cặp ứng dụng iOS và Android tương ứng, hoặc điều tra vấn đề cấu hình giao dịch mua trong ứng dụng trên cả hai cửa hàng.

Tính năng chính

• Một máy chủ MCP cho hai cửa hàng: Kết nối App Store Connect, Google Play hoặc cả hai.
• Quy trình liên cửa hàng: So sánh các gói đăng ký, tạo tổng quan ứng dụng kết hợp và chẩn đoán cấu hình giao dịch mua trong ứng dụng trên cả hai nền tảng.
• 27 công cụ chuyên dụng: Một bản cài đặt hai cửa hàng cung cấp 27 công cụ cho các thao tác cửa hàng phổ biến và truy cập API chung.
• Phạm vi API đầy đủ: Tìm kiếm và gọi 1.440 thao tác từ App Store Connect API v4.5, Android Publisher API v3 và Play Developer Reporting API v1beta1.
• Giảm tải ngữ cảnh: Danh mục API đầy đủ được truy cập thông qua các công cụ tìm kiếm và điều phối, thay vì hiển thị cả 1.440 thao tác dưới dạng các công cụ MCP riêng biệt.
• Lưu trữ thông tin xác thực cục bộ: Thông tin xác thực được lưu trong macOS Keychain khi có thể, với phương án dự phòng là tệp bị giới hạn quyền truy cập trên các hệ thống không thể sử dụng Keychain.
• Xác nhận khi ghi dữ liệu: Các thao tác thay đổi dữ liệu yêu cầu xác nhận rõ ràng bằng onayla=true.
• Chế độ chỉ đọc: Có thể hoàn toàn loại bỏ các công cụ ghi khỏi danh sách công cụ của mô hình.
• Không thu thập dữ liệu: Dự án không gửi dữ liệu phân tích, báo cáo lỗi hoặc dữ liệu sử dụng.

Điều kiện tiên quyết

Cài đặt Node.js 18 hoặc mới hơn trước khi chạy gói. Bạn cũng cần thông tin xác thực phù hợp cho từng cửa hàng muốn kết nối.

Yêu cầu đối với App Store Connect

Tạo khóa API App Store Connect và chuẩn bị Key ID, Issuer ID cùng tệp .p8 trong quá trình thiết lập. Vai trò App Manager đủ cho hầu hết thao tác. Các endpoint quản lý người dùng và quyền truy cập, cùng một số báo cáo phân tích, có thể yêu cầu quyền cao hơn.

Khóa phải là khóa API App Store Connect. Không thể dùng khóa StoreKit hoặc khóa thông báo đẩy thay thế.

Yêu cầu đối với Google Play

1. Mời tài khoản dịch vụ thông qua Play Console → Users and permissions, sau đó cấp quyền truy cập vào các ứng dụng liên quan.
2. Bật cả Android Publisher API và Play Developer Reporting API trong dự án Google Cloud liên kết.

Reporting API không chỉ cần cho các chỉ số sự cố mà còn cần cho việc phát hiện ứng dụng. Android Publisher API không cung cấp endpoint để liệt kê tất cả ứng dụng mà tài khoản có quyền truy cập.

Không thể đọc hợp đồng, thông tin thuế và thông tin ngân hàng thông qua các API này. Apple không cung cấp thông tin đó qua khóa API App Store Connect.

Cài đặt Mağaza MCP

Khởi chạy trình cài đặt tương tác bằng một lệnh:

npx magaza-mcp kur

Trình hướng dẫn sẽ hướng dẫn bạn qua các bước sau:

1. Chọn App Store Connect, Google Play hoặc cả hai cửa hàng.
2. Nhập Key ID và Issuer ID của App Store Connect, sau đó cung cấp đường dẫn đến tệp .p8.
3. Cung cấp đường dẫn đến tệp JSON của tài khoản dịch vụ Google Play.
4. Chọn các ứng dụng khách AI được phát hiện để cài đặt cấu hình MCP.
5. Chọn máy chủ có hoạt động ở chế độ chỉ đọc hay không.

Trình cài đặt xác thực thông tin Apple và Google bằng các yêu cầu API thực trước khi lưu. Thông tin xác thực không được ghi vào tệp cấu hình của ứng dụng khách AI. Cấu hình chỉ chứa những thông tin như các cửa hàng được bật thông qua MAGAZALAR.

Trên macOS, thông tin xác thực được lưu trong Keychain. Nếu Keychain không khả dụng, dự án sẽ chuyển sang dùng một tệp có quyền 0600.

Các ứng dụng khách MCP được hỗ trợ

Trình cài đặt hỗ trợ Claude Code, Claude Desktop, Antigravity, Cursor, Windsurf và Codex. Công cụ chỉ cập nhật mục magaza-mcp, giữ nguyên cấu hình không liên quan, tạo bản sao lưu .magaza-mcp-yedek trước khi ghi và thực hiện thao tác ghi nguyên tử.

Khởi động lại mọi ứng dụng khách đang mở sau khi thiết lập để chúng tải máy chủ MCP mới.

Xác minh cài đặt

Sử dụng các lệnh trạng thái và liệt kê công cụ để xác nhận kết quả:

npx magaza-mcp durum
npx magaza-mcp durum --json
npx magaza-mcp araclar
npx magaza-mcp surum
npx magaza-mcp yardim

durum báo cáo các cửa hàng đang được kết nối, còn araclar liệt kê các công cụ đã cài đặt. Các công cụ được đánh dấu bằng ✎ có thể sửa đổi dữ liệu cửa hàng.

Cách sử dụng cơ bản

Mağaza MCP được thiết kế để sử dụng thông qua các yêu cầu bằng ngôn ngữ tự nhiên trong trợ lý tương thích với MCP. Sau khi ứng dụng khách khởi động lại, hãy bắt đầu bằng một yêu cầu kiểm kê đơn giản:

Liệt kê các ứng dụng của tôi trên cả hai cửa hàng và cho biết hiện mỗi ứng dụng đang được phát hành ở đâu.

Khi cả hai cửa hàng được kết nối, magaza__genel_bakis sẽ kết hợp danh sách ứng dụng, ghép các sản phẩm iOS và Android tương ứng, đồng thời tách các ứng dụng chỉ được tìm thấy trên một cửa hàng.

So sánh giá gói thuê bao

Yêu cầu trợ lý so sánh một gói thuê bao cho một quốc gia cụ thể:

Gói thuê bao hàng tháng cho Note Keeper trên App Store và Google Play ở Thổ Nhĩ Kỳ có giá bao nhiêu? Có chênh lệch không?

Công cụ magaza__abonelik_karsilastir so sánh mã định danh sản phẩm, chu kỳ thanh toán và giá theo từng quốc gia. Công cụ này cũng chuyển đổi mã quốc gia sang định dạng mà mỗi cửa hàng yêu cầu.

Chẩn đoán sự cố mua hàng

Đối với khách hàng đã thanh toán nhưng chưa nhận được quyền truy cập cao cấp, hãy sử dụng yêu cầu như sau:

Một khách hàng cho biết họ đã thanh toán nhưng quyền truy cập cao cấp chưa được kích hoạt. Hãy kiểm tra thiết lập mua hàng trên cả hai cửa hàng và tóm tắt các nguyên nhân có thể xảy ra.

Công cụ magaza__iap_teshis kiểm tra sản phẩm đã được phát hành hay chưa, giá có tồn tại ở quốc gia liên quan hay không và gói cơ bản trên Google Play có dành cho người đăng ký mới hay không. Nếu cung cấp mã thông báo mua hàng trên Play, công cụ có thể xác thực mã thông báo đó trong quá trình chẩn đoán.

Kiểm tra App Store Connect

Các công cụ dành riêng cho App Store có thể liệt kê ứng dụng, bản phát hành, bản dựng TestFlight, bài đánh giá, nhóm gói thuê bao, giá gói thuê bao, giao dịch mua trong ứng dụng, nhóm TestFlight và báo cáo doanh số. Các yêu cầu mẫu gồm:

• Phiên bản App Store nào hiện đang bị kẹt ở trạng thái xét duyệt?
• Bản dựng TestFlight tôi tải lên hôm qua đã xử lý xong chưa?
• Hãy tóm tắt các bài đánh giá một sao và hai sao trong tuần qua.
• Tải báo cáo doanh số hằng ngày của ứng dụng này xuống.

Bạn cũng có thể thay đổi siêu dữ liệu cửa hàng và phản hồi đánh giá, nhưng các thao tác đó yêu cầu xác nhận rõ ràng.

Kiểm tra Google Play

Các công cụ Google Play hỗ trợ ứng dụng, kênh phát hành, bài đánh giá, gói thuê bao, giá gói cơ bản, sản phẩm mua một lần, xác thực giao dịch mua, giao dịch mua bị hủy và tỷ lệ sự cố Android vitals. Các yêu cầu mẫu gồm:

• Phiên bản nào đang ở kênh phát hành chính thức và bao nhiêu phần trăm người dùng nhận được phiên bản đó?
• Tỷ lệ sự cố có tăng trong 14 ngày qua không?
• Mã thông báo mua hàng này có hợp lệ không và gói thuê bao còn hoạt động không?
• Hiển thị các giao dịch mua đã hoàn tiền hoặc bị thu hồi trong khoảng thời gian hiện có.

Google chỉ cung cấp khoảng một tuần đánh giá gần đây nhất thông qua API tương ứng. Dữ liệu giao dịch mua bị hủy chỉ giới hạn trong 30 ngày gần nhất.

Thực hiện an toàn các thao tác ghi

Các công cụ như appstore__yorum_yanitla, appstore__metin_guncelle và play__yorum_yanitla có thể thay đổi dữ liệu cửa hàng. Chúng không được thực thi ngay ở yêu cầu đầu tiên. Thay vào đó, máy chủ trả về thao tác được đề xuất và nội dung phần thân yêu cầu dự kiến.

Sau khi xem xét đề xuất, hãy phê duyệt đề xuất và yêu cầu trợ lý lặp lại thao tác với:

onayla=true

Cơ chế xác nhận này được máy chủ thực thi, thay vì chỉ dựa vào giao diện của ứng dụng khách MCP.

Bật chế độ chỉ đọc

Để kiểm toán, lập báo cáo hoặc thử nghiệm thận trọng, hãy khởi động máy chủ ở chế độ chỉ đọc:

npx magaza-mcp --salt-okunur

Bạn cũng có thể đặt:

SALT_OKUNUR=1

Khi cả hai cửa hàng được kết nối, chế độ chỉ đọc giảm danh sách hiển thị từ 27 công cụ xuống còn 24. Các công cụ dành riêng cho thao tác ghi sẽ biến mất, vì vậy mô hình không thể thấy hoặc gọi chúng. Bộ điều phối tổng quát magaza__cagir vẫn khả dụng vì cũng cần thiết cho các thao tác đọc, nhưng sẽ từ chối các thao tác ghi trong chế độ chỉ đọc.

Sử dụng danh mục API đầy đủ

Các công cụ chuyên biệt bao quát những quy trình phổ biến, nhưng Mağaza MCP cũng cung cấp quyền truy cập vào 1.440 thao tác API. Thay vì đưa mọi thao tác vào ngữ cảnh của mô hình, hệ thống cung cấp ba công cụ tổng quát:

• magaza__endpoint_ara tìm kiếm danh mục API của các cửa hàng được kết nối và trả về tên thao tác, phương thức HTTP, đường dẫn và tham số phù hợp.
• magaza__sema hiển thị lược đồ nội dung phần thân yêu cầu cho một thao tác, đặc biệt hữu ích trước các yêu cầu POST hoặc PATCH.
• magaza__cagir gọi thao tác đã chọn và tự động điền các tham số đường dẫn.

Một lời nhắc nâng cao hữu ích là:

Hãy tìm kiếm trong API của cửa hàng được kết nối một endpoint quản lý tài nguyên này. Hiển thị lược đồ yêu cầu trước khi thực hiện bất kỳ thao tác ghi nào.

Các danh mục được tạo từ đặc tả OpenAPI chính thức của Apple dành cho App Store Connect và các tài liệu khám phá Android Publisher và Play Developer Reporting của Google. Các thao tác Apple đã lỗi thời vẫn có thể tìm kiếm khi chúng vẫn là cách duy nhất để sử dụng một tính năng, nhưng phần tóm tắt của chúng bắt đầu bằng [ESKİMİŞ] và có thứ hạng thấp hơn trong kết quả tìm kiếm.

Hiểu về cách ly công cụ

Máy chủ tránh trộn lẫn các cửa hàng thông qua một số quy tắc thiết kế:

• Mọi công cụ dành riêng cho một cửa hàng đều có tiền tố rõ ràng.
• Công cụ có tiền tố appstore__ không bao giờ gọi Google Play, còn công cụ play__ không bao giờ gọi Apple.
• Các công cụ của cửa hàng không được chọn sẽ không được tải vào bộ nhớ hoặc hiển thị cho mô hình.
• Các công cụ liên cửa hàng chỉ tồn tại khi cả hai cửa hàng được bật.
• Đối số magaza được các công cụ điều phối chấp nhận chỉ giới hạn ở các cửa hàng đã được cấu hình trong quá trình cài đặt.

Cài đặt hai cửa hàng sẽ tải 27 công cụ. Cài đặt chỉ có App Store tải 14 công cụ, còn cài đặt chỉ có Play tải 13 công cụ. Điều này giúp ngữ cảnh MCP phù hợp với môi trường đã cấu hình.

Mẹo bảo mật nâng cao

• Không dán thông tin xác thực vào cuộc trò chuyện: Tự chạy npx magaza-mcp kur và nhập đường dẫn thông tin xác thực thông qua trình hướng dẫn cục bộ.
• Sử dụng chế độ chỉ đọc để phân tích: Bật chế độ này khi bạn chỉ cần thông tin về bản phát hành, đánh giá, giá cả, giao dịch mua hoặc tình trạng hệ thống.
• Xem xét mọi thao tác ghi được đề xuất: Xác nhận ứng dụng, tài nguyên, ngôn ngữ và nội dung yêu cầu trước khi phê duyệt onayla=true.
• Cấp quyền tối thiểu: Sử dụng App Manager trên Apple, trừ khi một endpoint bắt buộc cần quyền truy cập cao hơn, và chỉ cấp cho tài khoản dịch vụ Google quyền truy cập các ứng dụng liên quan.
• Đảm bảo thời gian hệ thống chính xác: JWT của Apple có thời hạn 20 phút, vì vậy đồng hồ sai lệch đáng kể có thể gây lỗi xác thực.

Máy chủ xác thực và mã hóa các tham số đường dẫn, từ chối các nỗ lực duyệt đường dẫn như . và .., đồng thời xác thực máy chủ cho các URL tuyệt đối. Lưu lượng mạng chỉ được giới hạn ở API của Apple, Android Publisher API, Play Developer Reporting API và endpoint mã thông báo OAuth của Google.

Khắc phục sự cố

Apple trả về 401

Kiểm tra để đảm bảo Key ID, Issuer ID và tệp .p8 thuộc cùng một khóa API App Store Connect. Kiểm tra đồng hồ của máy vì JWT có thời gian không chính xác có thể bị từ chối. Đồng thời xác nhận tệp này không phải là khóa StoreKit hoặc khóa thông báo đẩy.

Apple trả về 403

Khóa API có thể chưa được cấp vai trò cần thiết cho thao tác đó. App Manager đáp ứng hầu hết quy trình, nhưng việc quản lý người dùng và một số báo cáo yêu cầu thêm quyền. Không thể truy xuất dữ liệu hợp đồng, thuế và ngân hàng thông qua API, bất kể vai trò nào.

Google Play trả về 403

Xác nhận tài khoản dịch vụ đã được mời trong Play Console và có quyền truy cập ứng dụng mục tiêu. Các thay đổi quyền có thể mất vài phút để áp dụng. Đồng thời kiểm tra Android Publisher API và Play Developer Reporting API đã được bật trong dự án Cloud.

Nếu lỗi liên quan đến endpoint cũ inappproducts, ứng dụng có thể đang sử dụng mô hình sản phẩm mới hơn của Google. Công cụ play__urunler xử lý trường hợp này bằng cách thử oneTimeProducts trước và chuyển sang mô hình cũ khi cần.

Thông tin kênh phát hành xuất hiện chậm

Google Play cung cấp thông tin về kênh phát hành thông qua một phiên chỉnh sửa. Các công cụ đọc tạo phiên, đọc dữ liệu rồi thoát mà không thực hiện commit, vì vậy không có thay đổi nào được thực hiện trên cửa hàng. Quy trình này yêu cầu thêm các yêu cầu HTTP và do đó có thể mất nhiều thời gian hơn.

Thiết lập phát triển

Để làm việc trực tiếp với dự án, hãy sao chép kho lưu trữ và cài đặt các phần phụ thuộc:

git clone https://github.com/tunaarikaya/magaza-mcp.git
cd magaza-mcp
npm install
npm run build
npm run kontrol
npm run dev

npm run build biên dịch mã nguồn TypeScript, npm run kontrol kiểm tra kiểu mà không tạo tệp đầu ra, còn npm run dev khởi động quá trình biên dịch ở chế độ theo dõi.

Để tạo lại các danh mục API từ ba tệp đặc tả trong spec/, hãy chạy:

node scripts/uret-katalog.mjs

Các danh mục thao tác được tạo sẽ được ghi vào src/katalog/; danh sách thao tác không được thiết kế để duy trì thủ công.

Kết luận

Mağaza MCP cung cấp một cách thực tế để vận hành App Store Connect và Google Play từ một trợ lý tương thích với MCP. Các công cụ đa cửa hàng giúp đơn giản hóa việc so sánh giá, kiểm kê ứng dụng và chẩn đoán giao dịch mua, trong khi danh mục API đầy đủ có thể tìm kiếm bao quát các thao tác ít phổ biến hơn. Cơ chế xử lý thông tin xác thực cục bộ, các bước xác nhận, chế độ chỉ đọc và việc không thu thập dữ liệu đo lường khiến công cụ phù hợp với những quy trình cần kiểm soát chặt chẽ quyền truy cập cửa hàng.