Databeak

🚀 DataBeak

AIアシスタントによるCSVデータ処理を革新するツールです。Model Context Protocol (MCP) を通じて、40以上のデータ操作、分析、検証ツールを提供します。

🚀 クイックスタート

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、ストリーミングダウンロード、チャンク処理をサポートします。
• 🔒 セッション管理 - 分離されたセッションを持つマルチユーザーサポートです。
• 🛡️ Webセーフ - ファイルシステムへのアクセスがなく、安全なWebホスティング用に設計されています。
• 🌟 コード品質 - ruff違反がゼロ、mypyの100%準拠、完璧なMCPドキュメント標準、包括的なテストカバレッジです。

📦 インストール

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モードで実行
uv run databeak --transport http --host 0.0.0.0 --port 8000

📚 ドキュメント

📚 完全なドキュメント

• インストールガイド - すべてのAIクライアントのセットアップ方法
• クイックスタートチュートリアル - 10分で学ぶ
• APIリファレンス - 40以上のツールのすべてをドキュメント化
• アーキテクチャ - 技術的な詳細

🔧 技術詳細

環境変数

DataBeakの動作を環境変数で設定できます（すべてDATABEAK_プレフィックスを使用）。

完全な設定オプションはsettings.pyを参照してください。

既知の制限事項

DataBeakはAIアシスタントとの対話型CSV処理用に設計されています。以下の制約に注意してください。

• データロード：URLと文字列内容のみ（Webホスティングのセキュリティ上、ローカルファイルシステムへのアクセスはありません）
• ダウンロードサイズ：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ツールでリソース使用量を監視してください。

💻 使用例

基本的な使用法

設定が完了したら、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"

🤝 コントリビュート

コントリビューションを歓迎します！以下の手順に従ってください。

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/) - 7つのテストファイルにまたがる43のFastMCPクライアントベースのプロトコルテスト
• E2Eテスト (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   # カバレッジ分析を伴う実行

詳細なテスト情報はテストガイドを参照してください。

📄 ライセンス

Apache 2.0 - LICENSEファイルを参照してください。

🛠️ サポート

• 問題報告: GitHub Issues
• ディスカッション: GitHub Discussions
• ドキュメント: jonpspri.github.io/databeak