ものしり

第2部 使いこなす

第9章 リファレンスの読み方(設定・CLI・API・MCP)

設定、CLI、API、MCP のリファレンスの地図を手に入れる。

読了の目安 約 43 分 ・ EmDash 1.3.1 / Astro 7 系(確認日 2026-10-29)

この章で学ぶこと

EmDash の公式リファレンスは広く、設定、CLI、サーバー側 API、REST API、MCP、サイト転送と、読む場所が多岐にわたります。この章の目的は、それらを丸ごと覚えることではありません。「どこに何が書いてあるか」という地図を頭に入れ、よく使うものだけ使い方まで押さえることです。

  • 設定(astro.config.mjs の emdash() オプション)を用途別に引けるようになる。
  • CLI を「ローカル作業用」と「稼働中サイトへの接続用」に分け、危険なコマンドを見分けられる。
  • サーバー側クエリ関数、REST API、MCP の三つの入口の違いと、認証・権限の考え方がわかる。
  • AI ツール連携、x402 決済、サイト転送(.emdash パッケージ)の位置づけがわかる。
  • 章末の「用途から引く」索引を、リファレンスを開く入口として使える。

基準は EmDash 1.3.1(確認日 2026-10-29)です。本文の事実は公式ドキュメントに基づき、筆者の見解は明示します。

1. 全体の地図: 同じ操作に入口が四つある

EmDash では、コンテンツの操作に管理画面、REST API、CLI、MCP の四つの入口があります。公式の「コンテンツライフサイクル」リファレンスによれば、これらは同じ状態遷移・権限・競合のルールを共有します。ただし既定の挙動には違いがあります。CLI の content create / content update は既定で自動公開し、下書きにするには --draft を付けます。一方、REST の保存と MCP の content_update は(公開済みエントリーに対しては)下書きを作ります。「CLI は管理画面や REST と同じ既定の挙動」とは考えないでください。

図 9-1 に示すように、管理画面・CLI・REST API・MCP は同じライフサイクル規則を共有し、サイトのページの読み出しは別のサーバー側クエリ関数が担います。右の注意のとおり、既定の挙動は入口ごとに同じではありません。

図 9-1: コンテンツ操作の四つの入口と、サイトの読み出し
知りたいこと 開くリファレンス この章の節
astro.config.mjs のオプション、環境変数 Configuration 2
npx emdash ... のコマンド CLI 3
.astro ページでの読み出し関数 JavaScript API 4
HTTP でのアクセス、認証、エラー REST API 5
AI エージェントからの操作、トークンの権限 MCP Server 6
状態遷移、_rev、ロック Content Lifecycle 5・6 で併用

2. 設定ファイル: emdash() オプションを用途別に引く

なぜ用途別か

Configuration リファレンスはオプション名の順に並んでおり、「何をしたいか」から引くには向きません。ここでは用途別に並べ替えます。設定の中心は astro.config.mjs の emdash({...}) で、補助として src/live.config.ts(コンテンツローダーの登録)、環境変数、package.json の emdash キーがあります。

どうやる: 最小構成

// astro.config.mjs(要点のみ)
import emdash, { local } from "emdash/astro";
import { sqlite } from "emdash/db";

emdash({
  database: sqlite({ url: "file:./data.db" }),
  storage: local({ directory: "./uploads", baseUrl: "/_emdash/api/media/file" }),
  plugins: [],
});

必須なのは database だけです。storage を省略すると、./.emdash/uploads に保存され /_emdash/api/media/file で配信されます。

用途別オプション早見表

用途 オプション 要点
データの置き場所 database (必須) sqlite / postgres / libsql / d1 / hyperdrive / durableObjects など。D1 系は @emdash-cms/cloudflare から import
migrations runtime は auto(既定) / check / manual。check は未適用の移行があると 503 を返す
メディア storage local / r2 / s3。s3() は S3_* 環境変数から読めるが、これは Node のみ。Workers では r2 か明示値
maxUploadSize 既定 52_428_800 バイト(公式 configuration は「50 MB」、site-transfer は「50 MiB」と表記。実際の値は 50 MiB)。超過は 413 または 400
images 既定 true。Astro の画像最適化とストレージを連携
mediaProviders Cloudflare Images / Stream をメディアライブラリに追加
速度 objectCache kvCache(Cloudflare KV)または memoryCache(Node・開発)。省略時は無効
middleware.outer EmDash より外側で動くミドルウェア。全ページキャッシュなどに使う
toolbar 編集ツールバーの配信方式。"server"(既定) / "client" / false。共有キャッシュの前段があるなら "client"
認証 auth 指定すると外部認証(Cloudflare Access の access())が唯一の方法になり、パスキーは無効化される
authProviders github() google() microsoft() atproto() などのログイン手段を追加
公開 URL・プロキシ siteUrl 公開オリジン(パスなし)。リバースプロキシ配下では必須級
allowedOrigins 複数ホスト名でパスキーを使うときの追加オリジン
trustedProxyHeaders クライアント IP を読むヘッダー。自分で管理するプロキシ配下のみ。Cloudflare では自動。未設定のセルフホストでは認証のレート制限が省略される
プラグイン plugins / sandboxed / sandboxRunner / sandbox / registry ネイティブ版は plugins、隔離実行は sandboxed + sandboxRunner。marketplace は非推奨
管理画面 admin ロゴ・サイト名・言語(locales)・hiddenNavItems
fonts 管理画面のフォント。日本語は scripts: ["japanese"]
運用 updateCheck 新バージョン通知(既定 true)。npm レジストリへの GET のみでサイトのデータは送らない
mcp MCP エンドポイントの有効・無効(既定で有効)
デモ playground 使い捨てデモ用。本番 CMS には使わない

落とし穴

  • siteUrl を忘れる。 非ループバックのホストで siteUrl も EMDASH_SITE_URL も未設定だと、セットアップが SITE_URL_REQUIRED で失敗します(Cloudflare Workers の本番ビルドは例外)。TLS を終端するリバースプロキシ配下では、Astro.url が内部アドレスになり、パスキーや OAuth のリダイレクトが壊れます。
  • siteUrl と Astro の site は別物。 siteUrl は EmDash 内部用で、テンプレートで自分が組み立てる canonical や OG の URL には Astro の site を使います。
  • hiddenNavItems は見えなくするだけ。 管理画面のメニューから消えるだけで、URL を知っていて権限があれば開けます。権限制御の手段ではありません。
  • auth を設定するとパスキーが使えなくなる。 切り替え前に、外部認証側でロールが正しく割り当てられるか(roleMapping、defaultRole)を確認します。
  • 画像の最適化は siteUrl をビルド時に読む。 EMDASH_SITE_URL を実行時にだけ設定すると、ローカル保存のメディアが最適化されません。

環境変数

変数 用途
EMDASH_SITE_URL(なければ SITE_URL) 公開オリジン
EMDASH_ENCRYPTION_KEY プラグインの秘密情報を保存時に暗号化する鍵。運用者が用意し、DB には保存されない。npx emdash secrets generate で生成
EMDASH_TOKEN / EMDASH_URL / EMDASH_HEADERS CLI の接続先とトークン(3 節)

セキュリティ: EMDASH_ENCRYPTION_KEY は鍵のローテーション時に古い鍵を即座に捨ててはいけません。公式の手順は、新しい鍵を既存値の先頭にカンマ区切りで足し、すべてのプラグイン秘密情報を保存し直してから古い鍵を外す、というものです。どの鍵 ID がまだ使われているかを EmDash は列挙しないため、再保存した資格情報の一覧を自分で管理します。

3. CLI: 用途別コマンド早見表

なぜ二種類に分けるか

CLI は emdash パッケージに含まれ、npx emdash または短縮名 em で呼べます。コマンドは性質が大きく二つに分かれます。

  • ローカル作業用: ローカルの SQLite ファイルを直接開く(init doctor seed export-seed)。migrate はデプロイ先の DB に対して動く。
  • 稼働中サイトへの接続用: HTTP で動いているインスタンスにつなぐ(types login whoami content schema media search taxonomy menu site)。

認証の優先順位

接続用コマンドは、次の順でトークンを決めます。

  1. --token フラグ
  2. 環境変数 EMDASH_TOKEN
  3. emdash login が ~/.config/emdash/auth.json に保存した資格情報
  4. 接続先が localhost でトークンがなければ、開発用バイパスで自動認証

接続先は --url(または EMDASH_URL)で、既定は http://localhost:4321 です。出力は対話端末なら整形され、--json またはパイプのときは生の JSON になります。

用途別コマンド表

環境の準備・確認(types のみ稼働中インスタンスに接続。ほかはローカル SQLite)

用途 コマンド 補足
DB 初期化 emdash init コア移行を実行し、package.json の emdash.schema の SQL を適用。--force で再適用
シード適用・検証 emdash seed [path] --validate は DB を変更しない(CI 向け)。--on-conflict skip/update/error、--skip-media
健全性チェック emdash doctor 接続・移行・コレクション・テーブル・ユーザーを検査。失敗があれば非ゼロ終了
型の生成 emdash types 稼働中インスタンス(開発サーバー等)に接続して .emdash/types.ts と schema.json を出力
現在のスキーマ+内容を書き出す emdash export-seed --with-content、--media-base-url。標準出力に JSON

デプロイ時

用途 コマンド 補足
移行の確認・適用 emdash migrate --check(適用せず確認)、--status --json。down や --dry-run はない

migrate の終了コードは、0 成功、1 エラー、2 未適用の既知の移行あり(--check)、3 未知の適用済み記録あり、4 確認なし・拒否・フィンガープリント不一致、130 中断です。CI では 2 と 3 を区別して扱えます。非対話の適用には、--status が表示する対象フィンガープリントを --expected-target-fingerprint で渡す必要があります。

コンテンツ操作(稼働中サイト)

用途 コマンド 補足
一覧・取得 content list <col> / content get <col> <id> get は _rev を返す
作成 content create <col> --data / --file / --stdin のどれか一つ。既定で自動公開、--draft で下書き
更新 content update <col> <id> --rev ... _rev が必須。古いと 409。既定で自動公開、--draft で下書きのまま保つ(REST・MCP とは異なる)
公開・非公開 content publish / unpublish
予約 content schedule <col> <id> --at <ISO8601> Z か UTC オフセット付き
削除(ゴミ箱) content delete ソフト削除
復元 content restore 下書きとして戻る
翻訳一覧 content translations

別のエディターが管理画面でエントリーを開いていると、更新・削除・公開などは ENTRY_LOCKED(409)で拒否されます。--override-lock で上書きできますが、相手の編集を壊す可能性があるため、まず待つのが原則です。

スキーマ・メディア・分類・メニュー・検索

用途 コマンド 補足
コレクション一覧・詳細 schema list / schema get <col>
コレクション作成 schema create <col> --label ...
フィールド追加 schema add-field <col> <field> --type ... 型は string, text, url, number, integer, boolean, datetime, select, multiSelect, portableText, image, file, reference, json, slug, repeater
フィールド削除 schema remove-field 値も失われる
コレクション削除 schema delete <col> --force で確認を省略
メディア media list / upload / get / delete / repair-usage repair-usage は Admin ロールと admin スコープが必要(REST では schema:manage 権限として検査)
全文検索 search "語" --collection --locale --limit
タクソノミー taxonomy list / terms / add-term
メニュー menu list / get 参照のみ(作成・更新コマンドはない)
サイト転送 site export / site import ... 8 節
鍵の生成 secrets generate / fingerprint --write .env は既存エントリーを --force なしでは上書きしない
認証 login / logout / whoami login は OAuth Device Flow

注意: --url を省略すると既定は http://localhost:4321 です。ポートを変えて開発サーバーを起動しているときは、--url の付け忘れで別のインスタンスを操作しないよう気をつけてください。

落とし穴

  • content create と content update は既定で公開します。下書きにしたい(公開中の記事を即時に書き換えたくない)なら --draft を忘れないでください。
  • emdash types の出力は、現状 bylines と terms を使いながら、対応する型(ContentBylineCredit、TaxonomyTerm)を import しない、と公式が注意しています。型チェックの前に import 行へ手で追加が必要で、再実行すると上書きされます。
  • init seed doctor export-seed はローカルの SQLite ファイル専用です。D1 や PostgreSQL の本番 DB に使うのは migrate です。
  • export-seed の $media は --media-base-url を付けないと相対パスになり、seed 側でスキップされてフィールドが空になります。localhost や私的ネットワークの URL からは seed がダウンロードしません。

セキュリティ

セキュリティ: CLI は本番にも向けられます。--url に本番 URL を渡した瞬間、手元のコマンドが本番データを変更します。次の点を守ってください。

  • 削除系を本番に向ける前に確認する: content delete(ゴミ箱)は戻せますが、schema remove-field と schema delete は保存済みの値を失います。実行前にバックアップを取り、schema get で対象を確認します。
  • emdash login のトークンは admin スコープを持つ: 資格情報は ~/.config/emdash/auth.json に保存されます。共有マシンや CI に残さないでください。CI では用途を絞ったトークンを EMDASH_TOKEN で渡します。
  • --force と --override-lock は確認・保護の解除: 習慣的に付けないでください。
  • 開発用バイパスは localhost のみ: ローカルで無トークンで動くのはこの仕組みのためで、本番では使えません。

4. 公開 API: サーバー側クエリ関数

なぜ

テーマやページ(.astro)からコンテンツを読むための関数群です。公式は「サイトテンプレート API」と呼び、保守されているテンプレートが実際に使う関数を契約として一覧しています。データベースのリポジトリやプラグイン作成用 API は対象外です。

どうやる

getEmDashCollection と getEmDashEntry がまず覚える二つで、どちらも例外を投げず { entries, error } / { entry, error } を返します(Astro のライブコンテンツコレクションと同じ流儀)。

import { getEmDashCollection, getEmDashEntry } from "emdash";

const { entries: posts, error } = await getEmDashCollection("posts", {
  status: "published", limit: 5, orderBy: { published_at: "desc" },
});

const { entry, error: e2 } = await getEmDashEntry("posts", slug);
if (e2) return new Response("Server error", { status: 500 });
if (!entry) return Astro.rewrite("/404");

重要なのはエラーと「見つからない」の区別です。見つからないときは entry が null で error は未設定、本当の障害のときだけ error が入ります。

getEmDashCollection のオプション(CollectionFilter)は次のとおりです。

オプション 意味
status draft / published / archived
limit 件数
cursor / offset ページネーション。同時には使えない。cursor は前回の nextCursor を渡す
where フィールド・タクソノミー・byline による絞り込み。範囲指定(gt gte lt lte)も可
orderBy 並び順
locale ロケール

用途別の関数一覧

用途 関数
一覧・単体の取得 getEmDashCollection, getEmDashEntry, getEmDashReferences(参照フィールドの続きのページ)
URL 処理 decodeSlug(動的ルートのパラメーターをデコード), slugify, resolveEmDashPath
リンクの安全化 sanitizeHref, isSafeHref
サイト設定 getSiteSettings, getSiteSetting(読み取り専用)
SEO getSeoMeta(フォールバック込み), getContentSeo(生の値), getHreflangAlternates
メニュー getMenu, getMenus
分類 getTaxonomyTerms, getTerm, getEntryTerms, getEntriesByTerm, getTermsForEntries(一括)
著者 getByline, getBylineBySlug, getEntriesByByline
検索 search(query, { collections, limit, cursor, scope })
コメント getComments, getCommentCount
ウィジェット・セクション getWidgetArea(s), getSection(s)
プレビュー generatePreviewToken, verifyPreviewToken, getPreviewUrl, isPreviewRequest
キャッシュ連携 get…WithCacheHint 系(getMenuWithCacheHint など)

落とし穴

  • ループ内で getEntryTerms を呼ばない。 一覧ページでは getTermsForEntries / getAllTermsForEntries で一括取得します。
  • getTaxonomyTerms は既定でカウントを含む。 カウントを表示しないなら includeCounts: false で負荷を減らせます。
  • プレビューは自動。 有効な _preview トークンがあると getEmDashEntry が下書きを返します。パラメーターは不要です。
  • サーバー側のコメント取得は最大 500 件。 ページネーションが必要なクライアントは REST API を使います。
  • 日本語検索のトークナイザー。 検索の設定(REST の search-enable)には porter unicode61(既定) / unicode61 / trigram があり、公式はスペースで区切らない言語には trigram を挙げています。ただし 3 文字未満のクエリは一致しません。

セキュリティ

セキュリティ: メニューやコンテンツに保存された URL をそのまま href に出さず、sanitizeHref を通します。javascript: などのスキーム、プロトコル相対 URL、制御文字を弾き、危険なら "#" を返します。

5. REST API: 認証・主要エンドポイント・エラー形式

位置づけ

REST API は /_emdash/api/ 以下にあり、OpenAPI 3.1 文書が GET /_emdash/api/openapi.json で得られます。OpenAPI に載っているものだけが外部クライアント向けの公式契約で、ソースにあっても載っていないルート(バックアップ、バイライン管理、プラグイン管理、セットアップ、インポートなど)は対象外です。クライアント生成にはこの文書を使うのが筋です。

認証

方式 使いどころ
セッション Cookie 管理画面・ブラウザ。状態を変える要求には X-EmDash-Request: 1 ヘッダーが必要(CSRF 対策)
Bearer トークン 外部クライアント。Authorization: Bearer $EMDASH_TOKEN。ヘッダーは不要

Bearer は個人アクセストークン(接頭辞 ec_pat_、管理画面で作成)か OAuth アクセストークンで、トークンのスコープとユーザーのロールの両方で制限されます。スコープがあってもロールが足りなければ拒否されます。コメントの公開取得・投稿(/comments/{collection}/{contentId})は認証不要で、投稿はモデレーション待ちになります。

レスポンス形式

成功は success: true と data、失敗は success: false と error.code / error.message です。

{ "success": false, "error": { "code": "NOT_FOUND", "message": "Content item not found" } }
ステータス 意味
400 入力不正
401 認証なし・無効
403 スコープ・権限不足
404 存在しない
409 状態の競合(_rev 不一致、ENTRY_LOCKED など)
413 アップロードが大きすぎる
422 プラグインが保存を拒否
500 内部エラー

エラーは code で分岐してください。メッセージ文は変わりえますが、コードは安定しています(公式の位置づけ)。

主要エンドポイント

公式のインベントリは数百行に及びます。分類だけ頭に入れれば十分です。

分類 パス 代表操作
Content /content/{collection}[/{id}] 一覧・作成・取得・更新・削除(ゴミ箱)
.../publish .../unpublish .../schedule 状態遷移
.../restore .../permanent ゴミ箱から復元、完全削除
.../compare .../discard-draft ライブと下書きの比較、下書きの破棄
.../lock 編集ロックの取得・解除(7 分のリース)
Media /media, /media/upload-url, /media/{id}/confirm 直接アップロード、署名 URL 方式
Schema /schema/collections[/{slug}/fields] コレクション・フィールドの CRUD
Taxonomies / Menus / Sections / Widgets /taxonomies /menus /sections /widget-areas 各 CRUD
Settings / Search / Redirects / Comments /settings /search /redirects /admin/comments
Users /admin/users 一覧・更新・無効化
Transfer /admin/transfer/... サイト転送(8 節)

更新は「読んでから書く」: _rev

コンテンツの更新は、まず GET で取得して _rev を受け取り、その値を PUT に添えます。

PUT /_emdash/api/content/articles/01J...
Authorization: Bearer $EMDASH_TOKEN
Content-Type: application/json

{ "data": { "title": "Updated launch notes" }, "_rev": "opaque-revision-token" }

_rev が古ければ競合(409)になり、他の編集者の変更を黙って上書きしません。_rev の扱いは入口ごとに違います(ライフサイクルリファレンスの表より)。

入口 更新時の _rev
REST 任意(省略すると無条件書き込み)
CLI(content update) 必須(--rev)
MCP 必須

MCP は AI が内容を読まずに上書きしないよう、必須になっています。REST で省略できる点は便利ですが、無条件の上書きを選ぶ自覚が必要です。

REST と MCP では、公開済みエントリーを更新すると、ライブは変わらず下書きが作られます。CLI の content update は既定で自動公開するため、ライブがそのまま書き換わります(--draft を付けたときだけ下書き)。compare で差分を確認し、publish で反映、不要なら discard-draft で捨てます。

落とし穴

  • ページネーションは cursor(前回応答の nextCursor をそのまま渡す。中身を解釈しない)と limit(1〜100、既定 50)。一部の一覧は page の番号指定も可で、両方を渡すと 400 です。
  • 通信が途中で切れたとき、エラーが「何も変わっていない」証拠にはなりません。ライフサイクル操作は、再試行する前にエントリーを読み直します。
  • アップロードの署名 URL が別オリジンの場合、EmDash のトークンをそこへ送らないでください(ストレージ側にトークンが漏れます)。

セキュリティ

セキュリティ: REST API には取り返しのつかない操作があります。スキーマ削除、コンテンツの完全削除、コメント削除、リダイレクトの 404 ログ全消去(DELETE /redirects/404s)、メディア保守系です。公式も、対象を正確に特定し最新のバックアップを取ってから送るよう警告しています。自動化に使うトークンは、必要最小限のスコープで発行してください。

セキュリティ: メディア利用状況の修復(/admin/media-usage/)は、Bearer の場合 admin スコープに加えて schema:manage 相当の権限が要る運用操作です(CLI の資料は「Admin ユーザーと admin スコープ」、REST の資料は「セッションは schema:manage、Bearer はさらに admin スコープ」と書き方が異なります。公式ドキュメントのファイル間で記述が異なりますが矛盾はなく、本書は両方を併記します)。公式の手順は、直接 DB に書き込むプロセスを止めてから有効化するもので、途中で取り消せません。必ずステージングで試してください。

6. MCP サーバー: AI エージェントから操作するときの権限と注意

位置づけ

/_emdash/api/mcp に組み込みの MCP サーバーがあります。既定で有効ですが、Bearer トークンが必須なので匿名アクセスはできません(セッション Cookie でも認証できません)。不要なら mcp: false で無効化します。トランスポートはステートレスな Streamable HTTP で、POST のみ受け付け、GET と DELETE は 405 です。

トークンの種類

方式 用途
OAuth 2.1 認可コード + PKCE 対話型の MCP クライアント。ブラウザーでスコープを承認
個人アクセストークン(ec_pat_) 長期の自動化
OAuth デバイス認可 CLI(emdash login)

OAuth の同意画面では、要求されたスコープがすべて選択済みで表示されます。不要なものを外してから承認するのが公式の勧めです。付与されるのは、要求・クライアント登録・ユーザーのロールの共通部分で、空の付与は拒否されます。

スコープ早見表

スコープ できること
content:read コンテンツ・バイライン・タクソノミー・メニュー・リビジョンの読み取りと検索
content:write コンテンツ・バイライン・リビジョンの変更(互換のため taxonomies:manage と menus:manage も含む)
media:read / media:write メディアの参照 / アップロード・更新・削除
schema:read / schema:write コレクション・フィールドの参照 / 作成・変更・削除
taxonomies:manage / menus:manage 分類 / メニューの変更
settings:read / settings:manage サイト設定の参照 / 更新
mcp:tools / mcp:tools:<pluginId> プラグインが公開する MCP ツールの呼び出し
transfer:export / transfer:analyze / transfer:execute サイト転送の各段階
admin コアのすべてのツール(転送を含む)。プラグインのツールは別途スコープが必要

スコープと別に、ロールで制限される

できること 最低ロール
公開済みコンテンツ・メディア・分類・メニューの読み取り Subscriber
下書き・予約・ゴミ箱・差分・リビジョンの読み取り、コンテンツ作成、メディアアップロード Contributor
自分の公開済みコンテンツの編集、自分のコンテンツの公開 Author
バイライン・分類・メニューの管理、全員のコンテンツ Editor
スキーマ・設定の読み取り Editor
スキーマ・設定の変更、完全削除、メディア利用状況の修復、サイト転送 Admin

「スコープがあってもロールが足りなければ拒否される」ので、トークンを強くするより、AI に使わせるアカウントのロールを低く保つほうが確実な防御になります(筆者の見解)。

図 9-2 に示すように、Bearer トークンの要求は、トークンのスコープとユーザーのロールの両方を満たしたときだけ許可されます。

図 9-2: スコープとロールの二重制限

落とし穴

  • content_update は部分更新で、省略したフィールドは保持されます。公開済みなら下書きが作られます。
  • media_usage_repair の partial / failed / stale は成功応答として返ります。isError だけで判断せず、状態と件数を見ます。
  • サイト転送の最中は、書き込み系ツール(プラグイン含む)が TRANSFER_IMPORT_IN_PROGRESS で失敗します。

セキュリティ

セキュリティ: AI に本番サイトを操作させるときの原則は次のとおりです。

  • 最小スコープで承認する。 記事の下書き作成だけなら content:read と content:write で足ります。admin は与えません。
  • ロールの低いアカウントで接続する。 下書き作成だけなら Contributor で十分です。
  • destructiveHint: true のツールは確認する。 公式は、削除できるツールは対象と現在の状態を確認してから呼ぶよう求めています。クライアント側で書き込み呼び出しを逐一承認する設定にします(ChatGPT 向けのガイドも、書き込み前の確認を勧めています)。
  • まず下書きで作らせ、人が確認してから公開する。
  • スキーマ変更は Admin 限定。 「フィールドを足して」と頼んだつもりでも、削除ツールも同じスコープに入っています。
  • プラグインの MCP ツールは管理者が個別に有効化する。 呼び出しは監査ログに記録されます。

7. AI ツール連携・x402 決済(概要)

AI ツール連携

サイトの MCP サーバーの URL は https://<ドメイン>/_emdash/api/mcp(ローカルは http://localhost:4321/_emdash/api/mcp)です。Claude はリモートのカスタムコネクターとして、Codex は次のように追加し、OAuth でログインします。

codex mcp add emdash-site --url https://example.com/_emdash/api/mcp
codex mcp login emdash-site

接続画面の操作は Anthropic や OpenAI 側で変わるため、公式は各社の最新手順を参照するよう案内しています。接続後は自然言語で頼めます。公式のコツは、コレクションを具体的に指定すること、先にスキーマを確認させること、下書きで作らせて公開前にレビューすること、compare で差分を見ること、リッチテキストは Portable Text なので複雑な書式は管理画面で整えることです。

x402 決済(概要のみ)

@emdash-cms/x402 は、サーバーレンダリングの Astro ルートに x402 決済プロトコルを足す独立の Astro インテグレーションです。EmDash がなくても動きます。支払いがない要求には 402 Payment Required と機械可読な支払い指示を返し、x402 に対応したエージェントやブラウザーが支払って再要求します。

項目 内容
設定 payTo(宛先ウォレット)、network(CAIP-2 形式。例 eip155:8453)、defaultPrice
ページでの使い方 Astro.locals.x402.enforce(request, { price }) が 402 の Response か結果を返す。返った Response はそのまま return する
EmDash との組み合わせ number 型フィールドに価格を持たせ、entry.data.price を enforce に渡す
bot-only モード Cloudflare Bot Management のスコアが閾値(既定 30)未満の要求だけ課金。データがなければ人間扱いで課金されない

注意: hasPayment() は支払いヘッダーの有無を見るだけで、検証しません。ヘッダーは偽造できるため、有料コンテンツを出す判断には必ず enforce() を使います。bot-only モードは、Bot Management のデータがない環境では強制がスキップされる(フェイルオープン)ため、欠落時に拒否したい用途には向きません。

本書では x402 の運用(ファシリテーターの選定、ウォレット管理、法務・税務)には踏み込みません。未検証です。

8. サイト転送(.emdash パッケージ)

なぜ

「別の EmDash にサイトを丸ごと移したい」ときの仕組みです。サイトパッケージは、コンテンツモデル、全ロケールの全エントリー(下書き・予約・ゴミ箱・リビジョン履歴を含む)、分類、メニュー、ウィジェット、リダイレクト、コメント、メディア本体、移植可能なサイト設定を含みます。SQLite、PostgreSQL、D1 の間でも移せます。

どうやる

エクスポート(元サイトで)

npx emdash login --url https://example.com
npx emdash site export --url https://example.com --output site.emdash

中断しても同じコマンドで再開できます。--no-comments でコメントを除外できます。管理画面の Settings → Transfer からも可能です。

インポート(移行先で。二段階)

npx emdash login --url https://new.example.com   # 移行先へ先にログイン(または --token)
npx emdash site import site.emdash --url https://new.example.com --analyze
npx emdash site import site.emdash --url https://new.example.com --plan sha256:... --confirm
  1. --analyze がパッケージを検証・アップロードし、インポート計画(プラン)とそのダイジェストを表示する。ブロッカーがあると終了コード 2。
  2. 計画を読んで、著者の対応付け(--map-principal)やタイトルの扱いを決める。決定を変えるとダイジェストも変わる。
  3. --plan <ダイジェスト> --confirm で、読んだ計画とダイジェストが一致するときだけ実行される。

図 9-3 に、書き出しから受領書の確認までの流れと、実行中の注意をまとめます。

図 9-3: サイト転送の流れ(書き出し、分析、計画の確認、実行)

移行先の条件

  • 管理者アカウントがあること、ストレージが設定されていること。
  • コンテンツが空であること。公式テンプレートでセットアップした直後のサイトは該当し、セットアップが作った初期の骨組み(シード済みコレクション等)は、計画を確認した後にインポートが削除します。
  • パッケージのロケールがすべて i18n 設定にあること(i18n 未設定のサイトは en のみ)。
  • 全メディアが maxUploadSize(既定 50 MiB = 52,428,800 バイト。configuration では「50 MB」と表記される)に収まること。

条件は GET /_emdash/api/admin/transfer/capabilities で確認できます。

落とし穴

  • 実行中は書き込みができない。 実行開始から完了まで(失敗・キャンセル後は「放棄」するまで)、他の書き込みは 503 TRANSFER_IMPORT_IN_PROGRESS で拒否されます。
  • 公開サイトは隠れない。 途中状態のサイトが訪問者に見えます。公式は、検証済みの受領書(レシート)を得るまで移行先を非公開に保つよう求めています。
  • 失敗・キャンセルは再開できず、放棄後は再インポートできない。 放棄(abandon)してもインポート済みデータは消えず、そのサイトはもう空ではありません。新しくセットアップしたサイトに入れ直します。
  • PostgreSQL へ移すとき: 整数は 32 ビット、number フィールドは 32 ビット浮動小数、全文検索は使えず無効化されます。
  • 成功すると受領書が出て、verification が verified であることを確認できます。受領書は署名されていないため、どのサーバーが発行したかの証明にはなりません。

セキュリティ

セキュリティ: サイトパッケージはバックアップと同等の機密情報です。下書きやゴミ箱の内容、著者・コメント投稿者のメールアドレスを含みます。公開バケットや共有フォルダに置かず、不要になったら削除してください。一方で、パッケージ自体は信頼できない入力として扱われ、コードや SQL を実行せず、URL も取得しません。

転送はロール Admin が必要で、admin スコープのトークンは三段階すべてを実行できます。AI エージェントには transfer:analyze だけを与える、といった絞り込みが可能です。その場合、site_export_start と site_import_start は管理者の承認(15 分以内)が要ります。承認は一回限りで、トークン・引数と結び付きます。承認できるのはセッションだけで、API トークンは承認できません。

WordPress との違い

観点 WordPress EmDash
設定の置き場 wp-config.php と DB の options astro.config.mjs・環境変数(インフラ)と管理画面(内容)
外部アクセス REST API とアプリケーションパスワード REST と MCP。スコープとロールの二重制限
競合する編集 最後の保存が勝つ _rev による検出、編集ロック(7 分)
サイトの移行 エクスポート XML・DB ダンプ サイトパッケージ(検証・受領書つき)。空のサイトにのみ

まとめ

  • リファレンスは「設定」「CLI」「サーバー側 API」「REST」「MCP」の五つに分けて引く。管理画面・REST・CLI・MCP は同じライフサイクル規則を共有する。
  • 設定は database だけが必須。本番では siteUrl、ストレージ、認証、maxUploadSize を意識する。
  • CLI はローカル SQLite 用と稼働中サイト用に分かれ、--url が本番を向いた時点で本番を操作する。削除系はゴミ箱・値の消失・完全削除で重さが違う。
  • 更新は「読んでから書く」(_rev)。REST では任意、CLI と MCP では必須。
  • MCP はスコープとロールの二重制限。AI には最小スコープ、低いロール、下書きまでを原則とする。
  • サイト転送は「分析 → 計画の確認 → ダイジェスト指定で実行」の二段階で、移行先は空のサイトに限る。

理解度チェック

  1. CLI の接続用コマンドが使うトークンの優先順位を、高い順に答えてください。また、localhost に無トークンで接続できる理由は何ですか。
  2. emdash content delete で削除した記事を完全に消すには、どの入口でどの操作が必要ですか。必要な権限も答えてください。
  3. 同じ「記事の更新」でも、REST、CLI、MCP で _rev の扱いが異なります。それぞれどう違い、なぜ MCP は必須になっていると考えられますか。
  4. AI エージェントに記事の下書き作成だけを任せたい場合、どのスコープを承認し、どのロールのアカウントで接続しますか。また、それでも守りきれないものは何ですか。
  5. サイト転送のインポートで --analyze と --plan ... --confirm の二段階に分けてある理由を説明してください。
  6. 次の作業に最初に開くリファレンスを選んでください。(a) リバースプロキシ配下でパスキーが失敗する (b) .astro で最新 5 件の記事を出す (c) AI に付与するスコープを決める

答え

  1. --token フラグ、EMDASH_TOKEN 環境変数、emdash login による保存済み資格情報、開発用バイパスの順です。接続先が localhost でトークンがない場合に、開発用バイパスのエンドポイントで自動認証されるためです。
  2. CLI の content delete はゴミ箱に移すだけです。完全削除は REST の DELETE /content/{collection}/{id}/permanent か、MCP の content_permanent_delete で行い、ゴミ箱内のエントリーが対象です。content:delete_permanent 権限(Admin)が必要です。CLI リファレンスには完全削除のコマンドが載っていません。
  3. REST は任意(省略すると無条件の上書き)、CLI の content update は --rev が必須、MCP も必須です。MCP が必須なのは、エージェントが現状を読まずに上書きすることを防ぐためと読めます(ライフサイクルリファレンスの趣旨。理由の解釈は筆者の見解)。
  4. content:read と content:write を承認し、admin は与えません。ロールは Contributor で、下書き作成・自分の下書きの編集ができます。守りきれないのは、与えたスコープの範囲内で起きる誤りです(たとえば不適切な内容の下書き)。そのため、下書きで作らせて人が確認してから公開します。
  5. 計画(何が作られ、何が削除され、どんなブロッカーや警告があるか)を人が読んでから実行するためです。実行にはその時点の計画ダイジェストが要り、計画が変わっていれば TRANSFER_PLAN_DIGEST_MISMATCH で拒否されます。レビューしていない計画は実行されません。
    1. Configuration(siteUrl、trustedProxyHeaders、Astro の security.allowedDomains)、(b) JavaScript API(getEmDashCollection)、(c) MCP Server(スコープとロール要件の表)。

付録: 用途から引く索引

やりたいこと 入口 書き方・リファレンスの節
DB やストレージを切り替える 設定 database / storage(2 節)
公開 URL・プロキシを正しく設定する 設定 siteUrl / trustedProxyHeaders / allowedOrigins
アップロード上限を変える 設定 maxUploadSize
管理画面の日本語フォントを足す 設定 fonts: { scripts: ["japanese"] }
外部ログイン(GitHub など)を足す 設定 authProviders
ローカル DB を初期化・検査する CLI init / doctor
シードを検証・適用する CLI seed --validate / seed
現状をシードに書き出す CLI export-seed --with-content
型を生成する CLI 自動(emdash-env.d.ts)/ types(リモート)
本番 DB の移行状況を調べる CLI migrate --check / --status --json
記事を作る・公開・予約する CLI / REST / MCP content create/publish/schedule
記事を安全に更新する 全入口 get → _rev → update
記事を消す(戻せる) CLI / REST / MCP content delete(ゴミ箱)
記事を完全に消す REST / MCP .../permanent / content_permanent_delete(Admin)
フィールドを足す CLI / REST / MCP schema add-field
一覧ページで記事を出す サーバー側 API getEmDashCollection(4 節)
記事ページを作る サーバー側 API getEmDashEntry + decodeSlug
検索ボックスを作る サーバー側 API / REST search / GET /search
保存済み URL を安全に出す サーバー側 API sanitizeHref
外部システムから操作する REST Bearer トークン + OpenAPI(5 節)
AI から操作する MCP OAuth + 最小スコープ(6 節)
有料コンテンツにする x402 enforce()(7 節)
サイトを別環境へ移す サイト転送 site export / site import(8 節)

出典

公式ドキュメント(EmDash、MIT License、Copyright 2026 Cloudflare Inc.)。ローカルの sources/emdash-docs/ にある以下のファイルを参照しました。公式サイトの対応ページは、URL が資料内の相対リンク(/reference/...、/guides/...)に基づく推定です。

  • 2 節(設定): reference/configuration.mdx (https://docs.emdashcms.com/reference/configuration/)(/reference/configuration/)
  • 3 節(CLI): reference/cli.mdx (https://docs.emdashcms.com/reference/cli/)(/reference/cli/)
  • 4 節(サーバー側 API): reference/api.mdx (https://docs.emdashcms.com/reference/api/)(/reference/api/)
  • 5 節(REST API・ライフサイクル): reference/rest-api.mdx (https://docs.emdashcms.com/reference/rest-api/)(/reference/rest-api/)、reference/content-lifecycle.mdx (https://docs.emdashcms.com/reference/content-lifecycle/)(/reference/content-lifecycle/)
  • 6 節(MCP サーバー): reference/mcp-server.mdx (https://docs.emdashcms.com/reference/mcp-server/)(/reference/mcp-server/)
  • 7 節(AI ツール、x402): guides/ai-tools.mdx (https://docs.emdashcms.com/guides/ai-tools/)(/guides/ai-tools/)、guides/x402-payments.mdx (https://docs.emdashcms.com/guides/x402-payments/)(/guides/x402-payments/)
  • 8 節(サイト転送): guides/site-transfer.mdx (https://docs.emdashcms.com/guides/site-transfer/)(/guides/site-transfer/)

外部: Model Context Protocol(https://modelcontextprotocol.io)、x402(https://www.x402.org/)。いずれも資料内のリンクを示したのみで、本章作成時に別途確認していません。