Gigapi MCP

🚀 GigAPI MCP Server

GigAPI Timeseries Lake用のMCPサーバーです。Claude Desktopやその他のMCP互換クライアントとのシームレスな統合を提供します。

✨ 主な機能

GigAPIツール

• run_select_query
  • GigAPIクラスターでSQLクエリを実行します。
  • 入力: sql (文字列): 実行するSQLクエリ、database (文字列): 実行対象のデータベース。
  • すべてのクエリは、GigAPIのHTTP APIを介してNDJSON形式で安全に実行されます。
• list_databases
  • GigAPIクラスター上のすべてのデータベースをリストします。
  • 入力: database (文字列): SHOW DATABASESクエリで使用するデータベース（デフォルトは "mydb"）。
• list_tables
  • データベース内のすべてのテーブルをリストします。
  • 入力: database (文字列): データベースの名前。
• get_table_schema
  • 特定のテーブルのスキーマ情報を取得します。
  • 入力: database (文字列): データベースの名前、table (文字列): テーブルの名前。
• write_data
  • InfluxDB Line Protocol形式でデータを書き込みます。
  • 入力: database (文字列): 書き込み先のデータベース、data (文字列): InfluxDB Line Protocol形式のデータ。
• health_check
  • GigAPIサーバーのヘルスステータスを確認します。
• ping
  • GigAPIサーバーにpingを送信して接続を確認します。

🚀 クイックスタート

1. MCPサーバーのインストール

オプションA: PyPIから（推奨）

# 初回リリース後、パッケージはPyPIで利用可能になります
# ユーザーはuvで直接インストールできます
uv run --with mcp-gigapi --python 3.11 mcp-gigapi --help

オプションB: ソースから

# リポジトリをクローンします
git clone https://github.com/gigapi/mcp-gigapi.git
cd mcp-gigapi

# 依存関係をインストールします
uv sync

2. Claude Desktopの設定

1. 以下の場所にあるClaude Desktopの設定ファイルを開きます。

• macOSの場合: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windowsの場合: %APPDATA%/Claude/claude_desktop_config.json

2. 以下の設定を追加します。

パブリックデモ用（テストに推奨）

{
  "mcpServers": {
    "mcp-gigapi": {
      "command": "uv",
      "args": [
        "run",
        "--with",
        "mcp-gigapi",
        "--python",
        "3.13",
        "mcp-gigapi"
      ],
      "env": {
        "GIGAPI_HOST": "gigapi.fly.dev",
        "GIGAPI_PORT": "443",
        "GIGAPI_TIMEOUT": "30",
        "GIGAPI_VERIFY_SSL": "true",
        "GIGAPI_DEFAULT_DATABASE": "mydb"
      }
    }
  }
}

ローカル開発用

{
  "mcpServers": {
    "mcp-gigapi": {
      "command": "uv",
      "args": [
        "run",
        "--with",
        "mcp-gigapi",
        "--python",
        "3.13",
        "mcp-gigapi"
      ],
      "env": {
        "GIGAPI_HOST": "localhost",
        "GIGAPI_PORT": "7971",
        "GIGAPI_TIMEOUT": "30",
        "GIGAPI_VERIFY_SSL": "false",
        "GIGAPI_DEFAULT_DATABASE": "mydb"
      }
    }
  }
}

認証付き

{
  "mcpServers": {
    "mcp-gigapi": {
      "command": "uv",
      "args": [
        "run",
        "--with",
        "mcp-gigapi",
        "--python",
        "3.13",
        "mcp-gigapi"
      ],
      "env": {
        "GIGAPI_HOST": "your-gigapi-server",
        "GIGAPI_PORT": "7971",
        "GIGAPI_USERNAME": "your_username",
        "GIGAPI_PASSWORD": "your_password",
        "GIGAPI_TIMEOUT": "30",
        "GIGAPI_VERIFY_SSL": "true",
        "GIGAPI_DEFAULT_DATABASE": "your_database"
      }
    }
  }
}

3. 重要: uv コマンドを uv 実行ファイルの絶対パスに置き換えます。

   which uv  # パスを検索します
   

4. 変更を適用するためにClaude Desktopを再起動します。

📚 詳細ドキュメント

API互換性

このMCPサーバーは、GigAPIのHTTP APIエンドポイントと連携するように設計されています。

クエリエンドポイント

• POST /query?db={database}&format=ndjson - NDJSON形式のレスポンスでSQLクエリを実行します
• すべてのクエリは、効率的なストリーミングのためにNDJSON（改行区切りJSON）形式で返されます

書き込みエンドポイント

• POST /write?db={database} - InfluxDB Line Protocolを使用してデータを書き込みます

管理エンドポイント

• GET /health - ヘルスチェック
• GET /ping - シンプルなping

💻 使用例

データの書き込み

InfluxDB Line Protocol形式を使用します。

curl -X POST "http://localhost:7971/write?db=mydb" --data-binary @/dev/stdin << EOF
weather,location=us-midwest,season=summer temperature=82
weather,location=us-east,season=summer temperature=80
weather,location=us-west,season=summer temperature=99
EOF

データの読み取り

JSON POSTを介してNDJSON形式でSQLクエリを実行します。

curl -X POST "http://localhost:7971/query?db=mydb&format=ndjson" \
  -H "Content-Type: application/json" \
  -d '{"query": "SELECT time, temperature FROM weather WHERE time >= epoch_ns('\''2025-04-24T00:00:00'\''::TIMESTAMP)"}'

データベース/テーブルの表示

# データベースを表示
curl -X POST "http://localhost:7971/query?db=mydb&format=ndjson" \
  -H "Content-Type: application/json" \
  -d '{"query": "SHOW DATABASES"}'

# テーブルを表示
curl -X POST "http://localhost:7971/query?db=mydb&format=ndjson" \
  -H "Content-Type: application/json" \
  -d '{"query": "SHOW TABLES"}'

# レコードをカウント
curl -X POST "http://localhost:7971/query?db=mydb&format=ndjson" \
  -H "Content-Type: application/json" \
  -d '{"query": "SELECT count(*), avg(temperature) FROM weather"}'

環境変数

必須変数

• GIGAPI_HOST: GigAPIサーバーのホスト名
• GIGAPI_PORT: GigAPIサーバーのポート番号（デフォルト: 7971）

オプション変数

• GIGAPI_USERNAME または GIGAPI_USER: 認証用のユーザー名（必要な場合）
• GIGAPI_PASSWORD または GIGAPI_PASS: 認証用のパスワード（必要な場合）
• GIGAPI_TIMEOUT: リクエストのタイムアウト時間（秒）（デフォルト: 30）
• GIGAPI_VERIFY_SSL: SSL証明書の検証を有効/無効にする（デフォルト: true）
• GIGAPI_DEFAULT_DATABASE: クエリで使用するデフォルトのデータベース（デフォルト: mydb）
• GIGAPI_MCP_SERVER_TRANSPORT: MCPサーバーのトランスポート方法を設定します（デフォルト: stdio）
• GIGAPI_ENABLED: GigAPI機能を有効/無効にする（デフォルト: true）

設定例

ローカル開発用

# 必須変数
GIGAPI_HOST=localhost
GIGAPI_PORT=7971

# オプション: ローカル開発用のデフォルト値を上書きします
GIGAPI_VERIFY_SSL=false
GIGAPI_TIMEOUT=60
GIGAPI_DEFAULT_DATABASE=mydb

認証付きの本番環境用

# 必須変数
GIGAPI_HOST=your-gigapi-server
GIGAPI_PORT=7971
GIGAPI_USERNAME=your_username
GIGAPI_PASSWORD=your_password

# オプション: 本番環境用の設定
GIGAPI_VERIFY_SSL=true
GIGAPI_TIMEOUT=30
GIGAPI_DEFAULT_DATABASE=your_database

パブリックデモ用

GIGAPI_HOST=gigapi.fly.dev
GIGAPI_PORT=443
GIGAPI_VERIFY_SSL=true
GIGAPI_DEFAULT_DATABASE=mydb

データ形式

GigAPIは、以下の構造を持つHiveパーティショニングを使用しています。

/data
  /mydb
    /weather
      /date=2025-04-10
        /hour=14
          *.parquet
          metadata.json

開発

開発環境のセットアップ

1. 依存関係をインストールします。

   uv sync --all-extras --dev
   source .venv/bin/activate
   

2. リポジトリのルートに .env ファイルを作成します。

   GIGAPI_HOST=localhost
   GIGAPI_PORT=7971
   GIGAPI_USERNAME=your_username
   GIGAPI_PASSWORD=your_password
   GIGAPI_TIMEOUT=30
   GIGAPI_VERIFY_SSL=false
   GIGAPI_DEFAULT_DATABASE=mydb
   

3. MCPインスペクターでテストするには、以下を実行します。

   fastmcp dev mcp_gigapi/mcp_server.py
   

テストの実行

# すべてのテストを実行します
uv run pytest -v

# 単体テストのみを実行します
uv run pytest -v -m "not integration"

# 統合テストのみを実行します
uv run pytest -v -m "integration"

# リンティングを実行します
uv run ruff check .

# パブリックデモでテストします
python test_demo.py

パブリックデモでのテスト

リポジトリには、パブリックGigAPIデモに対してMCPサーバーを検証するテストスクリプトが含まれています。

python test_demo.py

これにより、以下がテストされます。

• ✅ ヘルスチェックと接続性
• ✅ データベースのリスト表示（SHOW DATABASES）
• ✅ テーブルのリスト表示（SHOW TABLES）
• ✅ データクエリ（SELECT count(*) FROM table）
• ✅ サンプルデータの取得

PyPIへの公開

このパッケージは、各GitHubリリース時に自動的にPyPIに公開されます。公開プロセスは、GitHub Actionsワークフローによって処理されます。

• CIワークフロー (.github/workflows/ci.yml): プルリクエストとmainブランチへのプッシュ時にテストを実行します
• 公開ワークフロー (.github/workflows/publish.yml): リリースが作成されたときにPyPIに公開します

ユーザー向け

公開された後、ユーザーはPyPIから直接パッケージをインストールできます。

# MCPサーバーをインストールして実行します
uv run --with mcp-gigapi --python 3.11 mcp-gigapi

メンテナー向け

新しいバージョンを公開するには、以下の手順を実行します。

1. pyproject.toml でバージョンを更新します。
2. GitHubリリースを作成します。
3. ワークフローが自動的にPyPIに公開します。

詳細なリリース手順については、RELEASING.md を参照してください。

トラブルシューティング

一般的な問題

1. 接続拒否: GigAPIが実行中であり、ホスト/ポートが正しいことを確認します。
2. 認証失敗: ユーザー名/パスワードが正しいことを確認します。
3. SSL証明書エラー: 自己署名証明書の場合は、GIGAPI_VERIFY_SSL=false に設定します。
4. データベースが見つからない: 正しいデフォルトデータベース（通常は "mydb"）を使用していることを確認します。

デバッグモード

ログレベルを設定してデバッグログを有効にします。

import logging
logging.basicConfig(level=logging.DEBUG)

📄 ライセンス

Apache-2.0ライセンス

🤝 貢献方法

1. リポジトリをフォークします。
2. 機能ブランチを作成します。
3. 変更を加えます。
4. テストを追加します。
5. プルリクエストを送信します。

🛠️ サポート

• 問題報告: GitHub Issues
• ドキュメント: GigAPI Documentation