[!NOTE] まだテスト中です！

watsonx.data MCP Proxy

IBM watsonx.data Premium用のMCPプロキシサーバー。IBM watsonx.data remote Model Context Protocol (MCP) serverに接続し、IBM Cloud APIキーからアクセストークンを自動的に取得・更新してリクエストを中継します。

概要

このプロキシサーバーは、IBM watsonx.data Premiumのremote MCP server機能を利用するためのツールです。IBM Cloud IAMトークンの自動管理により、MCPクライアント（IBM BobやClaude Desktopなど）から簡単にwatsonx.dataのデータにアクセスできます。

特徴

• 自動トークン更新: IBM Cloud APIキーから自動的にトークンを取得し、期限切れ前に更新
• MCPプロトコル対応: Model Context Protocol (MCP)に完全対応
• 6つのツールをサポート: watsonx.dataのすべてのMCPツールに対応
• エラーハンドリング: 堅牢なエラー処理とリトライロジック
• ログ機能: 詳細なログでデバッグが容易

サポートされるツール

1. LIST_DOCUMENT_LIBRARY - ドキュメントライブラリの一覧取得
2. QUERY_DOCUMENT_LIBRARY - ドキュメントライブラリへのクエリ実行
3. LIST_DOCUMENT_SET - ドキュメントセットの一覧取得
4. QUERY_DOCUMENT_SET - ドキュメントセットへのクエリ実行
5. LIST_DATA_ASSETS - データアセット（テーブル）の一覧取得
6. QUERY_DATA_ASSETS - データアセットへのクエリ実行

インストール

前提条件

• Python 3.10以上
• pipx（推奨）またはpip
• IBM Cloud APIキー
• watsonx.data Premiumインスタンス

インストール方法

方法1: pipxでGitHubから直接インストール（推奨）

pipxを使用すると、独立した環境にインストールされ、システムのPython環境を汚染しません。

# pipxがインストールされていない場合
python -m pip install --user pipx
python -m pipx ensurepath

# GitHubから直接インストール
pipx install git+https://github.com/kyokonishito/watsonx_data_mcp_proxy.git

# 特定のブランチやタグからインストール
pipx install git+https://github.com/kyokonishito/watsonx_data_mcp_proxy.git@main
pipx install git+https://github.com/kyokonishito/[email protected]

方法2: pipでGitHubから直接インストール

# GitHubから直接インストール
pip install git+https://github.com/kyokonishito/watsonx_data_mcp_proxy.git

# または、ユーザーディレクトリにインストール
pip install --user git+https://github.com/kyokonishito/watsonx_data_mcp_proxy.git

方法3: ローカル開発用（開発者向け）

# リポジトリをクローン
git clone https://github.com/kyokonishito/watsonx_data_mcp_proxy.git
cd watsonx_data_mcp_proxy

# uvで仮想環境を作成（推奨）
uv venv
source .venv/bin/activate  # Linux/macOS
# または .venv\Scripts\activate  # Windows

# 開発モードでインストール
uv pip install -e ".[dev]"

# または、pipを使用
pip install -e ".[dev]"

インストールの確認

# コマンドが利用可能か確認
watsonx-data-mcp-proxy --help

# または、Pythonモジュールとして実行
python -m watsonx_data_mcp_proxy --help

アンインストール

pipxでインストールした場合

pipx uninstall watsonx-data-mcp-proxy

pipでインストールした場合

pip uninstall watsonx-data-mcp-proxy

ローカル開発環境の場合

# 開発モードでインストールした場合
pip uninstall watsonx-data-mcp-proxy

# または、仮想環境ごと削除
rm -rf .venv

使用方法

IBM Bob (MCP Client)での設定

IBM Bobで使用する場合、.bob/mcp.jsonに設定を追加します。インストール方法に応じて設定が異なります。

方法1: pipxでインストールした場合（推奨）

{
  "mcpServers": {
    "watsonx-data-premium": {
      "command": "watsonx-data-mcp-proxy",
      "env": {
        "IBM_CLOUD_API_KEY": "your-ibm-cloud-api-key",
        "WATSONX_DATA_URL": "https://your-instance.lakehouse.saas.ibm.com/api/v2/mcp/"
      }
    }
  }
}

方法2: ローカル開発環境の場合

仮想環境のPythonの絶対パスを指定します：

{
  "mcpServers": {
    "watsonx-data-premium": {
      "command": "/path/to/your/project/.venv/bin/python",
      "args": ["-m", "watsonx_data_mcp_proxy"],
      "env": {
        "IBM_CLOUD_API_KEY": "your-ibm-cloud-api-key",
        "WATSONX_DATA_URL": "https://your-instance.lakehouse.saas.ibm.com/api/v2/mcp/"
      }
    }
  }
}

例: プロジェクトが/Users/username/watsonx-data-mcp-proxyにある場合：

{
  "mcpServers": {
    "watsonx-data-premium": {
      "command": "/Users/username/watsonx-data-mcp-proxy/.venv/bin/python",
      "args": ["-m", "watsonx_data_mcp_proxy"],
      "env": {
        "IBM_CLOUD_API_KEY": "your-ibm-cloud-api-key",
        "WATSONX_DATA_URL": "https://your-instance.lakehouse.saas.ibm.com/api/v2/mcp/"
      }
    }
  }
}

重要:

• 環境変数は.bob/mcp.jsonのenvセクションで設定するため、シェルで別途exportする必要はありません
• ローカル開発環境では、必ず仮想環境のPythonの絶対パスを指定してください
• pythonやpython3などの相対コマンドは使用しないでください（モジュールが見つからないエラーが発生します）

Claude Desktop (MCP Client)での設定

Claude Desktopで使用する場合、設定ファイルの場所が異なります。

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

方法1: pipxでインストールした場合（推奨）

{
  "mcpServers": {
    "watsonx-data-premium": {
      "command": "watsonx-data-mcp-proxy",
      "env": {
        "IBM_CLOUD_API_KEY": "your-ibm-cloud-api-key",
        "WATSONX_DATA_URL": "https://your-instance.lakehouse.saas.ibm.com/api/v2/mcp/"
      }
    }
  }
}

方法2: ローカル開発環境の場合

{
  "mcpServers": {
    "watsonx-data-premium": {
      "command": "/path/to/your/project/.venv/bin/python",
      "args": ["-m", "watsonx_data_mcp_proxy"],
      "env": {
        "IBM_CLOUD_API_KEY": "your-ibm-cloud-api-key",
        "WATSONX_DATA_URL": "https://your-instance.lakehouse.saas.ibm.com/api/v2/mcp/"
      }
    }
  }
}

サーバーの起動

IBM BobまたはClaude Desktopを起動すると、自動的にプロキシサーバーが起動します。トークンは自動的に取得・更新されます。

手動でテストする場合（開発時のみ）：

export IBM_CLOUD_API_KEY="your-ibm-cloud-api-key"
export WATSONX_DATA_URL="https://your-instance.lakehouse.saas.ibm.com/api/v2/mcp/"
python -m watsonx_data_mcp_proxy

設定オプション

トークン更新マージン

デフォルトでは、トークンの有効期限の5分前に自動更新されます。この値はTokenManagerクラスのrefresh_marginパラメータで変更できます。

ログレベル

環境変数LOG_LEVELでログレベルを設定できます：

export LOG_LEVEL=DEBUG  # DEBUG, INFO, WARNING, ERROR, CRITICAL

開発

テストの実行

# すべてのテストを実行
pytest

# カバレッジレポート付きで実行
pytest --cov=src/watsonx_data_mcp_proxy --cov-report=html

# 特定のテストファイルのみ実行
pytest tests/test_token_manager.py

# 統合テストを実行（実際のwatsonx.dataに接続）
# 環境変数を設定して実行
export IBM_CLOUD_API_KEY="your-ibm-cloud-api-key"
export WATSONX_DATA_URL="https://your-instance.lakehouse.saas.ibm.com/api/v2/mcp/"
pytest tests/test_integration.py -v -m integration

# または、uv仮想環境を使用する場合
IBM_CLOUD_API_KEY="your-api-key" WATSONX_DATA_URL="https://your-instance.lakehouse.saas.ibm.com/api/v2/mcp/" uv run pytest tests/test_integration.py -v -m integration

# LIST_DATA_ASSETSテストを実行する場合（追加の環境変数が必要）
export WATSONX_DATA_CONTAINER_ID="your-container-id"
export WATSONX_DATA_PRESTO_CRN="your-presto-instance-crn"
export WATSONX_DATA_PRESTO_ENGINE_ID="your-presto-engine-id"
pytest tests/test_integration.py::test_list_data_assets -v -s

テストの種類

1. ユニットテスト (test_token_manager.py, test_server.py)

   • モックを使用した単体テスト
   • 高速で依存関係なし

2. 統合テスト (test_integration.py)

   • 実際のIBM Cloudとwatsonx.dataに接続
   • 環境変数の設定が必要

プロジェクト構造

mcp_wxd_premium/
├── src/
│   └── watsonx_data_mcp_proxy/
│       ├── __init__.py
│       ├── __main__.py
│       ├── server.py          # MCPサーバー実装
│       └── token_manager.py   # トークン管理
├── tests/
│   ├── test_token_manager.py  # トークン管理のテスト
│   ├── test_server.py         # サーバーのテスト
│   └── test_integration.py    # 統合テスト
├── .bob/
│   └── mcp.json              # IBM Bob設定ファイル
├── pyproject.toml            # プロジェクト設定
└── README.md                 # このファイル

トラブルシューティング

トークン取得エラー

RuntimeError: IBM Cloudトークンの取得に失敗しました

解決方法:

• IBM Cloud APIキーが正しいか確認
• APIキーに適切な権限があるか確認
• ネットワーク接続を確認

watsonx.data接続エラー

RuntimeError: watsonx.dataへのリクエストが失敗しました

解決方法:

• watsonx.data URLが正しいか確認
• watsonx.dataインスタンスでMCPサーバー機能が有効化されているか確認
• トークンに適切な権限があるか確認

レスポンス形式エラー

Invalid response format: 'rows' is not a string []

解決方法:

• watsonx.dataのMCPサーバーバージョンを確認
• プロキシサーバーのログを確認してレスポンス内容を調査

ライセンス

このプロジェクトはApache License 2.0の下でライセンスされています。詳細はLICENSEファイルを参照してください。

参考資料

• IBM watsonx.data Documentation
• IBM watsonx.data remote Model Context Protocol (MCP) server
• Model Context Protocol (MCP)
• IBM Cloud API Keys