Schemabrain

AI エージェントにデータベースの生の接続文字列を渡すのはやめましょう。

代わりに SchemaBrain を使いましょう。エージェントが SQL を一切書かず、クエリ実行前に PII を拒否し、すべての呼び出しを改ざん検知可能な監査ログに記録する、読み取り専用の信頼とインテリジェンスのレイヤーです。

Claude Desktop · Claude Code · Cursor · Windsurf · あらゆる MCP ホストに対応

SchemaBrain は、制御可能な定義からすべてのクエリをコンパイルします。プロンプトからデータベースの生の SQL に至る経路はありません。

AI エージェントとデータベースの間にある信頼のギャップを埋める、3 つの保証：

• 設計上の読み取り専用 — MCP ツールは 12 個あり、書き込み可能なものはありません。execute() ツールも query() ツールもなく、エージェントのプロンプトからデータベースへの書き込みに至る経路もありません。
• 取得時の PII 対応による拒否 — PII タグは、物理スキーマから結合やメトリクスを通じて引き継がれます。クエリがブロック対象のカテゴリに触れる場合、データベースに問い合わせる前に SchemaBrain が拒否します。
• 暗号学的監査チェーン — すべての呼び出し、拒否、復旧を、SHA256 ハッシュ付きの追記専用ログに記録します（ベストエフォート：ディスク容量不足または書き込み先が設定されていない場合は、クエリを失敗させずに警告を記録して続行します）。audit verify は、過去の行が書き換えられている場合、ゼロ以外の終了コードを返します。

動作を確認 — スキーマでは答えられないことを尋ねると、結合を捏造せずに拒否します：

あなた： プラン階層別に使用量を計算

SchemaBrain → エージェント： { "kind": "unreachable_entity", "recovery": { "suggested_tool": "resolve_join" } } — 使用イベントに plan_id がないため、SchemaBrain はこれを捏造しません。

Claude： その結合を捏造することはできません。代わりに、実際に解決できるプラン階層別の契約収益はこちらです。✓

→ SQL と結果を含むセッション全体

実際の動作を見る — 稼働中の Postgres スキーマがガバナンスの効いたナレッジグラフになり、ファイアウォールが安全なメトリクスを計算して情報漏えいを拒否します。すべての呼び出しは改ざん検知可能な監査ログに記録されます。エージェントも API キーも不要です：

---

uvx schemabrain init
# then: Cmd+Q Claude Desktop, relaunch, and ask: "list the entities SchemaBrain knows about"
# prefer a persistent install? pipx install schemabrain (or) pip install schemabrain

コスト： 同梱のデモの実行は $0（キュレーション済みパックを使用、API キー不要） · 新しい 84 列のスキーマを LLM でインデックス化する場合は約 $0.03 · 変更のないスキーマの再インデックス化は $0。詳細はサンプルセッションをご覧ください。

ステータス：0.6.0（ベータ版）。 現在は Postgres に対応しています（ローカルストア自体は SQLite です）。SQLite ／ Snowflake ／ BigQuery ／ MySQL のソースコネクターはロードマップに含まれています。

---

目次

目的に応じて、次の項目をご覧ください：

目的	移動先
同梱のフィクスチャで試す	クイックスタート
安全性の保証について理解する	安全性の保証
MCP クライアントを接続する	Claude Desktop · Claude Code · Cursor · Windsurf · Cline · ChatGPT（ロードマップ）
独自のエージェントループに接続する	docs/setup/manual.md
セマンティックレイヤーを構築する	docs/semantic-layer.md
本番環境で実行する（監査、ドリフト、Docker）	docs/operations.md
エージェントを監視する（tail、監査ログ、OTel）	docs/observability.md
Querybear ／ Anthropic の参照用 Postgres MCP と比較する	Querybear との比較 · Anthropic の参照実装との比較
Vanna ／ Atlan ／ dbt-mcp ／ WrenAI と比較する	docs/landscape.md

---

クイックスタート

まずは動作を見てみたいですか？ uvx schemabrain demo を実行してください。コマンドは 1 つで、プロンプトは表示されません。サンプル SaaS レイヤーを構築したあと、ダッシュボードを開くか、ターミナルでファイアウォールのデモを実行できます。ダッシュボード／デモの実行経路では API キーも Docker も不要です。以下の手順では、SchemaBrain を独自のデータベースに接続し、独自のエージェントに組み込む方法を説明します。

uvx schemabrain init から、Claude Desktop との連携が動作するまでの手順は 3 ステップです。独自の Postgres URL を貼り付ければ、Docker は不要で約 30 秒です。Enter キーを押して同梱のデモを使う場合、初回の init では Docker が起動し、約 67 MB の埋め込みモデルがダウンロードされます。キャッシュ済みなら約 45 秒です。

1. インストール

uvx schemabrain init        # zero-install: runs the wizard in one shot
# or install persistently first:
pipx install schemabrain    # (or) pip install schemabrain
schemabrain --version

ソースからのインストール（git clone ＋ uv の sync --extra dev）については、docs/setup.mdに記載されています。

2. セットアップウィザードを実行する

schemabrain init

init は 7 段階のウィザードです。1 つのコマンドで、「Postgres データベースがある」状態から「Claude Desktop がそのデータベースについての質問に答えられる」状態にできます。初回実行時に、必要な情報の入力を求められます。

• Postgres URL — 独自の接続文字列を貼り付けるか、Enter キーを押して、同梱の SaaS フィクスチャを使うローカルのデモ用 Postgres コンテナーを起動します（Docker は自動的に起動し、再実行しても同じ状態を保ちます）。
• ANTHROPIC_API_KEY — 任意です。スキップしても、ウィザードは Claude Desktop を引き続き接続します。デモ経路では、エンティティ、メトリクス、結合が同梱の YAML パックであらかじめキュレーションされているため、セマンティックレイヤーは設定不要で動作します。独自のデータベースでは、API キーを用意したあとに schemabrain entities suggest --apply を実行して、エンティティをキュレーションできます。

SchemaBrain init — activation wizard

  [1/7] Source check       ✓ source reachable + read-only
  [2/7] Index schema       ✓ 12 tables, 84 columns indexed
  [3/7] Curate entities    ✓ 12 entities applied (bundled demo pack)
  [4/7] Curate metrics     ✓ 5 metrics applied (bundled demo pack)
  [5/7] Curate joins       ✓ 11 canonical joins applied (bundled demo pack)
  [6/7] Wire host          ✓ wrote schemabrain entry to claude_desktop_config.json
                           (default; switch with --host claude-code|cursor|windsurf|manual)
  [7/7] Next               ✓ restart your MCP host, then ask: "list the entities SchemaBrain knows about"

ウィザードの完全なリファレンス（各段階の説明、フラグ、dbt の自動検出、Claude Desktop 以外のホスト向けの --print-only、--no-entities ／ --no-metrics ／ --no-joins によるオプトアウト、コスト上限による一時停止）については、docs/setup.mdをご覧ください。

3. Claude Desktop を再起動して質問する

1. Claude Desktop を完全に終了します。ウィンドウを閉じるだけではなく、Cmd+Q を使用してください。MCP 設定は、完全に終了した状態から起動したときにのみ読み込まれます。

2. 再起動します。

3. 新しい会話で、次のように尋ねます。

   SchemaBrain が把握しているエンティティを一覧表示してください

Claude が list_entities を呼び出し、user、order などを報告すれば完了です。そうでない場合は、トラブルシューティングをご覧ください。

ウィザードの実行後、schemabrain inspect でエージェントが利用できる情報を確認でき、schemabrain tail でツール呼び出しをリアルタイムにストリーミングできます。詳しくは docs/operations.md をご覧ください。

プロジェクトファイル

init が書き込むのは ./schemabrain.db（ローカルストアのため、gitignore に追加してください）とホスト設定のみです。編集可能な YAML として PII ポリシー と セマンティックレイヤー を調整するには、--emit-yaml-dir を指定して再実行します。

schemabrain init --url-env DATABASE_URL --emit-yaml-dir ./schemabrain
# → ./schemabrain/pii_policy.yaml + entities/ + metrics/ + joins/

ファイルを編集し、schemabrain apply ./schemabrain を実行します。schemabrain check で検証してから、serve を再起動してください。schemabrain.yaml はありません。設定は CLI フラグ、SCHEMABRAIN_* 環境変数（.env から自動的に読み込まれます）、およびこの YAML ツリーで行います。全体像については、プロジェクトについてをご覧ください。

---

安全性の保証

SchemaBrain が現在、SQL 境界で適用する 6 つの特性です。

1. 設定ではなく、アーキテクチャによる読み取り専用

MCP のインターフェースが公開する 12 個のツールは、どれも書き込みできません。execute() も query() もなく、セッションの状態にかかわらず、エージェントのプロンプトからデータベースへの書き込みに至る経路はありません。この保証は構造によるもので、エージェントが切り替えられるフラグではありません。schemabrain serve は多重の安全策として default_transaction_read_only=on も固定します。アーキテクチャによる読み取り専用 →

2. get_metric ツール境界での PII 対応拒否

ブロック対象の PII カテゴリーに触れる get_metric は、すべて refused エンベロープを返します。コンパイル済み SQL は実行されず、拒否の記録が mcp_audit に残ります。describe_entity も列レベルで同じ制御を適用し、ブロックされた列には redacted=True が設定されます。init は既定で、重大な情報漏えいにつながるカテゴリー（credential,payment_card,government_id）をブロックします。--pii-block はその集合を置き換えるため、対象を広げるには、置き換え後の集合全体を指定してください。検出は GDPR／CCPA／HIPAA／PCI の 12 カテゴリーを対象とした、列名のパターンマッチングによって行われます。コンテンツを考慮した分類は今後のロードマップに含まれています。PII の分類体系と伝播 →

3. 改ざん検知可能な監査ログ

すべてのツール呼び出しについて、追記専用の mcp_audit テーブルに 1 行が書き込まれます。記録されるのは、PII カテゴリー、コンテンツアドレス可能なフィンガープリント、sha256 ハッシュチェーンです。audit verify はチェーンを再検証し、過去の行が書き換えられている場合は 0 以外の終了コードを返します。

schemabrain audit verify   # exit 0 = chain clean

改ざん検知可能な監査チェーン →

4. 失敗は文字列ではなく、契約です

成功以外の呼び出し（拒否、エラー、縮退）では、解析が必要なメッセージではなく、構造化された recovery.suggested_args ブロックが返されます。PII によるブロック（status: "refused"）では、再試行するエンティティが提示されます。曖昧なディメンションや到達不能なエンティティ（status: "error"）では、選択すべき候補または次に呼び出すべきツールが提示されます。refused になるのはポリシーによる拒否のみです。「推測しません」は、リカバリー用ペイロードを伴う error です。

{ "status": "error", "kind": "ambiguous_time_dimension",
  "recovery": { "suggested_tool": "get_metric",
                "suggested_args": {"time_dimension": "order.placed_at"} } }

構造化されたリカバリー →

5. コンパイルパス：定義 → パラメーター化された SQL

エンティティ、メトリクス、正規の結合は、SchemaBrain 側で実行するパラメーター化された SQL にコンパイルされます。エージェントに表示されるのは、行と実行された SQL だけです。データベース上で任意のステートメントが実行されることはありません。init 中に LLM が提案した定義は、明示的にレビューして適用します。セマンティックレイヤーを構築する →

6. あらゆるエージェントループにプラグイン可能

Claude Desktop が参照するものと同じ MCP stdio インターフェースを、あらゆる MCP ホストに公開できます。独自の Anthropic、OpenAI、LangGraph ループも対象です。examples/anthropic_demo.py は約 260 行のドロップイン実装で、Claude Haiku 4.5 を schemabrain serve に接続し、エージェントが選択したツールを正確に出力します。Anthropic SDK のウォークスルー →

---

可観測性ダッシュボード

SchemaBrain には、MCP サーバーがすでに書き込んでいる監査、PII、拒否のデータを表示する、オプトイン方式の読み取り専用ダッシュボードが付属しています。schemabrain dashboard を実行すると、ビルド済みの静的 UI を提供するローカル FastAPI サイドカーが起動します。Node ランタイムも、ネットワークへの公開も、書き込み経路もありません。

pip install "schemabrain[ui]"
schemabrain dashboard
# → http://127.0.0.1:7878

これはコンソールではなくビューアーです。設定も、SQL パッドも、書き込み経路もありません。9 つの読み取り専用ビューがあり、それぞれ MCP エンベロープだけでは視覚的に把握できない、オペレーターの疑問に答えます。中核となるのは ナレッジグラフです。セマンティックレイヤーが結合のコンパイルに使うものと同じエンティティ・リレーションシップの射影として、スキーマを表示します。

• ナレッジグラフ（/graph）— スキーマは実際にどのようにつながっていますか？ エンティティをノード、正規結合をエッジ（宣言済みFKは実線、ログから抽出したものは破線）として表し、PIIを含むエンティティにはフラグを付け、拒否が発生しやすい箇所を強調表示します。強調表示された結合パスには宣言済みFKのカーディナリティも表示されます。テーブルの一覧ではなく、グラフとしてスキーマを表示します。
• 概要（/overview）— ホーム画面です。エンティティ、メトリクス、結合、致命的なPIIの件数をひと目で確認できます。
• エンティティ（/entities）— 並べ替え可能なインデックスです。任意のエンティティを開いて、カラム、PII、メトリクス、正規結合を確認できます。
• データ辞書（/dict）— すべてのテーブル、カラム、型、PIIクラス、結合、メトリクスを確認できます。ワンクリックでMarkdownにエクスポートできます（schemabrain docs が書き出すものと同じ成果物です）。
• PIIマトリクス（/pii）— 機密データを含むカラムはどれですか？ 分類済みのカラムを1行ずつ、PIIカテゴリごとに1つのセルで表示するヒートマップです。各カラムには、アドバイザリーバンドに応じてblock／redact／allowのタグが付きます。致命的な漏えいカテゴリ（credential、payment_card、government_id）に属するカラムは、ポリシーにかかわらずハードブロックされ、常に上部に表示されます。そのため、新しいスキーマをエージェントに渡す前に、users 内に隠れている payment_card カラムを見つけたり、デフォルトの --pii-block ポリシーに抵触する項目をひと目で確認したりできます。任意の行を選択すると、そのエンティティのカラム、メトリクス、結合を確認できます。
• 拒否（/refusals）— SchemaBrainは何をブロックし、エージェントには何が表示されましたか？ 保留された呼び出しを時系列で表示します。行を展開すると、発生した理由（pii_blocked、allowlist_violation、fragment_unsafe、cost_cap_exceeded、ambiguous_resolution、schema_drift）、ポリシーと交差した正確なカテゴリセット、エージェントが処理を再開するために受け取った構造化された error.recovery（推奨ツールと引数）を含むエンベロープ全体がインラインで表示されます。「エージェントがアクセスできないと言っている」といった問題のトリアージや、これらのヒントが実際に役立ったかどうかの確認に使用できます。
• 監査ビューアー（/audit）— 監査チェーンはまだ完全性を保っていますか？ 改ざんを検出できるログを視覚的に確認できます。結果にかかわらず、ツール呼び出しごとに必ず1行が記録され、chain_hash = sha256(prev_hash || canonical(row)) によって連鎖します。検証を実行するまでは整合性ストリップに not verified this session と表示され、実行後は verified · n/N intact と表示されます（または N rows edited after write と警告されます）。Verifyボタンをクリックすると、サーバー側でチェーンを再検証し、ブラウザーで表示中の各行についてRFC-6962のMerkle包含証明も再計算します。行を選択すると、ツール、ステータス、コストクラス、PIIカテゴリ、フィンガープリント、chain_hash、ルートまでの証明の階層を含む本文全体が表示されます。新しい呼び出しを反映するには再読み込みしてください。
• ポリシー（/policy）— ファイアウォールが適用するblock／redact／allowのグリッドです。常時有効な致命的漏えい対策の下限も開示されます（削除できません）。変更はCLIをコピーして実行する方式で行い、ダッシュボードから書き込みは行いません。
• ドリフト（/drift）— ストアが検出できる設定およびエンリッチメントのドリフトを表示します。それぞれにCLIの修正コマンドをコピーできます。

ナレッジグラフ — セマンティックレイヤーが結合をコンパイルする際に使うエンティティ関係の投影として、スキーマを表示します。致命的なPIIを含むエンティティにフラグを付け、正規結合パスを示します。

その他のダッシュボードビュー — 概要、PIIマトリクス、拒否、監査、エンティティ、データ辞書、ポリシーとドリフト

概要 — 境界全体を1画面で確認できます。何がバインドされ、何が保護され、何がドリフトしているかがわかります。

PII マトリクス — 機密データを含む列と、デフォルトのポリシーでブロックされるもの。

拒否 — ブロックされたすべての呼び出し、適用された理由、エージェントに返された復旧のヒント。

監査ビューア — 改ざんを検知できるチェーンを、各行のハッシュ連鎖までサーバー側で検証。

エンティティ — 生のスキーマからバインドされたすべてのビジネスエンティティと、PII の露出および結合数。

データディクショナリ — すべてのテーブル、列、型、結合を表示し、リポジトリや Wiki 用に Markdown でエクスポートできます。

ポリシー — ファイアウォールが適用するブロック／編集／許可グリッドと、常時適用される最低限のルール。

ドリフト — ストアが検出できる設定とエンリッチメントのドリフト。それぞれに CLI で修正するためのコピー可能なコマンドがあります。

ダッシュボードは 127.0.0.1 のみにバインドされます。設計上、--host フラグはありません。読み取り専用で、serve が書き込むものと同じ SQLite ストアを読み取ります。ダッシュボードと通信するエージェントはありません。

ダッシュボードガイド → · PII マトリクス → · 拒否 → · 監査ビューア →

---

対応クライアント

SchemaBrain は stdio 経由で Model Context Protocol を使用します。schemabrain init --host <X> は、4 つの MCP クライアント向けに公式設定を書き込みます。それ以外の MCP stdio 対応クライアントでは、--host manual を使用できます（設定スニペットが表示されるので、貼り付けてください）。

公式の接続設定

schemabrain init --host <X> は、MCP エントリをホストの設定ファイルに直接書き込みます。

クライアント	セットアップガイド	設定パス
Claude Desktop	/setup/claude-desktop	macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json
Claude Code	/setup/claude-code	claude mcp add を呼び出します
Cursor	/setup/cursor	~/.cursor/mcp.json
Windsurf	/setup/windsurf	~/.codeium/windsurf/mcp_config.json

その他の MCP stdio ホスト

schemabrain init --host manual を実行すると、JSON エントリが標準出力に表示されます。使用しているホストの設定に貼り付けてください。サブプロセスを起動して MCP stdio で通信するクライアントであれば、原理上は動作するはずですが、すべてを網羅的にテストしたわけではありません。一般的な接続先は次のとおりです。

• Zed — 詳しい手順は docs/setup/zed.md をご覧ください
• Codex CLI（ChatGPT ユーザー向けの動作確認済みの方法）— 詳しい手順は docs/setup/codex.md をご覧ください
• Cline（VS Code 拡張機能）— schemabrain init --host manual を実行すると、mcpServers ブロックが表示されます。MCP Servers → Configure MCP Servers から Cline の設定に貼り付けてください。詳しい手順は docs/setup/cline.md をご覧ください
• Continue — ~/.continue/config.json に貼り付けてください
• 独自のエージェントループ — Anthropic SDK を使用した約250行の参考実装については、examples/anthropic_demo.py をご覧ください

12個のツール、PIIを考慮した拒否、監査チェーン、復旧に関する契約は、トランスポートに依存しません。仕様に準拠した stdio MCP クライアントであれば、いずれも同じ保証を得られます。

エージェントフレームワーク

MCP サーバーを起動できるフレームワークであれば、どれからでも同じ stdio MCP インターフェースに接続できます。Anthropic SDK の方法は公式にテスト済みです。それ以外も、フレームワークの MCP 統合機能が stdio で通信するものであれば、原理上は動作します。

• Anthropic SDK — 公式の手順は docs/setup/manual.md をご覧ください。参考ループは examples/anthropic_demo.py をご覧ください
• LangChain / LangGraph — langchain-mcp-adapters を使用します
• Pydantic AI — 組み込みの MCP サポートを使用します
• CrewAI / AutoGen / Agno / 独自のループ — stdio MCP クライアントを備えたフレームワークであれば、原理上は動作します。個別にはテストしていません

フレームワークごとのアダプターは提供していません。フレームワーク標準の MCP クライアントで十分です。

未対応（クラウド / HTTPS ホスト）

SchemaBrain v0.6 は stdio のみで、HTTPS / SSE トランスポートには対応していません。クラウドの HTTPS エンドポイントを必要とするクライアントは、現時点では動作しません。

• ChatGPT Connectors — 回避策と v0.5 以降のロードマップについては、対応状況の詳細をご覧ください
• ホスト型 MCP ゲートウェイ — 設計上、対応していません（ローカルファーストの領域を対象としています。Querybear との比較をご覧ください）

現在 ChatGPT を利用する必要がある場合、コミュニティ製の stdio→HTTPS ブリッジ（mcp-remote、mcp-proxy など）が動作する可能性はありますが、特定のブリッジについて、PII / 監査 / 復旧の動作を検証したものはありません。

調達 / レビュー向けのセキュリティ態勢 →

---

セッション例

同梱の SaaS フィクスチャ（12個のテーブル、84個のカラム、12個のエンティティ）に対する、実際の Claude Desktop セッションです。長さを抑えるために簡略化しています。実際のエージェントはまず list_metrics / suggest_joins を調べ、その後、経路に到達できないと結論付けます。

あなた: SchemaBrain を使用して、プラン階層別の利用量を算出してください。

Claude: (get_metric(name="usage_volume", group_by=["plan.title"]) を呼び出します。メトリクスは usage_event をアンカーとしており、plan に到達するにはスキーマに存在しない結合が必要なため、拒否します:)

{ "status": "error",
  "error": {
    "kind": "unreachable_entity",
    "message": "entity 'plan' is not reachable from metric anchor 'usage_event'; no canonical join exists. Run `schemabrain joins suggest` to surface candidate joins.",
    "recovery": { "suggested_tool": "resolve_join",
                  "suggested_args": { "entity_a": "usage_event", "entity_b": "plan" } } } }

(Claude は結合レイヤーでも確認します。resolve_join("usage_event", "plan") は kind: no_canonical_join を返します。usage_events が持つのは workspace_id だけで、plan_id はなく、両者をつなぐテーブルもありません。)

先に結論をお伝えします。利用量をプラン別に算出することはできませんし、でっち上げてほしくもないはずです。このスキーマには、利用イベントとプランのモデル化された関係がありません。usage_events に記録されているのはプランではなく workspace_id で、両者を結合するものはありません。このつながりが存在しない限り、「プラン階層別の利用量」には答えられません。作り上げて答えることはしません。

代わりにお答えできるのは、プラン階層別の契約収益です（この経路は完全に解決できます。subscription_item → subscription → plan、どちらの結合も fk_constraint、confidence: HIGH です）。

SELECT p.title                                     AS plan_tier,
       SUM(si.unit_price_cents * si.seats) / 100.0  AS revenue   -- prices stored in integer cents
FROM   public.subscription_items si
JOIN   public.subscriptions      s ON si.subscription_id = s.id
JOIN   public.plans              p ON s.plan_id          = p.id
GROUP BY p.title
ORDER BY revenue DESC;

plan_tier	revenue
Enterprise	$379,620.00
Pro	$539.00
Free	$54.00

正直にお伝えしておくべき注意点が2つあります。

• 契約額であり、回収額ではありません。 これはサブスクリプションの明細収益（seats × unit_price_cents）であり、支払い済み請求書の金額ではありません。請求済みの合計額については、total_revenue メトリクスが代わりに invoices をアンカーとします。
• 単位は整数のセントです。 unit_price_cents は整数で保存されており、/ 100.0 で通貨単位に変換しています。

他との違いは、起きなかったことにあります。利用量をプラン別に尋ねられた場合、データベースを使うLLMツールの大半は、存在しない plan_id 列を使って JOIN plans p ON usage_events.plan_id = p.id を自信満々に出力するでしょう。SchemaBrain は拒否しました。get_metric は文章ではなく、recovery.suggested_tool: resolve_join を伴う kind: unreachable_entity を返しました。エージェントは結合をでっち上げる代わりに、構造化された復旧契約にプログラムから従いました。拒否して捏造しないという安全機構を、実際の動作で示しています。

コスト。 Claude Haiku 4.5 の場合、列あたり約 $0.0004 です（名前から意味を推測しにくい列には、--enable-sonnet で Sonnet 4.6 を選択できます）。同梱の12テーブルのフィクスチャ（84列、12エンティティ、5メトリクス、11結合）は事前に整備済みなので、デモの手順では $0 で適用できます。API キーも不要です。LLM による列の説明を使って84列をインデックス化すると、約 $0.03 かかります。直接測定した基準値は、Pagila の DVD レンタル用サンプルです（パーティションの重複を除いて87列）。105秒で $0.0299 でした。変更のないスキーマを再インデックス化する場合は $0 です。コンテンツアドレス可能なフィンガープリントにより、LLM の呼び出しが完全に省略されます。

Claude の SQL が機械的に正しいこと（および、注意点として挙げた内容が実際のデータの挙動であること）を確認するには、Claude が生成する SQL の検証をご覧ください。

このセッションをそのまま自分で実行するには: schemabrain init を実行すると、1つのコマンドで Claude Desktop の接続設定まで案内されます。その後、Claude に 「SchemaBrain を使用して、プラン階層別の利用量を算出してください。」 と尋ね、拒否してから代替案を示す様子を実際に確認してください。

今後の方向性

SchemaBrain は、AI エージェントとデータベースの間にある信頼とインテリジェンスのレイヤーへと進化しています。エージェントにスキーマのセマンティックマップを提供し、お客様が管理する定義から回答をコンパイルし、すべての呼び出しで PII を考慮した処理と監査を実現します。SQL 境界での安全性は、このレイヤーを示す証拠の一つであり、全体像ではありません。

この方針は、セマンティック基盤に支えられています。どの列が PII なのかを知らなければ、「このクエリは PII に触れています」と拒否することはできません。正規の結合定義がなければ、「この中間テーブルを介して結合してください」と答えることはできません。メトリクスの粒度を知らなければ、そのメトリクスを提供することはできません。

したがって、開発の順序は スキーマインテリジェンス → セマンティック基盤 → 信頼の基本機能 です。現在、エージェントが生の SQL を書くことはありません。エージェントは get_metric とセマンティックレイヤーのツールを呼び出し、SchemaBrain はエージェントには見えないパラメーター化 SQL をコンパイルします。また、PII を考慮した拒否、拒否または劣化したすべての呼び出しに対する構造化された復旧処理、ステートメントタイムアウトと行数上限を備えた読み取り専用の実行、改ざんを検出できる監査チェーンを提供します。この定義主導のコンパイル済み SQL の方針がデフォルトであり、推奨される方法です。エージェントが生成した任意の SQL を検査する方法（validate_query / execute）は、後日追加予定の任意選択によるオプトイン方式であり、方向転換の対象ではありません。ロードマップをご覧ください。

---

ロードマップ

v0.5 / v1 / v2 / v3 のラベルは、ロードマップ上のマイルストーン名であり、パッケージのバージョンではありません。パッケージでは厳格なセマンティックバージョニングを採用しています。1.0.0 は、外部ユーザーによる実運用で十分に検証され、強制的な破壊的変更を伴わない API のために留保されています。ADR-0003をご覧ください。

明示的な非目標や優先順位への働きかけ方を含む、全容を随時更新しているロードマップは、ROADMAP.md にあります。

現在 — v0.6.x で提供中

pip install schemabrain で利用できる機能：

• MCP サーバー、読み取り専用ツール 12 種 — find_relevant_tables、find_relevant_entities、describe_table、describe_column、describe_entity、list_entities、list_metrics、list_joins、suggest_joins、resolve_join、get_example_queries、get_metric。
• 定義主導のコンパイル — エージェントが生の SQL を書くことはありません。回答はお客様が管理する定義からコンパイルされ、データベース層で読み取り専用の実行が強制されるほか、ステートメントタイムアウトと行数上限が適用されます。
• スキーマインテリジェンスエンジン — Postgres をローカルの SQLite ストアにインデックス化します。コスト上限付きの LLM セマンティックエンリッチメント（不可解な列にはオプトインの Sonnet ルーティングを使用。--enable-sonnet）。オンデバイス埋め込み（BAAI/bge-small ONNX）。セマンティックなテーブル検索（これらの埋め込みに対するコサイン類似度を使用し、テーブルごとに最も一致する列に基づいて順位付け）。根拠と信頼度を伴うエンティティ識別。宣言済み FK、クエリログ、dbt の relationships に基づく結合のマイニング。複数ホップ BFS を備えた永続化済みの正規結合グラフ。メトリクスレイヤー。
• 信頼と安全性 — 列ごとの信頼度を伴う PII 分類（12 カテゴリにわたる 60 個のルール）、タグの伝播、致命的な情報漏えいを防ぐ下限設定（PII 列をキーにしたグループ化は行レベルの情報開示として拒否）、編集可能なポリシー（block / redact / allow と列ごとの上書き）、およびブラウザーで検証可能な RFC-6962 Merkle 証明と audit verify を備えた、改ざんを検出できる sha256 ハッシュチェーン監査ログ。
• グラフ主導のダッシュボード、9 つの画面 — 特徴的なインタラクティブなナレッジグラフに加え、概要、エンティティ（並べ替え可能なインデックスと、セマンティックペインを備えた詳細表示）、データディクショナリ（Markdown へのエクスポート）、PII マトリクス、拒否、監査ビューアー、編集可能なポリシーエディター、ドリフトインテリジェンスを備えています。デュアルテーマ対応、オプトイン、読み取り専用、127.0.0.1 のみで利用可能です。
• CLI — init、demo、index、import dbt、inspect、diff、check、entities、joins、metrics、policy {show, apply, tag}、docs、dashboard、doctor、serve、audit。Apache-2.0 ライセンスで PyPI とヘッドレス Docker イメージとして配布されています。

後日 — ロードマップ（延期済み。今後の方向性のみ）

フェーズ 2 — 差別化要素

• クエリコストの推定（コンパイル済み SQL の EXPLAIN）
• テナント分離の検出 — フィルター漏れとテナント間 JOIN のチェック
• 定義全体にわたる影響分析
• 使用状況インテリジェンス — ホットスポットと未使用テーブルの検出
• 汎用的なポリシールール文法
• クエリログを使わない暗黙的な FK の検出
• ツールのレスポンスに対するコンテキスト予算管理

フェーズ 3 — 探索的な取り組み

• 永続的なエージェントメモリ
• 複数エージェントの連携
• リモート MCP トランスポートと薄型クライアント SDK
• 明示的なフラグの背後にある、任意でオプトイン可能なエージェント作成 SQL の経路（validate_query / execute）。定義駆動でコンパイルされた SQL をデフォルトかつ推奨される方針とします。この経路が実装される場合、任意のエージェント生成 SQL を実行前に解析したいチーム向けです。まだ提供されておらず、定義駆動のデフォルト方針から転換する計画もありません。

このロードマップにあるものはすべてオープンソースです。

---

トラブルシューティング

初回実行で最もよくある 5 つの問題です。トラブルシューティングの全容は docs/setup/manual.md をご覧ください。

• pip install schemabrain で古いバージョンがインストールされました。 schemabrain --version を確認してください。最新リリースと一致しない場合は、pip のキャッシュが古くなっています。pip install --upgrade schemabrain を実行してください。schemabrain init は Claude Desktop のスニペットにも同じバージョンを書き込むため、再起動後も同じバージョンを再現できます。PyPI からインストールし、かつ uv が PATH にある場合、スニペットは uvx schemabrain==<pin> を実行します（pip でアップグレードした後、ピンは手動で更新してください）。それ以外の場合（ローカルホイール、編集可能インストール、Git チェックアウトなどの PyPI 以外からのインストール、または uvx がない場合）は、インストール済みの schemabrain エントリーポイントの絶対パスを固定します。このパスは init を実行した環境を参照します。
• init が source unreachable を報告します。 初回実行時は Postgres の準備ができていない可能性があります。数秒待ってから再実行してください。独自のデータベースの場合は、ホスト、ポート、認証情報を確認してください。どの形式の接続 URL も使用できます（postgresql://、postgres://、postgresql+psycopg://）。
• 最初の init または schemabrain index が約 60 秒間ハングします。 正常な動作です。初回のインデックス作成では ONNX 埋め込みモデル（約 67 MB）をダウンロードし、列ごとに LLM を 1 回呼び出します。2 回目以降の実行は高速です。
• init がステージ 6「wire host」で失敗します。 Claude Desktop を先にインストールする必要があります。SchemaBrain は Claude Desktop の設定ファイルに書き込みますが、そのファイルは Claude Desktop が少なくとも 1 回起動されるまで存在しません。
• 再起動後に Claude Desktop に SchemaBrain が表示されません。 Cmd+Q が必要です（ウィンドウを閉じるだけでは MCP 設定は再読み込みされません）。schemabrain doctor を実行して、設定が適用されたことを確認してください。doctor が問題なしと報告するのに Claude Desktop にツールが表示されない場合は、~/Library/Logs/Claude/mcp*.log を確認してください。
• Apple Silicon + Python 3.12。 fastembed の依存関係である onnxruntime には、Python 3.12 以降向けの arm64 ホイールがないため、埋め込みを作成できません。init は事前チェックでこれを検出し、Python 3.11（例：pyenv local 3.11.10）を使うか、--no-embed を指定して再実行するよう案内します（セマンティック検索の代わりにキーワード検索を使用します。それ以外はすべて動作します）。

---

ドキュメント

ドキュメント	内容
docs/setup.md	アクティベーションウィザード（推奨）— ホストを選び、ウィザードを実行して、エージェントに質問します（約60秒）
docs/setup/docker.md	Docker のインストール（埋め込みモデルを組み込み済みのイメージで、初回起動時のダウンロードは不要）
docs/setup/manual.md	手動での index、クエリのマイニング、ログ設定、トラブルシューティング、MCP Inspector、SQL 検証の段階的手順
docs/first-5-queries.md	init の後に実際に行うこと — 読み取り専用、PII を考慮した拒否、監査チェーン、構造化された復旧を試す5つのクエリ
docs/semantic-layer.md	エンティティ、メトリクス（複合式を含む）、正規結合（複数段階の結合を含む）の構築、dbt のインポート
docs/operations.md	inspect、check（ドリフト）、index --dry-run、Docker compose
docs/observability.md	tail、監査ログ、OTel エクスポート、PII の分類
docs/reference/mcp-tools/overview.mdx	12個すべての MCP ツールの完全なリファレンス（概要＋各ツールのページ12件）
docs/architecture.mdx	パイプライン、検索の契約、キャッシュのロジック、コストモデル、評価
docs/dashboard/overview.mdx	読み取り専用のオブザーバビリティダッシュボード — PII マトリックス、拒否、監査ビューアー
docs/landscape.md	Vanna / Atlan / dbt-mcp / WrenAI との比較。「これはセマンティックレイヤーですか？」
docs/threat-model.md	セキュリティモデルと境界
docs/adr/	アーキテクチャ決定記録（監査／PII の分類体系、ストアプロトコル、バージョニングポリシー、オブザーバビリティバス）
examples/	コピーしてすぐ使える MCP 設定、ヘッドレスエージェントのループ、E コマースのエンドツーエンドの解説

---

FAQ

データがマシンの外部に送信されますか？ LLM で拡充された列の説明と、その作成に使われる編集済みのサンプル値のみが送信されます。プロファイラーモジュールからデータが送信される前に、すべてのサンプルに対して3つの正規表現パス（メールアドレス、米国の SSN、クレジットカード番号のような数字の並び）が実行されます — schemabrain/profiler/stats.py を参照してください。Anthropic API 呼び出しで送信されるのは、列のメタデータ、編集済みのサンプル、隣接する列のコンテキストであり、生の行データは送信されません。埋め込みは fastembed（BAAI/bge-small-en-v1.5、ONNX、約67 MB）を使ってローカルで生成されます。

現在、どのデータベースに対応していますか？ 現在、ソースコネクターは Postgres 16+ のみです（ローカルストア自体は SQLite ファイルです）。SQLite のソースコネクター、および Snowflake / BigQuery / MySQL への対応は、ほぼ新しい DataSource の実装とプロファイラーの調整で実現でき、v1.x のロードマップに含まれています。

なぜ REST API ではなく MCP なのですか？ 利用者はサービスではなくエージェントだからです。MCP はツールの登録、スキーマの記述、リクエスト／レスポンスの転送を標準化します。エージェントは SchemaBrain をネイティブに検出し、そのツール群を利用できます — API ラッパーも、言語ごとに保守する SDK も必要ありません。

Cube や dbt Semantic Layer のようなセマンティックレイヤーですか？ 厳密には異なります — SchemaBrain は、セマンティックレイヤーを基盤として構築された、AI エージェントとデータベースの間に位置する信頼とインテリジェンスのレイヤーです。エンティティ、メトリクス、正規結合は、第一級の永続化された定義（list_entities、describe_entity、resolve_join、get_metric）であり、安全性のプリミティブ（アーキテクチャによる読み取り専用、PII を考慮した拒否、監査チェーン）を可能にします。セマンティック基盤は土台であり、ファイアウォールを含む SQL 境界の安全性は、このレイヤーの証明の一つであって、その全体像ではありません。Cube / dbt-mcp / Vanna / WrenAI との詳しい比較については、docs/landscape.md を参照してください。

その他の質問については、docs/setup/manual.md（ローカル埋め込みを使う理由や、その他のトラブルシューティング）をご覧ください。

---

ご自身の Postgres で実行する場合

AI エージェントを実際の（デモ用ではない）Postgres に接続している方がいれば、どのような感じかぜひ教えてください。うまくいったこと、問題が起きたこと、使いやすかった点や扱いにくかった点などをお聞かせください。GitHub のディスカッションまたはGitHub のイシューを作成するか、GitHub（@Arun-kc）までご連絡ください。接続の設定も喜んでお手伝いします。

---

コントリビューター

---

コントリビューションとライセンス

PR を歓迎します。基準は高く設定しています。テストファースト／カバレッジ 99%／Conventional Commits／アーキテクチャの不変条件に関するチェックリストについては、CONTRIBUTING.mdをご覧ください。CI ですべてを徹底しています。

バグ報告と機能リクエストには、.github/ISSUE_TEMPLATE/の構造化されたテンプレートをご利用ください。再現手順のないバグ報告や、根本的な問題が明確でない機能リクエストは、必要な情報を添えて再度オープンするよう依頼したうえでクローズします。

Apache 2.0。