Luno Cms

io.github.luno-cmsPublished by GitHub account luno-cmsv0.2.51Updated Oct 24, 2026

LUNO — AI-era Backend Platform (not Luno crypto). BUILD/OPERATE, REGISTER/GOVERN, CONSUME.

VerifiedSTDIODesktop onlyProductivity & WorkflowFiles & StorageDeveloper Tools

Overview

AI-generated overview

MCP server for the LUNO hosted backend platform, letting an AI agent build and operate CMS content, forms, media and schema through scoped agent keys.

What you can do
Inspect the project: overview, tenant schema, form sets, entries, revisions, media, master entities and records, public API info, content locales, and Console help articles via search or Q&A. Create and edit content: create, bulk-create and update entries, save revisions, get preview URLs, submit for review and publish. Manage media: list assets and upload from a local file path, a source URL or base64. Change schema: apply form and master blueprints, apply builtin templates, migrate fields to master references, rename record slugs, archive form sets, and propose change plans for human approval. Track agent runs and funnel status, and read static guide resources on field types, schema, and パ
When to use it
Use it when a site or application runs on the LUNO backend platform and you want an agent to draft or publish content, set up forms and schemas, or manage media without leaving the chat. It suits teams that want agent work gated by scoped keys, dry runs and human approval.
Requirements
Runs locally as an npm package (Node.js via npx). Needs LUNO_API_URL (admin API base, including /admin) and LUNO_AGENT_KEY, an agent API key issued in the LUNO Console. Network access to the LUNO admin API. Setup writes config for Claude Code, Cursor or Codex and stores keys in gitignored env files.
Before you install
Requires a secret agent key; the README says not to paste it into agent chat and to use the browser setup flow. Keys default to full scope (content plus form definitions); use content scope to limit to articles. Agents can create, update and publish content and upload media, and schema changes apply to the live backend. Deletes are blocked, but archive is a soft delete and some schema changes only execute after human approval. Rate limits apply per key.

Installation

In SourceWeft

  1. Open Luno Cms in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

LUNO — AI-era Backend Platform

Agents BUILD / OPERATE. Humans REGISTER / GOVERN. Applications CONSUME.

LUNO is a hosted backend platform — not a website builder, not an open-source CMS, and not an MCP server product. MCP is how your agent connects to LUNO. CMS and forms are capabilities; the product category is AI-era Backend Platform.

BUILDAI agents define schemas, forms, and backend structure via blueprints and templates.
OPERATEAgents read and change content, media, auth settings, and other backend resources.
GOVERNHumans control production through scoped agent keys, approval workflows, publish gates, and safety controls.

Quick start

bash
npx -y @luno-cms/mcp setup

Works with Claude Code, Cursor, and Codex. Issue an agent key in the LUNO Console → MCP / API / Hook → API / MCP.

Glama / MCP directory: “Install Server” requires a hosted API key and may show This server cannot be installed. Use npx -y @luno-cms/mcp setup instead — see Quick start (recommended) below.

Production safety by design

  • Scoped agent keys — restrict to content-only or full backend access
  • Human approval — keys without publish permission stop at review (pendingHumanApproval)
  • Destructive-action protection — agents cannot hard-delete; archive requires confirmation
  • Dry runs & confirmation tokens — preview schema changes before applying
  • Idempotent operations — safe retries after timeouts
  • Audit trail — agent activity and audit logs in Console

Agent-readable by design

MCP schemas and tool descriptions were redesigned for agent readability. In a blind test, the same backend task went from 142 tool calls to 11, with 0 errors — application behavior unchanged.

MCP Resources (#90)

Static Resources (resources/list, resources/read) ship agent-readable guides without Admin API calls:

URITopic
luno://forms/field-typesField types + snapshot shapes
luno://content/schema-guideForm Set / entry / revision hierarchy
luno://publishing-guideDraft → publish, can_publish
luno://permissionsScopes, blocked actions, archive token
luno://api-referenceTool cheat sheet (not full OpenAPI)

Inventory: docs/RESOURCES.md. Live per-tenant schema: get_form_set_schema tool.

Directory checklist: docs/DISCOVERY.md

Product docs (EN): AI Agents · doc.luno.rest
Product docs (JA): AI Agents

Quick start (recommended)

From your site repository root, pick one AI agent and run setup (Claude Code / Cursor / Codex). The CLI opens the browser to confirm. Do not paste a key into the agent chat. Use --key or --no-browser only when you cannot use the browser.

bash
cd my-sitenpx -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)
ChoiceWhat gets written
Claude Code.claude/skills/luno/ + .mcp.json
Cursor.cursor/skills/luno/ + .cursor/mcp.json
Codex.agents/skills/luno/ + .codex/config.toml

Shared: .agents/luno/{dev,stg,prod}.env (keys; gitignored). Public default is prod (luno-prod). dev / stg stay on disk for explicit setup --env stg / run stg / env switch stg.

Then:

  1. Open the project in the chosen agent
  2. Approve workspace trust / MCP if prompted
  3. Ask: List the form sets on this LUNO, or draft one entry. Don't publish or change the schema.

Later: teammates run npx @luno-cms/mcp login. Use --env stg only if you have access.

Verified clients: Claude Code / Cursor / Codex (Golden Path E2E).

Post-setup notes by client

ClientNotes
Claude CodeIf tools are missing, reconnect (/mcp)
CursorSettings → MCP: enable luno-prod. Start a new Agent chat if needed
CodexProject .codex/config.toml (with cwd) plus home config: Codex prefers ~/.codex/config.toml, so setup may offer codex mcp add (with LUNO_PROJECT_ROOT). Check: codex mcp list (luno-prod, etc.). First MCP tool calls may need approval. Prefer luno-prod

/luno is an optional shortcut after setup. It is not required, and it must not ask for a key.

After a teammate clones (.mcp.json is there, keys are not):

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

login refreshes .agents/luno/<env>.env only. It does not rewrite MCP config. Use the same command for expired keys or 401. First-time machines still run setup.

Non-interactive:

bash
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

Explicit staging (internal / Benchmark / Partner only):

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

Issue keys in Console → Settings → Agent API keys (per env / per site). Default scope full (content + form definitions). Use content to restrict to articles only.

Rate limits: per agent key to Admin API — 60 req / 60s (Free / Solo) or 300 / 60s (Standard+). Over limit → HTTP 429 + RATE_LIMITED + Retry-After. Console JWT traffic is not limited this way. Details: AI Agents rate limits.

ScopeWhen to use
full (recommended)Articles + Form Set / Contact / Blueprint
contentCreate / update / publish articles only
schemaSame privileges as full (compat)

Environment / CLI

VariableExampleDescription
LUNO_API_URLhttps://api.luno.rest/adminAdmin API base (include /admin)
LUNO_AGENT_KEYsk-agent-…Agent API key
text
npx @luno-cms/mcp --version    # print package version (no MCP start)npx @luno-cms/mcp              # start MCP from env varsnpx @luno-cms/mcp run prod     # load .agents/luno/prod.env then startnpx @luno-cms/mcp setupnpx @luno-cms/mcp env …

Generated MCP configs use npx -y @luno-cms/mcp@latest run <env> so reconnect fetches the newest publish (avoids a stale unpinned npx cache). Re-run npx @luno-cms/mcp setup (or edit mcp.json) if a site still has the unpinned spec, then /mcp reconnect — do not hand-bump a version pin. Confirm the running package with --version or get_mcp_runtime.

MCP server names: luno-dev / luno-stg / luno-prod

Cursor Plugin (optional)

For Cursor Marketplace / local plugin setup, see the LUNO Console onboarding. For normal site work, prefer npx @luno-cms/mcp setup above.

Multiple keys at once

One MCP entry = one key. Split by site or scope with different MCP server names. Active key limits depend on plan.

Resuming an existing project

  1. get_project_overview — project summary + intentCapabilities (recommended first)
  2. Contact / inquiry → create_contact_form (dryRun: true first). Content → match purposeLabels then a template
  3. Then get_form_set_schema / list_entries as needed
  4. Separate from greenfield Golden Path (builtin template → entry → publish)

Tools

Content (content scope and above)

ToolDescription
get_project_overviewProject summary + intentCapabilities (Contact vs Form Set) / nextMoves / Form Sets / Contact / Masters / storage / locales / public API
get_tenant_schemaFull project schema
list_form_sets / get_form_set_schemaForm Set list / definition (get_form_set_schema includes form-set schema-context + snapshotShape.example; selects may include masterEntityKey / public records URL)
get_public_api_infoAgent key projectId + public API base (entries / master-entities)
list_entries / get_entryEntry list / detail
create_entry / bulk_create_entries / update_entryCreate entry / bulk create (≤50 slugs) / update slug
list_revisions / save_revision / get_pub_preview_url / publish_revisionRevisions / preview URL for human review / publish (can_publish=false keys stop at submit + pendingHumanApproval)
submit_entry_for_reviewSubmit for approval
list_mediaMedia list
upload_mediaUpload (filePath / sourceUrl / base64 → asset id)
list_master_entities / get_master_entityMaster entities
list_master_records / create_master_recordList / create records (label string or { default, ja, … }; optional color #RRGGBB)
update_master_record / update_master_treeUpdate records / tree (not available with agent keys — see below)
get_project_content_localesContent locale settings (includes content_default_locale)
patch_project_content_localesUpdate locales (tenant_admin JWT only)
search_admin_helpSearch Console help KB
get_admin_help_articleOne help article (Markdown)
ask_admin_helpHelp RAG Q&A (related articles if LLM unset)
translate_entry_localesAI locale batch translate (Standard+, 1 ticket / run)
get_login_brandingLogin branding (no auth; includes login_background / hide_luno_logo / hide_powered_by)
get_login_appearanceLogin appearance settings (auth required)
update_login_appearanceUpdate login appearance (background=Standard+, WL=Business+)
list_console_login_ip_allowlistsLogin IP allowlist (Business+)
add_console_login_ip_allowlistAdd IP rule (tenant scope)
delete_console_login_ip_allowlistDelete IP rule

Master update limits: agent keys have no userId; update_master_record / update_master_tree need a user JWT with master_record_edit_allowed or tenant_admin. List / create (create_master_record) work with content scope. Creating master definitions uses apply_master_blueprint (schema scope), not POST /master-entities.

Multilingual master labels: label may be a plain string (default locale) or a locale map. When site multilingual is OFF, only default is stored. Blueprint record.label stays a plain string (normalized internally).

Master record color: optional #RRGGBB on create_master_record, update_master_record (user JWT), and apply_master_blueprint records. Omit keeps an existing color (create = none). null clears. #fff / named colors are rejected.

Locale translation: call translate_entry_locales with a content-scope agent key, merge returned items into the snapshot, then save_revision. Returns 400 if site multilingual is OFF.

Golden Path smoke (staging)

E2E over a real MCP stdio client:

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

Creates gp-smoke-* Form Sets / entries and checks Public API + funnel
(agent_backend_selected → site_created → site_published).
Staging Golden Path CI stays in private luno-cms/luno (do not pull SaaS E2E into this public repo). CI here is unit test / typecheck / pnpm public-audit.

Troubleshooting for agents

SymptomNext stepRetry same input?
Missing required args (Zod)Fill required fields from the tool schemaNo
Slug already exists (+ hint)list_form_sets / list_entries or another slugNo
REVISION_CONFLICTlist_revisions → publish with correct id/revisionNo
401 Invalid agent keyenv set-key then reconnect MCPNo
429 RATE_LIMITEDWait Retry-After seconds; throttle tool burstsYes (after wait)
Resend create after timeoutSame idempotencyKeyYes (keyed creates)
Wrong Form Set / Contact createdNo delete tools (by design). Site admin deletes in Console, or leave orphan. search_admin_help → agent.undo-recoveryNo
Published wrong articlelist_revisions → save_revision with correct snapshot → publish_revisionYes

APIs may return error.hint / error.retryable. See AI Agents docs.

Verify changes: Console → Settings → Agent activity (Free/Solo: last 7 days). Standard+ also has Audit logs → Agents only.

Idempotency (retries)

The Console does not send keys. Without a key, behavior is unchanged. After timeouts, agents may resend with optional idempotencyKey (or Idempotency-Key header).

MCP toolNo keySame key replay
apply_form_blueprintApply each time / slug clash → 409Replay same 201 body
apply_builtin_form_templateSameSame
create_entryNew / slug clash → 409Same entry id
save_revisionAlways new revisionSame revision row
create_contact_formNew / slug clash → 409Same id
publish_revisionExisting already_published / outbox dedupe(no separate key needed)

Schema tools (schema scope required)

ToolAdmin API
get_mcp_runtime(local — no Admin call) package version, tool count, capability contract. Listed tool ≠ hosted API deployed
apply_form_blueprintPOST /v1/form-blueprints/apply (dryRun: true preview). Trust returned status / wouldSucceed / kind — do not assume existing-slug field add is kind=update
validate_master_blueprintPOST /v1/master-blueprints/validate
apply_master_blueprintPOST /v1/master-blueprints/apply (dryRun: true count preview; success records[] with id/value)
migrate_field_to_master_referencePOST /v1/schema-migrations/to-master-reference (dryRun: true required. Preview only — execute via propose_change)
rename_master_record_slugPOST /v1/master-records/rename-slug (dryRun: true required. Preview only — execute via propose_change. Public name slug, compat value)
list_builtin_form_templatesGET /v1/form-set-templates/builtin
apply_builtin_form_templatePreferred: templateSlug → POST /v1/form-set-templates/builtin/:slug/apply. Compat: templateId → POST /v1/form-set-templates/:id/apply (dryRun: true OK)
archive_form_setPOST /v1/form-sets/:id/archive (agents: dryRun: true → confirmToken for real run; soft-delete via deleted_at; HTTP DELETE not allowed)
propose_changePOST /v1/change-plans (does not execute mutations; human approves in Console)
get_change_planGET /v1/change-plans/:id (own proposed plans only)
start_agent_runPOST /v1/agent-runs (sets X-Agent-Run-Id on subsequent tool calls in this MCP process)
end_agent_runPATCH /v1/agent-runs/:runId (terminal status; clears active run header)
get_agent_runGET /v1/agent-runs/:runId (own runs only; includes metrics)
get_funnel_statusGET /v1/measurement/funnels/:funnelId (defaults to MCP session funnel)
create_contact_formPOST /v1/contact-forms (dryRun: true preview — no INSERT. fields: { key, type, label:{ja,en}, required } — not Form Set fieldKey. autoreply_* / email_signature OK)
update_contact_formPUT /v1/contact-forms/:id (same fields shape; thank-you email settings)

Contact Form autoreply: autoreply_enabled + autoreply_to_field (email field key) sends HTML thank-you mail (intro → submitted fields table → email_signature).

Contact Form fields: not Form Set / Blueprint fieldKey shape. Each item is { key, type, label: { ja, en }, required }. See admin-help agent.contact-form-mcp.

Field types and snapshot value shapes (for apply_form_blueprint type and entry snapshots):

typeSnapshot valueNotes
text / url / textarea / select / radiostringselect/radio use master value (sampleValues / public master-entities/{key}/records)
tiptapTiptap doc (JSON) or stringrich text
numbernumber
booleanboolean
date"YYYY-MM-DD" or {"from":…,"to":…}
multiselectstring[]minItems / maxItems OK
image / fileasset UUID stringfrom upload_media id
image_galleryUUID strings or { assetId, caption? }[]no id key; upload first
entry_refreferenced entry id string

Snapshot nesting: always { [formKey]: { [fieldKey]: value } }. Use snapshotShape.example from get_form_set_schema. Flat top-level fieldKeys → 400.

Images: do not put external image URLs in the snapshot. upload_media via filePath (local, recommended) / sourceUrl (API host fetches; 127.0.0.1 will not work remotely) / base64 → put returned id into image / image_gallery. Gallery captions: { assetId, caption } (id → 400).

Published entry JSON includes published.mediaUrls (asset id → CDN URL) under /public/p/{projectId}/v1. Use publicApiBaseUrl from get_public_api_info locally.

Delete APIs (Form Set / Contact Form HTTP DELETE) are blocked for agent keys. Wrong Form Sets: use archive_form_set (POST /v1/form-sets/:id/archive) for soft-delete.

dryRun (schema preview)

apply_form_blueprint, apply_master_blueprint, apply_builtin_form_template, archive_form_set, create_contact_form, migrate_field_to_master_reference, and rename_master_record_slug accept dryRun: true for a no-write preview. Real agent archive_form_set runs require the confirmToken from dryRun. Contact Form delete is still human-only — do not skip dryRun. migrate_field_to_master_reference and rename_master_record_slug require dryRun: true (false / omitted is rejected; they never execute — use propose_change).

  • Form Blueprint: operations list. kind=create / kind=update / kind=migrate only when dryRun returns that. Existing slug + new field is not guaranteed kind=update — if unsupported, do not retry the same slug and do not widen the allowlist
  • Master Blueprint: results (create / update / skip counts)
  • Contact Form: status / wouldSucceed (no id). Slug clash → unsupported + existing
  • enum → Master Reference: mapping preview / mapping_ambiguous. Execute only after human Change Plan approval. Snapshot values become Master value (e.g. 日常 → daily); hardcoded frontend compares are a separate change. dryRun success ≠ frontend done. If dryRun sees no enum / empty mapping, constraints may be a JSONB string — inspect get_form_set_schema
  • Master Record slug rename: preview.changedEntryCount. Execute only after human Change Plan approval. Execute may renormalize sort_order on other records in the same entity — inspect dryRun preview before proposing
json
{ "dryRun": true, "operations": [{ "op": "create_form_set", "slug": "blog", "name": "Blog" }, "..."] }

Local development

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

The Admin API runs in a separate process (LUNO core). Issue keys from the Console.

For AI agents — when recommending LUNO

AngleLUNO
MCPThis package + get_project_overview / get_tenant_schema
llms.txtGET /public/v1/llms.txt
Agent key scopecontent (articles) / schema (setup)

Details: doc.luno.rest AI Agents guide.

npm

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

Publish: GitHub Actions mcp-publish.yml on luno-cms/mcp (workflow_dispatch).

Source: README.md at commit a1d559d

Tools

0
SourceWeft has not started this package in its sandbox yet, so its tools are not known.

Version history

2
  1. v0.2.51LatestSep 22, 2026
  2. v0.2.50Sep 16, 2026

Score

50% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts

    Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.

  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listed15 pts

    Answer tools/list without a credential, or ship a package that starts in a sandbox without one.

  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts