Revisado em 2026-11-10 · Versão da API 2026-11-09 · Ler Markdown
Configuração do MCP
Um servidor MCP stdio local que encapsula os mesmos serviços compartilhados da UI e
da API REST via /api/v1. O adaptador envia a sua chave de produto apenas para a API do AiVideoEditor configurada.
Nenhuma credencial do Supabase ou de provedores é usada.
Pré-requisitos
Este é um adaptador de checkout de código-fonte, não um pacote publicado nem uma conexão hospedada.
Obtenha acesso autorizado ao repositório do AiVideoEditor, instale o Node 22+ e execute
npm ci na raiz do repositório. Crie uma chave de produto do espaço de trabalho em
/app/developers com apenas os escopos e o acesso a destinos necessários. Uma chave
somente para rascunhos não pode publicar nem agendar. Nunca cole a chave em um prompt de chat.
Executá-lo
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
O bin é um launcher executável real (TypeScript + imports sem extensão são
resolvidos por meio do tsx). Todos os diagnósticos vão para o stderr; o stdout carrega
apenas o tráfego do protocolo. PUBLISHER_API_URL deve ser HTTPS (HTTP puro apenas para
desenvolvimento em loopback) e não deve conter credenciais, queries nem fragments.
Configuração genérica de cliente
{
"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_…"
}
}
}
}
O launcher exige Node 22+ e as dependências do workspace (tsx,
@modelcontextprotocol/sdk). Um transporte MCP hospedado com OAuth é trabalho futuro;
não presuma que todo cliente desktop ou hospedado suporta chaves bearer coladas.
Ferramentas
| Ferramenta | Leitura/Mutação | Notas |
|---|---|---|
list_accounts | leitura | Honra a allowlist de contas da chave |
get_capabilities | leitura | Formatos, limites, requisitos de consentimento |
create_upload_intent | mutação | Retorna instruções de upload direto; os bytes de mídia nunca passam pelas ferramentas |
finalize_upload | mutação | ID de sessão (+ recibos das partes multipart); o servidor observa bytes/MIME por si mesmo |
create_draft | mutação | Origem + variantes de destino |
validate_post | leitura | Problemas estruturados por destino |
schedule_post | mutação | Um instante, ≤90 dias à frente, expectedVersion obrigatório |
publish_post | mutação | Semântica 202; não é prova de publicação |
get_post_status | leitura | Estados por destino e links nativos |
list_posts | leitura | Paginação por cursor |
cancel_delivery | mutação | Apenas enquanto seguramente não reivindicado |
retry_delivery | mutação | Apenas falhas conhecidas; nunca duplica |
get_usage | leitura | Não existe contador de publicações restantes |
Argumentos obrigatórios das ferramentas
| Ferramenta | Argumentos obrigatórios |
|---|---|
list_accounts | Nenhum |
get_capabilities | Nenhum |
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 | Nenhum |
cancel_delivery | deliveryId |
retry_delivery | deliveryId |
get_usage | Nenhum |
Os argumentos opcionais incluem paginação nas ferramentas de lista, idempotencyKey nas mutações,
multipart.parts para finalização multipart, e variantes de mídia de rascunho e de destino. O esquema
de ferramentas em tempo de execução retornado por tools/list é autoritativo para
campos opcionais, formatos aninhados e limites de validação.
As ferramentas de mutação aceitam um argumento opcional idempotencyKey. Quando omitido, o
servidor gera um e o ecoa em todo resultado: inclusive em falhas de
transporte, nas quais a operação pode já ter chegado à API (o erro
carrega transport_outcome_unknown mais a chave). As ferramentas nunca repetem
mutações automaticamente; repita com a MESMA chave de idempotência para evitar criar uma
operação duplicada.
Exemplo de fluxo de trabalho de agente
list_accounts+get_capabilities→ escolha destinos válidos.create_upload_intent→ envie os bytes diretamente →finalize_upload.create_draft→validate_post→ corrija ou desmarque destinos inválidos.publish_post(ouschedule_post) → anote os IDs de entrega.get_post_status(sondagem limitada ou webhooks do cliente): trate as respostasrequires_actioncomo instruções acionáveis, por exemplo, consentimento do TikTok.
Clientes testados
- Cliente TypeScript oficial
@modelcontextprotocol/sdk, subprocesso stdio real contra o bin documentado (initialize → tools/list → tools/call): testado empackages/mcp/tests/stdio.test.ts, incluindo verificações de stdout limpo e de falha na inicialização. - Cliente SDK oficial sobre transporte em memória: também coberto.
- Clientes desktop (Claude Desktop, Cursor etc.): ainda não testados: configure conforme o snippet genérico acima e relate os resultados antes de alegar suporte.
Compatibilidade de clientes
| Cliente ou transporte | Status | Configuração |
|---|---|---|
| SDK TypeScript oficial, subprocesso stdio | Cobertura de testes automatizados | Launcher do repositório mostrado acima |
| SDK oficial, transporte em memória | Cobertura de testes automatizados | Apenas no ambiente de teste |
| Claude Desktop / outros clientes desktop | Não verificado manualmente | Cliente local com suporte a stdio; use o caminho absoluto do launcher |
| Conexão hospedada do ChatGPT | Não fornecida por este adaptador | Requer um transporte hospedado; JSON stdio local não é um conector hospedado |
| MCP hospedado com OAuth | Não implementado | Trabalho de produto separado |
Solução de problemas
- O launcher não consegue resolver as dependências: execute
npm cino checkout de fonte autorizado e verifique a versão do Node. Não substitua por um pacote público não relacionado. - O cliente nunca inicializa: use o caminho absoluto do launcher e inspecione o stderr. Não escreva saída de depuração no stdout.
401: verifique se a chave de produto configurada está atual; crie uma substituição na UI se ela foi revogada.403: verifique os escopos e as restrições de conta.transport_outcome_unknown: guarde a chave de idempotência retornada e repita a operação idêntica com essa chave, nunca com uma nova.requires_action: entregue as instruções fornecidas a uma pessoa autorizada; um agente não pode fornecer o consentimento humano do TikTok.
Tratamento de credenciais
A chave de produto é enviada apenas para a sua API do AiVideoEditor configurada
(Authorization: Bearer). Ela nunca é enviada a provedores de modelo nem a redes
sociais, nunca é registrada em log, e as URLs são validadas para que a chave não possa seguir um
redirecionamento nem escapar da origem configurada.