本文へスキップ
mtbmtb

エージェントに渡す ​

mtb は人間がAIに使わせることを想定した CLI です。 このページでは、 そのために人間が準備しておくことをまとめています。

人間がやること、エージェントがやること ​

誰が
接続先の登録（mtb profile add）人間（またはエージェントに URL を渡して実行させる）
サインイン（mtb auth login）人間。Webサービスパスワードを持っているのは人間だから
どのサイトを操作するか決める人間。--site-id か既定サイトIDで固定する
実際の操作エージェント
削除してよいかの判断人間（--yes を付けるかどうか）

最初の3つを人間が済ませておくのが基本形です。エージェントに認証情報を 扱わせる必要はありません。

知識の渡し方は3通り ​

1. Claude Code プラグイン（いちばん確実） ​

/plugin marketplace add ideamans/claude-public-plugins
/plugin install mtb@ideamans-plugins

CLI の使い方だけでなく、Movable Type で CMS を作る知識（オブジェクトの 選び分け・権限・アーカイブ・614 のテンプレートタグ）も含まれています。 詳しくはClaude Code プラグイン。

2. mtb llm を読ませる ​

プラグインが使えないホストでは、埋め込みリファレンスをそのまま読ませます。

bash
mtb llm                  # Markdown（そのまま貼れる）
mtb llm --format json    # 章ごとのJSON配列（必要な章だけ渡す）

内容は認証・接続先・命名規則・出力・代表的なワークフロー・失敗モードの一覧です。 バイナリに埋め込まれているので、ネットワークが無くても読めます。

プロジェクトの CLAUDE.md や AGENTS.md に、次の1行を書いておくのが手軽です。

markdown
Movable Type を操作するときは `mtb` を使い、先に `mtb llm` を読むこと。

3. --help を読ませる ​

--help には、エンドポイントのパラメータが公式の OpenAPI 定義のまま表示されます。 迷ったらコマンド名を探すより速いことが多いです。

bash
mtb sites entries --help          # ぶら下がっている操作
mtb sites entries list --help     # パラメータ（公式の説明文つき）

コンテキストの消費を抑える ​

MT はリソースの全属性を返します。 サイト2件で 5KB、記事50件なら数十KB になり、 読み込むだけでコンテキストを大きく消費します。一覧では必ず --fields を使わせてください。

bash
mtb sites list --fields id,name,url                    # 200バイト弱で済む
mtb sites entries list 4 --fields id,title,status --limit 50

--fields はどのコマンドでも使えます。MT は GET にしか fields を用意して いませんが、対応していないエンドポイントでは mtb が応答を受け取ったあとに絞り込みます。 そのため、「作成したもののIDだけを受け取る」こともできます。

bash
mtb sites entries create --site-id 1 --entry @entry.json --fields id --compact
# => {"id":42}

1つの値だけが必要なら --extract を使います（jq は不要です）。

bash
ID=$(mtb sites entries create --site-id 1 --entry @e.json --extract id)

安全策 ​

何をするか
--dry-run送らずに、送るはずだった内容を表示する
--yes破壊的操作（DELETE）の確認を省く。付けなければ、端末でない環境では実行されずにエラー
--confirm <名前>サイトの削除など、中身ごと消える操作で、対象の名前を入力させる
終了コード原因ごとに分かれている（一覧）

--yes を無条件に付けさせないこと。 エージェントには「意図した削除にだけ 付ける」と伝えてください。プラグインのスキルにはそう記載してあります。

サイトの削除・ログの全消し・テンプレートの初期化は、--yes だけでは実行されません。

bash
mtb sites delete 2 --yes                       # 何が失われるかと、打つべき名前が出る
mtb sites delete 2 --yes --confirm "アイデアマンズ ブログ"

1件の削除と同じ扱いにすると、IDの取り違えでサイトが丸ごと消えます。 実際に総当たりテストでサイトが消えたため、この仕様にしています。

終了コードで分岐させる ​

エージェントに「失敗したら何をするか」を判断させるための表です。

コード意味次の手
2未認証・認証切れmtb auth login をやり直す
3権限不足リトライしても直らない。 人間に戻す
4対象が無いIDとベースURLを確認する
5呼び出し方の誤り送信していない。 直して再実行してよい
6接続できない・時間切れリトライの余地がある
8保存はできたが書き出せなかったテンプレートの誤りを直す

全部は終了コードにあります。

事故を防ぐ運用 ​

  • 検証用の MT を1つ用意する。 最初にそこで動作を確かめてから、本番を対象にします
  • 本番のプロファイル名を分かりやすくする（prod）。エージェントが --profile を書くときに目に入ります
  • 作業ディレクトリに .env を置いて固定する。 ただし 「どのディレクトリで実行したかで接続先が変わる」ことは覚えておいてください （接続先）
  • 操作の前に mtb profile show を実行させる。 設定を重ね合わせた結果と、読み込んだ .env の場所が表示されます

Claude Code で権限を絞るなら、スキルと同じ設定が使えます。

allowed-tools: Bash(mtb:*) Bash(jq:*) Read Write

任せてよい仕事、任せない仕事 ​

向いているもの

  • 数が多い仕事（記事の一括投入、画像の一括アップロード、棚卸し）
  • 環境をまたぐ仕事（ステージングと本番の差分・反映）
  • 決まった手順の繰り返し（公開前の点検、再構築の確認）
  • テンプレートの修正（プレビューで試してから反映できる）

任せないほうがよいもの

  • サイトの削除、ログの全消し、テンプレートの初期化。人間が --confirm を入力する
  • 本文の書式が絡む一括置換。Markdown やブロックエディタの原稿は、 取り出し方を間違えると原稿の書式が崩れます（データの受け渡し）
  • テーマの適用。テンプレートをすべて入れ替える操作です（テーマ）

次は ​

Last updated: