第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 は同じライフサイクル規則を共有し、サイトのページの読み出しは別のサーバー側クエリ関数が担います。右の注意のとおり、既定の挙動は入口ごとに同じではありません。
| 知りたいこと | 開くリファレンス | この章の節 |
|---|---|---|
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 ファイルを直接開く(
initdoctorseedexport-seed)。migrateはデプロイ先の DB に対して動く。 - 稼働中サイトへの接続用: HTTP で動いているインスタンスにつなぐ(
typesloginwhoamicontentschemamediasearchtaxonomymenusite)。
認証の優先順位
接続用コマンドは、次の順でトークンを決めます。
--tokenフラグ- 環境変数
EMDASH_TOKEN emdash loginが~/.config/emdash/auth.jsonに保存した資格情報- 接続先が 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 行へ手で追加が必要で、再実行すると上書きされます。initseeddoctorexport-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 トークンの要求は、トークンのスコープとユーザーのロールの両方を満たしたときだけ許可されます。
落とし穴
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--analyzeがパッケージを検証・アップロードし、インポート計画(プラン)とそのダイジェストを表示する。ブロッカーがあると終了コード 2。- 計画を読んで、著者の対応付け(
--map-principal)やタイトルの扱いを決める。決定を変えるとダイジェストも変わる。 --plan <ダイジェスト> --confirmで、読んだ計画とダイジェストが一致するときだけ実行される。
図 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 には最小スコープ、低いロール、下書きまでを原則とする。
- サイト転送は「分析 → 計画の確認 → ダイジェスト指定で実行」の二段階で、移行先は空のサイトに限る。
理解度チェック
- CLI の接続用コマンドが使うトークンの優先順位を、高い順に答えてください。また、localhost に無トークンで接続できる理由は何ですか。
emdash content deleteで削除した記事を完全に消すには、どの入口でどの操作が必要ですか。必要な権限も答えてください。- 同じ「記事の更新」でも、REST、CLI、MCP で
_revの扱いが異なります。それぞれどう違い、なぜ MCP は必須になっていると考えられますか。 - AI エージェントに記事の下書き作成だけを任せたい場合、どのスコープを承認し、どのロールのアカウントで接続しますか。また、それでも守りきれないものは何ですか。
- サイト転送のインポートで
--analyzeと--plan ... --confirmの二段階に分けてある理由を説明してください。 - 次の作業に最初に開くリファレンスを選んでください。(a) リバースプロキシ配下でパスキーが失敗する (b)
.astroで最新 5 件の記事を出す (c) AI に付与するスコープを決める
答え
--tokenフラグ、EMDASH_TOKEN環境変数、emdash loginによる保存済み資格情報、開発用バイパスの順です。接続先が localhost でトークンがない場合に、開発用バイパスのエンドポイントで自動認証されるためです。- CLI の
content deleteはゴミ箱に移すだけです。完全削除は REST のDELETE /content/{collection}/{id}/permanentか、MCP のcontent_permanent_deleteで行い、ゴミ箱内のエントリーが対象です。content:delete_permanent権限(Admin)が必要です。CLI リファレンスには完全削除のコマンドが載っていません。 - REST は任意(省略すると無条件の上書き)、CLI の
content updateは--revが必須、MCP も必須です。MCP が必須なのは、エージェントが現状を読まずに上書きすることを防ぐためと読めます(ライフサイクルリファレンスの趣旨。理由の解釈は筆者の見解)。 content:readとcontent:writeを承認し、adminは与えません。ロールは Contributor で、下書き作成・自分の下書きの編集ができます。守りきれないのは、与えたスコープの範囲内で起きる誤りです(たとえば不適切な内容の下書き)。そのため、下書きで作らせて人が確認してから公開します。- 計画(何が作られ、何が削除され、どんなブロッカーや警告があるか)を人が読んでから実行するためです。実行にはその時点の計画ダイジェストが要り、計画が変わっていれば
TRANSFER_PLAN_DIGEST_MISMATCHで拒否されます。レビューしていない計画は実行されません。 - Configuration(
siteUrl、trustedProxyHeaders、Astro のsecurity.allowedDomains)、(b) JavaScript API(getEmDashCollection)、(c) MCP Server(スコープとロール要件の表)。
- Configuration(
付録: 用途から引く索引
| やりたいこと | 入口 | 書き方・リファレンスの節 |
|---|---|---|
| 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/)。いずれも資料内のリンクを示したのみで、本章作成時に別途確認していません。