Warehouse Context

warehouse-context-mcp

AI エージェントにデータウェアハウスに関する信頼できる、ガバナンスの効いたコンテキストを提供するMCPサーバーです。各テーブルの意味、データの出所、鮮度に加え、書き込み不可、無制限に実行されない、個人データが漏えいしない方法でクエリを実行できます。

コーディングエージェントや分析エージェントは、SQL の扱いは得意ですが、どのテーブルを信頼すべきかを把握するのは苦手です。スキーマだけでは、fct_voyage_economicsがTCEのガバナンス対象ソースであること、stg_voyagesがステージングテーブルであること、contact_emailが個人データであること、あるいはあるテーブルの更新が2日前に止まったことまでは分かりません。このサーバーは、ツール呼び出し1回でそのコンテキストを取得できるようにし、その他すべてにガードレールを設けます。

ツール

ツール	エージェントが取得できる情報
list_tables	説明されている目的と所有者を含む、すべてのテーブル
describe_table	カラム、型、説明、PIIフラグ、粒度、行数、未ドキュメントのカラム
table_lineage	上流のソースと下流の利用者。循環に対応し、深さを制限
table_freshness	最終更新日時、経過時間、ドキュメント化された期待値を満たしているか
sample_rows	PIIをマスキングしたサンプル行
run_query	読み取り専用のSELECT文を1つ実行。行数を制限し、PIIを保護

バックエンド

バックエンド	ステータス	参照するネイティブコンテキスト	読み取り専用の接続レイヤー
DuckDB	v0.1	なし（YAMLカタログのみ）	ファイルをread_onlyで開く
Snowflake	v0.2	テーブル／カラムのコメント、piiオブジェクトタグ	SELECTのみ許可するロール（デモスクリプトではWCM_READER）
Databricks	v0.2	Unity Catalogのコメント、piiカラムタグ	USEとSELECTの権限のみを持つプリンシパル

データウェアハウスに保存されたコメントとタグは、キュレーション済みのYAMLカタログと統合されます。キュレーション済みの値が優先され、ネイティブの値は不足分を補い、どちらかのソースにPIIフラグがあれば、そのフラグは維持されます。

ガードレール

エージェントが送信するすべてのクエリは、攻撃者が書いたものとして扱います。エージェントは、読み取った内容によってプロンプトインジェクションを受ける可能性があるためです。保護は独立した複数の層で構成され、それぞれ個別にテストされています。

1. 許可リスト方式のクエリポリシー。 SQL は sqlglot で解析され、レビュー済みの構文と関数だけで構成された、単一の SELECT でなければなりません。それ以外は、事前に想定しておかなくても拒否されます。対象には、テーブル関数、LATERAL、SUMMARIZE、再帰 CTE、および SYSTEM$…、READ_FILES、SECRET、HTTP_REQUEST、GETENV などのすべてのベンダー関数が含まれます。
2. 実際のスキーマに対する名前解決。 * は展開され、エイリアス、CTE、サブクエリを通じて、すべての列が既知のテーブルの実在する列に解決されなければなりません。値として行全体を使用するクエリは拒否されます。
3. SQL 内での PII マスキング。 SELECT リスト内の PII 列は、クエリの送信前に '***' に置き換えられるため、値がデータウェアハウスの外に出ることはありません。件数の集計（COUNT(DISTINCT email)）は可能ですが、フィルタリング、ソート、グループ化、計算への使用は拒否されるため、値を一度に 1 回ずつテストして推測することはできません。
4. 厳格に制限された接続。 DuckDB は読み取り専用で開かれ、外部ファイルおよびネットワークへのアクセスは無効化され、設定もロックされます。Snowflake ではセカンダリロールを除外した SELECT 専用ロールを使用し、管理者ロールは拒否されます。Databricks では USE および SELECT の権限のみを持つプリンシパルを使用します。
5. 実行と結果の上限設定。 すべてのクエリに行数の上限、タイムアウト、値ごとのサイズ上限、合計バイト数の上限が設定されます。値が引用される可能性があるため、PII を含むテーブルではデータウェアハウスのエラーメッセージを表示しません。

範囲： 設定されたスキーマ内のテーブルのみが対象です。名前は各 SQL 方言の大文字・小文字の規則に従って比較され、実行される SQL ではすべてのテーブルが完全修飾名で指定されます。

データウェアハウスに保存された PII タグ（Snowflake のタグ、Unity Catalog の列タグ）は、キュレーション済みカタログと統合され、起動時に読み取り可能でなければなりません（読み取れない場合はフェイルクローズ）。また、10 分ごとに更新されます。本番データでは、データウェアハウスネイティブのマスキング（マスキングポリシーまたは列マスク）も使用してください。サーバーによるマスキングは、多層防御の一部です。

独立したレビューで以前のバージョンを破るために使用されたクエリは tests/attacks/ にあり、コミットのたびに実行されます。脅威モデル、ADR 0004、SECURITY.md も参照してください。

クイックスタート

クローンせずに試すことができます（uv が必要です）。--demo を指定すると、初回起動時に構築される、同梱の完全な合成配送データウェアハウスが提供されます。

uvx warehouse-context-mcp --demo

PyPI、コンテナーイメージ（ghcr.io/andremuraro/warehouse-context-mcp）、および io.github.AndreMuraro/warehouse-context-mcp としての MCP Registry からも利用できます。リリースにはビルド来歴が含まれています。SECURITY.md を参照してください。

MCP クライアントから使用する

リポジトリをクローンすれば、すでに設定済みです。 .mcp.json（Claude Code）、.vscode/mcp.json（VS Code）、.codex/config.toml（Codex）は、それぞれデモサーバーを起動します。各クライアントは、プロジェクトのサーバーを信頼する前に確認を求めます。

代わりに、すべての環境に追加する場合：

クライアント	コマンドまたは設定
Claude Code	claude mcp add --scope user warehouse -- uvx warehouse-context-mcp --demo
Claude Desktop	claude_desktop_config.json：mcpServers の下に "warehouse": {"command": "uvx", "args": ["warehouse-context-mcp", "--demo"]}
VS Code	ユーザーの mcp.json：servers の下に "warehouse": {"type": "stdio", "command": "uvx", "args": ["warehouse-context-mcp", "--demo"]}
Codex	codex mcp add warehouse -- uvx warehouse-context-mcp --demo
HTTP 経由の任意のクライアント	docker compose up を実行し、http://127.0.0.1:8000/mcp を指定します。

Claude Code プラグインとエージェントスキル

このリポジトリは、Claude Code のプラグインマーケットプレイスでもあります。このプラグインにはサーバーと warehouse-context スキルが含まれており、エージェントにワークフロー（検索、説明、鮮度の確認、クエリ、実行した SQL の引用）と、拒否された場合の対応方法を教えます。

/plugin install warehouse-context --marketplace AndreMuraro/warehouse-context-mcp

同じスキルはプロジェクトで使えるよう、.claude/skills/（Claude Code）と .agents/skills/（Codex）にもチェックインされており、どちらも VS Code から読み込まれます。または、plugins/warehouse-context/skills/warehouse-context/ を個人用のスキルフォルダーにコピーしてください。

実際のデータウェアハウスを使う場合は、--demo を --backend snowflake または --backend databricks に置き換え、以下の設定も行ってください。

次のように質問してみてください。「前四半期に平均 TCE が最も高かった船舶クラスはどれですか？ そのテーブルは最新ですか？」

開発

uv が必要です。未インストールの場合は Python 3.14 をインストールします。

uv sync --all-extras                            # creates .venv from uv.lock
uv run pytest

Snowflake または Databricks

uv sync --extra snowflake                # or --extra databricks, or --all-extras
cp .env.example .env                     # fill in your own values; .env is git-ignored
# run examples/snowflake_demo.sql (or databricks_demo.sql) once in the warehouse
uv run warehouse-context-mcp --backend snowflake --catalog path/to/catalog.yaml

設定は SNOWFLAKE_* / DATABRICKS_* 環境変数または ./.env から読み込まれます。実際の環境変数が優先され、空の値は未設定として扱われます。Snowflake のキーペア認証では、uv run scripts/snowflake_keypair.py を実行すると、実行すべき ALTER USER ステートメントが 1 つ表示されます。

Snowflake CLI 接続の共有

Snowflake CLI を使用している場合は、アカウント情報やサインイン情報を繰り返し設定する代わりに、サーバーがその接続の 1 つを使うように設定できます。

# connections.toml (~/.snowflake/, or %USERPROFILE%\AppData\Local\snowflake\ on Windows)
[wcm]
account = "orgname-accountname"
user = "you"
authenticator = "SNOWFLAKE_JWT"
private_key_file = "~/.snowflake/snowflake_key.p8"

snow sql -c wcm -f examples/snowflake_demo.sql      # one-time demo setup, as an admin role
SNOWFLAKE_CONNECTION_NAME=wcm SNOWFLAKE_ROLE=WCM_READER uv run warehouse-context-mcp --backend snowflake

接続からアカウント情報とサインイン情報が提供されます。設定した SNOWFLAKE_* の値は接続の値より優先され、このパッケージのデフォルト値が優先されることはありません。接続後、サーバーはセッションの実際のデータベースとスキーマを使用し、管理者ロール（ACCOUNTADMIN、SYSADMIN、…）を拒否するため、管理作業用に保持している CLI 接続を使って SELECT 専用ロールを迂回することはできません。

ライブテストでは、実際のデータウェアハウスに対してデモの想定結果を検証します。それ以外の場合はスキップされます。

WCM_LIVE=snowflake uv run pytest -m live

Windows では同じコマンドを PowerShell で実行できます。変数は $env:WCM_LIVE = "snowflake" と設定してください。

Databricks Free Edition では、個人用アクセストークンはワークスペース管理者に属するため、読み取り専用の接続レイヤーは利用できません。ただし、クエリポリシーは引き続き適用されます。実際のワークスペースでは、USE と SELECT の権限のみを持つサービスプリンシパルを使用してください。

Python のバージョン

	3.14	3.15
コア、DuckDB	✓	✓
Databricks エクストラ	✓	✓（lz4 と thrift はソースからビルド）
Snowflake エクストラ	✓	未対応：3.15 用の wheel がなく、ソースビルドも失敗するため、環境マーカーによってエクストラはスキップされます

HTTP トランスポートとコンテナー

デフォルトでは、サーバーは stdio 経由で MCP を使用します。クライアントがサーバーを起動します。--transport http を指定すると、代わりに長時間稼働する Streamable HTTP サービスとして実行され、ステートレスな JSON レスポンスと /healthz エンドポイントを提供します。

uv run warehouse-context-mcp --demo --transport http --port 8000
claude mcp add --transport http warehouse http://127.0.0.1:8000/mcp

HTTP トランスポートには認証機能がありません。DNS リバインディング対策は、すべてのインターフェースにバインドしている場合も有効です。Host ヘッダーに localhost、または --allowed-host で渡した名前が指定されているリクエストのみが処理されます。ループバックで公開するか、認証プロキシを前段に配置してください。

Docker

docker compose up --build                        # demo warehouse at http://127.0.0.1:8000/mcp
docker run --rm -i warehouse-context-mcp:local   # or stdio, for clients that launch a command

イメージは uv.lock からビルドされ、非 root ユーザーとして実行されます。また、すべてのバックエンドと合成デモウェアハウスが含まれています。Compose では、読み取り専用ファイルシステム、Linux ケイパビリティなし、no-new-privileges の設定で実行し、ポートは 127.0.0.1 のみで公開します。

実際のウェアハウスを使う場合は、.env に必要事項を記入してプロファイルを起動してください。認証情報は環境変数ではなく、/run/secrets 配下のシークレットファイルとしてコンテナに渡されます。

docker compose --profile snowflake up --build    # :8001, key-pair sign-in (no browser in a container)
docker compose --profile databricks up --build   # :8002, token from DATABRICKS_TOKEN

• Snowflake では、SNOWFLAKE_ACCOUNT、SNOWFLAKE_USER、および SNOWFLAKE_PRIVATE_KEY_PATH に指定したキーファイルを使用します。Snowflake CLI の接続名は、ホスト上でのみ使える便利な機能です。
• Linux ホスト： キーファイルを自分だけが読み取れる場合は、自分のユーザーとして実行します：WCM_UID=$(id -u) WCM_GID=$(id -g) docker compose ...。
• バージョンタグが付いたイメージは ghcr.io/andremuraro/warehouse-context-mcp に公開されます。

CI ではイメージをビルドし、stdio トランスポートを確認します。Compose サービスを起動して正常な状態になるまで待機し、HTTP 経由でツールを呼び出します。また、外部の Host ヘッダーが拒否されることを確認し、コンテナが非 root かつ読み取り専用であることを検証します。

カタログ

意味情報は、コードと同様に Git でレビューされる YAML ファイルに記述されています（デモのカタログ）：

tables:
  fct_voyage_economics:
    description: Time-charter-equivalent economics per voyage.
    owner: freight-analytics
    grain: voyage_id
    upstream: [stg_voyages]
    freshness_column: computed_at
    expected_freshness_hours: 12
    columns:
      tce_usd_per_day: { description: TCE in USD per day. }

本番環境では、dbt ドキュメント、Unity Catalog のコメント、またはデータカタログから生成できます。

アーキテクチャ

src/warehouse_context_mcp/
├── demo/          the bundled synthetic warehouse and its catalog
├── domain/        catalog, result models, namespace, errors (no I/O beyond YAML)
├── guardrails/    QueryPolicy: parse, scope, PII rules, row limit; result masking
├── warehouses/    Warehouse protocol + DuckDB, Snowflake, Databricks adapters
├── service.py     WarehouseContext: combines the three; no MCP dependency
├── server.py      MCP transport: six read-only tools, stdio or Streamable HTTP
├── settings.py    pydantic-settings for connection config and secrets
└── cli.py         entry point

依存関係は内側に向かっています。トランスポートはサービスを認識し、サービスはドメイン、ガードレール、Warehouse プロトコルを認識します。一方、ドメイン内のものは MCP もドライバーも認識しません。

• エンドツーエンドの型付け。 ツールの結果は変更不可の pydantic モデルであり、MCP クライアントはすべての出力について JSON スキーマを受け取ります。ツールの引数には、入力スキーマ内で上限が設定されています（depth は 1～5、max_rows は ≤ 1000）。DB-API ドライバーには、ドライバーの paramstyle を型パラメーターとする Cursor[P] プロトコルを介してアクセスするため、位置パラメーターを名前付きスタイルのドライバーにバインドすると型エラーになります。
• データとしてのエラー。 ガードレールによる拒否は {"ok": false, "error": ...} として返されるため、エージェントはクエリを修正できます。プログラミングエラーや不明なテーブルは例外を発生させます。
• ウェアハウスに依存しないコア。 アダプターが記述するのは、メタデータの格納場所だけです。取得、キャッシュ、許可リストの適用、カタログの構築は、DbApiWarehouse で共通化されています。

ガードレールとツールチェーンに関する決定については、docs/adr を参照してください。

開発

uv run ruff format          # format
uv run ruff check           # lint: every ruff rule, with a short documented ignore list
uv run ty check             # type check, strict rules
uv run pytest --cov         # tests with branch coverage

CI では、Python 3.14 と 3.15（Linux）、および 3.14（Windows）で同じ処理を実行し、wheel のビルドとスモークテストを行います。

ロードマップ

• v0.1：DuckDB アダプター、カタログ、6 つのツール、3 層のガードレール、テスト、CI
• v0.2：Snowflake と Databricks Unity Catalog のアダプター、ネイティブコメントと PII タグ、スキーマのスコープ指定
• v0.3：Python 3.14 以降、uv、ruff、ty、階層化されたパッケージ、型付きのツール入出力、ポリシーによるテーブル名の修飾
• v0.4：Streamable HTTP トランスポート、強化されたコンテナイメージと Compose 設定、Snowflake CLI 接続、セットアップ不要の --demo、クライアント設定、PyPI および MCP Registry のリリースパイプライン
• dbt の manifest.json からカタログをインポート
• 評価：サーバーの使用あり・なしで20個のアナリスト向け質問に回答し、正確性とテーブル選択を採点
• ツールごとの監査ログ

ライセンス

MIT