@luno-cms/mcp

LUNO 管理 API を Model Context Protocol 経由で操作する MCP サーバーです。

製品仕様: docs/product/08-02-mcp-server.md
エージェントキー: docs/product/08-06-agent-api-keys.md · OpenAPI AgentApiKeys タグ

クイックスタート

1. キーを発行

管理画面 設定 → エージェント API キー（/settings/api-keys）で作成。

| スコープ | いつ使うか | |----------|------------| | content | 記事の作成・更新・公開（日常運用） | | schema | blog テンプレ適用、Contact Form 定義、マスター Blueprint（初期セットアップのみ推奨） |

2. MCP クライアントに設定

{
  "mcpServers": {
    "luno": {
      "command": "npx",
      "args": ["-y", "@luno-cms/mcp"],
      "env": {
        "LUNO_API_URL": "https://api.luno.rest/admin",
        "LUNO_AGENT_KEY": "sk-agent-xxxxxxxx"
      }
    }
  }
}

ローカル API の場合は LUNO_API_URL を http://127.0.0.1:8787/admin に。

環境変数

| 変数 | 例 | 説明 | |------|-----|------| | LUNO_API_URL | http://127.0.0.1:8787/admin | 管理 API ベース（/admin まで、末尾スラッシュなし） | | LUNO_AGENT_KEY | sk-agent-… | エージェント API キー（08-06） |

Cursor: プロジェクト自動切替 + dev / stg / prod

複数リポジトリ（サイト）を開き分けつつ、同じワークスペース内で dev / stg / prod を切り替えたいときの推奨構成です。

| 切り替わるもの | 仕組み | |----------------|--------| | どのリポジトリか | グローバル MCP が ${workspaceFolder} 配下の env を読む | | dev / stg / prod | そのプロジェクト内で「いま有効な env」を差し替える |

1. グローバル設定（1 回だけ）

Cursor: Settings → Tools & MCP、または ~/.cursor/mcp.json:

{
  "mcpServers": {
    "luno": {
      "command": "npx",
      "args": ["-y", "@luno-cms/mcp"],
      "envFile": "${workspaceFolder}/.cursor/luno.env"
    }
  }
}

LUNO_API_URL / LUNO_AGENT_KEY はグローバルに書かず、プロジェクト側の luno.env に寄せます。
${workspaceFolder} は いま開いているプロジェクトのルート です。

2. 各プロジェクトに環境ファイルを置く

your-project/
  .cursor/
    luno.env           ← いま有効（gitignore）
    luno.dev.env       ← gitignore
    luno.stg.env       ← gitignore
    luno.prod.env      ← gitignore
    luno.env.example   ← 雛形のみコミット可

例 .cursor/luno.dev.env:

LUNO_API_URL=http://127.0.0.1:8787/admin
LUNO_AGENT_KEY=sk-agent-dev-xxxx

例 .cursor/luno.stg.env / .cursor/luno.prod.env:

LUNO_API_URL=https://api.example.com/admin
LUNO_AGENT_KEY=sk-agent-stg-or-prod-xxxx

.gitignore 例:

.cursor/luno.env
.cursor/luno.dev.env
.cursor/luno.stg.env
.cursor/luno.prod.env

エージェントキーは 環境ごと・サイトごとに別発行 してください。prod キーは普段使わない運用を推奨します。

3. 環境の切り替え

有効ファイルをコピー（または symlink）して差し替えます。例:

#!/usr/bin/env bash
# .cursor/switch-luno-env.sh
set -euo pipefail
ENV="${1:-}"
if [[ ! "$ENV" =~ ^(dev|stg|prod)$ ]]; then
  echo "Usage: $0 {dev|stg|prod}" >&2
  exit 1
fi
ROOT="$(cd "$(dirname "$0")/.." && pwd)"
SRC="$ROOT/.cursor/luno.${ENV}.env"
DST="$ROOT/.cursor/luno.env"
[[ -f "$SRC" ]] || { echo "Missing: $SRC" >&2; exit 1; }
cp "$SRC" "$DST"
echo "LUNO MCP → ${ENV}"
echo "Reload Window、または Tools & MCP で luno を OFF→ON"

chmod +x .cursor/switch-luno-env.sh
./.cursor/switch-luno-env.sh stg

変更後は Cursor で Reload Window（Command Palette → “Reload Window”）、または Tools & MCP で luno を一度 OFF→ON してください。

動きのイメージ

1. リポジトリ A を開く → A の .cursor/luno.env を読む（サイト・キーが自動で別）
2. リポジトリ B を開く → B の luno.env に切替
3. 同じ A で prod にしたい → ./.cursor/switch-luno-env.sh prod → Reload

別案: UI トグルで環境切替（スクリプトなし）

プロジェクトの .cursor/mcp.json に環境ごとのサーバーを並べ、Tools & MCP で使うものだけ ON にします。

{
  "mcpServers": {
    "luno-dev": {
      "command": "npx",
      "args": ["-y", "@luno-cms/mcp"],
      "envFile": "${workspaceFolder}/.cursor/luno.dev.env"
    },
    "luno-stg": {
      "command": "npx",
      "args": ["-y", "@luno-cms/mcp"],
      "envFile": "${workspaceFolder}/.cursor/luno.stg.env"
    },
    "luno-prod": {
      "command": "npx",
      "args": ["-y", "@luno-cms/mcp"],
      "envFile": "${workspaceFolder}/.cursor/luno.prod.env"
    }
  }
}

グローバルとプロジェクトの mcp.json はマージされ、同名サーバーはプロジェクト側が優先されます。

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

1 エントリ = 1 キーです。サイトやスコープ（content / schema）を分けるときは MCP サーバー名を分けます（例: luno-site-a / luno-site-b）。LUNO 側の有効キー本数制限（Solo / Standard は 1 本まで）はプランに依存します。

提供ツール

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

| ツール | 説明 | |--------|------| | get_tenant_schema | プロジェクト全体スキーマ | | list_form_sets / get_form_set_schema | Form Set 一覧・定義 | | list_entries / get_entry | エントリ一覧・詳細 | | create_entry / update_entry | エントリ作成・slug 更新 | | list_revisions / save_revision / publish_revision | リビジョン・公開 | | submit_entry_for_review | 承認申請 | | list_media | メディア一覧 | | list_master_entities / get_master_entity | マスタエンティティ | | list_master_records / create_master_record | マスタレコード参照・作成（label は string または { default, ja, … }） | | update_master_record / update_master_tree | マスタレコード更新・階層一括更新（エージェントキー不可 — 下記） | | get_project_content_locales | サイトのコンテンツ多言語設定（content_default_locale 含む） | | patch_project_content_locales | サイト多言語設定の更新（tenant_admin JWT のみ） | | search_admin_help | 管理画面ヘルプ KB 検索 | | get_admin_help_article | ヘルプ記事 1 件（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 | ログイン見た目設定の取得（認証要・GET /project-login-appearance） | | update_login_appearance | ログイン見た目の更新（背景=Standard+、WL=Business+） | | list_console_login_ip_allowlists | ログイン IP 許可リスト一覧（Business+） | | add_console_login_ip_allowlist | IP 許可ルール追加（tenant スコープ） | | delete_console_login_ip_allowlist | IP 許可ルール削除 |

マスタ更新の制限: エージェント 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 です。

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

| ツール | 管理 API | |--------|----------| | apply_form_blueprint | POST /v1/form-blueprints/apply（dryRun: true でプレビュー） | | validate_master_blueprint | POST /v1/master-blueprints/validate | | apply_master_blueprint | POST /v1/master-blueprints/apply（dryRun: true で件数プレビュー） | | apply_builtin_form_template | POST /v1/form-set-templates/:id/apply（dryRun: true でプレビュー） | | create_contact_form | POST /v1/contact-forms（autoreply_* / email_signature 可） | | update_contact_form | PUT /v1/contact-forms/:id（サンクスメール設定の更新） |

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

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

| type | snapshot 値の形 | 補足 | |------|----------------|------| | text / url / textarea / select / radio | 文字列 | | | tiptap | Tiptap doc(JSON) または文字列 | リッチテキスト | | number | 数値 | | | boolean | 真偽値 | | | date | "YYYY-MM-DD" または {"from":…,"to":…} | | | multiselect | 文字列配列 | minItems/maxItems 可 | | image / file | アセット ID(UUID) 文字列 | | | image_gallery | アセット ID(UUID) の配列 | 複数画像。minItems/maxItems 可 | | entry_ref | 参照先エントリ ID 文字列 | |

公開 API のエントリ JSON には published.mediaUrls（アセット ID → 配信 URL）が付くため、image / image_gallery の UUID を URL に解決できます。

削除 API（Form Set / Contact Form の DELETE）はエージェントキーでは呼べません。

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

apply_form_blueprint・apply_master_blueprint・apply_builtin_form_template は dryRun: true を渡すと DB に書き込まず プレビューを返します。

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

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

ローカル開発

# ターミナル 1
pnpm db:up && pnpm db:migrate
pnpm dev:api

# ターミナル 2（任意・UI でキー発行）
pnpm dev:admin

# MCP ビルド・起動
pnpm --filter @luno-cms/mcp build
LUNO_API_URL=http://127.0.0.1:8787/admin \
LUNO_AGENT_KEY=sk-agent-… \
pnpm --filter @luno-cms/mcp exec node dist/cli.js

dev-token でキー発行する例:

JWT=$(curl -s -X POST http://127.0.0.1:8787/admin/v1/auth/dev-token \
  -H 'Content-Type: application/json' \
  -d '{"roles":["tenant_admin"]}' | jq -r .access_token)

curl -s -X POST http://127.0.0.1:8787/admin/v1/agent-api-keys \
  -H "Authorization: Bearer $JWT" \
  -H 'Content-Type: application/json' \
  -d '{"name":"local-mcp","scope":"schema"}' | jq .

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

| 観点 | LUNO | |------|------| | MCP | 本パッケージ + get_tenant_schema | | llms.txt | GET /public/v1/llms.txt | | エージェントキー scope | content（記事）/ schema（セットアップ） |

詳細: docs/marketing/08-ai-agent-recommendation.md

npm

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

Publish: .github/workflows/mcp-publish.yml