Company MCP Server - Google Workspace Integration

# Service Account 認証のセットアップ

自動化や共有運用向けのセットアップ手順です。

## OAuth との違い

| | OAuth | Service Account |
|---|-------|-----------------|
| ユースケース | 個人利用、ローカル開発 | 自動化、共有運用 |
| 認証 | ユーザーがブラウザで認証 | 秘密鍵で自動認証 |
| アクセス範囲 | ユーザーの全ファイル | 明示的に共有されたファイルのみ |
| 推奨設定 | - | `DRIVE_ALLOWLIST_FOLDERS` 必須 |

## 1. Service Account の作成

Google Cloud Console > IAM & Admin > Service Accounts:

1. `+ CREATE SERVICE ACCOUNT` をクリック
2. 情報を入力:
   - Service account name: `mcp-server`
   - Service account ID: `mcp-server`
   - Description: `MCP Server for Google Workspace`
3. `CREATE AND CONTINUE`
4. ロール: スキップ（後で設定）
5. `DONE`

## 2. キーの作成

1. 作成した Service Account をクリック
2. `KEYS` タブ
3. `ADD KEY` > `Create new key`
4. Key type: `JSON`
5. `CREATE` - JSONファイルがダウンロードされます

## 3. API の有効化

Google Cloud Console > APIs & Services > Library で以下を有効化:

- Gmail API
- Google Drive API
- Google Sheets API
- Google Docs API
- Google Calendar API

## 4. キーの配置

```bash
mkdir -p apps/mcp-server-google/.secrets
mv ~/Downloads/xxx-xxx-xxx.json apps/mcp-server-google/.secrets/service-account.json
```

## 5. 環境変数の設定

```bash
cd apps/mcp-server-google
cp .env.example .env
```

`.env` を編集:

```bash
AUTH_MODE=service_account
SERVICE_ACCOUNT_PATH=.secrets/service-account.json
SERVICE_ACCOUNT_EMAIL=mcp-server@your-project.iam.gserviceaccount.com
```

## 6. リソースの共有設定

### Drive / Sheets / Docs

Service Account がアクセスするには、**明示的な共有が必要**です:

1. 操作対象のフォルダ/ファイルを開く
2. 共有 > Service Account のメールアドレスを追加
3. 権限: 編集者（または閲覧者）

### Gmail

Service Account から Gmail を使用するには追加設定が必要です:

1. Google Workspace 管理者コンソールで domain-wide delegation を設定
2. Service Account に適切なスコープを付与

**注意**: これは高度な設定です。個人のGmailには使用できません。

### Calendar

Gmail と同様、domain-wide delegation が必要です。

## 7. フォルダ制限の設定（推奨）

セキュリティのため、操作可能なフォルダを制限します:

```bash
# .env
DRIVE_ALLOWLIST_FOLDERS=1a2b3c4d5e6f,7g8h9i0j1k2l
```

フォルダIDの取得方法:
1. Google Drive でフォルダを開く
2. URLの末尾のIDをコピー
   `https://drive.google.com/drive/folders/1a2b3c4d5e6f` → `1a2b3c4d5e6f`

## 8. 動作確認

```bash
pnpm dev
```

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

### "Permission denied"

- Service Account にファイル/フォルダが共有されているか確認
- `DRIVE_ALLOWLIST_FOLDERS` に対象フォルダが含まれているか確認

### "The caller does not have permission"

- API が有効化されているか確認
- Service Account に適切な IAM ロールがあるか確認

### Gmail/Calendar が使えない

- Domain-wide delegation の設定が必要です
- Google Workspace の管理者に依頼してください

## セキュリティのベストプラクティス

1. **キーのローテーション**: 定期的に新しいキーを作成し、古いキーを無効化
2. **最小権限の原則**: 必要なフォルダのみ共有
3. **フォルダ制限**: `DRIVE_ALLOWLIST_FOLDERS` を必ず設定
4. **監査ログの確認**: `logs/` ディレクトリを定期的にチェック
5. **書き込み無効化**: 本番環境では `*_WRITE_ENABLED=false` を検討

## 参考リンク

- [Service Account 概要](https://cloud.google.com/iam/docs/service-accounts)
- [Domain-wide Delegation](https://developers.google.com/identity/protocols/oauth2/service-account#delegatingauthority)