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 分