RPC アクション: 関数のコンパイル

Kozou はスキーマの名詞 — テーブルとビュー — を忠実な REST / OpenAPI / MCP / Admin UI サーフェスにコンパイルします。v1.4 以降は動詞もコンパイルできます。COMMENT でタグ付けされた Postgres 関数が、同じ 4 つのサーフェスすべてで呼び出し可能な アクション になります。

これが重要なのは、Kozou が推奨するセキュリティモデル — JWT → SET LOCAL ROLE → 行レベルセキュリティ + 列 GRANT — が、意味のある書き込み (注文を承認、入金を記録、公開) を関数に集約し、テーブルレベルの書き込み権限を revoke するためです。これらの動詞は、本来であればすべての生成サーフェスの外側に落ちてしまいます。RPC アクションはそれらを同じ認可機構の上に取り戻します。新しい認証モデルは不要で、どの role が各関数を実行できるかはデータベースが施行します。

Kozou の出力の中で RPC がどこに位置するかは @kozou/api REST レイヤーと COMMENT 規約を参照してください。

関数を露出する

デフォルトでは何も露出されません。関数は、その COMMENT が @expose: rpc タグを持つときにのみアクションへコンパイルされます。

COMMENT ON FUNCTION approve_order(order_id uuid) IS
  '注文を承認し在庫を確保する。
   @ai: 冪等ではない — 再呼び出し前に注文ステータスを確認すること。
   @policy: 承認できるのはマネージャーのみ。
   @expose: rpc';

このタグ 1 つで、関数は 4 つのサーフェスすべて にコンパイルされます。

REST — POST /rpc/<schema>.<fn>。名前付き引数の JSON ボディを取ります (例: POST /rpc/public.approve_order { "order_id": "…" })。
OpenAPI — POST /rpc/<schema>.<fn> operation (operationId: rpc.<schema>.<fn>)。@ai / @policy の advisory は x-kozou-ai / x-kozou-policy として付与されます。
MCP — describe_functions ツールが各アクションのシグネチャと advisory を返すので、AI エージェントはどんなアクションが存在しどう呼ぶかを把握できます。
Admin UI — “Actions” ページが引数フォーム (テーブルフォームと同じ widget 推論 — enum-select、relation-select など) を描画し、結果を表示します。

引数は名前付き (スカラ / enum / FK 型) で、DEFAULT を持つ引数は省略できます。戻り値の wire マッピング:

Postgres の戻り	Wire
スカラ (`integer`、`text`、`uuid` など)	その値
単一 composite / 表の 1 行	オブジェクト
`SETOF` / `RETURNS TABLE(...)`	配列 — 行型ならオブジェクトの配列、スカラ集合なら値の配列
`void`	`204 No Content` (REST)、MCP `call` 経由では `{ ok: true, note: … }`

露出は権限ではない

@expose: rpc タグは「この動詞をサーフェスに出す」という意味であり、誰が実行できるか を決めるものではありません。それを施行するのは、リクエストの role (JWT クレーム由来、SET LOCAL ROLE 経由) における PostgreSQL の EXECUTE 権限です。EXECUTE を持たない呼び出し元は 42501 となり、Kozou はこれを汎用的なボディとともに 403 Forbidden にマッピングします。関数は role のトランザクション内で実行されるので、関数自身のチェックと RLS が効きます。

そのため、露出にはガードレールがあります。いずれかを満たさないタグ付き関数は 露出されず、ビルドがそれを大きく報告します (黙って消えることはありません)。

PUBLIC EXECUTE は hard skip

CREATE FUNCTION はデフォルトで EXECUTE を PUBLIC に付与します。この付与が残ったままのタグ付き関数は、誰でも — 匿名 role を含め — エンドポイントを呼べてしまうため、skip されます。まず締めてください。

REVOKE EXECUTE ON FUNCTION approve_order(uuid) FROM PUBLIC;
GRANT EXECUTE ON FUNCTION approve_order(uuid) TO app_manager;

意図的に public 呼び出し可能にしたい関数 (例: 匿名検索) は、明示的に宣言します — COMMENT に @expose: rpc public、または api.rpc.allowPublicExecute に列挙します。

SECURITY DEFINER は二重 opt-in が必要

SECURITY DEFINER 関数は 所有者 権限で実行され、呼び出し元の RLS をバイパスしうる — 最も強力で footgun になりやすいケースです。次の両方を満たすときにのみ露出されます。

api.rpc.allowDefiner に列挙されていること (migration 作成者のタグとは別の、operator による deploy 時の opt-in)。かつ
owner-safe な search_path を宣言していること — 各要素がその所有者しかオブジェクトを作成できないスキーマ (例: pg_catalog) で、末尾に pg_temp を置くこと。
```
CREATE FUNCTION settle_invoice(invoice_id uuid) RETURNS void
  LANGUAGE sql SECURITY DEFINER
  SET search_path = pg_catalog, pg_temp
  AS $$ … $$;
```
書き込み可能なスキーマを含む search_path (別の role が、所有者が未修飾で解決するオブジェクトを仕込めてしまう) は拒否されます。

その他の loud skip

オーバーロード名 (同一 schema.name が複数)、VARIADIC / polymorphic / 無名引数、マッピング不能な戻り型はビルド issue とともに skip されるので、タグ付けしたのに現れない関数は必ず理由がわかります。

MCP エージェントからアクションを実行する

describe_functions はエージェントにアクションを 学ばせ、call ツールはそれを実行させます — describe → act の「act」側です。これは opt-in でデフォルト OFF: オペレーターが実行を有効化するまで、MCP サーバーは describe 専用です。

kozou.config.yaml の server.mcp.execution で有効化します。

server:
  mcp:
    execution:
      enabled: true
      role: kozou_mcp_agent          # call の実行 role (server.mcp.http.auth なしの場合は必須)
      # claims: { tenant_id: acme }    # 任意。RLS 向けに publish される
      # allow: [public.approve_order]  # 任意の allowlist。省略 = 露出アクション全部

実行を有効化すると、bundled kozou mcp サーバーは { "function": "<schema>.<fn>", "args": { … } } を取る call ツールを列挙します。関数は REST サーフェスと同じ施行エンベロープ (SET LOCAL ROLE + publish した claims をトランザクション内で) で実行されるので、関数の EXECUTE 権限とそれ自身の RLS が適用されます。call が到達できるのは describe_functions が既に広告している関数 (および任意の allow リストとの積集合) だけで、それ以外は「unknown function」として扱われます (露出されていない関数は存在しない関数と区別できません)。

デフォルトは単一サービス role — OAuth で per-user に

REST サーフェスは リクエストごと の JWT を運ぶので、各呼び出しはそのユーザーの role で実行されます。server.mcp.http.auth なしでは MCP にエンドユーザーのトークンがありません: call はすべてのリクエストで 1 つの オペレーター設定 role として実行され、エージェントは role や claims を 選べません (選べれば self-elevate できてしまうため)。これは意図的に粗い設計です。

least-privilege role を使う

実行 role の EXECUTE 付与と関数の RLS が境界のすべてなので、call には 専用の least-privilege role を与えてください — DB owner や superuser は避け、エージェントが実行してよい関数にだけ GRANT EXECUTE します。

CREATE ROLE kozou_mcp_agent NOLOGIN;
GRANT kozou_mcp_agent TO app_login;   -- 接続のログイン role
GRANT EXECUTE ON FUNCTION approve_order(uuid) TO kozou_mcp_agent;

SECURITY DEFINER が最も鋭い縁です: definer 関数は 所有者 として実行され、実行 role の RLS をバイパスするので、call の有効化と definer アクションが揃うとエージェントは所有者権限の動詞を起動できます。definer 関数はそもそも露出に allowDefiner の二重 opt-in を要します — 実行を有効化する前にレビューしてください。

エラーとトランスポート

失敗した呼び出しは 汎用的な メッセージの MCP エラー結果を返します — permission denied、制約カテゴリ、RAISE の場合は “the function call failed”。生の DB エラー文はエージェントに返しません (サーバーログにのみ出します)。

MCP の HTTP トランスポートはデフォルトでは無認証です: call 有効時、ポートに到達できる誰もが実行 role としてアクションを実行できるため、サーバーは非 loopback bind 時により強い起動警告を出します。127.0.0.1 (デフォルト) のままにするか、前段に auth/proxy を置くか、OAuth resource-server モード (server.mcp.http.auth) を有効にしてください — 有効時は毎リクエストに検証済み bearer トークンが必要になり、call は固定 role ではなくトークンごとの role として実行されます (リモート MCP と OAuth)。call の wire 形は RPC サーフェスの他と同様、 Kozou v1.6 時点で安定した契約です。env-only の standalone @kozou/mcp CLI は describe 専用のままで、実行は bundled kozou mcp の機能です。

設定

2 つの RPC allowlist は kozou.config.yaml の api.rpc 配下にあり、デフォルトは空です (これらが無くても、PUBLIC EXECUTE を revoke した invoker 関数は露出されます)。

api:
  rpc:
    allowDefiner:
      - public.approve_order      # schema 修飾
    allowPublicExecute:
      - public.search

関数を提供するのは内製の @kozou/api バックエンド (デフォルト) だけです。外部 PostgREST opt-out では Admin UI は Actions サーフェスを隠し、PostgREST 自身の /rpc/ を使います。