Luno Cms

io.github.luno-cms由 GitHub 账号 luno-cms 发布v0.2.51更新于 Oct 24, 2026

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

已验证STDIO仅桌面效率与工作流文件与存储开发者工具

概览

AI 生成的概览

面向 LUNO 托管后端平台的 MCP 服务器，让 AI 代理通过受限代理密钥构建和运营 CMS 内容、表单、媒体与数据结构。

可以做什么
查看项目：概览、租户结构、表单集、条目、修订、媒体、主实体与记录、公共 API 信息、内容语言设置，以及通过搜索或问答获取控制台帮助文章。创建与编辑内容：新建、批量新建和更新条目，保存修订，获取预览链接，提交审核并发布。管理媒体：列出素材，并从本地文件路径、来源网址或 base64 上传。变更结构：应用表单与主数据蓝图、应用内置模板、将字段迁移为主数据引用、重命名记录 slug、归档表单集，以及提交变更计划供人工审批。跟踪代理运行与漏斗状态，并读取关于字段类型、结构和发布流程的静态指南资源。
适用场景
当站点或应用运行在 LUNO 后端平台上，且希望代理在对话中起草或发布内容、搭建表单与数据结构、管理媒体时使用。适合希望用受限密钥、试运行和人工审批来约束代理操作的团队。
运行要求
以 npm 包形式在本地运行（通过 npx 使用 Node.js）。需要 LUNO_API_URL（管理 API 基础地址，含 /admin）和 LUNO_AGENT_KEY，后者是在 LUNO 控制台签发的代理 API 密钥。需要能访问 LUNO 管理 API 的网络。安装流程会为 Claude Code、Cursor 或 Codex 写入配置，并把密钥存入被 git 忽略的环境文件。
安装前请注意
需要秘密代理密钥；README 要求不要把密钥粘贴到代理对话中，应使用浏览器安装流程。密钥默认拥有完整权限（内容加表单定义），可用 content 范围限制为仅文章。代理可创建、更新和发布内容并上传媒体，结构变更会作用于线上后端。删除被禁止，但归档属于软删除，部分结构变更需人工审批后才执行。每个密钥有速率限制。

安装

在 SourceWeft 中

  1. 打开 控制台中的 Luno Cms，将其添加到工作区。
  2. 为需要使用其工具的对话启用该服务。

Desktop only，通过 STDIO。 STDIO 服务会启动本地进程，因此需要 SourceWeft 桌面宿主。

其他 MCP 客户端

参照 仓库 中的启动说明。

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).

来源：README.md，提交 a1d559d

工具

0
SourceWeft 尚未在沙箱中启动过该软件包，因此其工具未知。

版本历史

2
  1. v0.2.51最新Sep 22, 2026
  2. v0.2.50Sep 16, 2026

评分

已满足适用检查项的 50%

该评分衡量此收录条目的完整程度，依据注册中心条目、端点与公开来源计算得出。它不是对服务器本身的评价，也不表示服务器安全或当前可用：可连通性是带日期的检查结果，评分也不包含安装量或用户评价。

  • 近 30 天内可连通25 分

    请保持端点能够响应 MCP 握手；SourceWeft 每 30 天探测一次。

  • 已声明认证方式10 分

    请在注册中心条目中声明凭据请求头，或保持端点能够响应探测，以便判定其认证方式。

  • 已列出工具15 分

    请让服务器在无凭据时响应 tools/list，或发布可在沙箱中无凭据启动的软件包。

  • 描述必需15 分
  • 图标10 分
  • 文档15 分
  • 许可证10 分