rex0220 kSQL アクションプラグイン - ⑦ オーサリング編（設定を AI に作ってもらう）

Last updated at 2026-11-08Posted at 2026-11-03

これまでの記事は、設定画面で SQL とアクションを手で作る話でした。この記事では、AI に頼んで設定ファイルを作ってもらう方法を紹介します。公開した MCP サーバー（kact）を Claude Desktop か Claude Code に入れると、日本語の依頼から設定ファイルができます。

シリーズ: 概要 / ① 詳細画面 / ② 一覧 / ③ 集計 / ④ 運用 / ⑤ 事例 / ⑥ イベント / ⑦ オーサリング（この記事） / ⑧ 請求データ / ⑨ 締めの画面 / ⑩ どこに出すか / ⑪ 多言語 / ⑫ オーサリング改善

この記事で作るもの

点検アプリに、ボタンを押したらそのレコードの「確認済」にチェックを入れるだけのアクションを作ります。

項目コード	型
`点検日`	日付
`担当`	文字列（1 行）
`確認済`	チェックボックス（選択肢は `Y` の 1 つだけ）

いちばん小さな処理ですが、詳細画面と一覧の両方にボタンを出すことと、もう Y が入っているレコードではボタンを出さないことまで含めます。一周りを 1 本の記事で追えます。

仕組みの概要

AI が触るのは上の 3 本の矢印、つまり kintone からの読み取り・zip の中の検査・作業フォルダーへの書き出しだけです。kintone のレコードが変わるのは、利用者が設定を反映してボタンを押したときだけになります。

大事な前提

AI は kintone に書き込みません。 ツールが kintone に送るのは読み取り（GET）だけで、アプリの一覧・項目定義・一覧（ビュー）しか読みません。レコードも読みません
設定の取り込みと実行は利用者が行います。 AI が作るのは設定ファイル（JSON）だけで、それを設定画面でアップロードして保存・反映するのはあなたです
検査はプラグイン本体と同じコードで動きます。MCP はプラグインの zip からオーサリング API を読み込んで呼ぶので、「ツールは通ったのに設定画面で保存できない」が起きにくい作りです

用意するもの

kSQL アクションプラグインの zip（Ver.1 以降。試用版でかまいません）。検査と計算式エンジンはこの zip から読みます
kintone の接続のファイル（任意）。項目定義を読むのに使います。kSQL の ksql.config.json と同じ形で、作業フォルダーの外に置きます
作業フォルダー。できた設定ファイルを置く場所です

入れ方（Claude Code）

/plugin marketplace add rex0220/ksql-action-authoring
/plugin install ksql-action@rex0220-ksql-action

入れたら /config で、プラグインの zip と接続のファイルを絶対パスで指定し、Claude Code を起動し直します。

入れ方（Claude Desktop）

リリースのページから .mcpb をダウンロードしてダブルクリックし、拡張機能の設定で作業フォルダー・zip・接続のファイルを指定します。

読めているかは kact_status で確かめられます。

プラグインの版 1 / オーサリング API の版 4 / 計算式エンジン あり

頼んでみる

チャットにこう書きます。

kSQL アクションの設定を作ってください。
アプリ 4399「[記事] 点検」で、ボタンを押したらそのレコードの「確認済」に Y を入れるだけの処理です。
ボタンはレコードの詳細画面と、一覧で選んだレコードに対して出したいです。
もう Y が入っているレコードでは、ボタンを出さないでください。
一覧でまとめて実行するときも、すでに Y のレコードは対象から外してください。

最後の 2 行は、別々の設定になります。「ボタンを出さない」は表示条件、「対象から外す」は実行条件です。詳しくは後の「できた設定」で説明します。

アプリ番号は自分で書きます。 ツールの決まりで、AI はアプリ番号・一覧 ID・項目コードを推測しません（違うアプリを壊さないためです）。

AI は次の順で道具を呼びます。

#	道具	何のため
1	`kact_status`	zip が読めるか（版・オーサリング API の版・計算式エンジン）
2	`kact_fields`	項目定義の控えを取る
3	`kact_try`	表示条件の式を試し計算する
4	`kact_save_config`	設定ファイルを作る（保存の前に検査を通す）
5	`kact_explain`	実行計画（取り込む前に「全件に当たらないか」を見る）

項目定義を取ると検査が強くなる

kact_fields でアプリの項目定義を読むと、作業フォルダーに控えが置かれます。

項目定義を fields/<profile>/APP4399.json に置いた（11 項目）

確認済       CHECK_BOX          確認済
担当         SINGLE_LINE_TEXT   担当
点検日       DATE               点検日
レコード番号  RECORD_NUMBER      writable: false（自動）
更新日時     UPDATED_TIME       writable: false（自動）
…

writable: false が付いているのは、kintone が値を決める項目（レコード番号・作成者・更新日時など）と、計算項目・ルックアップのコピー先です。SET に書けない項目がひと目で分かります。

これがある場合とない場合で、計算式の検査の深さが変わります。

控え	見るもの
なし	式の構文だけ（引用符と括弧の対応）
あり	設定画面の保存と同じ検査。項目コードと関数名の誤りもその場で止まる

項目コードを 1 文字打ち間違えただけでも、保存の前に分かります。

式を試す（`kact_try`）

「もう Y が入っているレコードではボタンを出さない」は表示条件（計算式）です。チェックボックスなので、書き方に落とし穴があります。

kact_try は、架空の値を当てて式を実際に評価します。チェックボックスが空・1 つ選択・2 つ選択のときで比べると、こうなります。

式	空	`["Y"]`	`["A","Y"]`
`IN(確認済, "Y")`	偽	真	真
`確認済 = "Y"`	偽	真	偽
`確認済`（そのまま読む）	`""`	`"Y"`	`"A,Y"`
`ARRAY_COUNT(確認済)`	0	1	2
`LENGTH(確認済)`	0	1	3

= で比べてはいけません。 チェックボックスは複数選べるので、2 つ以上選ばれていると "A,Y" という文字列との比較になって外れます。LENGTH も文字数を返すので、選んだ数を数えるなら ARRAY_COUNT です。

したいこと	式
その値が入っている	`IN(確認済, "Y")`
その値が入っていない	`NOT(IN(確認済, "Y"))`
どれか 1 つでも入っている	`IN(状態, "A", "B")`
両方そろっている	`AND(IN(状態, "A"), IN(状態, "B"))`
何も選ばれていない	`ARRAY_COUNT(確認済) = 0`

今回の表示条件は NOT(IN(確認済, "Y")) です。kact_try の返りは、値のほかに表示条件として見たときの真偽と、パラメーターとして SQL に注入される文字列も教えてくれます。

NOT(IN(確認済, "Y"))
  確認済 が空      → value: true  / condition: 真（ボタンを出す）
  確認済 が ["Y"]  → value: false / condition: 偽（ボタンを出さない）

評価にはプラグイン本体の実行時と同じコードを使っています（真偽の判定も、パラメーターの文字列化も、実機と同じ関数です）。ですから、同じ値・同じ条件なら実機と同じ結果になります。実際のレコードの値は違うので、確かめたい場面の値を渡してください。

できた設定

SQL（1 文だけ）

-- @ksql dialect: 1
DECLARE @_record = '';

UPDATE LAPP_点検 SET 確認済 = 'Y'
 WHERE $id = @_record;

_record は予約パラメーターで、処理の対象になっているレコードの ID が自動で入ります。DECLARE に書くだけでよく、params には書けません（予約名は設定に書けない決まりです）
LAPP_点検 は論理アプリ名です。設定の「論理アプリの対応表」で 点検 → アプリ 4399 と結びつけます
SET 確認済 = 'Y' は kintone へ ["Y"] を送ります（チェックボックスは配列）

アクションの要点

設定	値	理由
種類	レコード	対象のレコードが 1 件に決まる
起動	詳細メニュー	詳細画面のボタン
一覧でも使う	はい	一覧のパネルにも出す
選択の渡し方	1 件ずつ	`_record` を使うのでこれ
表示条件	`NOT(IN(確認済, "Y"))`	もう `Y` のレコードにはボタンを出さない
実行条件	`NOT(IN(確認済, "Y"))`	一覧で選ばれても実行しない（「条件外」に数える）
実行条件 NG のメッセージ	`"すでに確認済みです"`	詳細画面で押されたときに出す文
確認	なし	1 項目に印を付けるだけ。押してすぐ終わるほうが現場は楽
書き込み上限	300	一覧でまとめて押したときの歯止め

確認を「なし」にするときは、書き込み上限が必須です（歯止めのない自動実行を作らせないため）。

表示条件と実行条件は効く場所が違う

同じ式を 2 か所に書いているのは、効く場所が違うからです。ここはつまずきやすいところです。

	表示条件	実行条件
いつ見るか	画面を開いたとき	押されたとき（レコードごと）
偽のとき	ボタンを出さない	実行せず、メッセージを出す
詳細画面	効く	効く
一覧の選択	効かない	効く（「条件外」に数える）
イベント起動	効かない	効く

一覧でまとめて押すときは、表示条件では弾けません。 表示条件は「ボタンを出すかどうか」の判定なので、Y が入っているレコードを選んで押しても、そのまま対象になってしまいます。一覧でも外したいなら、実行条件に同じ式を書きます。

この記事の処理は何度実行しても結果が同じ（SET は全置換なので Y が増えない）ため害はありませんが、すでに処理済みのレコードを対象から外したいときは実行条件が歯止めになります。

ただし、実行条件は同時実行の排他制御ではありません。押されたときに条件を見るだけなので、2 人がほぼ同時に押すと、どちらの実行でも条件を通ってしまうことがあります。採番・請求の確定・在庫の引き落としのように1 回しか実行してはいけない処理では、ログアプリによるロックを併せて使ってください（④ 運用編）。

実行計画を見る（`kact_explain`）

取り込む前に、その SQL が kintone に何を投げるかを見られます。kintone には行きません（控えの項目定義だけで計算します）。

[UPDATE]
  target:        APP900000000 (900000000)
  kintone query: $id = "@_record"
  selection: exact native pushdown; JS residual none
  search abort: DML fail-closed (SearchAbortedError; mutation 0)
  api:           GET /k/v1/records.json → PUT /k/v1/records.json
  set type:      単純 SET
  set fields:
    確認済 = 'Y'
  estimated API consumption (dialect 1):
    write: 不明（上限 dmlMaxRows=100 と仮定: 最大 1 回、100 件/HTTP リクエスト）

読みどころは 2 つです。

exact native pushdown — 絞り込みがkintone 側で効いている（全件を取ってから JS で絞ってはいない）という意味です。ここが JS residual になっていたら、条件の書き方を見直す合図です
set fields — 実際に書き換わる項目。意図しない項目が並んでいないかを見ます

APP900000000 はエンジンが内部で付ける名前で、アプリ番号ではありません。使ったアプリは返りの usedApps（ここでは [4399]）で分かります。

これは静的な計画です。 kintone のレコードは読んでいないので、次のことは実行計画では分かりません。

実際に何件が更新されるか（不明（上限 … と仮定） と出ているのはそのためです）
実データに対する権限エラー・ほかの人との競合
実際に消費する API の回数

「絞り込みが効いているか」「書き換わる項目は意図どおりか」を取り込む前に確かめるための道具で、実行結果を保証するものではありません。最後は試験用のアプリで実際に押して確かめてください。

取り込む

できた設定ファイルを、設定画面でアップロードします。

プラグインの設定画面を開く
［設定をアップロード］でファイルを選ぶ
取り込み方を選ぶ（設定がまだ無いアプリなら全置換、既にあるアプリに足すなら追加）
［保存する］
［運用環境に反映］

5 を忘れると画面の見え方は変わりません。 デスクトップの動きは運用環境の設定を読むので、保存しただけでは反映されません。

動かす

詳細画面

ヘッダーに［確認済にする］が出ます。押すと確認なしで実行され、結果が出ます。

完了しました（追加 0 / 更新 1 / 削除 0、0.5 秒）

［画面を更新］を押すと 確認済 に Y が入り、そしてボタンが消えます（表示条件が効いたため）。

一覧

一覧には「選択したレコードのみ一括処理」のチェックと、アクションのパネルが出ます。

レコードを選んでボタンを押すと、開始の確認が 1 回だけ出ます。

3 件のレコードに対して「確認済にする」を 1 件ずつ実行します。よろしいですか？

実行すると、内訳が返ります。すでに Y が入っているレコードを 1 件混ぜて 3 件選んだときの実測です。

対象 3 件: 成功 2 / 失敗 0 / 条件外 1 / 未処理 0（書き込み 2 件、0.9 秒）

Y 済みの 1 件が条件外に数えられ、書き込みは 2 件だけでした。これが実行条件の効果です。実行条件を書いていなければ、この 1 件も「成功」に数えられ、同じ値で上書きされていました。

もう一歩: 件数が多いとき

上の設定はレコード 1 件ずつ実行します（詳細画面と同じ SQL 1 本で済むのが利点です）。選ぶ件数が多いときは、一覧専用にもう 1 本足すと速くなります。

-- 一覧専用（まとめて 1 回）。詳細画面には出さない
-- @ksql dialect: 1
DECLARE @_selected = [];

UPDATE LAPP_点検 SET 確認済 = 'Y'
 WHERE $id IN @_selected;

	1 件ずつ	まとめて 1 回
実行の回数	選んだ件数ぶん	1 回
目安	約 0.7 秒 / 件・API 4 回 / 件	1 回ぶん
選べる上限	一括の上限（既定 300）	min(一括の上限, 200)
詳細画面でも使えるか	使える	使えない

_selected は選んだレコードの ID の配列です。DECLARE @_selected = []; と配列で宣言します。この形では _record が使えないので、詳細画面のボタンとは別のアクションになります。

気をつける点

1. SET はチェックボックスの選択を全置換します。

選択肢が複数ある項目に SET 確認済 = 'Y' と書くと、ほかの印は消えます。残したいなら「Y だけの項目」を別に作ってください。この記事で選択肢を Y の 1 つだけにしたのはそのためです。

2. 複数の選択肢を入れることはできます。

書き方	kintone へ送る値
`SET タグ = 'A,B'`（カンマ区切り）	`["A","B"]`
`SET タグ = ['A', 'B']`（配列リテラル）	`["A","B"]`
`SET タグ = @v`（パラメーターで `"A,B"`）	`["A","B"]`
`SET タグ = ''`	`[]`（空にする）

パラメーター経由でもカンマで分割されるので、計算式で "A,B" を組み立てれば、現場の選択に応じた複数セットもできます。

3. 「今の印を残したまま 1 つだけ足す」はできません。

エンジンにはそういう書き方がありますが、プラグインの実行経路では意図的に閉じてあります。全置換の形で書いてください。

4. 選択肢に無い値も、そのまま kintone に送られます。

SET タグ = 'Z' は ["Z"] を送ろうとして、実行して初めて kintone のエラーになります。設定の保存では止まりません。選択肢の名前は正確に書いてください。

（なお kact_try に渡す架空の値のほうは、選択肢に無い値を書くとその場で止まります。式を試すときの打ち間違いは拾えます。）

5. 予約パラメーターは params に書きません。

_record や _selected を params に書くと保存時にエラーになります。DECLARE に書くだけです。

6. 取り込みと実行はあなたの仕事です。

AI は kintone に書き込みません。作られた設定は、取り込んで反映して初めて動きます。本番のアプリに入れる前に、試験用のアプリで一度動かしてください。

まとめ

MCP（kact）を入れると、日本語の依頼から設定ファイルができます
項目定義を読ませると、計算式を項目コードまで検査できます
kact_try で、式の値・表示条件としての真偽・SQL に注入される文字列を、取り込む前に確かめられます
kact_explain で、絞り込みが kintone 側で効いているかを取り込む前に見られます
kintone への書き込みは利用者の操作だけ。AI は読み取りしかしません

ツールのソースと資料は ksql-action-authoring（MIT）で公開しています。

You get articles that match your needs
You can efficiently read back useful information
You can use dark theme

What you can do with signing up