# Databricks Apps上のカスタムMCPサーバー

このプロジェクトは、Databricks Apps上でカスタムMCP (Model Context Protocol) サーバーを構築・デプロイするためのサンプル実装です。LLM（Claude、Cursor等）から呼び出し可能な2つのツールを提供します。

## 提供するツール

1. **get_stock_info**: TSE（東京証券取引所）の株式情報を取得
2. **run_query_on_databricks**: Databricks SQLウェアハウスでSQLクエリを実行

## プロジェクト構成

```
custom_mcp/
├── app.py              # MCPサーバーのメインアプリケーション
├── main.py             # Uvicornサーバーのエントリーポイント
├── app.yaml            # Databricks Apps設定ファイル
├── databricks.yml      # Databricksバンドル設定
├── requirements.txt    # Python依存関係
└── README.md           # このファイル
```

## セットアップ

### 必要な環境

- Python 3.11以上
- Databricks CLI
- Databricksワークスペースへのアクセス権限

### ローカル開発環境のセットアップ

1. **仮想環境の作成と有効化**

```bash
python3 -m venv .venv
source .venv/bin/activate  # Windowsの場合: .venv\Scripts\activate
```

2. **依存関係のインストール**

```bash
pip install -r requirements.txt
```

3. **ローカルでサーバーを起動**

```bash
python main.py
```

サーバーは `http://localhost:8000` で起動します。

4. **ヘルスチェック**

```bash
curl http://localhost:8000/health
```

## Databricks Appsへのデプロイ

### 前提条件

- Databricks CLIがインストールされていること
- Databricksワークスペースに認証済みであること
- SQLウェアハウスが作成されていること

### デプロイ手順

1. **app.yamlの設定**

`app.yaml`の`WAREHOUSE_ID`環境変数に、使用するSQLウェアハウスのIDを設定します。

```yaml
command: ["python", "main.py"]
env:
  - name: 'WAREHOUSE_ID'
    value: 'your-warehouse-id-here'
```

2. **Databricks Appsにデプロイ**

```bash
databricks apps deploy
```

3. **デプロイの確認**

```bash
databricks apps list
```

デプロイされたアプリのURLを確認します。

## LLMクライアントからの利用

### Claude Desktop / Cursor の設定例

MCPサーバーの設定ファイル（`claude_desktop_config.json`または`cursor_config.json`）に以下を追加します：

```json
{
  "mcpServers": {
    "databricks-custom-mcp": {
      "url": "https://your-databricks-app-url.com",
      "transport": "http"
    }
  }
}
```

### 使用例

LLMに以下のように指示することで、ツールを呼び出せます：

```
トヨタ自動車（7203）の株価情報を教えてください
```

```
SQLクエリ "SELECT * FROM catalog.schema.table LIMIT 10" を実行してください
```

## トラブルシューティング

### よくある問題と解決方法

#### 1. ツールが呼び出されない

**問題**: LLMがMCPサーバーを認識するが、ツールが表示されない

**原因**:
- `@mcp.tool()`デコレーターで`name`パラメータを指定していた
- MCPアプリのマウントパスが間違っていた（`/mcp`ではなく`/`にマウント）

**解決方法**:
```python
# ❌ 間違った方法
@mcp.tool(name="tool_name", description="...")
def my_tool():
    pass

app.mount("/mcp", mcp_app)  # ❌ サブパスにマウント

# ✅ 正しい方法
@mcp.tool()
def my_tool():
    """ツールの説明をdocstringに記載"""
    pass

app.mount("/", mcp_app)  # ✅ ルートパスにマウント
```

#### 2. `FastMCP object has no attribute 'app'` エラー

**問題**: `app = mcp.app`や`app = mcp.http_app()`でエラーが発生

**解決方法**: FastMCPでは以下の方法でASGIアプリを作成します：

```python
# ✅ 正しい方法
mcp_app = mcp.streamable_http_app()
app = FastAPI(lifespan=lambda _: mcp.session_manager.run())
app.mount("/", mcp_app)
```

#### 3. `ModuleNotFoundError: No module named 'custom_server'`

**問題**: モジュールが見つからないエラー

**原因**: ディレクトリ構造が複雑すぎた（`src/custom_server`のような入れ子構造）

**解決方法**: フラットなディレクトリ構造にして、`main.py`と`app.py`を同じディレクトリに配置

#### 4. DataFrameが返せない

**問題**: `run_query_on_databricks`でpandas DataFrameを直接返すとエラー

**解決方法**: 文字列に変換してから返す

```python
@mcp.tool()
def run_query_on_databricks(sql_query: str):
    # ... クエリ実行 ...
    df = pd.DataFrame(rows, columns=[...])
    return df.to_string()  # ✅ 文字列に変換
```

#### 5. Uvicornのreloadモードで起動しない

**問題**: `uvicorn.run(reload=True)`が動作しない

**解決方法**: reloadモードでは、アプリオブジェクトを文字列で指定する必要があります：

```python
# ✅ 正しい方法
uvicorn.run(
    "app:app",  # インポートパスを文字列で指定
    host="0.0.0.0",
    port=8000,
    reload=True,
)
```

## 開発のヒント

### ツールの追加方法

新しいツールを追加する場合は、`@mcp.tool()`デコレーターを使用します：

```python
@mcp.tool()
def my_custom_tool(param1: str, param2: int) -> str:
    """このツールの説明をここに記載します。

    LLMがツールを選択する際に、この説明を参考にします。
    """
    # ツールの実装
    result = some_operation(param1, param2)
    return str(result)  # 文字列で返すことを推奨
```

### リソースの追加方法

動的なリソースを公開する場合は、`@mcp.resource()`デコレーターを使用します：

```python
@mcp.resource("data://{resource_id}")
def get_resource(resource_id: str) -> str:
    """動的リソースを取得"""
    return f"Resource content for {resource_id}"
```

### ログの確認

Databricks Appsのログは、Databricks CLIまたはウェブUIから確認できます：

```bash
databricks apps logs <app-name>
```

## セキュリティに関する注意事項

1. **認証**: Databricks Appsは自動的にBearerトークン認証を提供します
2. **環境変数**: 機密情報は`app.yaml`の`env`セクションで設定し、コードにハードコーディングしないでください
3. **SQLインジェクション**: SQLクエリを実行するツールでは、必要に応じて入力検証を実装してください

## 参考リンク

- [FastMCP Documentation](https://gofastmcp.com/)
- [Databricks Apps Documentation](https://docs.databricks.com/apps/index.html)
- [Model Context Protocol Specification](https://modelcontextprotocol.io/)
- [参考実装例](https://github.com/databrickslabs/mcp/tree/master/examples/custom-server)

## ライセンス

このプロジェクトはサンプル実装です。自由に改変・利用してください。

## サポート

問題が発生した場合は、以下を確認してください：

1. Databricks Appsのログ
2. ローカル環境でのテスト結果
3. MCPクライアント側の設定

---

**作成日**: 2025-11-06
**バージョン**: 1.0.0