googleapis/genai-toolbox

⭐ 5,121 🍴 399 Go📄 Apache License 2.0 GitHubで見る →

主な特徴

**17種類のデータベースサポート**: PostgreSQL, MySQL, BigQuery, Redis, Neo4j等
**MCPプロトコル対応**: v20241105およびv20250326バージョン対応
**YAMLベースのシンプルな設定**: コードを書かずにツール定義
**セキュリティ優先**: パラメータ化クエリ、認証、アクセス制御
**複数言語のSDK**: Python, JavaScript/TypeScript, Go対応
**動的リロード**: 設定変更をサーバー再起動なしに反映
**OpenTelemetry統合**: メトリクスと分散トレーシング

リポジトリ解析: googleapis/genai-toolbox

基本情報

リポジトリ名: googleapis/genai-toolbox
主要言語: Go
スター数: 5,121
フォーク数: 399
最終更新: アクティブに開発中
ライセンス: Apache License 2.0
トピックス: MCP Server, Database Tools, Gen AI, Model Context Protocol, Database Integration

概要

一言で言うと

genai-toolboxは、AIモデルとデータベースを安全に接続するためのModel Context Protocol (MCP)サーバー。YAML設定で簡単にデータベースツールを定義し、AIアプリケーションから安全に呼び出せる。

詳細説明

MCP (Model Context Protocol)は、AIモデルと外部ツール・データソースを統合するためのプロトコル。genai-toolboxはこのMCPに対応したオープンソースのデータベースツールボックスで、接続プーリング、認証、セキュリティなどの複雑さを隐蔽し、AIアプリケーションの開発を簡素化する。元々「Gen AI Toolbox for Databases」として開発され、後にMCP対応が追加された。

主な特徴

17種類のデータベースサポート: PostgreSQL, MySQL, BigQuery, Redis, Neo4j等
MCPプロトコル対応: v20241105およびv20250326バージョン対応
YAMLベースのシンプルな設定: コードを書かずにツール定義
セキュリティ優先: パラメータ化クエリ、認証、アクセス制御
複数言語のSDK: Python, JavaScript/TypeScript, Go対応
動的リロード: 設定変更をサーバー再起動なしに反映
OpenTelemetry統合: メトリクスと分散トレーシング

使用方法

インストール

前提条件

Go 1.21以上（ソースからビルドする場合）
データベースアクセス権限
適切な認証情報（データベース種別による）

インストール手順

# 方法1: バイナリダウンロード
export VERSION=0.8.0
curl -O https://storage.googleapis.com/genai-toolbox/v$VERSION/linux/amd64/toolbox
chmod +x toolbox

# 方法2: Docker使用
export VERSION=0.8.0
docker pull us-central1-docker.pkg.dev/database-toolbox/toolbox/toolbox:$VERSION

# 方法3: Goインストール
go install github.com/googleapis/genai-toolbox@v0.8.0

基本的な使い方

Hello World相当の例

# tools.yaml - 最小限の設定
sources:
  demo-postgres:
    kind: postgres
    host: localhost
    port: 5432
    database: testdb
    user: postgres
    password: password

tools:
  hello-db:
    kind: postgres-sql
    source: demo-postgres
    description: Get database version
    statement: SELECT version()

# サーバー起動
./toolbox --tools-file tools.yaml

# ツール実行
curl -X POST http://localhost:5000/tools/hello-db/invoke

実践的な使用例

# ユーザー検索ツール
tools:
  search-users:
    kind: postgres-sql
    source: production-db
    description: Search users by name or email
    parameters:
      - name: search_term
        type: string
        description: Name or email to search
    statement: |
      SELECT id, name, email, created_at
      FROM users
      WHERE name ILIKE '%' || $1 || '%'
         OR email ILIKE '%' || $1 || '%'
      ORDER BY created_at DESC
      LIMIT 10

# ツールセットでグループ化
toolsets:
  user-management:
    - search-users
    - create-user
    - update-user

# Python SDKでの使用
from toolbox_langchain import ToolboxClient

async with ToolboxClient("http://localhost:5000") as client:
    tools = await client.load_toolset("user-management")
    result = await tools["search-users"].invoke(
        {"search_term": "john"}
    )

高度な使い方

# 複数データベースと認証設定
sources:
  analytics-bq:
    kind: bigquery
    project: ${GCP_PROJECT}
    location: us-central1
    
  cache-redis:
    kind: redis
    host: ${REDIS_HOST}
    port: 6379
    password: ${REDIS_PASSWORD}
    
  graph-neo4j:
    kind: neo4j
    host: ${NEO4J_HOST}
    user: neo4j
    password: ${NEO4J_PASSWORD}

tools:
  # BigQuery分析ツール
  analyze-user-behavior:
    kind: bigquery-sql
    source: analytics-bq
    description: Analyze user behavior patterns
    authRequired: ["analyst", "admin"]
    parameters:
      - name: start_date
        type: string
      - name: end_date
        type: string
    statement: |
      WITH user_sessions AS (
        SELECT 
          user_id,
          COUNT(DISTINCT session_id) as session_count,
          AVG(session_duration_seconds) as avg_duration
        FROM `${GCP_PROJECT}.analytics.sessions`
        WHERE date BETWEEN @start_date AND @end_date
        GROUP BY user_id
      )
      SELECT * FROM user_sessions
      LIMIT 100

  # Neo4jグラフクエリ
  find-connections:
    kind: neo4j-cypher
    source: graph-neo4j
    description: Find user connections
    parameters:
      - name: user_id
        type: string
    statement: |
      MATCH (u:User {id: $user_id})-[:FOLLOWS]->(f:User)
      RETURN f.id, f.name
      LIMIT 10

ドキュメント・リソース

公式ドキュメント

README.md: プロジェクト概要、クイックスタート
DEVELOPER.md: 開発者向け詳細ガイド
CONTRIBUTING.md: 貢献ガイドライン
docs/: 詳細ドキュメント（英語）
公式サイト: https://github.com/googleapis/genai-toolbox

サンプル・デモ

tests/各データベースディレクトリ: 統合テストが使用例として参考になる
internal/prebuiltconfigs/: 事前定義されたツール設定
MCP統合例: Claude Desktopでの使用設定

チュートリアル・ガイド

クイックスタート: README内のステップバイステップガイド
SDKドキュメント: Python, JavaScript, Go各SDKの使用方法
データベース固有の設定: 各データベースタイプごとの設定方法

技術的詳細

アーキテクチャ

全体構造

genai-toolboxはAIアプリケーションとデータベースの間のコントロールプレーンとして動作。プラグインアーキテクチャを採用し、新しいデータベースやツールをインターフェース実装で追加可能。

ディレクトリ構成

genai-toolbox/
├── cmd/                    # CLIコマンドとオプション
├── internal/
│   ├── auth/              # 認証（Google認証サポート）
│   ├── log/               # 構造化ログ
│   ├── prebuiltconfigs/   # 事前定義ツール設定
│   ├── server/            # HTTPおよびMCPサーバー実装
│   ├── sources/           # データベース接続実装
│   ├── telemetry/         # OpenTelemetry統合
│   └── tools/             # ツール実装
├── tests/                 # 各データベースの統合テスト
└── docs/                  # 包括的なドキュメント

主要コンポーネント

Sources: データベース接続の抽象化
- 場所: internal/sources/
- 依存: 各データベースドライバー
- インターフェース: Source interface
Tools: ツール実行ロジック
- 場所: internal/tools/
- 依存: Sources
- インターフェース: Tool interface, Execute() method
Server: HTTP/MCPエンドポイント
- 場所: internal/server/
- 依存: Tools, Sources
- インターフェース: REST API, WebSocket (MCP)
Config: YAML設定パーサー
- 場所: internal/server/config.go
- 依存: YAMLライブラリ
- インターフェース: LoadConfig(), ReloadConfig()

技術スタック

コア技術

言語: Go 1.21以上
プロトコル: MCP (Model Context Protocol) v20241105, v20250326
主要ライブラリ:
- YAMLパーサー: 設定ファイル読み込み
- データベースドライバー: 各データベース固有
- OpenTelemetry: メトリクスとトレース
- Google Cloud SDK: 認証とクラウドサービス連携

開発・運用ツール

ビルドツール: Go modules, Docker
テスト:
- 統合テスト: 各データベースごと
- Cloud Build: 自動テスト実行
CI/CD:
- GitHub Actions
- Cloud Buildパイプライン
デプロイ:
- バイナリ配布: Google Cloud Storage
- Dockerイメージ: Artifact Registry

設計パターン・手法

インターフェースベース設計: Source, Toolインターフェース
プラグインアーキテクチャ: 新データベース/ツールの追加が容易
設定駆動開発: YAMLでツール定義、コード変更不要
関心の分離: ソース（接続）とツール（操作）を分離
セキュリティファースト: パラメータ化クエリ、認証チェック

データフロー・処理フロー

1. YAML設定読み込み
   ↓
2. Source初期化（データベース接続）
   ↓
3. Tool初期化（Sourceとステートメントを結び付け）
   ↓
4. HTTP/MCPサーバー起動
   ↓
5. リクエスト受信
   ↓
6. 認証・認可チェック
   ↓
7. パラメータ検証
   ↓
8. Tool実行（データベースクエリ）
   ↓
9. 結果フォーマットと返却

API・インターフェース

公開API

Native Toolbox API

GET /tools: 利用可能なツール一覧
GET /tools/{tool-name}: ツールマニフェスト取得
POST /tools/{tool-name}/invoke: ツール実行
GET /toolsets/{toolset-name}: ツールセット情報

# ツール一覧
curl http://localhost:5000/tools

# ツール実行
curl -X POST http://localhost:5000/tools/search-users/invoke \
  -H "Content-Type: application/json" \
  -d '{"search_term": "john"}'

MCP API

WebSocketエンドポイント: MCPプロトコル対応
JSON-RPC 2.0: メソッド呼び出し
メソッド: initialize, tools/list, tools/call

// MCPクライアント設定 (Claude Desktop)
{
  "mcpServers": {
    "database-toolbox": {
      "type": "sse",
      "url": "http://localhost:5000/mcp/sse"
    }
  }
}

設定・カスタマイズ

設定ファイル

# tools.yaml - 完全な設定例
# ソース定義
sources:
  main-db:
    kind: postgres
    host: ${DB_HOST}        # 環境変数サポート
    port: 5432
    database: ${DB_NAME}
    user: ${DB_USER}
    password: ${DB_PASSWORD}
    pool:
      maxConnections: 10
      idleTimeout: 30s

# ツール定義
tools:
  get-user:
    kind: postgres-sql
    source: main-db
    description: Get user by ID
    authRequired: ["user", "admin"]  # 認証要求
    parameters:
      - name: user_id
        type: int
        description: User ID
    statement: |
      SELECT * FROM users WHERE id = $1

# ツールセット
toolsets:
  user-ops:
    - get-user
    - list-users
    - create-user

# サーバー設定
server:
  port: 5000
  auth:
    enabled: true
    providers:
      - google-iam
  telemetry:
    enabled: true
    exporter: google-cloud

拡張・プラグイン開発

新しいデータベースサポートを追加する場合：

internal/sources/に新しいsource実装を追加
Sourceインターフェースを実装
internal/tools/に対応するtool実装を追加
YAMLで新しいkindを定義して使用

パフォーマンス・スケーラビリティ

パフォーマンス特性

接続プーリング: 効率的なデータベース接続管理
最適化手法:
- パラメータ化クエリでSQLi防止
- クエリ結果のリミット設定
- 接続タイムアウト設定
動的リロード: サーバー再起動なしで設定変更反映

スケーラビリティ

水平スケール: 複数インスタンスで負荷分散可能
マルチテナント: データベースごとに分離されたソース定義
コネクションプール: データベースごとの最大接続数制御
ステートレス: サーバー自体はステートレス

制限事項

技術的な制限:
- 同期的なAPI呼び出し
- データベース固有の制限に依存
- 大量データ転送時のメモリ使用
運用上の制限:
- 各データベースの認証情報管理が必要
- YAML設定の構文エラーに注意
- MCPプロトコルバージョンの互換性

評価・所感

技術的評価

強み

幅広いデータベースサポート: 17種類以上のデータベースに対応
シンプルな設定: YAMLで簡単にツール定義、コード不要
セキュリティ重視: パラメータ化クエリ、認証・認可機能
MCP標準対応: AIアプリケーションとの統合が容易
エンタープライズ機能: OpenTelemetry、動的リロード
豊富なSDK: 複数言語とフレームワーク対応

改善の余地

非同期API: 現在は同期的なAPIのみ
GUI管理ツール: コマンドラインとYAML編集のみ
キャッシュ機能: クエリ結果のキャッシュがない
ドキュメント: 日本語ドキュメントがない

向いている用途

AIアプリケーションのデータベース統合: LLMからの安全なデータアクセス
マルチデータベース管理: 複数種類のデータベースを統一APIで
チャットボット開発: データベース情報を参照するボット
データ分析ツール: AIを使ったデータ分析
エンタープライズRAG: 企業データへのアクセス

向いていない用途

リアルタイム処理: 低レイテンシが必要なシステム
大量データ処理: ETLやバッチ処理
トランザクション管理: 複雑なトランザクション制御
スタンドアロンデータベースクライアント: AI統合が前提

総評

genai-toolboxは、AIアプリケーションとデータベースを安全に繋ぐ優れたソリューション。MCPプロトコル対応によりClaude等のAIアプリケーションとの統合がスムーズで、YAMLベースのシンプルな設定で開発者の負担を大幅に軽減。特に17種類のデータベースサポートは圧巻的で、マルチデータベース環境での使用に最適。Googleが開発していることもあり、エンタープライズ品質の実装とセキュリティ機能が充実している。Gen AI時代のデータベースアクセスのスタンダードとなる可能性を秘めたプロジェクト。