コンテンツにスキップ
Kozou

kozou mcp

kozou mcp は @kozou/mcp を基盤とする Model Context Protocol サーバーを起動します。設定された PostgreSQL データベースを内省し、DDL と COMMENT メタデータから Schema Context を構築して、AI エージェント (Claude Code、Claude Desktop、その他の MCP クライアント) に少数の 読み取り専用 ツールとして提供します。

このサーバーはコンテキストプロバイダーであり、クエリエンジンではありません。スキーマの 構造と意味 — テーブルとビューの定義、リレーション、注釈付けされたビジネス概念 — を エージェントに渡すことで、エージェント自身がデータについて推論し、独自の SQL を書けるように します。サーバー自体は SQL を生成することも、実行することも、データベースに書き込むことも 決してありません。

このページはコマンドリファレンスです。エンドツーエンドのエージェント連携 (設定ファイルの エントリ、クライアントのセットアップ、動作するセッション) については、 MCP クライアントを接続する を参照してください。

概要

Section titled “概要”
Terminal window
kozou mcp [--stdio | --http] [--port <n>] [--host <host>] [--config <path>]

サーバーは接続情報 (データベース URL、スキーマ、キャッシュ TTL) を kozou.config.yaml から読み取ります。完全なスキーマについては kozou.config.yaml を参照してください。 データベースは読み取り専用で開かれ、マイグレーションは実行されず、行は一切書き込まれません。

トランスポート

Section titled “トランスポート”

kozou mcp は 2 つのトランスポートをサポートします。デフォルトは stdio です — --stdio も --http も渡さなかった場合、サーバーは stdio で起動します。

stdio (デフォルト)

Section titled “stdio (デフォルト)”
Terminal window
kozou mcp --stdio

stdio トランスポートは標準入出力経由で MCP を話します。これは MCP クライアントが サーバーを子プロセスとして起動するときに使いたいトランスポートで、Claude Code と Claude Desktop はこの方式で接続します。クライアントがプロセスのライフサイクルを 所有するため、設定すべきポートやホストはありません。

同梱の kozou.config.yaml テンプレートはデータベース URL を ${DATABASE_URL} プレースホルダーとして参照しているため、通常はコマンドを起動する環境でその変数を 指定します:

Terminal window
DATABASE_URL=postgres://kozou:kozou@localhost:5432/kozou \
  npx kozou mcp --stdio

CLI が ${DATABASE_URL} を展開するのは、設定テンプレートがそれを参照しているからに すぎません。kozou は KOZOU_DATABASE_URL 変数を直接読み取ることはありません。

HTTP

Section titled “HTTP”
Terminal window
kozou mcp --http --port 3334 --host 127.0.0.1

HTTP トランスポートは MCP の Streamable HTTP トランスポートを使用し、コンテナ化された 環境やリモートデプロイメント向けです。そこではサーバーが長時間稼働するプロセスとして動作し、 クライアントはネットワーク越しにそれに到達します。デフォルトではポート 3334 の 127.0.0.1 にバインドします。

HTTP モードでは、サーバーはメモリ内の Schema Context キャッシュを無効化する POST /admin/refresh エンドポイントも公開します (キャッシュ を参照)。

フラグ

Section titled “フラグ”
フラグ説明デフォルト
--stdiostdio トランスポートで MCP を提供します。トランスポートフラグが指定されないとき有効
--httpStreamable HTTP トランスポートで MCP を提供します。—
--port <n>HTTP のリッスンポート (HTTP モードのみ)。3334
--host <host>HTTP のバインドホスト (HTTP モードのみ)。127.0.0.1
--config <path>kozou.config.yaml へのパス。作業ディレクトリから解決

ツール

Section titled “ツール”

サーバーは 7 つの読み取り専用ツールを公開します。これらはスキーマと、あなたが定義した 概念 (データベースビュー) に直接対応します:

ツール入力返すもの
list_tables任意の schema、includeSystemスキーマ内のテーブルと、そのラベル、説明、推定行数。
describe_tablequalifiedName (例: public.products)1 つのテーブルの完全なスキーマ: 列、型、null 許容性、デフォルト、列挙値、主キー、外部キーリレーション、チェック制約 — COMMENT の @ai ノートを含む。
list_views任意の schemaスキーマ内のビューと、そのラベルおよび目的。
describe_viewqualifiedNameビューの列、説明、基となるテーブル、SQL 定義。
list_concepts—スキーマ内のビジネス概念。v0.1 では各概念はデータベースビューです。
get_concept_contextname概念の @ai ノート、推奨されるクエリソース、結合の提案、関連テーブル、@example で宣言された例示クエリ。
describe_functions—RPC アクション として公開された関数 (@expose: rpc) のシグネチャ。引数、戻り値の型、@ai・@policy の助言ノートを含む。

これらのツールは、あなたが COMMENT テキストにエンコードした意味を表面化します。 Comment conventions で説明されている @ai、@widget、@policy、@example タグが、ツールが返す aiDescription、aiNotes、exampleQueries フィールドに反映されます。

アクションの実行 (opt-in)

Section titled “アクションの実行 (opt-in)”

上記の 7 つのツールは読み取り専用です。もう 1 つ — call — は RPC アクション として公開された関数を 実行 します (describe → act の「act」側)。これは デフォルト OFF: オペレーターが kozou.config.yaml で server.mcp.execution を (role 付きで) 有効化したときだけ 列挙・実行可能になります。関数は REST サーフェスと同じ SET LOCAL ROLE + RLS エンベロープでその単一 role として実行され、生の DB エラー文を返さず、エージェントは role を選べません。per-user 認可には不適です (それには REST API を使ってください)。 有効化手順・least-privilege role・SECURITY DEFINER の注意は MCP エージェントからアクションを実行する を参照してください。

デフォルトで読み取り専用

Section titled “デフォルトで読み取り専用”

デフォルトでは SQL を生成、実行、書き込みするためのツールは意図的に存在しません (実行は上記の明示的な opt-in です)。内部では、 内省はすべてのクエリを読み取り専用で実行します。エージェントはコンテキストを受け取り、 データレイヤー — デフォルトでは自前の @kozou/api REST バックエンド、オプトアウトすれば外部の PostgREST — に対して独自のクエリを 組み立てます。読み取り専用の MCP サーフェスとデータ API の分離は、Kozou の 出力サーフェス モデルの一部です。

エラー

Section titled “エラー”

ツールが失敗すると、例外を投げる代わりに MCP のエラー結果 — isError: true と テキストによる説明 — を返します。スタックトレースが含まれるのは、サーバーが KOZOU_DEV=1 で実行されているときのみです。

キャッシュ

Section titled “キャッシュ”

Schema Context はプロセスメモリにキャッシュされ、ディスクに永続化されることは 決してありません。次のいずれかによって無効化されます:

  • HTTP モード — POST /admin/refresh リクエスト。
  • stdio モード — プロセスへの SIGHUP シグナル。
  • TTL — キャッシュ TTL が経過した後 (デフォルト 60 秒。KOZOU_CACHE_TTL_MS または kozou.config.yaml の cache.ttlMs で上書き可能)。

DDL や COMMENT テキストを変更した後はキャッシュをリフレッシュして、再起動なしで エージェントが更新されたスキーマを見られるようにしてください。

例

Section titled “例”

接続文字列を環境で指定して、デフォルトの stdio サーバーを実行します:

Terminal window
DATABASE_URL=postgres://kozou:kozou@localhost:5432/kozou \
  kozou mcp --stdio

デフォルトのループバックアドレスとポートで HTTP サーバーを実行します:

Terminal window
DATABASE_URL=postgres://kozou:kozou@localhost:5432/kozou \
  kozou mcp --http --port 3334 --host 127.0.0.1

COMMENT を編集した後、稼働中の HTTP サーバーのキャッシュを無効化します:

Terminal window
curl -X POST http://127.0.0.1:3334/admin/refresh

作業ディレクトリ外の設定ファイルをサーバーに指定します:

Terminal window
kozou mcp --stdio --config ./config/kozou.config.yaml

クライアントは JSON 引数オブジェクトを添えてツールを名前で呼び出します。例えば、 products テーブルに対する describe_table:

{
  "name": "describe_table",
  "arguments": { "qualifiedName": "public.products" }
}

関連項目

Section titled “関連項目”
  • MCP クライアントを接続する — kozou mcp を Claude Code または Claude Desktop に登録し、実際のセッションをエンドツーエンドで実行します。
  • kozou dev — 開発中に単一のコマンドから、同梱の Admin UI を MCP HTTP サーバーと並べて実行します。
  • kozou inspect — MCP ツールが提供するのと同じ Schema Context を、検査や差分比較のために JSON または YAML としてダンプします。