Databeak

🚀 DataBeak

DataBeak 借助模型上下文协议（MCP），为 AI 助手处理 CSV 数据带来变革。它提供 40 多种专业工具，用于数据操作、分析和验证，极大提升了 AI 处理 CSV 数据的能力和效率。

🚀 快速开始

使用 DataBeak 最快的方式是搭配 uvx（无需安装）：

针对 Claude Desktop

将以下内容添加到你的 MCP 设置文件中：

{
  "mcpServers": {
    "databeak": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/jonpspri/databeak.git",
        "databeak"
      ]
    }
  }
}

针对其他 AI 客户端

DataBeak 可与 Continue、Cline、Windsurf 和 Zed 配合使用。具体配置示例请参考安装指南。

HTTP 模式（高级用法）

对于基于 HTTP 的 AI 客户端或自定义部署：

# 以 HTTP 模式运行
uv run databeak --transport http --host 0.0.0.0 --port 8000

# 访问服务器：http://localhost:8000/mcp
# 健康检查：http://localhost:8000/health

快速测试

配置完成后，向你的 AI 助手提出以下请求：

"Load this CSV data: name,price\nWidget,10.99\nGadget,25.50"
"Load CSV from URL: https://example.com/data.csv"
"Remove duplicate rows and show me the statistics"
"Find outliers in the price column"

✨ 主要特性

• 🔄 全面的数据操作：从 URL 和字符串内容加载、转换和分析 CSV 数据。
• 📊 高级分析功能：提供统计分析、相关性分析、异常值检测和数据剖析等功能。
• ✅ 数据验证：支持模式验证、质量评分和异常检测。
• 🎯 无状态设计：采用干净的 MCP 架构，支持外部上下文管理。
• ⚡ 高性能：运用异步 I/O、流式下载和分块处理技术。
• 🔒 会话管理：支持多用户，会话相互隔离。
• 🛡️ 网络安全：不访问文件系统，专为安全的网络托管设计。
• 🌟 代码质量高：无 ruff 违规，100% 符合 mypy 规范，MCP 文档标准完善，测试覆盖率全面。

📦 安装指南

不同的使用场景有不同的安装和配置方式：

• Claude Desktop：在 MCP 设置文件中添加特定配置。
• 其他 AI 客户端：参考安装指南进行配置。
• HTTP 模式：使用特定命令以 HTTP 模式运行。

💻 使用示例

基础用法

配置完成后，可向 AI 助手发送简单的 CSV 数据处理请求，如：

"Load this CSV data: name,price\nWidget,10.99\nGadget,25.50"

高级用法

可以请求更复杂的操作，如从 URL 加载数据、去除重复行并查看统计信息、查找特定列的异常值等：

"Load CSV from URL: https://example.com/data.csv"
"Remove duplicate rows and show me the statistics"
"Find outliers in the price column"

📚 详细文档

📚 完整文档

• 安装指南：适用于所有 AI 客户端的设置说明。
• 快速入门教程：10 分钟快速上手。
• API 参考：详细记录了 40 多种工具的使用方法。
• 架构说明：技术细节介绍。

🔧 技术细节

环境变量配置

可以使用环境变量（均以 DATABEAK_ 为前缀）来配置 DataBeak 的行为：

完整的配置选项请参考 settings.py。

已知限制

DataBeak 专为与 AI 助手进行交互式 CSV 处理而设计，使用时需注意以下限制：

• 数据加载：仅支持从 URL 和字符串内容加载数据（出于网络托管安全考虑，不访问本地文件系统）。
• 下载大小：每个 URL 下载最大为 100MB（可通过 DATABEAK_MAX_DOWNLOAD_SIZE_MB 配置）。
• DataFrame 大小：每个 DataFrame 最大内存使用量为 1GB，最大行数为 100 万（可配置）。
• 会话管理：最多支持 100 个并发会话，会话超时时间为 1 小时（可配置）。
• 内存使用：处理大型数据集可能需要大量内存，可使用 health_check 工具进行监控。
• CSV 方言：假定为标准 CSV 格式，复杂方言可能需要预处理。
• 并发处理：支持异步 I/O 进行并发 URL 下载，支持并行会话。
• 数据类型：自动进行类型推断，复杂类型可能需要显式转换。
• URL 加载：仅支持 HTTPS，出于安全考虑，阻止私有网络（127.0.0.1、192.168.x.x、10.x.x.x）。

对于处理大型数据集的生产部署，可调整环境变量，并使用 health_check 和 get_server_info 工具监控资源使用情况。

📄 许可证

本项目采用 Apache 2.0 许可证，请参阅 LICENSE 文件获取详细信息。

贡献与开发

贡献代码

我们欢迎大家贡献代码！请按照以下步骤进行：

1. 分叉仓库。
2. 创建功能分支（git checkout -b feature/amazing-feature）。
3. 进行修改并添加测试。
4. 运行质量检查：uv run -m pytest。
5. 提交拉取请求。

注意：所有更改必须通过拉取请求进行，预提交钩子会阻止直接提交到 main 分支。

开发环境设置

# 设置开发环境
git clone https://github.com/jonpspri/databeak.git
cd databeak
uv sync

# 本地运行服务器
uv run databeak

# 运行测试
uv run -m pytest tests/unit/          # 单元测试（主要）
uv run -m pytest                      # 所有测试

# 运行质量检查
uv run ruff check
uv run mypy src/databeak/

测试结构

DataBeak 实现了全面的单元测试和集成测试：

• 单元测试（tests/unit/）：940 多个快速、独立的模块测试。
• 集成测试（tests/integration/）：基于 FastMCP 客户端的 43 个协议测试，分布在 7 个测试文件中。
• 端到端测试（tests/e2e/）：计划中，用于完整工作流验证。

测试执行：

uv run pytest -n auto tests/unit/          # 运行单元测试（940 多个测试）
uv run pytest -n auto tests/integration/   # 运行集成测试（43 个测试）
uv run pytest -n auto --cov=src/databeak   # 运行并进行覆盖率分析

详细的测试信息请参考 测试指南。

支持与反馈

• 问题反馈：GitHub Issues
• 讨论交流：GitHub Discussions
• 文档查阅：jonpspri.github.io/databeak