Data Profiler

概述

要让 AI Agent 对数据文件进行推理，通常需要把数据行粘贴到对话中。这样既耗费资源，遇到大型文件时还会被截断，而且模型仍只能猜测列类型和空值比例。

这个服务可直接回答问题。一次工具调用即可返回结构化摘要，其体积比数据小几个数量级，同时提供更多信息：

645 MB 的文件无论付出多大代价，都无法放入上下文窗口。这里不到两秒就能完整描述它。

演示

运行 python demo.py 会生成一个刻意包含问题的数据集，对其进行概况分析，并报告结果：

通过 MCP 客户端查看同一个分析器——提出一个问题，调用一次 profile_dataset，无需让任何数据行进入对话，就能完整描述文件：

分析开始之前就发现了三个实际问题：一列的值始终不变，一列完全为空，还有一列日期被当作文本排序——因此 "2024-10-01" < "2024-9-01"——悄无声息地破坏所有基于时间的结果。

功能

• 六种数据质量标记——常量、全空、疑似 ID、混合类型，以及以文本形式存储的数字或日期。
• 完整的列统计信息——数据类型、空值数量和比例、不同值数量、样本值、数值的四分位数、日期范围、类别的高频值。
• 输出有上限——无论输入多宽，响应都保持精简，并始终报告被截断的内容。
• 如实采样——对大型文件进行采样，但绝不隐瞒；始终包含实际行数。
• 五种格式、十一种扩展名——.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"
    }
  }
}

若要将服务限制在一个目录中，请添加 "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 生成的示例数据集的原始输出，其中展示了六列中的三列：

{
  "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 会将分析限制在一个目录中。检查前会规范化路径，因此 .. 和符号链接都无法逃出该目录。

限制

• 只读本地文件。 不支持数据库、URL，也不会写入数据。
• 默认抽样。 除非传入 sample_rows=null，否则统计数据仅反映前 50,000 行。
• 面向行。 不提供跨列相关性、异常值检测或图表。
• 遵循 pandas 解析规则。 分析结果反映的是 pandas 读取到的内容，也就是你自己的代码会读取到的内容。特别是，"NA"、"N/A" 和 "None" 会被视为缺失值，因此若某个区域列用 "NA" 表示北美，就会报告空值。这个陷阱会明确提示，而不会隐藏。
• 不会展平嵌套 JSON。 不可哈希的单元格不适用重复项检查，结果会报告为 null。
• 每次调用处理一个 Excel 工作表。 分析结果会注明读取的工作表并列出其余工作表；传入 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 握手，以确认服务能够启动并声明其工具。

发布

通过 Trusted Publishing 自动发布到 PyPI，因此此仓库中不会存储 API 令牌。发布 GitHub Release 会触发 .github/workflows/release.yml，该工作流会构建发行包、验证构建的 wheel 确实能够安装和导入，然后上传发行包。

欢迎提交问题和拉取请求。

路线图

• 发布到 PyPI
• Gzip 压缩输入（.csv.gz、.jsonl.gz）
• 列入官方 MCP 注册表
• 数值特征的跨列相关性摘要
• 在一次调用中分析多个工作表的 Excel 文件
• 远程数据源（s3://、https://）

许可证

MIT © Rida Aderkane