Revisionato 2026-11-10 · Versione API 2026-11-09 · Leggi Markdown
Configurazione MCP
Un server MCP stdio locale che incapsula gli stessi servizi condivisi della UI e
della REST API via /api/v1. L'adattatore invia la tua product key solo all'API AiVideoEditor configurata.
Non vengono usate credenziali Supabase o di provider.
Prerequisiti
Questo è un adattatore da checkout sorgente, non un pacchetto pubblicato o una connessione ospitata.
Ottieni accesso autorizzato al repository AiVideoEditor, installa Node 22+, ed esegui
npm ci alla radice del repository. Crea una product key del workspace in
/app/developers con solo gli scope e l'accesso alle destinazioni necessari. Una chiave
solo bozze non può pubblicare o programmare. Non incollare mai la chiave in un prompt di chat.
Eseguirlo
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
Il bin è un vero launcher eseguibile (TypeScript + import senza estensione vengono
risolti attraverso tsx). Tutta la diagnostica va su stderr; stdout trasporta
solo traffico di protocollo. PUBLISHER_API_URL deve essere HTTPS (plain HTTP solo per
lo sviluppo su loopback) e non deve portare credenziali, query o frammenti.
Configurazione generica del client
{
"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_…"
}
}
}
}
Il launcher richiede Node 22+ e le dipendenze del workspace (tsx,
@modelcontextprotocol/sdk). Un transport MCP ospitato con OAuth è lavoro futuro;
non dare per scontato che ogni client desktop o ospitato supporti bearer key incollate.
Strumenti
| Strumento | Lettura/Mutazione | Note |
|---|---|---|
list_accounts | read | Rispetta la allowlist di account della chiave |
get_capabilities | read | Formati, limiti, requisiti di consenso |
create_upload_intent | mutate | Restituisce istruzioni di upload diretto; i byte dei media non passano mai attraverso gli strumenti |
finalize_upload | mutate | ID sessione (+ ricevute delle parti multipart); il server osserva da sé byte/MIME |
create_draft | mutate | Sorgente + varianti di destinazione |
validate_post | read | Problemi strutturati per destinazione |
schedule_post | mutate | Un istante, ≤90 giorni avanti, expectedVersion richiesta |
publish_post | mutate | Semantica 202; non prova di pubblicazione |
get_post_status | read | Stati per destinazione e link nativi |
list_posts | read | Paginazione a cursore |
cancel_delivery | mutate | Solo finché sicuramente non preso in carico |
retry_delivery | mutate | Solo fallimenti noti; mai duplicati |
get_usage | read | Non esiste alcun contatore di post rimanenti |
Argomenti richiesti degli strumenti
| Strumento | Argomenti richiesti |
|---|---|
list_accounts | Nessuno |
get_capabilities | Nessuno |
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 | Nessuno |
cancel_delivery | deliveryId |
retry_delivery | deliveryId |
get_usage | Nessuno |
Gli argomenti opzionali includono la paginazione sugli strumenti di lista, idempotencyKey sulle mutazioni,
multipart.parts per la finalizzazione multipart, e media delle bozze e varianti
di destinazione. Lo schema runtime degli strumenti restituito da tools/list fa autorità per
i campi opzionali, le forme annidate e i limiti di validazione.
Gli strumenti che mutano accettano un argomento opzionale idempotencyKey. Quando omesso, il
server ne genera uno e lo riporta in ogni risultato: inclusi i fallimenti di
transport, dove l'operazione può essere già arrivata all'API (l'errore
porta transport_outcome_unknown più la chiave). Gli strumenti non ripetono mai automaticamente
le mutazioni; ritenta con la STESSA chiave di idempotenza per evitare di creare un'operazione duplicata.
Esempio di flusso di lavoro dell'agente
list_accounts+get_capabilities→ scegli destinazioni valide.create_upload_intent→ carica i byte direttamente →finalize_upload.create_draft→validate_post→ correggi o deseleziona le destinazioni non valide.publish_post(oschedule_post) → annota gli ID di consegna.get_post_status(polling limitato o webhook del cliente): tratta le risposterequires_actioncome istruzioni azionabili, es. consenso TikTok.
Client testati
- Client TypeScript ufficiale
@modelcontextprotocol/sdk, subprocess stdio reale contro il bin documentato (initialize → tools/list → tools/call): testato inpackages/mcp/tests/stdio.test.ts, inclusi controlli di stdout pulito e fallimento all'avvio. - Client SDK ufficiale su transport in-memory: anch'esso coperto.
- Client desktop (Claude Desktop, Cursor, ecc.): non ancora testati: configura secondo lo snippet generico sopra e riporta i risultati prima di dichiarare supporto.
Compatibilità dei client
| Client o transport | Stato | Configurazione |
|---|---|---|
| SDK TypeScript ufficiale subprocess stdio | Copertura di test automatizzati | Launcher del repository mostrato sopra |
| SDK ufficiale transport in-memory | Copertura di test automatizzati | Solo harness di test |
| Claude Desktop / altri client desktop | Non verificato manualmente | Client locale con supporto stdio; usa il percorso assoluto del launcher |
| Connessione ospitata ChatGPT | Non fornita da questo adattatore | Richiede un transport ospitato; il JSON stdio locale non è un connettore ospitato |
| MCP ospitato con OAuth | Non implementato | Lavoro di prodotto separato |
Risoluzione dei problemi
- Il launcher non riesce a risolvere le dipendenze: esegui
npm cinel checkout sorgente autorizzato e verifica la versione di Node. Non sostituire con un pacchetto pubblico non correlato. - Il client non si inizializza mai: usa il percorso assoluto del launcher e ispeziona stderr. Non scrivere output di debug su stdout.
401: verifica che la product key configurata sia attuale; creane una sostituta nella UI se revocata.403: controlla gli scope e le restrizioni degli account.transport_outcome_unknown: conserva la chiave di idempotenza restituita e ritenta l'operazione identica con quella chiave, mai una nuova.requires_action: consegna le istruzioni fornite a una persona autorizzata; un agente non può fornire il consenso umano TikTok.
Gestione delle credenziali
La product key viene inviata solo alla tua API AiVideoEditor configurata
(Authorization: Bearer). Non viene mai inviata ai provider dei modelli o ai social
network, non viene mai registrata nei log, e gli URL sono validati così la chiave non può seguire un
redirect o sfuggire all'origin configurato.