kozou mcp

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

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

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

概要

kozou mcp [--stdio | --http] [--port <n>] [--host <host>] [--config <path>]

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

トランスポート

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

stdio (デフォルト)

kozou mcp --stdio

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

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

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

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

HTTP

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 エンドポイントも公開します (キャッシュを参照)。

フラグ

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

ツール

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

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

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

設計上、読み取り専用

SQL を生成、実行、書き込みするためのツールは意図的に存在しません。内部では、内省はすべてのクエリを読み取り専用で実行します。エージェントはコンテキストを受け取り、データレイヤー — v0.1 では PostgREST、または v0.2 系列の実験的な自社製 @kozou/api レイヤー — に対して独自のクエリを組み立てます。読み取り専用の MCP サーフェスとデータ API の分離は、Kozou の出力サーフェスモデルの一部です。

エラー

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

キャッシュ

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

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

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

例

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

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

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

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

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

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

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

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

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

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