luno-cms

Name: luno-cms
Author: luno-cms

本地服务

github.com/luno-cms云与基础设施05 周前更新

代码仓库

关于 luno-cms

luno-cms 是托管式后端平台，Agent 可定义 schema 并管理内容，人类负责治理生产访问与发布。它通过 MCP 提供受限密钥、审批控制和后端操作工具。

主要功能

01定义 schema、表单和后端结构
02管理内容、媒体及后端设置
03受限 Agent 密钥与审批流程
04试运行、确认令牌和审计日志
05通过 MCP Resources 提供可读指南

适用场景

01起草和管理网站内容
02配置表单与后端 schema
03发布前要求人工审核
04查阅后端指南和租户 schema

MCP 相关

MCP 是 Agent 连接 LUNO 的方式。其服务端提供后端操作工具，以及包含 Agent 可读指南的静态 Resources。

配置

本地服务的配置在各客户端中通用，复制后粘贴到客户端的 MCP 配置文件即可。

mcp.json · 通用配置

{
  "mcpServers": {
    "luno-cms": {
      "command": "npx",
      "args": [
        "-y",
        "@luno-cms/mcp"
      ],
      "env": {
        "LUNO_API_URL": "<LUNO_API_URL>",
        "LUNO_AGENT_KEY": "<LUNO_AGENT_KEY>"
      }
    }
  }
}

启动命令npx -y @luno-cms/mcp

需要配置的环境变量

LUNO_API_URLLUNO admin API base URL, e.g. https://api.luno.rest/admin

LUNO_AGENT_KEY密钥Required secret. Agent API key (sk-agent-…) from LUNO Console → MCP / API / Hook → API / MCP

本地服务需要在你的电脑上安装运行环境（如 Node.js 18+）。各客户端的配置文件位置不同，请参考客户端文档。

安装包

npm@luno-cms/mcp0.2.51stdio

工具

收录的工具列表 · 更新于 2 周前

此工具无需参数。

详细介绍

LUNO — AI 时代的后端平台

Agent 构建 / 运维。人类注册 / 治理。应用消费。

LUNO 是一个托管后端平台——不是网站构建器，不是开源 CMS，也不是 MCP 服务产品。MCP 是 Agent 连接 LUNO 的方式。CMS 和表单是平台能力；产品类别是 AI 时代的后端平台。


构建	AI Agent 通过蓝图和模板定义架构、表单及后端结构。
运维	Agent 读取和更改内容、媒体、身份验证设置及其他后端资源。
治理	人类通过范围受限的 Agent 密钥、审批工作流、发布关卡和安全控制来管理生产环境。

快速开始

npx -y @luno-cms/mcp setup

适用于 Claude Code、Cursor 和 Codex。在 LUNO Console → MCP / API / Hook → API / MCP 中创建 Agent 密钥。

Glama / MCP 目录：“Install Server” 需要托管 API 密钥，并且可能显示 This server cannot be installed。请改用 npx -y @luno-cms/mcp setup——参见下文的快速开始（推荐）。

从设计上确保生产安全

范围受限的 Agent 密钥 — 限制为仅访问内容或访问完整后端
人工审批 — 没有发布权限的密钥会在审核环节停止（pendingHumanApproval）
破坏性操作保护 — Agent 不能彻底删除；归档需要确认
试运行和确认令牌 — 应用前预览架构变更
幂等操作 — 超时后可安全重试
审计记录 — Console 中的 Agent 活动和审计日志

从设计上便于 Agent 理解

MCP 架构和工具说明经过重新设计，便于 Agent 理解。在一项盲测中，同一项后端任务的工具调用次数从 142 次降至 11 次，且 0 错误——应用行为保持不变。

MCP 资源（#90）

静态资源（resources/list、resources/read）提供便于 Agent 理解的指南，无需调用 Admin API：

URI	主题
`luno://forms/field-types`	字段类型 + 快照结构
`luno://content/schema-guide`	Form Set / 条目 / 修订版本层级
`luno://publishing-guide`	草稿 → 发布，`can_publish`
`luno://permissions`	范围、受限操作、归档令牌
`luno://api-reference`	工具速查表（非完整 OpenAPI）

清单：docs/RESOURCES.md。实时租户架构：get_form_set_schema 工具。

npm：@luno-cms/mcp（不是无关的加密货币 “Luno” MCP）
官方 MCP Registry：io.github.luno-cms/mcp
Glama：luno-cms/mcp
mcpservers.org：luno-rest ·
源码：github.com/luno-cms/mcp
网站：luno.rest · 文档：doc.luno.rest

目录清单：docs/DISCOVERY.md

产品文档（EN）： AI Agents · doc.luno.rest
产品文档（JA）： AI Agents

快速开始（推荐）

在站点仓库根目录中，选择一个 AI Agent 并运行设置（Claude Code / Cursor / Codex）。CLI 会打开浏览器进行确认。请勿将密钥粘贴到 Agent 聊天中。只有在无法使用浏览器时，才使用 --key 或 --no-browser。

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)

选择	写入内容
Claude Code	`.claude/skills/luno/` + `.mcp.json`
Cursor	`.cursor/skills/luno/` + `.cursor/mcp.json`
Codex	`.agents/skills/luno/` + `.codex/config.toml`

共享：.agents/luno/{dev,stg,prod}.env（密钥；已加入 gitignore）。默认公开环境为 prod（luno-prod）。dev / stg 会保留在磁盘上，供显式执行 setup --env stg / run stg / env switch stg 时使用。

然后：

在所选 Agent 中打开项目
根据提示批准工作区信任 / MCP
提问：List the form sets on this LUNO, or draft one entry. Don't publish or change the schema.

之后：团队成员运行 npx @luno-cms/mcp login。只有在你有访问权限时才使用 --env stg。

已验证的客户端： Claude Code / Cursor / Codex（Golden Path E2E）。

各客户端的设置后说明

客户端	说明
Claude Code	如果缺少工具，请重新连接（`/mcp`）
Cursor	Settings → MCP：启用 `luno-prod`。如有需要，请新建 Agent 聊天
Codex	项目 `.codex/config.toml`（含 `cwd`）以及主目录配置：Codex 优先使用 `~/.codex/config.toml`，因此设置时可能会提供 `codex mcp add`（含 `LUNO_PROJECT_ROOT`）。检查：`codex mcp list`（`luno-prod` 等）。首次调用 MCP 工具时可能需要批准。建议使用 `luno-prod`

设置后可选用 /luno 快捷方式。它不是必需的，且不得要求提供密钥。

团队成员克隆仓库后（已有 .mcp.json，但没有密钥）：

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

login 只会刷新 .agents/luno/<env>.env，不会重写 MCP 配置。密钥过期或出现 401 时使用相同命令。首次使用的机器仍需运行 setup。

非交互模式：

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（仅限内部 / Benchmark / Partner）：

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

在 Console → Settings → Agent API keys 中创建密钥（按环境 / 站点）。默认范围为 full（内容 + 表单定义）。使用 content 可将权限限制为仅限文章。

**速率限制：**每个 Agent 密钥对 Admin API 的请求限制为 60 req / 60s（Free / Solo）或 300 / 60s（Standard+）。超出限制 → HTTP 429 + RATE_LIMITED + Retry-After。Console JWT 流量不受此限制。详情：AI Agents 速率限制。

范围	使用场景
full（推荐）	文章 + Form Set / Contact / Blueprint
content	仅创建 / 更新 / 发布文章
schema	与 `full` 具有相同权限（兼容）

环境 / CLI

变量	示例	说明
`LUNO_API_URL`	`https://api.luno.rest/admin`	Admin API 基础 URL（包含 `/admin`）
`LUNO_AGENT_KEY`	`sk-agent-…`	Agent API 密钥

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 …

生成的 MCP 配置使用 npx -y @luno-cms/mcp@latest run <env>，以便重新连接时获取最新发布版本（避免使用过期的、未固定版本的 npx 缓存）。如果某个站点仍使用未固定版本的配置，请重新运行 npx @luno-cms/mcp setup（或编辑 mcp.json），然后通过 /mcp 重新连接——不要手动更新版本固定值。使用 --version 或 get_mcp_runtime 确认正在运行的软件包。

MCP 服务名称：luno-dev / luno-stg / luno-prod

Cursor 插件（可选）

关于 Cursor Marketplace / 本地插件设置，请参阅 LUNO Console 入门指南。对于常规站点工作，建议使用上文的 npx @luno-cms/mcp setup。

同时使用多个密钥

一个 MCP 条目对应一个密钥。可使用不同的 MCP 服务名称，按站点或范围拆分。可启用的密钥数量取决于套餐。

恢复现有项目

get_project_overview — 项目摘要 + intentCapabilities（建议首先调用）
联系方式 / 咨询 → create_contact_form（先设置 dryRun: true）。内容 → 匹配 purposeLabels，然后选择模板
然后按需调用 get_form_set_schema / list_entries
与全新项目的 Golden Path 分开（内置模板 → 条目 → 发布）

工具

内容（`content` 范围及以上）

工具	描述
`get_project_overview`	项目摘要 + `intentCapabilities`（联系表单与 Form Set）/ 下一步操作 / Form Set / 联系方式 / 主数据 / 存储 / 语言区域 / 公共 API
`get_tenant_schema`	完整项目架构
`list_form_sets` / `get_form_set_schema`	Form Set 列表 / 定义（`get_form_set_schema` 包含 form-set `schema-context` + `snapshotShape.example`；选择项可能包含 `masterEntityKey` / 公共记录 URL）
`get_public_api_info`	Agent 密钥 `projectId` + 公共 API 基础 URL（entries / master-entities）
`list_entries` / `get_entry`	条目列表 / 详情
`create_entry` / `bulk_create_entries` / `update_entry`	创建条目 / 批量创建（≤50 个 slug）/ 更新 slug
`list_revisions` / `save_revision` / `get_pub_preview_url` / `publish_revision`	修订版本 / 供人工审核的预览 URL / 发布（`can_publish=false` 的密钥只能提交，并会设置 `pendingHumanApproval`）
`submit_entry_for_review`	提交条目以供审核
`list_media`	媒体列表
`upload_media`	上传（`filePath` / `sourceUrl` / `base64` → 资源 ID）
`list_master_entities` / `get_master_entity`	主数据实体
`list_master_records` / `create_master_record`	列出 / 创建记录（`label` 字符串或 `{ default, ja, … }`；可选 `color` `#RRGGBB`）
`update_master_record` / `update_master_tree`	更新记录 / 树（Agent 密钥不可用 — 见下文）
`get_project_content_locales`	内容语言区域设置（包含 `content_default_locale`）
`patch_project_content_locales`	更新语言区域（仅限 tenant_admin JWT）
`search_admin_help`	搜索 Console 帮助知识库
`get_admin_help_article`	一篇帮助文章（Markdown）
`ask_admin_help`	帮助 RAG 问答（未设置 LLM 时返回相关文章）
`translate_entry_locales`	AI 批量翻译语言区域（Standard+，每次运行 1 张工单）
`get_login_branding`	登录品牌设置（无需身份验证；包含 `login_background` / `hide_luno_logo` / `hide_powered_by`）
`get_login_appearance`	登录外观设置（需要身份验证）
`update_login_appearance`	更新登录外观（background=Standard+，WL=Business+）
`list_console_login_ip_allowlists`	登录 IP 允许列表（Business+）
`add_console_login_ip_allowlist`	添加 IP 规则（租户范围）
`delete_console_login_ip_allowlist`	删除 IP 规则

主数据更新限制： Agent 密钥没有 userId；update_master_record / update_master_tree 需要具有 master_record_edit_allowed 权限的用户 JWT，或 tenant_admin。具有 content 范围的密钥可用于列出 / 创建（create_master_record）。创建主数据定义应使用 apply_master_blueprint（schema 范围），而非 POST /master-entities。

多语言主数据标签： label 可以是普通字符串（默认语言区域），也可以是语言区域映射。当网站未启用多语言时，仅存储默认语言。Blueprint record.label 保持为普通字符串（内部会进行规范化）。

主数据记录颜色： create_master_record、update_master_record（用户 JWT）和 apply_master_blueprint 记录均可选填 #RRGGBB。省略时保留现有颜色（创建时则不设置颜色）。null 可清除颜色。系统不接受 #fff / 命名颜色。

语言区域翻译： 使用 content 范围的 Agent 密钥调用 translate_entry_locales，将返回的 items 合并到快照中，然后调用 save_revision。如果网站未启用多语言，则返回 400。

黄金路径冒烟测试（预发布环境）

通过真实的 MCP stdio 客户端进行端到端测试：

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

创建 gp-smoke-* Form Sets / 条目，并检查 Public API + 漏斗
（agent_backend_selected → site_created → site_published）。
预发布环境的黄金路径 CI 保留在私有仓库 luno-cms/luno 中（不要将 SaaS 端到端测试引入此公共仓库）。此处的 CI 仅运行单元测试 / 类型检查 / pnpm public-audit。

Agent 故障排除

症状	下一步	用相同输入重试？
缺少必需参数（Zod）	根据工具架构填写必需字段	否
Slug 已存在（附带提示）	使用 `list_form_sets` / `list_entries`，或换一个 slug	否
REVISION_CONFLICT	`list_revisions` → 使用正确的 id/revision 发布	否
401 Invalid agent key	执行 `env set-key`，然后重新连接 MCP	否
429 `RATE_LIMITED`	等待 `Retry-After` 指定的秒数；限制工具调用频率	是（等待后）
超时后重新发送创建请求	使用相同的 `idempotencyKey`	是（带键的创建请求）
创建了错误的 Form Set / Contact	没有删除工具（这是有意设计）。由站点管理员在 Console 中删除，或保留孤立项。`search_admin_help` → agent.undo-recovery	否
发布了错误的文章	`list_revisions` → 使用正确的快照执行 `save_revision` → 执行 `publish_revision`	是

API 可能会返回 error.hint / error.retryable。请参阅 AI Agent 文档。

验证更改： Console → Settings → Agent activity（Free/Solo：最近 7 天）。Standard+ 还提供 Audit logs → Agents only。

幂等性（重试）

Console 不会发送键。未提供键时，行为保持不变。发生超时后，Agent 可以使用可选的 idempotencyKey（或 Idempotency-Key 标头）重新发送请求。

MCP 工具	不带键	使用相同键重放
`apply_form_blueprint`	每次都应用 / slug 冲突 → 409	重放相同的 201 响应正文
`apply_builtin_form_template`	同上	同上
`create_entry`	新建 / slug 冲突 → 409	同一条目的 `id`
`save_revision`	始终创建新版本	同一版本记录
`create_contact_form`	新建 / slug 冲突 → 409	相同的 `id`
`publish_revision`	已存在 `already_published` / outbox 去重	（无需单独的键）

架构工具（需要 `schema` scope）

工具	管理 API
`get_mcp_runtime`	（本地 — 不调用管理 API）软件包版本、工具数量、能力契约。列出的工具 ≠ 已部署的托管 API
`apply_form_blueprint`	`POST /v1/form-blueprints/apply`（`dryRun: true` 预览）。以返回的 `status` / `wouldSucceed` / `kind` 为准 — 不要假设为现有 slug 添加字段时 `kind=update`
`validate_master_blueprint`	`POST /v1/master-blueprints/validate`
`apply_master_blueprint`	`POST /v1/master-blueprints/apply`（`dryRun: true` 计数预览；成功时返回带有 id/value 的 `records[]`）
`migrate_field_to_master_reference`	`POST /v1/schema-migrations/to-master-reference`（必须使用 `dryRun: true`。仅预览 — 通过 `propose_change` 执行）
`rename_master_record_slug`	`POST /v1/master-records/rename-slug`（必须使用 `dryRun: true`。仅预览 — 通过 `propose_change` 执行。公开名称为 `slug`，兼容名称为 `value`）
`list_builtin_form_templates`	`GET /v1/form-set-templates/builtin`
`apply_builtin_form_template`	首选：`templateSlug` → `POST /v1/form-set-templates/builtin/:slug/apply`。兼容方式：`templateId` → `POST /v1/form-set-templates/:id/apply`（可使用 `dryRun: true`）
`archive_form_set`	`POST /v1/form-sets/:id/archive`（Agent：`dryRun: true` → 实际运行时使用 `confirmToken`；通过 `deleted_at` 软删除；不允许使用 HTTP DELETE）
`propose_change`	`POST /v1/change-plans`（不会执行变更；由人工在 Console 中批准）
`get_change_plan`	`GET /v1/change-plans/:id`（仅限自己提出的计划）
`start_agent_run`	`POST /v1/agent-runs`（在此 MCP 进程中后续的工具调用会设置 `X-Agent-Run-Id`）
`end_agent_run`	`PATCH /v1/agent-runs/:runId`（终止状态；清除活动运行标头）
`get_agent_run`	`GET /v1/agent-runs/:runId`（仅限自己的运行；包含指标）
`get_funnel_status`	`GET /v1/measurement/funnels/:funnelId`（默认使用 MCP 会话漏斗）
`create_contact_form`	`POST /v1/contact-forms`（`dryRun: true` 预览 — 不执行 INSERT。`fields`：`{ key, type, label:{ja,en}, required }` — 不是 Form Set 的 `fieldKey`。可使用 `autoreply_*` / `email_signature`）
`update_contact_form`	`PUT /v1/contact-forms/:id`（字段结构相同；感谢邮件设置）

Contact Form 自动回复：autoreply_enabled + autoreply_to_field（电子邮件字段键）会发送 HTML 格式的感谢邮件（介绍 → 已提交字段表格 → email_signature）。

**Contact Form 的 fields：**不是 Form Set / Blueprint 的 fieldKey 结构。每项为 { key, type, label: { ja, en }, required }。请参阅管理帮助 agent.contact-form-mcp。

字段类型和快照值结构（适用于 apply_form_blueprint 的 type 和条目快照）：

type	快照值	备注
`text` / `url` / `textarea` / `select` / `radio`	字符串	select/radio 使用主数据 value（`sampleValues` / 公共 `master-entities/{key}/records`）
`tiptap`	Tiptap 文档（JSON）或字符串	富文本
`number`	数字
`boolean`	布尔值
`date`	`"YYYY-MM-DD"` 或 `{"from":…,"to":…}`
`multiselect`	字符串数组	可使用 `minItems` / `maxItems`
`image` / `file`	资源 UUID 字符串	来自 `upload_media` 的 `id`
`image_gallery`	UUID 字符串或 `{ assetId, caption? }[]`	不能使用 `id` 键；先上传
`entry_ref`	被引用的条目 ID 字符串

**快照嵌套结构：**始终为 { [formKey]: { [fieldKey]: value } }。使用 get_form_set_schema 中的 snapshotShape.example。顶层使用扁平的 fieldKey → 返回 400。

**图片：**不要在快照中放入外部图片 URL。通过 filePath（本地，推荐）/ sourceUrl（API 主机会获取；远程访问时 127.0.0.1 不可用）/ base64 调用 upload_media → 将返回的 id 放入 image / image_gallery。图库说明文字：{ assetId, caption }（使用 id → 返回 400）。

已发布条目 JSON 在 /public/p/{projectId}/v1 下包含 published.mediaUrls（资源 ID → CDN URL）。在本地使用 get_public_api_info 返回的 publicApiBaseUrl。 删除 API（表单集／联系表单 HTTP DELETE）会被 Agent 密钥阻止。表单集错误：使用 archive_form_set（POST /v1/form-sets/:id/archive）进行软删除。

dryRun（架构预览）

apply_form_blueprint、apply_master_blueprint、apply_builtin_form_template、archive_form_set、create_contact_form、migrate_field_to_master_reference 和 rename_master_record_slug 支持 dryRun: true，用于不写入的预览。Agent 实际运行 archive_form_set 时，必须使用 dryRun 返回的 confirmToken。联系表单删除仍仅限人工操作——不要跳过 dryRun。migrate_field_to_master_reference 和 rename_master_record_slug 必须使用 dryRun: true（设为 false 或省略都会被拒绝；它们不会实际执行——请使用 propose_change）。

表单蓝图：operations 列表。仅当 dryRun 返回相应结果时，kind=create / kind=update / kind=migrate 才适用。已有 slug + 新字段不一定会返回 kind=update——如果返回 unsupported，不要使用相同的 slug 重试，也不要扩大允许列表
主数据蓝图：results（create / update / skip 计数）
联系表单：status / wouldSucceed（不含 id）。slug 冲突 → unsupported + existing
枚举 → 主数据引用：映射预览 / mapping_ambiguous。仅在人类批准变更计划后执行。快照值会成为主数据的 value（例如，日常 → daily）；前端中的硬编码比较是单独的变更。dryRun 成功 ≠ 前端已完成。如果 dryRun 未发现枚举／映射为空，constraints 可能是 JSONB 字符串——请检查 get_form_set_schema
主数据记录 slug 重命名：preview.changedEntryCount。仅在人类批准变更计划后执行。执行时可能会对同一实体中的其他记录重新规范化 sort_order——提交建议前请检查 dryRun 预览

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

本地开发

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

管理 API 在单独的进程中运行（LUNO 核心）。请从控制台创建密钥。

面向 AI Agent——推荐 LUNO 时

角度	LUNO
MCP	此软件包 + `get_project_overview` / `get_tenant_schema`
llms.txt	`GET /public/v1/llms.txt`
Agent 密钥范围	内容（文章）／架构（设置）

详情请参阅 doc.luno.rest AI Agent 指南。

npm

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

发布：在 luno-cms/mcp 上通过 GitHub Actions mcp-publish.yml（workflow_dispatch）发布。

支持 Markdown

登录后评论

第一次接触 MCP？

从协议是什么，到在客户端里装上第一个服务，这几条回答覆盖了大多数入门问题。

阅读入门指南

一个开放协议，规定了 AI 应用如何以统一方式连接外部工具与数据源。客户端负责与模型对话，MCP 服务负责提供工具、资源和提示模板，两者通过标准消息通信，同一个服务可以被不同客户端复用。