Data Profiler

概要

AI エージェントがデータファイルについて推論できるようにするには、通常、会話に行データを貼り付けます。 これはコストがかかり、大きなデータでは途中で切り詰められ、列の型や NULL の割合についてモデルが推測することになります。

このサーバーは、その問いに直接答えます。1 回のツール呼び出しで、データより桁違いに小さく、データの情報をより多く伝える構造化サマリーを返します。

645 MB のファイルは、どれだけコンテキストウィンドウに余裕があっても収まりません。このファイルは 2 秒足らずで完全に特性化されます。

デモ

python demo.py は意図的に問題を含めたデータセットを生成してプロファイルし、結果を報告します。

MCP クライアントから見た同じプロファイラーです。質問を 1 つすると profile_dataset を 1 回呼び出し、会話に 1 行も含めることなくファイルの特性を把握します。

分析を始める前に、実際の問題が 3 つ明らかになりました。値が変化しない列、完全に空の列、そしてテキストとして並べ替えられる日付列です。そのため "2024-10-01" < "2024-9-01" となり、時間に基づく結果が気づかないうちに壊れてしまいます。

機能

• 6 種類のデータ品質フラグ — 定数、すべて NULL、ID の可能性、型の混在、テキストとして保存された数値または日付。
• 列の統計情報を網羅 — データ型、NULL 数と割合、異なる値の数、サンプル値、数値の四分位数、日付の範囲、カテゴリの頻出値。
• 出力サイズを制限 — 入力の列数にかかわらず応答は小さく保たれ、切り詰められた内容も必ず報告します。
• サンプリングを明示 — 大きなファイルはサンプリングしますが、その事実を隠しません。実際の行数は常に含まれます。
• 5 つの形式、11 の拡張子 — .csv .tsv .txt .parquet .pq .json .jsonl .ndjson .xlsx .xlsm .xls。テキスト形式には .gz 形式もあります。
• パスの制限 — オプションの --root で、プロファイリング対象を単一のディレクトリに制限します。
• 設定不要 — データベースもインデックスもウォームアップも不要です。ファイルを指定するだけです。

アーキテクチャ

flowchart LR
    A["MCP client<br/>Claude Code, Claude Desktop"]
    B["server.py<br/>MCP adapter"]
    C["profiler.py<br/>pure pandas, no MCP"]
    D[("Local files<br/>CSV, Parquet<br/>JSON, Excel")]

    A -->|"profile_dataset(path)"| B
    B -->|"validate, confine to --root"| C
    C -->|"sampled read"| D
    D -->|"DataFrame"| C
    C -->|"bounded JSON profile"| B
    B -->|"tool result"| A

プロファイリングのロジックはすべて profiler.py にあり、MCP から何もインポートしません。プロトコル用ハーネスなしでユニットテストが可能で、通常の Python ライブラリとしても利用できます。server.py はアダプターにすぎません。

インストール

Python 3.10 以降が必要です。

pip install mcp-data-profiler

pip install git+https://github.com/Ridadata/mcp-data-profiler.git

Claude Code

claude mcp add data-profiler -- mcp-data-profiler

Claude Desktop およびその他の MCP クライアント

クライアントの MCP 設定に追加します：

{
  "mcpServers": {
    "data-profiler": {
      "command": "mcp-data-profiler"
    }
  }
}

サーバーを 1 つのディレクトリに限定するには、"args": ["--root", "/path/to/your/data"] を追加します。

使用方法

登録したら、自然な言葉で尋ねます：

• 「data/orders.csv をプロファイルしてください」
• 「欠損値がある列はどれですか？」
• 「このデータセットはモデリングに使えるほどクリーンですか？」

ツールリファレンス

profile_dataset(path, sample_rows=50000, max_columns=100, top_k=5, sheet=None)

品質フラグ

Python ライブラリとして

from mcp_data_profiler import profile_dataset

profile = profile_dataset("data/orders.csv", sample_rows=None)
print(profile["shape"])          # {'rows_profiled': 5000, 'total_rows': 5000, 'columns': 6}
print(profile["duplicate_rows"]) # 0

出力例

python demo.py で生成されたサンプルデータセットの出力をそのまま掲載しています。6 列のうち 3 列を示しています：

{
  "file": { "name": "orders.csv", "format": "csv", "size_bytes": 247263 },
  "shape": { "rows_profiled": 5000, "total_rows": 5000, "columns": 6 },
  "sampled": false,
  "columns": [
    {
      "name": "order_id",
      "dtype": "str",
      "null_count": 0,
      "null_pct": 0.0,
      "unique_count": 5000,
      "sample_values": ["ORD-000000", "ORD-000001", "ORD-000002"],
      "flags": ["high_cardinality_possible_id"]
    },
    {
      "name": "amount_eur",
      "dtype": "float64",
      "null_count": 0,
      "null_pct": 0.0,
      "unique_count": 1368,
      "stats": {
        "min": 2.65, "max": 1369.65, "mean": 684.2364, "std": 395.254451,
        "q25": 341.65, "median": 683.65, "q75": 1025.65
      },
      "sample_values": [2.65, 39.65, 76.65]
    },
    {
      "name": "currency",
      "dtype": "str",
      "null_count": 0,
      "null_pct": 0.0,
      "unique_count": 1,
      "top_values": [{ "value": "EUR", "count": 5000 }],
      "sample_values": ["EUR", "EUR", "EUR"],
      "flags": ["constant"]
    }
  ],
  "duplicate_rows": 0
}

order_id には top_values が含まれていないことに注意してください。ほぼ一意な列では各値の件数が 1 になるため、ノイズで応答を埋めるのではなく、リストを省略します。

ファイルをサンプリングした場合、プロファイルには "sampled": true、実際の total_rows、およびサンプリングしたことを示す sampling_note も含まれます。

設計上の注意

出力の上限。 ツールの処理コストは、説明対象のデータより小さくなければなりません。そのため、入力の幅にかかわらず応答に上限を設け、長い文字列は切り詰めます。ほぼ一意な列では、各値の件数が 1 になるため、頻出値のリストを省略します。

正直なサンプリング。 大きなファイルはサンプルからプロファイルを作成しますが、結果には必ず実際の行数と併せて "sampled": true が含まれます。サンプリングした統計を黙って提示すれば、それは誤った統計です。行数は Parquet のメタデータ、または生データの改行スキャンから取得し、ファイル全体をメモリに読み込んで解析することはありません。

誤った結果を黙って返さない。 誤解を招く可能性のあるすべてのデフォルト設定に、同じルールを適用します。ワークブックの最初のシートはタイトルページであることが多いため、Excel のプロファイルでは、使用したシート名を必ず示し、他のシートも列挙します。未確認のシートをクリーンなデータセットとして報告することはありません。CSV の区切り文字は、列数が安定するか候補を試して推測します。これにより、文字頻度による推測でヘッダーが崩れることなく、ヨーロッパのオープンデータで一般的なセミコロン区切りのファイルも処理できます。gzip のバイト列をテキストとして調べるともっともらしく見えても完全に誤った結果になるため、圧縮ファイルはどちらの確認を行う前にも展開します。

パスの安全性。 --root を使うと、プロファイル対象を 1 つのディレクトリに限定できます。確認の前にパスを正規化するため、.. やシンボリックリンクを使って範囲外にアクセスすることはできません。

制限事項

• 読み取り専用のローカルファイル。 データベース、URL、書き込みには対応していません。
• デフォルトではサンプリング。 sample_rows=null を指定しない限り、統計は先頭 50,000 行を対象とします。
• 行指向。 列間の相関、外れ値の検出、プロットには対応していません。
• pandas の解析規則が適用されます。 プロファイルには pandas が認識した内容が表示されます。これは独自のコードが認識する内容と同じです。特に、"NA"、"N/A"、"None" は 欠損値 として読み込まれるため、北米を示す "NA" が含まれる地域列では、null が報告されます。この落とし穴は隠さず、明示します。
• ネストされた JSON はフラット化されません。 ハッシュできないセルがある場合、重複チェックは適用できず、null として報告されます。
• 1 回の呼び出しで対象にできる Excel シートは 1 つです。 プロファイルでは読み込んだシート名を示し、残りのシートも列挙します。シートを切り替えるには sheet を渡します。

開発

git clone https://github.com/Ridadata/mcp-data-profiler.git
cd mcp-data-profiler
pip install -e ".[dev]"

pytest                                  # 40 tests
ruff check src tests demo.py            # lint
ruff format --check src tests demo.py   # formatting
python demo.py                          # profile a generated sample dataset
python demo.py path/to/your.csv         # profile your own files

CI では、Python 3.10～3.13（Linux）に加え、Windows と macOS でテストスイートを実行します。また、ビルドしたサーバーに対して実際に stdio ハンドシェイクを実行し、サーバーが起動してツールを公開することを確認します。

リリース

PyPI への公開にはTrusted Publishingを利用して自動化しているため、このリポジトリに API トークンは保存されていません。GitHub リリースを公開すると .github/workflows/release.yml が実行され、配布パッケージをビルドし、ビルドした wheel が実際にインストールされてインポートできることを検証してから、アップロードします。

Issue やプルリクエストを歓迎します。

ロードマップ

• PyPI で公開
• gzip 圧縮された入力（.csv.gz、.jsonl.gz）
• 公式 MCP レジストリに登録
• 数値特徴量の列間相関の概要
• 1 回の呼び出しで複数シートの Excel をプロファイリング
• リモートソース（s3://、https://）

ライセンス

MIT © Rida Aderkane