# karte-datahub-mcp

KARTE のイベントデータを BigQuery 経由で安全にクエリするための MCP（Model Context Protocol）サーバーです。

Claude Code などの MCP 対応 AI アシスタントに KARTE イベントデータへのアクセス機能を提供します。

## 前提条件

- Python 3.13 以上
- [uv](https://docs.astral.sh/uv/) パッケージマネージャー
- GCP サービスアカウントの認証情報ファイル
- KARTE API キー

## セットアップ

### 1. 依存関係のインストール

```bash
cd karte-datahub-mcp
uv sync
```

### 2. 環境変数

| 環境変数 | 必須 | 説明 | デフォルト |
|---------|------|------|-----------|
| `KARTE_API_KEY` | Yes | KARTE API キー | - |
| `CREDENTIAL_FILE` | No | サービスアカウントキーファイルパス | - |
| `BQ_PROJECT` | No | BigQuery クエリ実行用 GCP プロジェクト | - |
| `DATA_PROJECT` | No | KARTE データプロジェクト | `karte-data` |

### 3. Claude Code への登録

`.mcp.json` に以下を追加します。

```json
{
  "mcpServers": {
    "karte-datahub-mcp": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/karte-datahub-mcp", "karte-mcp-server"],
      "env": {
        "KARTE_API_KEY": "<your-karte-api-key>",
        "CREDENTIAL_FILE": "/path/to/credential.json",
        "BQ_PROJECT": "<your-gcp-project>"
      }
    }
  }
}
```
### 注意

- Pathは絶対パスである必要があります
- 払い出しサービスアカウントを利用する場合は、「BQ_PROJECT」に以下を設定
  - prd-karte-service-account-2



## 提供ツール

MCP サーバーとして以下の 4 つのツールを公開します。

### `query_karte_events` - イベントデータ取得

KARTE イベントテーブルからデータを取得します。

| パラメータ | 型 | デフォルト | 説明 |
|-----------|-----|-----------|------|
| `select_columns` | string | `"*"` | SELECT句（例: `"event_name, user_id"`）|
| `where_clause` | string \| null | null | WHERE条件（例: `"event_name = 'click'"`）|
| `date_from` | string \| null | 2日前 | 開始日（YYYYMMDD形式）|
| `date_to` | string \| null | 昨日 | 終了日（YYYYMMDD形式）|
| `limit` | int \| null | 100 | 取得件数上限（1〜10000）。null で制限なし |
| `order_by` | string \| null | null | ORDER BY句（例: `"sync_date DESC"`）|

### `count_karte_events` - イベント件数集計

イベントの件数を集計します。GROUP BY にも対応しています。

| パラメータ | 型 | デフォルト | 説明 |
|-----------|-----|-----------|------|
| `where_clause` | string \| null | null | WHERE条件 |
| `date_from` | string \| null | 2日前 | 開始日（YYYYMMDD形式）|
| `date_to` | string \| null | 昨日 | 終了日（YYYYMMDD形式）|
| `group_by` | string \| null | null | GROUP BY句（例: `"event_name"`）|

### `describe_karte_events_schema` - スキーマ取得

KARTE イベントテーブルのカラム名・型・説明などのスキーマ情報を返します。パラメータはありません。

### `execute_karte_sql` - カスタムSQL実行

任意の SQL を実行します。ガードレールが自動適用されます。

| パラメータ | 型 | デフォルト | 説明 |
|-----------|-----|-----------|------|
| `sql` | string | - | 実行する SQL 文 |
| `dry_run` | bool | false | true でスキャン量のみ確認 |
| `no_limit` | bool | false | true で自動 LIMIT 付与をスキップ |

## 使い方の例

Claude Code から自然言語で利用できます。

```
> KARTEの直近のイベントを10件見せて
→ query_karte_events(limit=10)

> クリックイベントだけを取得して
→ query_karte_events(where_clause="event_name = 'click'")

> event_name ごとのイベント数を集計して
→ count_karte_events(group_by="event_name")

> テーブルにどんなカラムがあるか教えて
→ describe_karte_events_schema()

> ユーザーごとのイベント数TOP10を出して
→ execute_karte_sql(sql="SELECT user_id, COUNT(*) as cnt FROM ... GROUP BY user_id ORDER BY cnt DESC LIMIT 10")
```

## セキュリティ・ガードレール

| 機能 | 説明 |
|------|------|
| 破壊的SQL拒否 | DROP, DELETE, INSERT, UPDATE, TRUNCATE, ALTER, CREATE を禁止 |
| 日付範囲制限 | 最大 30 日間まで |
| LIMIT 強制 | カスタム SQL で未指定時に `LIMIT 1000` を自動付与（`no_limit=true` でスキップ可）|
| `_TABLE_SUFFIX` 必須 | ワイルドカードテーブルへのクエリに日付制約を強制 |
| LIMIT 上限 | 1〜10000 の範囲に制限 |

## サーバー単体起動

```bash
KARTE_API_KEY=<your-key> uv run karte-mcp-server
```

## Cloud Run へのデプロイ

Cloud Run にデプロイすると、リモートの MCP サーバーとして複数のクライアントから利用できます。

### 1. server.py に HTTP トランスポートを追加

現在のサーバーは `stdio` トランスポートのみ対応しています。Cloud Run で使うには `streamable-http` トランスポートを追加します。

`server.py` の `main()` 関数を以下のように変更します。

```python
import os

def main():
    """MCPサーバーを起動する."""
    transport = os.environ.get("MCP_TRANSPORT", "stdio")
    if transport == "streamable-http":
        _server.run(
            transport="streamable-http",
            host="0.0.0.0",
            port=int(os.environ.get("PORT", "8080")),
        )
    else:
        _server.run(transport="stdio")
```

### 2. Dockerfile を作成

プロジェクトルート（`karte-datahub-mcp/`）に `Dockerfile` を作成します。

```dockerfile
FROM python:3.13-slim

COPY --from=ghcr.io/astral-sh/uv:latest /uv /uvx /bin/

WORKDIR /app

COPY pyproject.toml uv.lock ./
RUN uv sync --frozen --no-dev

COPY src/ src/

ENV MCP_TRANSPORT=streamable-http
ENV PORT=8080

EXPOSE 8080

CMD ["uv", "run", "karte-mcp-server"]
```

### 3. デプロイ

```bash
# GCPプロジェクトの設定
export GCP_PROJECT=<your-gcp-project>
export REGION=asia-northeast1

# Cloud Run にデプロイ（ソースから直接ビルド）
gcloud run deploy karte-mcp-server \
  --source . \
  --project $GCP_PROJECT \
  --region $REGION \
  --set-env-vars "KARTE_API_KEY=<your-karte-api-key>,MCP_TRANSPORT=streamable-http,BQ_PROJECT=<your-bq-project>" \
  --no-allow-unauthenticated
```

サービスアカウントの認証情報は Cloud Run のデフォルトサービスアカウント、または `--service-account` で指定したサービスアカウントの権限が使われるため、`CREDENTIAL_FILE` の設定は不要です。対象の BigQuery データセットへの読み取り権限をサービスアカウントに付与してください。

### 4. Claude Code からリモートサーバーに接続

デプロイ後、`.mcp.json` にリモートサーバーとして登録します。

```json
{
  "mcpServers": {
    "karte-bigquery": {
      "type": "streamable-http",
      "url": "https://<your-service-url>/mcp/",
      "headers": {
        "Authorization": "Bearer <id-token>"
      }
    }
  }
}
```

`--no-allow-unauthenticated` でデプロイした場合、認証トークンが必要です。以下で取得できます。

```bash
gcloud auth print-identity-token
```

または、認証付きプロキシ経由で接続する場合は `gcloud run services proxy` を利用します。

```bash
gcloud run services proxy karte-mcp-server \
  --project $GCP_PROJECT \
  --region $REGION \
  --port 8080
```

この場合、`.mcp.json` の URL は `http://localhost:8080/mcp/` を指定します。

## テスト

```bash
uv run pytest
```

## 技術スタック

- **FastMCP** - MCP サーバーフレームワーク
- **google-cloud-bigquery** - BigQuery SDK
- **Pydantic** - データバリデーション
- **pytest** / **pytest-asyncio** - テスト