Tài liệu AppScreenshotsKết nối công cụ AI
Kết nối Claude Code, Codex, Gemini CLI và các MCP client khác để tạo và chỉnh sửa dự án ảnh chụp bằng AI, xem lại bằng công cụ trình duyệt và xuất trong trình chỉnh sửa web.
Kết nối công cụ AI
Khi MCP được bật trên bản triển khai AppScreenshots này, hãy kết nối một công cụ tương thích tới:
https://appscreenshots.net/api/mcpChọn HTTP/Streamable HTTP và OAuth. Đăng nhập bằng tài khoản AppScreenshots trong trình duyệt, chọn các dự án và tài nguyên công cụ được phép dùng, và quyết định xem nó có được tạo dự án hay không. Không cần truy cập cơ sở dữ liệu hay khóa API.
Để có tổng quan kèm prompt mẫu, xem trang MCP.
Kết nối ứng dụng của bạn
Các lệnh dưới đây đăng ký điểm cuối với từng ứng dụng. Sau khi kết nối, hoàn tất đăng nhập trên trình duyệt khi ứng dụng hiển thị nó.
claude mcp add --transport http --scope user appscreenshots https://appscreenshots.net/api/mcpSau đó chạy /mcp trong Claude Code và cấp quyền. Để kết nối theo phạm vi dự án, hãy gộp một tệp .mcp.json thay vì đăng ký phạm vi người dùng; đừng cấu hình cả hai trừ khi bạn có ý ghi đè phạm vi.
codex mcp add appscreenshots --url https://appscreenshots.net/api/mcp
codex mcp login appscreenshotsHoặc gộp một phần [mcp_servers.appscreenshots] với url = "..." vào config.toml của ứng dụng.
gemini mcp add --transport http --scope user appscreenshots https://appscreenshots.net/api/mcpTrong Gemini CLI, chạy /mcp auth appscreenshots. Biến thể tệp cài đặt dùng httpUrl cho Streamable HTTP kèm "oauth": {"enabled": true}.
Mở /mcp-config, thêm một HTTP server với điểm cuối, rồi dùng /mcp-config login appscreenshots. Tệp cấu hình là ~/.kimi-code/mcp.json:
{
"mcpServers": {
"appscreenshots": {
"url": "https://appscreenshots.net/api/mcp"
}
}
}Khởi động lại phiên sau khi thêm cấu hình. Các bản phân phối kimi-cli cũ dùng kimi mcp add --transport http --auth oauth.
Gộp server vào ~/.zcode/cli/config.json dưới mcp.servers, hoặc thêm HTTP service tên appscreenshots trong Settings → MCP:
{
"mcp": {
"servers": {
"appscreenshots": {
"type": "http",
"url": "https://appscreenshots.net/api/mcp",
"oauth": {
"type": "authorization_code",
"scope": "projects:read projects:write assets:read offline_access"
}
}
}
}
}Khởi động lại phiên và hoàn tất đăng nhập OAuth trên trình duyệt khi ứng dụng hiển thị. Hãy nhanh: ứng dụng desktop hủy một lần cấp quyền đang chờ sau khoảng 180 giây.
Dùng mục kết nối MCP tùy chỉnh có sẵn trong tài khoản hoặc workspace của bạn và chọn OAuth với điểm cuối ở trên. Tính khả dụng phụ thuộc vào cài đặt tài khoản và workspace — một kho GitHub công khai không tự tạo mục trong danh mục ChatGPT.
Tích hợp ứng dụng được ghi lại theo tài liệu chính thức và một bài kiểm thử đầu-cuối hoàn chỉnh ở mức giao thức (OAuth, tạo dự án, chỉnh sửa, xem trước trên web, xuất). Việc chứng nhận từng ứng dụng còn đang tiến hành; xem ma trận kiểm chứng của bộ kết nối cho trạng thái hiện tại.
Bộ kết nối
Kho công khai appscreenshots-mcp cung cấp tệp cấu hình sẵn cho mọi ứng dụng phía trên, một Skill agent tùy chọn dạy quy trình chụp ảnh, và lệnh doctor kiểm tra server từ terminal của bạn:
git clone https://github.com/horace68/appscreenshots-mcp.git
node bin/appscreenshots.mjs config claude # in một đoạn cấu hình cho ứng dụng
node bin/appscreenshots.mjs install-skill claude
node bin/appscreenshots.mjs doctorTrợ giúp này chỉ in cấu hình và cài Skill. Nó không phải stdio server cục bộ — hãy dùng tính năng kết nối từ xa gốc của ứng dụng.
Công cụ
Chín công cụ dưới đây được cung cấp qua Streamable HTTP. Ứng dụng có thể thêm tiền tố vào tên. Server được lưu trữ là nguồn chuẩn cho schema đầu vào và quyền tài khoản.
| Công cụ | Loại | Chức năng |
|---|---|---|
get_capabilities | Đọc | Quyền hạn, giới hạn thiết kế (100–5000 px), thiết bị, loại phần tử, maxFrames (20), maxElementsPerFrame (100), chế độ xem trước/xuất |
search_templates | Đọc | Tìm siêu dữ liệu mẫu công khai (query, offset) |
get_template | Đọc | Đọc một mẫu có quyền theo id |
list_projects | Đọc | Liệt kê dự án được cấp quyền, 25 mỗi trang |
get_project | Đọc | Đọc phiên bản hiện tại và thiết kế chỉnh sửa được, kèm editorUrl |
get_project_preview | Đọc | Liên kết trình chỉnh sửa, phiên bản, khung và hướng dẫn xem lại trên trình duyệt — là văn bản, không phải ảnh |
list_assets | Đọc | Liệt kê tài nguyên dùng chung và tài nguyên trong dự án được cấp quyền, 50 mỗi trang |
create_project | Ghi | Tạo từ mẫu hoặc canvas trống (name, templateId tùy chọn, width, height, idempotencyKey) |
update_project | Ghi | Áp dụng 1–100 thao tác có cấu trúc mỗi lần gọi, kèm expectedRevision và idempotencyKey |
Thao tác chỉnh sửa
update_project nhận một danh sách thao tác phân biệt:
set_name— đổi tên dự ánadd_frame/remove_frame/reorder_frames— quản lý khungupsert_element— chèn hoặc thay thế phần tử; yêu cầu hình học đầy đủ và giữ các trường bị bỏ qua của cùng loạipatch_element— chỉnh sửa một phần theoidphần tử; không được đổi loạiremove_element— xóa phần tửset_background— đặt nền của một khung; nền dùng chung được cố định theo từng khungset_locales— đặt 1–20 ngôn ngữ và ngôn ngữ mặc địnhset_canvas— kích thước canvas (100–5000) và chế độ (separatehoặccontinuous)
Phần tử mang kiểu chữ, trường mockup thiết bị, tham chiếu assetId ảnh, hình khối, biểu tượng, rotation và stackOrder. Ảnh chỉ được tham chiếu bằng assetId đã cấp quyền — không bao giờ bằng URL hay đường dẫn cục bộ, và các tham chiếu hiện có được giữ phía server nên đừng gửi lại.
Mỗi lần ghi hợp lý nên dùng một khóa idempotency mới; chỉ dùng lại cho một lần thử lặp lại y hệt. Sau xung đột phiên bản, đọc phiên bản mới nhất rồi mới tiếp tục. Không bao giờ dùng SQL, HTML hay script làm chỉ dẫn chỉnh sửa.
Lỗi
Lỗi trả về thân JSON {code, message} với isError: true:
| Mã | Ý nghĩa |
|---|---|
REVISION_CONFLICT | Dự án đã đổi sau expectedRevision — đọc lại và thử lại |
ASSET_NOT_AUTHORIZED | Tài nguyên không được chọn trên trang đồng ý |
FRAME_NOT_FOUND / ELEMENT_NOT_FOUND | Khung hoặc phần tử được tham chiếu không tồn tại |
ELEMENT_TYPE_CHANGE_NOT_ALLOWED | patch_element không thể đổi loại phần tử |
INVALID_FRAME_ORDER / INVALID_DEFAULT_LOCALE | Thứ tự khung hoặc ngôn ngữ mặc định không hợp lệ |
DUPLICATE_ID | Một id xung đột với id hiện có |
PROJECT_SIZE_LIMIT | Vượt giới hạn khung, phần tử hoặc tải trọng |
RATE_LIMITED | Quá nhiều lượt gọi — HTTP 429 kèm Retry-After |
Ủy quyền và giới hạn
Server dùng OAuth 2.1 với PKCE và đăng nhập qua trình duyệt:
- Phạm vi:
projects:read,projects:write(chỉ khi bạn cho phép tạo hoặc chỉnh sửa),assets:readvàoffline_access. - Token truy cập có hiệu lực một giờ; token refresh có hiệu lực 30 ngày.
- Token truy cập yêu cầu một lượt cấp còn hiệu lực: thu hồi kết nối thì token hiện tại ngừng hoạt động ngay lập tức.
- Giới hạn tốc độ: 60 lượt gọi MCP mỗi phút trên gói miễn phí và 120 mỗi phút trên gói trả phí. Vượt giới hạn trả về HTTP 429 kèm
Retry-After: 60. - Thân yêu cầu giới hạn 2 MB; dự án giới hạn 20 khung và 100 phần tử mỗi khung.
Quyền của gói vẫn áp dụng như thường: các giới hạn về dự án, mẫu trả phí, phông tùy chỉnh và xuất hàng loạt không đổi, và không có phí AI lưu trữ — thiết kế và nội dung do AI kết nối cung cấp.
Bắt đầu với ảnh chụp của bạn
Tải các ảnh chụp gốc trong trình chỉnh sửa web trước. Sau đó ủy quyền dự án đó hoặc chọn tài nguyên riêng lẻ trên trang đồng ý. MCP không cung cấp công cụ tải tệp nhị phân; tệp đính kèm trong hội thoại không tự động khả dụng với dịch vụ này.
Thử prompt này:
Tạo một dự án ảnh chụp App Store tiếng Anh từ một mẫu có sẵn, dùng các tài nguyên đã được cấp quyền của tôi. Dùng tiêu đề ngắn và bố cục gọn gàng. Mở trình chỉnh sửa bằng công cụ trình duyệt có sẵn, kiểm tra ảnh chụp và sửa các lỗi hiển thị, rồi đưa tôi liên kết dự án để xuất trên web.
AI kết nối đảm nhiệm thiết kế và nội dung; MCP lưu các dự án có thể chỉnh sửa. get_project_preview trả về liên kết trình chỉnh sửa và hướng dẫn xem lại, không phải dữ liệu ảnh. Một agent có công cụ trình duyệt có thể mở trình chỉnh sửa, kiểm tra ảnh, sửa thiết kế qua MCP rồi tải lại an toàn để xem phiên bản mới nhất. Đăng nhập trình duyệt tách biệt với OAuth của MCP, và các thay đổi chưa lưu cần được giữ trước khi tải lại. Người dùng xem trước và xuất trong trình chỉnh sửa web.
Quản lý truy cập
Mở Settings → Connected AI tools để đổi các dự án/tài nguyên đã chọn hoặc thu hồi một kết nối. Công cụ không thể truy cập dự án chưa được chọn. Nếu website và một công cụ AI cùng chỉnh sửa một dự án, hãy đọc lại phiên bản mới nhất trước khi lưu các thay đổi xung đột.
Xem lại trên trình duyệt không cần Browserless hay hàng đợi kết xuất nền. MCP này cung cấp công cụ dự án và hướng dẫn xem lại bằng trình duyệt, không phải kết xuất đám mây. Nếu không có công cụ trình duyệt/ảnh, agent nên trả về liên kết trình chỉnh sửa và báo rằng việc kiểm tra trực quan còn treo, thay vì khẳng định đã xác minh.
Xử lý sự cố
| Triệu chứng | Cách xử lý |
|---|---|
invalid_redirect_uri: web clients require https redirect URIs | Dùng chuyển hướng loopback (http://127.0.0.1:<cổng>/callback hoặc http://localhost:<cổng>/callback) và để đăng ký loopback mặc định theo native client |
401 kèm WWW-Authenticate: Bearer resource_metadata=… | Phản hồi khám phá bình thường cho lượt gọi chưa xác thực — hoàn tất luồng OAuth trong ứng dụng của bạn |
| Ủy quyền liên tục hết hạn | Kết nối lại từ ứng dụng; lượt cấp bị thu hồi hoặc hết hạn làm token refresh vô hiệu |
| Ứng dụng hủy đăng nhập trình duyệt | Hoàn tất đăng nhập nhanh (một số ứng dụng hủy sau ~180 giây) rồi khởi động lại kết nối |
Phản hồi 429 RATE_LIMITED | Chờ Retry-After (60 giây) rồi thử lại; nâng gói trả phí để được 120 lượt gọi/phút |
Để có ghi chú riêng cho từng ứng dụng và ma trận kiểm chứng hiện tại, xem hướng dẫn xử lý sự cố của bộ kết nối.