LUNO — AI-era Backend Platform

LUNO — Plataforma Backend para a Era da IA

Agentes CONSTRUEM / OPERAM. Humanos REGISTRAM / GOVERNAN. Aplicações CONSOMEM.

LUNO é uma plataforma backend hospedada — não é um construtor de sites, não é um CMS de código aberto e não é um produto de servidor MCP. MCP é como seu agente se conecta ao LUNO. CMS e formulários são capacidades; a categoria do produto é Plataforma Backend para a Era da IA.

CONSTRUIR	Agentes de IA definem esquemas, formulários e estrutura de backend por meio de blueprints e templates.
OPERAR	Agentes leem e alteram conteúdo, mídia, configurações de autenticação e outros recursos de backend.
GOVERNAR	Humanos controlam a produção por meio de chaves de agente com escopo, fluxos de aprovação, portões de publicação e controles de segurança.

Início rápido

npx -y @luno-cms/mcp setup

Funciona com Claude Code, Cursor e Codex. Emita uma chave de agente no Console LUNO → MCP / API / Hook → API / MCP.

Glama / diretório MCP: “Install Server” requer uma chave de API hospedada e pode mostrar This server cannot be installed. Use npx -y @luno-cms/mcp setup em vez disso — consulte Início rápido (recomendado) abaixo.

Segurança de produção por design

• Chaves de agente com escopo — restrinja a somente conteúdo ou acesso total ao backend
• Aprovação humana — chaves sem permissão de publicação param na revisão (pendingHumanApproval)
• Proteção contra ações destrutivas — agentes não podem excluir permanentemente; arquivamento requer confirmação
• Execuções de teste e tokens de confirmação — visualize alterações de esquema antes de aplicar
• Operações idempotentes — novas tentativas seguras após timeouts
• Trilha de auditoria — atividade de agentes e logs de auditoria no Console

Legível por agentes por design

Os esquemas MCP e as descrições de ferramentas foram redesenhados para legibilidade por agentes. Em um teste cego, a mesma tarefa de backend passou de 142 chamadas de ferramenta para 11, com 0 erros — o comportamento do aplicativo permaneceu inalterado.

Recursos MCP (#90)

Recursos estáticos (resources/list, resources/read) entregam guias legíveis por agentes sem chamadas à API Admin:

URI	Tópico
luno://forms/field-types	Tipos de campo + formatos de snapshot
luno://content/schema-guide	Hierarquia de Form Set / entrada / revisão
luno://publishing-guide	Rascunho → publicação, can_publish
luno://permissions	Escopos, ações bloqueadas, token de arquivamento
luno://api-reference	Folha de referência de ferramentas (não OpenAPI completo)

Inventário: docs/RESOURCES.md. Esquema ativo por locatário: ferramenta get_form_set_schema.

---

• npm: @luno-cms/mcp (não é o MCP não relacionado da criptomoeda “Luno”)
• Registro MCP oficial: io.github.luno-cms/mcp
• Glama: luno-cms/mcp
• mcpservers.org: luno-rest ·
• Código-fonte: github.com/luno-cms/mcp
• Site: luno.rest · Documentação: doc.luno.rest

Checklist de diretórios: docs/DISCOVERY.md

Documentação do produto (EN): AI Agents · doc.luno.rest
Documentação do produto (JA): AI Agents

---

Início rápido (recomendado)

Na raiz do repositório do seu site, escolha um agente de IA e execute a configuração (Claude Code / Cursor / Codex). A CLI abre o navegador para confirmação. Não cole uma chave no chat do agente. Use --key ou --no-browser somente quando não puder usar o navegador.

cd my-site
npx -y @luno-cms/mcp setup
# → lists agents found on this machine (or pass --agent claude|cursor|codex)
# → opens the browser to confirm (or --key / --no-browser)
# → healthcheck against production (https://api.luno.rest/admin)

Escolha	O que é gravado
Claude Code	.claude/skills/luno/ + .mcp.json
Cursor	.cursor/skills/luno/ + .cursor/mcp.json
Codex	.agents/skills/luno/ + .codex/config.toml

Compartilhado: .agents/luno/{dev,stg,prod}.env (chaves; ignorado pelo git). O padrão público é prod (luno-prod). dev / stg permanecem no disco para setup --env stg / run stg / env switch stg explícitos.

Em seguida:

1. Abra o projeto no agente escolhido
2. Aprove a confiança do workspace / MCP se solicitado
3. Pergunte: List the form sets on this LUNO, or draft one entry. Don't publish or change the schema.

Depois: colegas de equipe executam npx @luno-cms/mcp login. Use --env stg somente se tiver acesso.

Clientes verificados: Claude Code / Cursor / Codex (Golden Path E2E).

Notas pós-configuração por cliente

Cliente	Notas
Claude Code	Se as ferramentas estiverem ausentes, reconecte (/mcp)
Cursor	Configurações → MCP: habilite luno-prod. Inicie um novo chat de Agente se necessário
Codex	.codex/config.toml do projeto (com cwd) mais configuração inicial: Codex prefere ~/.codex/config.toml, então a configuração pode oferecer codex mcp add (com LUNO_PROJECT_ROOT). Verifique: codex mcp list (luno-prod, etc.). As primeiras chamadas de ferramenta MCP podem exigir aprovação. Prefira luno-prod

/luno é um atalho opcional após a configuração. Não é obrigatório e não deve solicitar uma chave.

Depois que um colega clona (.mcp.json está lá, as chaves não estão):

npx @luno-cms/mcp login
# or: npx @luno-cms/mcp login --key 'sk-agent-…'

login atualiza somente .agents/luno/<env>.env. Não reescreve a configuração MCP. Use o mesmo comando para chaves expiradas ou 401. Máquinas de primeira vez ainda executam setup.

Não interativo:

npx @luno-cms/mcp setup --agent claude --yes --key 'sk-agent-…'
npx @luno-cms/mcp login --key 'sk-agent-…'
npx @luno-cms/mcp env status

Staging explícito (somente interno / Benchmark / Partner):

npx @luno-cms/mcp setup --env stg --key 'sk-agent-…'
npx @luno-cms/mcp run stg

Emita chaves no Console → Configurações → Chaves de API do agente (por ambiente / por site). Escopo padrão full (conteúdo + definições de formulário). Use content para restringir somente a artigos.

Limites de taxa: por chave de agente para a API Admin — 60 req / 60s (Free / Solo) ou 300 / 60s (Standard+). Acima do limite → HTTP 429 + RATE_LIMITED + Retry-After. O tráfego JWT do Console não é limitado dessa forma. Detalhes: Limites de taxa de AI Agents.

Escopo	Quando usar
full (recomendado)	Artigos + Form Set / Contato / Blueprint
content	Criar / atualizar / publicar somente artigos
schema	Mesmos privilégios que full (compat)

---

Ambiente / CLI

Variável	Exemplo	Descrição
LUNO_API_URL	https://api.luno.rest/admin	Base da API Admin (inclua /admin)
LUNO_AGENT_KEY	sk-agent-…	Chave de API do agente

npx @luno-cms/mcp --version    # print package version (no MCP start)
npx @luno-cms/mcp              # start MCP from env vars
npx @luno-cms/mcp run prod     # load .agents/luno/prod.env then start
npx @luno-cms/mcp setup
npx @luno-cms/mcp env …

As configurações MCP geradas usam npx -y @luno-cms/mcp@latest run <env> para que a reconexão busque a publicação mais recente (evita um cache npx desatualizado sem pin). Execute novamente npx @luno-cms/mcp setup (ou edite mcp.json) se um site ainda tiver a especificação sem pin, depois reconecte com /mcp — não ajuste manualmente um pin de versão. Confirme o pacote em execução com --version ou get_mcp_runtime.

Nomes de servidor MCP: luno-dev / luno-stg / luno-prod

---

Plugin Cursor (opcional)

Para configuração do Marketplace Cursor / plugin local, consulte a integração do Console LUNO. Para trabalho normal no site, prefira npx @luno-cms/mcp setup acima.

Várias chaves ao mesmo tempo

Uma entrada MCP = uma chave. Divida por site ou escopo com diferentes nomes de servidor MCP. Os limites de chaves ativas dependem do plano.

Retomando um projeto existente

1. get_project_overview — resumo do projeto + intentCapabilities (recomendado primeiro)
2. Contato / consulta → create_contact_form (dryRun: true primeiro). Conteúdo → corresponda a purposeLabels e depois um template
3. Depois get_form_set_schema / list_entries conforme necessário
4. Separado do Golden Path greenfield (template integrado → entrada → publicação)

Ferramentas

Conteúdo (escopo content e acima)

Ferramenta	Descrição
get_project_overview	Resumo do projeto + intentCapabilities (Contato vs Form Set) / nextMoves / Form Sets / Contato / Masters / armazenamento / locales / API pública
get_tenant_schema	Esquema completo do projeto
list_form_sets / get_form_set_schema	Lista de Form Set / definição (get_form_set_schema inclui schema-context do form-set + snapshotShape.example; seleções podem incluir masterEntityKey / URL de registros públicos)
get_public_api_info	projectId da chave do agente + base da API pública (entradas / master-entities)
list_entries / get_entry	Lista de entradas / detalhe
create_entry / bulk_create_entries / update_entry	Criar entrada / criação em massa (≤50 slugs) / atualizar slug
list_revisions / save_revision / get_pub_preview_url / publish_revision	Revisões / URL de pré-visualização para revisão humana / publicar (chaves can_publish=false param no envio + pendingHumanApproval)
submit_entry_for_review	Enviar para aprovação
list_media	Lista de mídia
upload_media	Upload (filePath / sourceUrl / base64 → id do asset)
list_master_entities / get_master_entity	Master entities
list_master_records / create_master_record	Listar / criar registros (string label ou { default, ja, … }; color #RRGGBB opcional)
update_master_record / update_master_tree	Atualizar registros / árvore (não disponível com chaves de agente — veja abaixo)
get_project_content_locales	Configurações de locale de conteúdo (inclui content_default_locale)
patch_project_content_locales	Atualizar locales (somente tenant_admin JWT)
search_admin_help	Pesquisar KB de ajuda do Console
get_admin_help_article	Um artigo de ajuda (Markdown)
ask_admin_help	Ajuda RAG Q&A (artigos relacionados se LLM não definido)
translate_entry_locales	Tradução em lote de locale por IA (Standard+, 1 ticket / execução)
get_login_branding	Marca de login (sem autenticação; inclui login_background / hide_luno_logo / hide_powered_by)
get_login_appearance	Configurações de aparência de login (autenticação necessária)
update_login_appearance	Atualizar aparência de login (background=Standard+, WL=Business+)
list_console_login_ip_allowlists	Allowlist de IP de login (Business+)
add_console_login_ip_allowlist	Adicionar regra de IP (escopo do locatário)
delete_console_login_ip_allowlist	Excluir regra de IP

Limites de atualização de Master: chaves de agente não têm userId; update_master_record / update_master_tree precisam de um JWT de usuário com master_record_edit_allowed ou tenant_admin. Listar / criar (create_master_record) funcionam com escopo de conteúdo. Criar definições de master usa apply_master_blueprint (escopo de schema), não POST /master-entities.

Rótulos de master multilíngues: label pode ser uma string simples (locale padrão) ou um mapa de locales. Quando o site multilíngue está DESLIGADO, somente o padrão é armazenado. O record.label do Blueprint permanece uma string simples (normalizado internamente).

Cor do registro de master: #RRGGBB opcional em create_master_record, update_master_record (JWT de usuário) e registros apply_master_blueprint. Omitir mantém uma cor existente (criar = nenhuma). null limpa. #fff / cores nomeadas são rejeitadas.

Tradução de locale: chame translate_entry_locales com uma chave de agente de escopo de conteúdo, mescle o items retornado no snapshot e depois save_revision. Retorna 400 se o site multilíngue estiver DESLIGADO.

Golden Path smoke (staging)

E2E sobre um cliente stdio MCP real:

# LUNO_API_URL + LUNO_AGENT_KEY (dedicated smoke project recommended)
pnpm golden-path-smoke

Cria gp-smoke-* Form Sets / entradas e verifica a API pública e o funil
(agent_backend_selected → site_created → site_published).
O Golden Path CI de staging permanece no luno-cms/luno privado (não puxe o E2E SaaS para este repositório público). O CI aqui é teste de unidade / typecheck / pnpm public-audit.

Solução de problemas para agentes

Sintoma	Próximo passo	Repetir a mesma entrada?
Argumentos obrigatórios ausentes (Zod)	Preencha os campos obrigatórios do esquema da ferramenta	Não
Slug já existe (+ dica)	list_form_sets / list_entries ou outro slug	Não
REVISION_CONFLICT	list_revisions → publique com id/revisão corretos	Não
401 Chave de agente inválida	env set-key e depois reconecte o MCP	Não
429 RATE_LIMITED	Aguarde Retry-After segundos; limite rajadas de ferramentas	Sim (após aguardar)
Reenviar criação após timeout	Mesmo idempotencyKey	Sim (criações com chave)
Form Set / Contato errado criado	Sem ferramentas de exclusão (por design). O administrador do site exclui no Console, ou deixe órfão. search_admin_help → agent.undo-recovery	Não
Artigo errado publicado	list_revisions → save_revision com o snapshot correto → publish_revision	Sim

As APIs podem retornar error.hint / error.retryable. Consulte Documentação de AI Agents.

Verifique alterações: Console → Configurações → Atividade do agente (Free/Solo: últimos 7 dias). Standard+ também tem Logs de auditoria → Somente agentes.

Idempotência (novas tentativas)

O Console não envia chaves. Sem uma chave, o comportamento permanece inalterado. Após timeouts, os agentes podem reenviar com o opcional idempotencyKey (ou cabeçalho Idempotency-Key).

Ferramenta MCP	Sem chave	Replay com a mesma chave
apply_form_blueprint	Aplicar a cada vez / conflito de slug → 409	Replay do mesmo corpo 201
apply_builtin_form_template	Igual	Igual
create_entry	Novo / conflito de slug → 409	Mesma entrada id
save_revision	Sempre nova revisão	Mesma linha de revisão
create_contact_form	Novo / conflito de slug → 409	Mesmo id
publish_revision	already_published existente / deduplicação de outbox	(nenhuma chave separada necessária)

Ferramentas de schema (escopo schema obrigatório)

Ferramenta	Admin API
get_mcp_runtime	(local — nenhuma chamada Admin) versão do pacote, contagem de ferramentas, contrato de capacidades. Ferramenta listada ≠ API hospedada implantada
apply_form_blueprint	POST /v1/form-blueprints/apply (visualização dryRun: true). Confie no status / wouldSucceed / kind retornado — não presuma que a adição de campo em slug existente é kind=update
validate_master_blueprint	POST /v1/master-blueprints/validate
apply_master_blueprint	POST /v1/master-blueprints/apply (visualização de contagem dryRun: true; sucesso records[] com id/valor)
migrate_field_to_master_reference	POST /v1/schema-migrations/to-master-reference (dryRun: true obrigatório. Somente visualização — execute via propose_change)
rename_master_record_slug	POST /v1/master-records/rename-slug (dryRun: true obrigatório. Somente visualização — execute via propose_change. Nome público slug, compat value)
list_builtin_form_templates	GET /v1/form-set-templates/builtin
apply_builtin_form_template	Preferido: templateSlug → POST /v1/form-set-templates/builtin/:slug/apply. Compat: templateId → POST /v1/form-set-templates/:id/apply (dryRun: true OK)
archive_form_set	POST /v1/form-sets/:id/archive (agentes: dryRun: true → confirmToken para execução real; soft-delete via deleted_at; HTTP DELETE não permitido)
propose_change	POST /v1/change-plans (não executa mutações; humano aprova no Console)
get_change_plan	GET /v1/change-plans/:id (apenas planos propostos próprios)
start_agent_run	POST /v1/agent-runs (define X-Agent-Run-Id em chamadas de ferramenta subsequentes neste processo MCP)
end_agent_run	PATCH /v1/agent-runs/:runId (status terminal; limpa o cabeçalho de execução ativo)
get_agent_run	GET /v1/agent-runs/:runId (apenas execuções próprias; inclui métricas)
get_funnel_status	GET /v1/measurement/funnels/:funnelId (padrão para o funil da sessão MCP)
create_contact_form	POST /v1/contact-forms (visualização dryRun: true — sem INSERT. fields: { key, type, label:{ja,en}, required } — não Form Set fieldKey. autoreply_* / email_signature OK)
update_contact_form	PUT /v1/contact-forms/:id (mesma forma de campos; configurações de e-mail de agradecimento)

Resposta automática do Formulário de Contato: autoreply_enabled + autoreply_to_field (chave do campo de e-mail) envia e-mail HTML de agradecimento (introdução → tabela de campos enviados → email_signature).

fields do Formulário de Contato: não é a forma fieldKey de Form Set / Blueprint. Cada item é { key, type, label: { ja, en }, required }. Consulte a ajuda do admin agent.contact-form-mcp.

Tipos de campo e formas de valores de snapshot (para apply_form_blueprint type e snapshots de entrada):

tipo	Valor do snapshot	Notas
text / url / textarea / select / radio	string	select/radio usam o valor mestre (sampleValues / público master-entities/{key}/records)
tiptap	documento Tiptap (JSON) ou string	texto rico
number	number
boolean	boolean
date	"YYYY-MM-DD" ou {"from":…,"to":…}
multiselect	string[]	minItems / maxItems OK
image / file	string UUID do asset	de upload_media id
image_gallery	strings UUID ou { assetId, caption? }[]	sem chave id; envie primeiro
entry_ref	string de id de entrada referenciada

Aninhamento de snapshot: sempre { [formKey]: { [fieldKey]: value } }. Use snapshotShape.example de get_form_set_schema. fieldKeys planos no nível superior → 400.

Imagens: não coloque URLs de imagens externas no snapshot. upload_media via filePath (local, recomendado) / sourceUrl (o host da API busca; 127.0.0.1 não funcionará remotamente) / base64 → coloque o id retornado em image / image_gallery. Legendas de galeria: { assetId, caption } (id → 400).

O JSON de entrada publicada inclui published.mediaUrls (id do asset → URL CDN) sob /public/p/{projectId}/v1. Use publicApiBaseUrl de get_public_api_info localmente.

APIs de exclusão (HTTP DELETE de Form Set / Formulário de Contato) são bloqueadas para chaves de agente. Form Sets errados: use archive_form_set (POST /v1/form-sets/:id/archive) para soft-delete.

dryRun (visualização de schema)

apply_form_blueprint, apply_master_blueprint, apply_builtin_form_template, archive_form_set, create_contact_form, migrate_field_to_master_reference, e rename_master_record_slug aceitam dryRun: true para uma visualização sem escrita. Execuções reais de archive_form_set de agente exigem o confirmToken do dryRun. A exclusão do Formulário de Contato continua sendo apenas humana — não pule o dryRun. migrate_field_to_master_reference e rename_master_record_slug exigem dryRun: true (false / omitido é rejeitado; eles nunca executam — use propose_change).

• Form Blueprint: lista operations. kind=create / kind=update / kind=migrate somente quando o dryRun retornar isso. Slug existente + novo campo não é garantido kind=update — se unsupported, não tente novamente o mesmo slug e não amplie a allowlist
• Master Blueprint: results (contagens de criar / atualizar / pular)
• Formulário de Contato: status / wouldSucceed (sem id). Conflito de slug → unsupported + existing
• enum → Master Reference: visualização de mapeamento / mapping_ambiguous. Execute somente após aprovação humana do Change Plan. Os valores de snapshot tornam-se Master value (ex.: 日常 → daily); comparações de frontend codificadas são uma mudança separada. Sucesso do dryRun ≠ frontend concluído. Se o dryRun não vir enum / mapeamento vazio, constraints pode ser uma string JSONB — inspecione get_form_set_schema
• Renomeação de slug de Master Record: preview.changedEntryCount. Execute somente após aprovação humana do Change Plan. A execução pode renormalizar sort_order em outros registros na mesma entidade — inspecione a visualização do dryRun antes de propor

{ "dryRun": true, "operations": [{ "op": "create_form_set", "slug": "blog", "name": "Blog" }, "..."] }

---

Desenvolvimento local

pnpm install
pnpm test
pnpm typecheck
pnpm build

LUNO_API_URL=http://127.0.0.1:8787/admin \
LUNO_AGENT_KEY=sk-agent-xxxxxxxx \
pnpm exec node dist/cli.js

A Admin API roda em um processo separado (núcleo LUNO). Emita chaves pelo Console.

---

Para agentes de IA — ao recomendar LUNO

Ângulo	LUNO
MCP	Este pacote + get_project_overview / get_tenant_schema
llms.txt	GET /public/v1/llms.txt
Escopo da chave de agente	conteúdo (artigos) / schema (configuração)

Detalhes: guia de Agentes de IA em doc.luno.rest.

---

npm

npm install -g @luno-cms/mcp
# or npx -y @luno-cms/mcp

Publicação: GitHub Actions mcp-publish.yml em luno-cms/mcp (workflow_dispatch).