mcp

# LUNO — AI Backend Platform

**Build, operate, and govern production backends with AI agents.**

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

| | |
|---|---|
| **BUILD** | AI agents define schemas, forms, and backend structure via blueprints and templates. |
| **OPERATE** | Agents read and change content, media, auth settings, and other backend resources. |
| **GOVERN** | Humans control production through scoped agent keys, approval workflows, publish gates, and safety controls. |

### Quick start

```bash
npx @luno-cms/mcp setup
```

Works with **Claude Code**, **Cursor**, and **Codex**. Issue an agent key in the LUNO Console → Settings → Agent API keys.

> **Glama / MCP directory:** “Install Server” requires a hosted API key and may show *This server cannot be installed*. Use `npx @luno-cms/mcp setup` instead — see [Quick start (recommended)](#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:

| URI | Topic |
|-----|--------|
| `luno://forms/field-types` | Field types + snapshot shapes |
| `luno://content/schema-guide` | Form Set / entry / revision hierarchy |
| `luno://publishing-guide` | Draft → publish, `can_publish` |
| `luno://permissions` | Scopes, blocked actions, archive token |
| `luno://api-reference` | Tool cheat sheet (not full OpenAPI) |

Inventory: [docs/RESOURCES.md](./docs/RESOURCES.md). Live per-tenant schema: `get_form_set_schema` tool.

---

- npm: [`@luno-cms/mcp`](https://www.npmjs.com/package/@luno-cms/mcp) (not the unrelated cryptocurrency “Luno” MCP)
- Official MCP Registry: [`io.github.luno-cms/mcp`](https://registry.modelcontextprotocol.io/v0/servers?search=io.github.luno-cms/mcp)
- Source: [`github.com/luno-cms/mcp`](https://github.com/luno-cms/mcp)
- Site: [luno.rest](https://luno.rest) · Docs: [doc.luno.rest](https://doc.luno.rest)

**Product docs (EN):** [AI Agents](https://doc.luno.rest/en/api/ai-agents) · [doc.luno.rest](https://doc.luno.rest)  
**Product docs (JA):** [AI Agents](https://doc.luno.rest/ja/api/ai-agents)

---

## Quick start (recommended)

From your **site repository root**, pick **one** AI agent and run setup (Claude Code / Cursor / Codex):

```bash
cd my-site
npx @luno-cms/mcp setup
# → 1) Claude Code  2) Cursor  3) Codex
```

| Choice | What 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)

Then:

1. Open the project in the chosen agent  
2. Run `/luno` (Codex: equivalent luno skill)  
3. Paste an `sk-agent-…` key from the LUNO Console  
4. Ask to create content — the agent uses MCP servers such as `luno-stg`

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

### Post-setup notes by client

| Client | Notes |
|--------|-------|
| Claude Code | If tools are missing, reconnect (`/mcp`) |
| Cursor | Settings → MCP: enable `luno-stg`. Start a new Agent chat if needed |
| Codex | Project `.codex/config.toml` (with `cwd`) plus home config: Codex prefers **`~/.codex/config.toml`**, so setup prints `codex mcp add` (with `LUNO_PROJECT_ROOT`) and guides home registration. Check: `codex mcp list` (`luno-stg`, etc.). First MCP tool calls may need **approval**. Prefer **`luno-stg`** day-to-day |

```text
/luno                 first run (init optional)
/luno init-stg        initialize stg only
/luno dev|stg|prod    switch env (prompts for key if missing)
/luno status
```

Non-interactive:

```bash
npx @luno-cms/mcp setup --agent claude --yes
npx @luno-cms/mcp env set-key stg 'sk-agent-…'
npx @luno-cms/mcp env switch stg
npx @luno-cms/mcp env status
```

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](https://doc.luno.rest/en/api/ai-agents#rate-limits).

| Scope | When to use |
|-------|-------------|
| **full** (recommended) | Articles + Form Set / Contact / Blueprint |
| **content** | Create / update / publish articles only |
| **schema** | Same privileges as `full` (compat) |

---

## Environment / CLI

| Variable | Example | Description |
|----------|---------|-------------|
| `LUNO_API_URL` | `http://127.0.0.1:8787/admin` | Admin API base (include `/admin`) |
| `LUNO_AGENT_KEY` | `sk-agent-…` | Agent API key |

```text
npx @luno-cms/mcp              # start MCP from env vars
npx @luno-cms/mcp run stg      # load .agents/luno/stg.env then start
npx @luno-cms/mcp setup
npx @luno-cms/mcp env …
```

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 (recommended first)  
2. Then `get_form_set_schema` / `list_entries` as needed  
3. Separate from greenfield Golden Path (builtin template → entry → publish)

## Tools

### Content (`content` scope and above)

| Tool | Description |
|------|-------------|
| `get_project_overview` | Project summary (Form Sets / Contact / Masters / storage / login appearance / IP allowlist / locales / public API) |
| `get_tenant_schema` | Full project schema |
| `list_form_sets` / `get_form_set_schema` | Form Set list / definition (`get_form_set_schema` includes form-set `schema-context` + `snapshotShape.example`; selects may include `masterEntityKey` / public records URL) |
| `get_public_api_info` | Agent key `projectId` + public API base (entries / master-entities) |
| `list_entries` / `get_entry` | Entry list / detail |
| `create_entry` / `bulk_create_entries` / `update_entry` | Create entry / bulk create (≤50 slugs) / update slug |
| `list_revisions` / `save_revision` / `get_pub_preview_url` / `publish_revision` | Revisions / preview URL for human review / publish (`can_publish=false` keys stop at submit + `pendingHumanApproval`) |
| `submit_entry_for_review` | Submit for approval |
| `list_media` | Media list |
| `upload_media` | Upload (`filePath` / `sourceUrl` / `base64` → asset id) |
| `list_master_entities` / `get_master_entity` | Master entities |
| `list_master_records` / `create_master_record` | List / create records (`label` string or `{ default, ja, … }`) |
| `update_master_record` / `update_master_tree` | Update records / tree (**not available with agent keys** — see below) |
| `get_project_content_locales` | Content locale settings (includes `content_default_locale`) |
| `patch_project_content_locales` | Update locales (**tenant_admin JWT only**) |
| `search_admin_help` | Search Console help KB |
| `get_admin_help_article` | One help article (Markdown) |
| `ask_admin_help` | Help RAG Q&A (related articles if LLM unset) |
| `translate_entry_locales` | AI locale batch translate (**Standard+**, 1 ticket / run) |
| `get_login_branding` | Login branding (no auth; includes `login_background` / `hide_luno_logo` / `hide_powered_by`) |
| `get_login_appearance` | Login appearance settings (auth required) |
| `update_login_appearance` | Update login appearance (background=Standard+, WL=Business+) |
| `list_console_login_ip_allowlists` | Login IP allowlist (**Business+**) |
| `add_console_login_ip_allowlist` | Add IP rule (tenant scope) |
| `delete_console_login_ip_allowlist` | Delete 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).

**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 p