MCP データ分析エージェント

SQLite と PostgreSQL 上の MCP クライアント向けの、ローカルファーストでガバナンスされた分析基盤です。

mcp-data-analysis-agent は、MCP クライアントにデータベースへの直接アクセスの代わりに、小さく監査可能なデータアクセス層を提供します。SQL を実行前に検証し、読み取り専用接続を使用し、結果と実行時間を制限し、レシート付きの可観測性レコードを書き込み、認証情報はオペレーターのマシン上に保持します。

存在理由

MCP クライアントはデータについて推論できますが、無制限のデータベース認証情報を受け取ったり、任意のステートメントを黙って実行したりすべきではありません。このプロジェクトは、その境界に対するローカルな制御ポイントを提供します:

• データベースのパス、URL、パスワード、トークンを無視される .env ファイルに保持します。

• パラメータ化された単一の SELECT または WITH ステートメントのみを許可します。

• 変更、DDL、コマンド、アタッチメント、複数ステートメント、安全でない関数、制限付きフィールド、安全でないアーティファクトパスをブロックします。

• アプリケーションポリシーに加えて、データベースレベルの読み取り専用アクセスを要求します。

• 正規化された SQL、タイミング、タスクリンク、レシート、ハッシュ、イベントタイムラインを後で監査できるように保持します。

サーバーは stdio のみを使用します。公開 API をホストせず、ソースデータをアップロードせず、リモート認証情報を保存せず、本番データベースユーザーを作成しません。

Related MCP server: sql-explorer-mcp

機能

• SQLAlchemy Core と SQLGlot ポリシー検証による SQLite および PostgreSQL アクセス。

• ソース、スキーマ、リレーションシップ、プロファイル、品質/鮮度、スキーマドリフトの検出。

• 検証、実行計画の説明、制限付き実行、非負オフセットページネーション、キャンセル、タイムアウト、同時実行制限。

• 公開、内部、機密、制限付きフィールド/ソースの分類。

• 承認済みセマンティックメトリクス、Git ネイティブレシピ、期間比較、変更検出、チャート推奨。

• オフライン HTML ダッシュボード、CSV、Parquet、Typst PDF、レシートメタデータ、安全なアトミック出力ディレクトリ。

• ClineFlow コンテキストロード、タスクジャーナル、不変のクエリ/実行レコード、イベントタイムライン、整合性検証。

• 決定的な小売、SaaS、サポートフィクスチャ。ローカル SQLite から PostgreSQL へのパリティフィクスチャを含みます。

前提条件

• Python 3.11 以降と uv。

• サポートされているレポートレンダリングインストール用の Typst。

• ローカルパリティフィクスチャ用の createdb を含む PostgreSQL コマンドラインツール。

• 対象プロジェクト内の健全な ClineFlow/OKF バンドル。

mcp-data-cli preflight を実行して、利用可能なユーザースコープのパッケージマネージャーを通じて必要なローカルツールをインストールまたは報告します。設定されたソースに連絡することはありません。mcp-data-cli doctor はローカルインストールを検証します。設定されたソースがない場合は configuration_pending として報告され、インストール失敗とは見なされません。

インストール

このリポジトリを現在のプロジェクトにインストール

エージェントまたはオペレーターがこの GitHub リポジトリをプロジェクトにインストールするよう求められた場合は、リポジトリインストーラーを使用してください。裸の uv tool install コマンドではありません:

cd /path/to/your-project
curl -fsSL https://raw.githubusercontent.com/hassanvfx/mcp-data-analysis-agent/main/install.sh | bash

インストーラーはコマンドラインツールをインストールし、実行されたディレクトリを初期化します。無視される決定的な小売プレイグラウンドを作成し、1 つのプライベートな MCP_DATA_SOURCE_URL 値を .env に書き込み、ソースポリシーを書き込み、検出されたすべてのサポート対象クライアントに MCP サーバーをマージします。パッケージをプロジェクトにコピーせず、データベース URL や認証情報をクライアント設定に入れることはありません。クライアントの信頼/有効化と再起動プロンプトは、各クライアントアプリケーションの制御下にあります。

uv tool install は意図的にユーザーレベルの実行可能ファイルをインストールし、プロジェクトを変更するポストインストールフックを実行しません。実行可能ファイルを個別にインストールし、その後自分で mcp-data-cli init を実行する場合にのみ使用してください。

PyPI 互換ワークフロー

uv tool install mcp-data-analysis-agent
cd /path/to/your-project
mcp-data-cli preflight
mcp-data-cli init
mcp-data-cli doctor

パッケージリリース前に現在のリポジトリバージョンをインストールするには、インストールコマンドを次に置き換えます:

uv tool install git+https://github.com/hassanvfx/mcp-data-analysis-agent.git

サポートされている MCP クライアントでの最初のサーバー使用時に、エージェントは .mcp-data/playground.sqlite に決定的な開発専用小売 SQLite プレイグラウンドを作成して開きます。共有 MCP welcome ツールは、その探索方法と実際のソースへの切り替え方法を説明します。init は同じプレイグラウンドを明示的なプロジェクトポリシーとプライベートな .env に具体化し、1 回の確認後に安全な MCP クライアントエントリをマージします。明示的なリポジトリインストーラーは init --yes を使用します。これは、そのスコープの書き込みに対する単一の承認であるためです。

setup --all を使用してクライアント設定のみをプレビューするか、setup --all --apply を使用して 1 回の明示的な確認後に mcp-data-analysis stdio エントリのみをマージします。無関係なサーバーと設定は保持されます。setup --status を使用して検出と現在の設定状態を検査します。

セットアップは MCP 定義のみを構成します。クライアントの信頼/有効化プロンプトをバイパスしたり、IDE を起動/再起動したりすることはできません。VS Code の設定詳細は VS Code と VS Code の GitHub Copilot に文書化されています。Continue はプロジェクト MCP フラグメントを MCP ガイド で文書化しています。

チェックサム検証済みリリースブートストラップ

バージョン付きホイールとその公開 SHA-256 チェックサムの場合:

MCP_DATA_RELEASE_URL='https://example.invalid/mcp_data_analysis_agent-0.1.0-py3-none-any.whl' \
MCP_DATA_RELEASE_SHA256='published-sha256' \
./install.sh

ブートストラップには curl と uv が必要で、sha256sum または shasum でアーティファクトを検証し、チェックサムが一致した場合のみインストールします。その後、リポジトリインストーラーとまったく同じように現在のプロジェクトを初期化します。sudo を使用せず、本番データベースに連絡しません。ローカルの決定的なデモデータのみを作成します。

アクティブなソースを 1 つ設定

標準インストールでは、data という名前のアクティブなソースが 1 つだけ、.env にプライベートな値が 1 つだけあります: MCP_DATA_SOURCE_URL。これはパッケージ定数やテスト値ではなく、オペレーターが自分の読み取り専用データベースを指すように変更する唯一の値です。.env はプライベートに保ち、Git で無視されます。

初回使用時、data は自動的に生成された小売プレイグラウンドを指します。その選択をプロジェクトの .env に具体化する準備ができたら mcp-data-cli init を実行します。次のように書き込みます:

MCP_DATA_SOURCE_URL='/absolute/path/to/your-project/.mcp-data/playground.sqlite'

プレイグラウンドは開発専用の合成データです。新しいインストールがスキーマ検出、ガバナンスされたクエリ、レシート、レポートをすぐに実行できるようにします。本番データではなく、後の init 実行で上書きされることもありません。すべてのサポート対象クライアントは、同じ stdio サーバーのウェルカム手順と welcome MCP ツールを受け取ります。

# .mcp-data-agent.toml
[agent]
default_row_limit = 500
max_row_limit = 5000
query_timeout_seconds = 30

# The database dialect is inferred from MCP_DATA_SOURCE_URL.
[source]
env = "MCP_DATA_SOURCE_URL"
allowed_schemas = ["analytics"]
classification = "internal"

[classification.columns]
email = "restricted"

# .env — never commit this file. Change this single value for your own source.
MCP_DATA_SOURCE_URL='postgresql://readonly_user:password@localhost:5432/analytics'

SQLite の場合、同じ単一の変数を絶対ファイルパスまたは SQLite URL にします。PostgreSQL の場合、postgres:// または postgresql:// URL を使用します。手動の方言設定は不要です:

MCP_DATA_SOURCE_URL=/absolute/path/to/your.sqlite
# or: MCP_DATA_SOURCE_URL='postgresql://readonly_user:password@localhost:5432/analytics'

CLI 呼び出しでは data をソース引数として使用します。例: mcp-data-cli schema data。エージェントは、サポートされていない URL スキーム、相対 SQLite パス、URL と競合するレガシー宣言方言を拒否します。確立されたマルチソースポリシーは読み取り可能なままですが、init はそれらを書き換えることを意図的に拒否します。手動で移行するか、新しい簡素化されたプロジェクトを開始してください。

PostgreSQL の場合、書き込みや DDL 権限のない専用の最小権限アカウントを使用します。エージェントは読み取り専用セッションも有効にし、設定されたスキーマ検索パスを適用しますが、データベース側のアクセス制御は必須のままです。

典型的なワークフロー

実行前に検証し、計画を検査して、制限付きクエリを実行します:

mcp-data-cli sql data 'SELECT id, name, stock FROM products WHERE id = :id' --params '{"id": 1}'
mcp-data-cli explain data 'SELECT id, name, stock FROM products WHERE id = :id' --params '{"id": 1}'
mcp-data-cli query data 'SELECT id, name, stock FROM products ORDER BY id' --limit 25 --offset 0

複数の操作が 1 つの分析に属する場合は、明示的なタスクを作成します:

mcp-data-cli task-begin 'Inventory review' 'Identify stockout risk.'
mcp-data-cli observe <task-id>
mcp-data-cli task-complete <task-id> 'Findings recorded.'
mcp-data-cli evaluate-task <task-id>

呼び出し元が選択した新しいディレクトリにレポートを生成します。既存のディレクトリとシンボリックリンクのトラバーサルは拒否されます。

mcp-data-cli report data 'SELECT id, name, stock FROM products' outputs/inventory --pdf --parquet

各レポートには、オフライン HTML、CSV、オプションの Parquet/PDF アーティファクト、レシートメタデータ、パス、コンテンツハッシュが含まれます。生成されたアーティファクト、ソース、認証情報はコミットしてはなりません。

開発フィクスチャと PostgreSQL パリティ

init は上記の小さな小売プレイグラウンドのみを作成します。コントリビューターは、追加の決定的な合成フィクスチャを明示的に生成できます:

mcp-data-cli dataset retail /tmp/retail.sqlite --tier unit --seed 1
mcp-data-cli dataset-postgres retail mcp_data_parity --tier unit --seed 1
# Seed an already-created disposable test database; creates only mcp_seed_<domain>.
MCP_DATA_TEST_POSTGRES_URL='postgresql://mcp_data_test@localhost:5432/mcp_data_parity' \
  mcp-data-cli seed-postgres retail --seed 1

dataset-postgres はローカルの createdb を使用し、既存のデータベース名を拒否し、SQLite データを一時ディレクトリにのみ作成し、それを mcp_parity スキーマの下の新しい PostgreSQL データベースにコピーします。手動で使い捨ての PostgreSQL URL を提供する必要はありません。

seed-postgres は、既にプロビジョニングされた分離されたテストデータベース用です。環境からプライベートなテスト URL を読み取り、予約された mcp_seed_retail、mcp_seed_saas、または mcp_seed_support スキーマのみを置き換えます。public/アプリケーションスキーマには触れません。

アダプターの動作を開発するときは、分離された PostgreSQL インスタンスで完全なローカル品質スイートを実行します。CI は、リンティング、型チェック、テスト、カバレッジゲート、実際の Typst レンダリング、SQLite/PostgreSQL パリティ、シークレットスキャン、依存関係監査、SBOM 生成、信頼できる公開リリース自動化をカバーします。

uv run ruff check src tests scripts
uv run mypy src
uv run pytest --cov=mcp_data_agent --cov-branch
uv run python scripts/check_coverage.py coverage.json
./validate-okf

安全上重要な設定、コンテキスト、台帳、SQL ポリシーモジュールは、100% の行とブランチのカバレッジを必要とします。全体のゲートは、少なくとも 90% の行カバレッジと 85% のブランチカバレッジを必要とします。

セキュリティと運用契約

• クエリはパラメータ化され、データベース接続/実行前に検証されます。

• 結果の制限とオフセットはプロジェクトポリシーによって管理されます。呼び出し元の SQL はそれらをバイパスできません。

• 制限付き列は実行前に拒否され、シークレットのようなパラメータは可観測性レコードで編集されます。

• タスクジャーナル、クエリレシート、実行、イベントは knowledge/ と observability/ の下に保存されます。データベース URL、生のシークレット、ソースデータベース、結果キャッシュ、レポートバイナリは除外されます。

• ローカル合成データセットは開発インフラストラクチャのみであり、本番オンボーディングではありません。

完全な運用および開示契約については、運用ガイダンス、セキュリティポリシー、MIT ライセンス を参照してください。

貢献とリリース

焦点を絞ったコミットを使用し、注釈付きの checkpoint-* タグを保持してください。これらは配信マイルストーンの明示的なロールバックポイントです。アクティブな ClineFlow エンジニアリングジャーナルとナレッジログを重要な変更で更新し、OKF 検証を実行してから、実装とナレッジの証拠を一緒にコミットします。

GitHub Actions は、リリース公開時にディストリビューションをビルドして検証します。リリースエンドポイントと公開認証情報はリポジトリ設定です。このコードベースに保存されることはありません。