Đã xem lại 2026-11-10 · Phiên bản API 2026-11-09 · Đọc Markdown
Thiết lập MCP
Một máy chủ MCP stdio cục bộ bao bọc cùng các dịch vụ dùng chung với UI và
REST API qua /api/v1. Bộ chuyển đổi chỉ gửi khóa sản phẩm của bạn đến API AiVideoEditor
đã cấu hình. Không dùng thông tin xác thực Supabase hay nhà cung cấp.
Điều kiện tiên quyết
Đây là bộ chuyển đổi từ mã nguồn, không phải gói đã phát hành hay kết nối hosted.
Có được quyền truy cập được ủy quyền vào kho mã AiVideoEditor, cài Node 22+, và chạy
npm ci tại thư mục gốc của kho. Tạo một khóa sản phẩm cho không gian làm việc tại
/app/developers chỉ với các phạm vi và quyền truy cập điểm đến cần thiết. Khóa chỉ
bản nháp không thể đăng hay lên lịch. Không bao giờ dán khóa vào prompt trò chuyện.
Chạy nó
export PUBLISHER_API_URL=https://app.example.com # HTTPS; http://localhost is allowed for dev
export PUBLISHER_API_KEY=pk_v1_… # create in /app/developers
node packages/mcp/bin/publisher-mcp.mjs # or: npm start --workspace packages/mcp
Tệp thực thi là một launcher thực sự (TypeScript + các import không có phần mở rộng được
giải quyết qua tsx). Mọi chẩn đoán đi đến stderr; stdout chỉ mang
lưu lượng giao thức. PUBLISHER_API_URL phải là HTTPS (HTTP thuần chỉ cho môi trường
phát triển loopback) và không được mang thông tin xác thực, truy vấn hay fragment.
Cấu hình máy client chung
{
"mcpServers": {
"autoposted": {
"command": "node",
"args": ["/absolute/path/to/packages/mcp/bin/publisher-mcp.mjs"],
"env": {
"PUBLISHER_API_URL": "https://app.example.com",
"PUBLISHER_API_KEY": "pk_v1_…"
}
}
}
}
Launcher yêu cầu Node 22+ và các phụ thuộc của không gian làm việc (tsx,
@modelcontextprotocol/sdk). Truyền tải MCP hosted với OAuth là công việc tương lai;
đừng giả định mọi máy client desktop hay hosted đều hỗ trợ bearer key được dán vào.
Các công cụ
| Công cụ | Đọc/Thay đổi | Ghi chú |
|---|---|---|
list_accounts | read | Tuân theo danh sách cho phép tài khoản của khóa |
get_capabilities | read | Định dạng, giới hạn, yêu cầu đồng ý |
create_upload_intent | mutate | Trả về hướng dẫn tải lên trực tiếp; dữ liệu media không bao giờ đi qua công cụ |
finalize_upload | mutate | ID phiên (+ biên nhận phần multipart); máy chủ tự quan sát byte/MIME |
create_draft | mutate | Nguồn + các biến thể điểm đến |
validate_post | read | Các vấn đề có cấu trúc theo điểm đến |
schedule_post | mutate | Một thời điểm, tối đa 90 ngày phía trước, yêu cầu expectedVersion |
publish_post | mutate | Ngữ nghĩa 202; không phải bằng chứng đã đăng |
get_post_status | read | Trạng thái theo điểm đến và liên kết gốc |
list_posts | read | Phân trang bằng con trỏ |
cancel_delivery | mutate | Chỉ khi vẫn chưa được nhận an toàn |
retry_delivery | mutate | Chỉ các thất bại đã biết; không bao giờ trùng lặp |
get_usage | read | Không có bộ đếm bài đăng còn lại |
Tham số công cụ bắt buộc
| Công cụ | Tham số bắt buộc |
|---|---|
list_accounts | Không có |
get_capabilities | Không có |
create_upload_intent | filename, declaredMime, declaredBytes |
finalize_upload | assetId, sessionId |
create_draft | caption, destinations |
validate_post | postId |
schedule_post | postId, scheduledAt, timezone, expectedVersion |
publish_post | postId |
get_post_status | postId |
list_posts | Không có |
cancel_delivery | deliveryId |
retry_delivery | deliveryId |
get_usage | Không có |
Các tham số tùy chọn bao gồm phân trang trên các công cụ liệt kê, idempotencyKey
trên các thao tác thay đổi, multipart.parts cho việc hoàn tất multipart, và media bản nháp
cùng các biến thể điểm đến. Schema công cụ runtime được trả về từ tools/list là có thẩm quyền
về các trường tùy chọn, cấu trúc lồng nhau và giới hạn xác thực.
Các công cụ thay đổi chấp nhận tham số tùy chọn idempotencyKey. Khi bỏ trống,
máy chủ sẽ tạo một khóa và phát lại nó trong mọi kết quả: kể cả các thất bại
truyền tải, nơi thao tác có thể đã đến được API (lỗi mang
transport_outcome_unknown cùng khóa đó). Các công cụ không bao giờ tự động thử lại
thao tác thay đổi; hãy thử lại với cùng khóa idempotency để tránh tạo thao tác trùng lặp.
Ví dụ quy trình làm việc của tác nhân
list_accounts+get_capabilities→ chọn các điểm đến hợp lệ.create_upload_intent→ tải byte trực tiếp →finalize_upload.create_draft→validate_post→ sửa hoặc bỏ chọn các điểm đến không hợp lệ.publish_post(hoặcschedule_post) → ghi lại các ID gửi đi.get_post_status(polling có giới hạn hoặc webhook của khách hàng): coi các phản hồirequires_actionlà hướng dẫn có thể hành động, ví dụ đồng ý TikTok.
Các máy client đã thử nghiệm
- Máy client TypeScript chính thức
@modelcontextprotocol/sdk, subprocess stdio thực với tệp thực thi đã được tài liệu hóa (initialize → tools/list → tools/call): đã thử nghiệm trongpackages/mcp/tests/stdio.test.ts, bao gồm các kiểm tra stdout sạch và thất bại khi khởi động. - Máy client SDK chính thức qua truyền tải trong bộ nhớ: cũng đã được bao phủ.
- Các máy client desktop (Claude Desktop, Cursor, v.v.): chưa thử nghiệm: cấu hình theo đoạn mã chung ở trên và báo cáo kết quả trước khi tuyên bố hỗ trợ.
Tương thích máy client
| Máy client hoặc truyền tải | Trạng thái | Thiết lập |
|---|---|---|
| SDK TypeScript chính thức qua subprocess stdio | Có kiểm thử tự động | Launcher của kho hiển thị ở trên |
| Truyền tải trong bộ nhớ của SDK chính thức | Có kiểm thử tự động | Chỉ bộ khung kiểm thử |
| Claude Desktop / các máy client desktop khác | Chưa xác minh thủ công | Máy client cục bộ hỗ trợ stdio; dùng đường dẫn launcher tuyệt đối |
| Kết nối hosted của ChatGPT | Không do bộ chuyển đổi này cung cấp | Đòi hỏi truyền tải hosted; JSON stdio cục bộ không phải connector hosted |
| MCP hosted với OAuth | Chưa triển khai | Công việc sản phẩm riêng |
Khắc phục sự cố
- Launcher không giải quyết được các phụ thuộc: chạy
npm citrong bản checkout mã nguồn được ủy quyền và kiểm tra phiên bản Node. Không thay bằng một gói công khai không liên quan. - Máy client không bao giờ khởi tạo: dùng đường dẫn launcher tuyệt đối và kiểm tra stderr. Không ghi đầu ra gỡ lỗi ra stdout.
401: xác minh khóa sản phẩm đã cấu hình còn hiện hành; tạo khóa thay thế trong UI nếu đã bị thu hồi.403: kiểm tra các phạm vi và giới hạn tài khoản.transport_outcome_unknown: giữ lại khóa idempotency được trả về và thử lại thao tác giống hệt với khóa đó, không bao giờ dùng khóa mới.requires_action: chuyển các hướng dẫn được cung cấp cho một người có thẩm quyền; tác nhân không thể cung cấp sự đồng ý của con người cho TikTok.
Xử lý thông tin xác thực
Khóa sản phẩm chỉ được gửi duy nhất đến API AiVideoEditor đã cấu hình
(Authorization: Bearer). Nó không bao giờ được gửi đến các nhà cung cấp mô hình hay mạng
xã hội, không bao giờ được ghi nhật ký, và các URL được xác thực để khóa không thể
đi theo chuyển hướng hay thoát khỏi origin đã cấu hình.