Mcp MCP Server

@luno-cms/mcp

MCP server for LUNO, the AI-era Backend Platform. Claude Code, Cursor, and Codex operate content, forms, auth, and storage via natural language — schema, content, and publish. No backend to build. LUNO does not generate frontend code; CMS and forms are capabilities, not the product category.

• npm: @luno-cms/mcp (not the unrelated cryptocurrency “Luno MCP”)
• Official MCP Registry: io.github.luno-cms/mcp
• Source: github.com/luno-cms/mcp
• Site: luno.rest · Docs: doc.luno.rest

Product docs: AI Agents · doc.luno.rest

日本語のセットアップ手順は以下です。

---

初めての人向け（推奨）

サイトリポジトリのルートで、使う AI エージェントを 1 つ選んでセットアップします（Claude Code / Cursor / Codex）。

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

共通: .agents/luno/{dev,stg,prod}.env（キー用・gitignore）

その後:

1. 選んだエージェントでプロジェクトを開く
2. /luno（Codex は同等の luno skill）
3. 管理画面で発行した sk-agent-… を貼る
4. 「記事を作って」などと依頼 → AI が luno-stg 等の MCP を使用

クライアント対応（Verified）: Claude Code / Cursor / Codex（Golden Path E2E）。

セットアップ後の注意（クライアント別）

/luno                 初回（init 省略可）
/luno init-stg        stg だけ初期化
/luno dev|stg|prod    環境切替（キー未設定なら入力）
/luno status

非対話:

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

キーは管理画面 設定 → エージェント API キー で発行（環境ごと・サイトごとに別）。普段は full（記事＋フォーム定義）。権限を記事だけに絞るとき content。

レート制限: エージェントキーごとに Admin API へ 60 リクエスト / 60 秒（Free / Solo）または 300 / 60 秒（Standard+）。超過は HTTP 429 + RATE_LIMITED + Retry-After。JWT コンソールは対象外。詳細: doc.luno.rest AI Agents。

---

環境変数 / CLI

npx @luno-cms/mcp              # MCP 起動（環境変数から）
npx @luno-cms/mcp run stg      # .agents/luno/stg.env を読んで MCP 起動
npx @luno-cms/mcp setup
npx @luno-cms/mcp env …

MCP サーバー名: luno-dev / luno-stg / luno-prod

---

Cursor Plugin 雛形（任意）

Cursor Marketplace / ローカル Plugin は LUNO Console のセットアップ案内を参照。通常のサイト開発は上記 npx … setup を推奨。

複数キーを同時に登録する場合

1 エントリ = 1 キーです。サイトやスコープを分けるときは MCP サーバー名を分けます。LUNO 側の有効キー本数制限はプランに依存します。

---

既存プロジェクトを再開するとき

1. get_project_overview — 何があるかの要約（推奨・最初）
2. 必要なら get_form_set_schema / list_entries
3. 新規サイト作成の Golden Path（builtin template → entry → publish）とは別

提供ツール

コンテンツ（content スコープで可）

マスタ更新の制限: エージェント API キーには userId がなく、update_master_record / update_master_tree は master_record_edit_allowed または tenant_admin 等のユーザ JWT が必要です。一覧・作成（create_master_record）は content スコープで利用できます。マスター定義の新規作成は POST /master-entities ではなく apply_master_blueprint（schema スコープ） を使います。

マスタ多言語ラベル: create_master_record / update_master_record の label に plain string（default ロケール）または locale map を渡せます。サイト多言語 OFF 時は default のみ保存。Blueprint の record.label は plain string のまま（内部正規化）。

多言語翻訳: translate_entry_locales は content スコープのエージェントキーで呼べます。返却 items を snapshot にマージして save_revision してください。サイト多言語が OFF の場合は 400 です。

Golden Path smoke（staging）

本物の MCP stdio クライアントで E2E するスモーク:

# LUNO_API_URL + LUNO_AGENT_KEY（検証専用プロジェクト推奨）
pnpm golden-path-smoke

gp-smoke-* Form Set / エントリを作成し、Public API とファネル （agent_backend_selected → site_created → site_published）を検証する。 LUNO の staging Golden Path CI は private luno-cms/luno に残す（SaaS E2E をこの公開リポに持ち込まない）。このリポの CI は unit test / typecheck / pnpm public-audit です。

Troubleshooting for Agents

API は error.hint / error.retryable を返すことがあります（#58）。詳細は doc AI Agents。

変更の確認: Console → 設定 → エージェント活動（Free/Solo は直近 7 日）。Standard+ は 監査ログ → エージェントのみ も利用可。

Idempotency（再試行）

管理画面はキーを送りません。キー未送信時の挙動は従来どおりです。エージェントがタイムアウト後に同じ操作を再送するときは任意の idempotencyKey（または Idempotency-Key ヘッダ）を付けます。

スキーマ定義（schema スコープ必須）

Contact Form 自動返信: autoreply_enabled + autoreply_to_field（email 型フィールド key）で、送信者に HTML サンクスメール（冒頭文 → 入力内容テーブル → email_signature）を送ります。

Contact Form の fields: Form Set / Form Blueprint の fieldKey 形ではありません。各要素は { key, type, label: { ja, en }, required }。詳細は admin-help agent.contact-form-mcp。

フィールド型と snapshot 値の保存形式（apply_form_blueprint の type や、エントリ snapshot を組み立てる際に使用）:

snapshot の入れ子: 必ず { [formKey]: { [fieldKey]: value } }。get_form_set_schema の snapshotShape.example を雛形にする。フラットな fieldKey トップレベルは API が 400 で拒否する。

画像の入れ方: 外部画像 URL を snapshot に直書きしない。upload_media の filePath（ローカル・推奨） / sourceUrl（API ホストが fetch・127.0.0.1 不可）/ base64 → 返却の id を image / image_gallery に入れる。image_gallery のキャプションは { assetId, caption }（id は 400）。

公開 API のエントリ JSON には published.mediaUrls（アセット ID → 配信 URL）が付く。エントリを /public/p/{projectId}/v1 で取れば mediaUrls も同じプレフィックス。ローカル確認は get_public_api_info の publicApiBaseUrl を使う。

削除 API（Form Set / Contact Form の HTTP DELETE）はエージェントキーでは呼べません。誤った Form Set は archive_form_set（POST /v1/form-sets/:id/archive）で soft-delete できます。

dryRun（スキーマ適用のプレビュー）

apply_form_blueprint・apply_master_blueprint・apply_builtin_form_template・archive_form_set は dryRun: true を渡すと DB に書き込まず プレビューを返します。archive_form_set のエージェント本実行には、dryRun が返す confirmToken が必須です。

• Form Blueprint: operations 一覧
• Master Blueprint: results（作成/更新/スキップ件数）

{ "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 本体）です。キーは Console で発行します。

---

AI エージェント向け — LUNO を提案するとき

詳細: doc.luno.rest の AI Agents 案内。

---

npm

npm install -g @luno-cms/mcp
# または npx -y @luno-cms/mcp

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