kSQL アクション — 設定のオーサリング（tools と MCP）
kintone プラグイン 「kSQL アクション」（rex0220 kSQL Action） の設定を、AI（Claude）が要望から作り・直すための環境です。 作った設定は、利用者がプラグインの設定画面で 設定をアップロード → 保存 → 運用環境に反映 して使います。
- AI は kintone に書き込みません。 読むのは項目定義などの GET だけで、取り込みと実行は必ず人が画面で行います。
- 検査はプラグイン本体と同じコードを使います。 設定の形・SQL（kSQL の Flow dialect 1）・テーブルへの書き戻し（APPLY）・計算式の検査は、
利用者が持っているプラグインの zip に同梱された「オーサリング API」（
config_js/ksql-action-authoring-api.js）を読み込んで呼びます。 このリポジトリに有償プラグインのコードは入っていません。 - 配り方は 2 つ: Claude Code のプラグイン（ツール名の接頭辞は
kact_）と、Claude Desktop の.mcpb。
要るもの
| もの | 置き場所 | 備考 |
|---|---|---|
| kSQL アクションプラグインの zip | 利用者が配布元から入手したもの | .env の KACT_PLUGIN_ZIP（または MCP の設定項目）で場所を指定 |
| kintone の接続のファイル | 作業フォルダーの外 | kSQL の ksql.config.json と同じ形。アプリごとの閲覧だけの API トークン |
| Node | 20 以上 |
使い方（概要）
- 作業フォルダーを用意し、MCP（または CLI）を登録する。
- AI に作りたいアクションを伝える（「受注を顧客ごとに集計して、集計アプリのテーブルに書き戻したい」など）。
- AI が項目定義を読み、SQL と計算式を組み立て、本体と同じ検査を通してから設定ファイルを保存する。
- 利用者が設定画面で取り込み、保存し、運用環境に反映して、ボタンを押して確かめる。
このリポジトリの中身
| フォルダー | 中身 |
|---|---|
src/ |
tools の中核（zip の読み取り、エンジンとオーサリング API の読み込み、検査の呼び出し）と MCP サーバー |
vendor/ |
zip に入っていない moment（プラグインは CDN から読むため、tools は自前で持つ） |
docs/ |
手順と資料（kact_docs が返すもの。manifest.json が章の一覧） |
dist/ |
npm run build が作る MCP サーバー 1 ファイル（dist/mcp.mjs） |
ツール（段階 2 まで）
| ツール | すること | 書き込み |
|---|---|---|
kact_docs |
手順と資料（最初に呼ぶ）。引数なしで目次、section で章、query で探す |
なし |
kact_status |
tools の版と、zip（プラグインの版・オーサリング API の版・計算式エンジン）の診断 | なし |
kact_workspace_status |
作業フォルダーの場所と、その直下の JSON の名前 | なし |
kact_files |
作業フォルダーの JSON の一覧（設定ファイルは digest・アクションの数・アプリ ID も） |
なし |
kact_check |
設定ファイルをプラグイン本体と同じ規則で検査（エラーと注意） | なし |
kact_actions |
設定ファイルの中身を 1 アクション 1 行で（SQL 本文は返さない。digest 付き） |
なし |
kact_diff |
2 つの設定の差（アクション単位。SQL と計算式は変わった行だけ） | なし |
kact_save_config |
新しい設定ファイルを検査してから保存（上書きしない） | 作業フォルダー |
kact_update_action |
アクションを 1 つ差し替える・足す（expectedDigest で照合） |
作業フォルダー |
kact_pull |
設定画面でダウンロードした設定を作業フォルダーに写す（元は残す） | 作業フォルダー |
kintone には何も書きません。 書くのは作業フォルダーの中だけで、取り込みと実行は利用者が設定画面で行います。
保存の約束
- ファイルは作業フォルダーからの相対パスだけ（
..・絶対パス・symlink の先はdenied）。 - 新規は上書きしない（同じ名前なら
conflict）。更新はexpectedDigestの照合（読んだ後に変わっていたらconflict）。 - 検査（本体と同じ規則）のエラーがあれば書かない（
invalidと findings を返す）。注意（warning）は書いてから伝える。 - 確定は「一時ファイル → ロック → 確かめ直し → 原子的に置く」（
src/commit-file.ts）。
起動の設定（AI の引数では変えられない）
--surface claude-code | desktop |
出すツールの出し分け |
KACT_PLUGIN_ZIP |
kSQL アクションプラグインの zip の場所 |
KACT_WORKSPACE |
作業フォルダー（省略時は起動したフォルダー） |
ライセンス
MIT（LICENSE）。zip から読み込む kSQL アクションプラグインと計算式エンジンのコードはこのリポジトリには含まれません。