ktx レビュー：データ用エージェントに倉庫の文脈を注入する CLI と MCP サーバー

ktx が埋めようとしている穴は「毎回の再探索」

汎用エージェントにデータ分析を頼むと、質問のたびに倉庫の構造を調べ直し、メトリクスの計算式をその場で作り、結果として承認済みの定義と食い違う数値が返ってくる。README はこの症状を明示的に挙げている。既存のセマンティックレイヤーは承認済み定義を持つ代わりに手作業の維持を要求し、社内の wiki やドキュメントに溜まった知識を取り込まない。ktx はこの二つを同時に扱うと主張しており、対象は Claude Code、Codex、Cursor、OpenCode のようなエージェントを業務データに向けたいチームである。README が挙げる利用条件は、承認済みメトリクス定義でエージェントに倉庫を問い合わせたい、dbt や Looker、Metabase、Notion、社内 wiki に知識が散っている、正規の SQL を毎回作り直すのではなく再利用したい、の三つ。逆に倉庫がない場合と、単発のクエリが一回欲しいだけの場合は対象外と明記されている。

取り込みは source connector から wiki Markdown と YAML へ

README に掲載された ingestion-flow の図が示す流れは、データベース、BI ツール、モデリングコード、ドキュメントを source connector 経由で取り込み、context builder で組み立て、reconciliation で突き合わせ、validation を通したうえで、wiki Markdown とセマンティックレイヤー YAML を生成するというもの。テーブルのサンプリング、メタデータと利用パターンの取得、join 可能な列の検出、ソースへの注釈付けもここで行われる。セマンティックレイヤー側は生のテーブルと高レベルのメトリクスを join グラフで結び、chasm trap と fan trap を自動で解決すると README は説明している。これによりエージェントは正規の SQL を書き直す代わりにメトリクスを宣言的に取得できる、というのが設計意図である。ただし図と README の記述から確認できるのは流れの段階名までで、各段階の判定アルゴリズムや精度は公開情報からは読み取れない。

提供側は CLI と MCP の二経路、検索は全文と意味検索の併用

生成物をエージェントに渡す経路は二つある。一つは CLI で、ktx sl "revenue" がセマンティックソースを、ktx wiki "refund policy" がローカル wiki ページを検索する。もう一つは MCP サーバーで、ktx mcp start で起動し、エージェントクライアントから接続する。README の mcp-runtime-flow の図によれば、エージェントは MCP 経由で ktx に問い合わせ、ktx が wiki とセマンティックレイヤーを横断して検索し、承認済みメトリクスを返し、それを読み取り専用の SQL にコンパイルして倉庫に対して実行する。検索は全文検索と意味検索を組み合わせると説明されている。読み取り専用という制約は比較表でも明示されており、エージェントが倉庫側のデータを書き換える経路は想定されていない。ここで注意したいのは、SQL の実行主体が ktx である点だ。エージェントが生成した SQL をそのまま流すのではなく、承認済み定義を経由させる構造になっている。

導入は ktx setup と ktx status の二コマンドから

グローバルインストールは npm install -g @kaelio/ktx。続けて ktx setup を実行すると、ローカルの ktx プロジェクトの作成または再開、provider と接続の設定、コンテキストの構築、エージェント連携のインストールまでが行われる。状態確認は ktx status で、README の例ではプロジェクトのパス、Project ready、LLM ready（claude-sonnet-4-6）、Embeddings ready（text-embedding-3-small）、Databases configured、Context sources configured、ktx context built、Agent integration ready が並ぶ。コンテキストの再構築は ktx ingest が担い、設定済みの全接続を対象にする。README には重要な注意として、ktx status が ktx mcp start --project-dir ... を表示した場合は、エージェントクライアントを開く前にそれを実行するよう書かれている。アップグレードは npm install -g @kaelio/ktx@latest で行う。すでにエージェントを使っている場合の導線として、プロジェクトディレクトリから Run npx skills add Kaelio/ktx --skill ktx と依頼する方法も提示されている。

LLM の鍵は自前、課金は ktx 側から発生しない

README の注記は、ktx を自前の LLM API キー、またはローカルのエージェントサインインで動かすと説明している。具体的には Claude Code 経由の Claude Pro/Max サブスクリプション、あるいはローカルの Codex 認証である。ktx 自体からの追加の使用量課金はない、というのがこの注記の主張だ。費用の所在がエージェント側のサブスクリプションや API キーに移るということで、既に Claude Code や Codex を契約しているチームにとっては導入の追加コストが小さい。一方で、これらの契約がないチームは別途 API キーを用意する必要がある。ktx status の例に claude-sonnet-4-6 と text-embedding-3-small が表示されていることから、LLM と埋め込みモデルは別々に設定される構成だと分かる。埋め込み側のモデルをどう選ぶか、その切り替えが検索品質にどう効くかは README からは読み取れない。

接続先は広いが、倉庫が前提という制約は動かない

対応する倉庫は PostgreSQL、Snowflake、BigQuery、ClickHouse、MySQL、SQL Server、SQLite、DuckDB、Amazon Athena、MongoDB。連携先は dbt、MetricFlow、LookML、Looker、Metabase、Sigma、Notion、Google Drive と幅広い。ただし README は「ktx は倉庫の上に載る」と明言しており、SQL 倉庫そのものがない環境では動かない。DuckDB や SQLite が含まれるため小規模な検証はしやすいが、本番の分析基盤として何を想定しているかは公開情報からは判断できない。もう一つの制約は、取り込みと突き合わせが自動である代わりに、矛盾の検出は人間のレビュー待ちになる点だ。README は「矛盾を検出し、人間のレビュー用にフラグを立てる」と書いており、自動で正解に収束するとは主張していない。wiki や Notion の記述が古い場合、その古い内容がコンテキストに入り込み、レビューが回らないままエージェントの回答に反映される経路が残る。

汎用エージェントでも従来型セマンティックレイヤーでもない位置づけ

README の比較表は、汎用エージェント、従来型セマンティックレイヤー、ktx の三つを並べている。汎用エージェントは倉庫の文脈を自動で構築せず、承認済みメトリクス定義も持たない。従来型セマンティックレイヤーは承認済み定義を持つが、join 可能な列の検出や fan/chasm trap の解決は手作業で、wiki や Notion の知識は取り込まない。ktx はこの両方の列を埋め、CLI と MCP の両方を提供し、読み取り専用で動くと主張している。実際の差は、既存のセマンティックレイヤー製品がモデリングを人間の作業として要求するのに対し、ktx はソースからの取り込みと突き合わせを自動処理の対象に置いている点にある。ただし比較表は README の自己申告であり、手作業の維持がどの程度減るかを第三者が検証した数値は提示されていない。従来型のセマンティックレイヤーを既に運用しているチームにとっては、置き換えではなく併存させたときに定義の二重管理が起きないかが実務上の論点になる。

ライセンスと維持コスト、そして最初に確かめること

ライセンスは Apache-2.0 で、リポジトリの LICENSE に置かれている。Apache-2.0 は特許許諾条項を含む寛容型ライセンスとして知られるが、生成物である wiki Markdown やセマンティックレイヤー YAML の扱い、あるいは同梱されるモデルやデータの権利については、この記事の材料からは判断できない。法務判断は読者の組織で行う必要がある。維持コストの面では、ktx 自体の更新は npm install -g @kaelio/ktx@latest で完結する一方、コンテキストの鮮度は ktx ingest の再実行にかかっている。スキーマ変更やメトリクス定義の変更のたびに再取り込みが必要かどうか、差分だけを更新する仕組みがあるかどうかは README からは読み取れない。リリースは v0.14.0、v0.15.0、v0.16.0 と短期間に続いており、0.x 系である点は導入判断で考慮すべき事実だ。最初に確かめるべきは、ktx status の各項目が自環境で yes になるか、そして生成された YAML と Markdown をレビューする担当を決められるかである。

編集部の結論

SQL 倉庫を持ち、dbt や Looker、Metabase、Notion などに散った定義をエージェントに一貫して使わせたいチームは、ktx setup と ktx status でプロジェクトの準備状態を確認するところから始める価値がある。逆に倉庫そのものがない場合や、単発のアドホッククエリを一回投げたいだけの場合は、README 自身が psql やノートブックを勧めており、導入する理由が薄い。導入前に確認すべきは、ktx status が表示する LLM、Embeddings、Databases、Context sources、Agent integration の各項目が自分の環境で yes になるか、そして生成された wiki Markdown とセマンティックレイヤー YAML を誰がレビューするかである。矛盾の検出は人間の確認待ちとして設計されているため、レビュー担当を決められないチームでは、誤った定義がそのままエージェントの回答に流れ込む経路が残る。

公式情報源

1. Kaelio/ktx on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases