# Collab Integration — Google Drive (deployment curls)

Google Drive tools — same contract as Calendar / HubSpot collab.

---

## Contract

| | |
|---|---|
| Method / path | `POST /internal/v1/tools/{tool_name}` |
| Local | `http://localhost:6010` |
| Prod | `https://adhoc-mcp.lucos.com` |
| Headers | `Content-Type: application/json`, `X-Lucos-Org-Id` (required). Optional: `X-Lucos-User-Email`, `X-Lucos-User-Id` |
| Body | `{ "environment": "staging" \| "prod", "args": { ... } }` |

Whose Drive: `args.user` / `as_user` (name or email). Default = requester identity.

### Identity propagation (ChatGPT → Google)

| Source | Behavior |
|--------|----------|
| `X-Lucos-User-Email` | Used as Google subject when valid Workspace email |
| `X-Lucos-User-Id` + `LUCOS_USER_GOOGLE_MAP` | Maps Lucos/ChatGPT user id → Google email when email header is missing |
| `args.user` / `as_user` | Explicit person (overrides “me”) |
| Fallback | `DRIVE_INDEX_ADMIN_EMAIL` |

```bash
# Example map (JSON object)
LUCOS_USER_GOOGLE_MAP={"chatgpt-user-abc":"yogesh.kaurav@admedia.com"}
```

HelloMCP can send email/id via `GDRIVE_USER_EMAIL` / `GDRIVE_USER_ID` (or `LUCOS_USER_ID`).

---

## Tools ↔ HelloMCP mapping

| Collab tool (path) | HelloMCP tool | Env URL override |
|--------------------|---------------|------------------|
| `gdrive_search_files` | `gdrive_search` | `GDRIVE_SEARCH_URL` |
| `gdrive_read_file` | `gdrive_read` / `gdrive_read_sheet` | `GDRIVE_READ_URL` |
| `gdrive_query_sheet` | `gdrive_query_sheet` | `GDRIVE_QUERY_SHEET_URL` |
| `gdrive_list_workspaces` | `gdrive_list_workspaces` | `GDRIVE_LIST_WORKSPACES_URL` |
| `gdrive_drive_overview` | `gdrive_drive_overview` | `GDRIVE_DRIVE_OVERVIEW_URL` |
| `gdrive_user_drive_info` | `gdrive_user_drive_info` | `GDRIVE_USER_DRIVE_INFO_URL` |
| `gdrive_lookup_owned_file` | `gdrive_lookup_owned_file` | `GDRIVE_LOOKUP_OWNED_FILE_URL` |
| `gdrive_find_duplicates` | `gdrive_find_duplicates` | `GDRIVE_FIND_DUPLICATES_URL` |
| `gdrive_list_recent_activity` | `gdrive_list_recent_activity` | `GDRIVE_LIST_RECENT_ACTIVITY_URL` |
| `gdrive_list_permissions` | `gdrive_list_permissions` | `GDRIVE_LIST_PERMISSIONS_URL` |
| `gdrive_list_revisions` | `gdrive_list_revisions` | `GDRIVE_LIST_REVISIONS_URL` |
| `gdrive_list_comments` | `gdrive_list_comments` | `GDRIVE_LIST_COMMENTS_URL` |

### Capability checklist

| Requirement | Status | How |
|-------------|--------|-----|
| Map ChatGPT user → Google identity | Done | `X-Lucos-User-Email` / `GDRIVE_USER_EMAIL` |
| List folder children + recursive | Done | `folder_id` + optional `recursive=true` |
| Search Drive / folder / org mime | Done | `query`, `mime_type` (video/image/ppt/exe/…), owner-index mime |
| created-after / modified-after | Done | `created_after`, `modified_after` (ISO date/datetime) |
| Rich metadata + checksums / revision id | Done | `md5_checksum`, `sha256_checksum`, `head_revision_id`, `version` |
| Shortcuts | Done | `shortcut_target_id` / `shortcut_target_mime_type` on search/read |
| Read + cursors | Done | `gdrive_read_file` (`offset` / `next_offset`) |
| Query sheet rows | Done | `gdrive_query_sheet` |
| Owned-by / last-edited-by | Done | `owned_by`, `modified_by` |
| Dupes / pairs / misplaced | Done | Canonical Summaries+Transcripts = paired (not misplaced); `conflicting_versions` for multiples |
| Permissions / sharing | Done | `gdrive_list_permissions` |
| Version history | Done | `gdrive_list_revisions` |
| Comments | Done | `gdrive_list_comments` (may need extra scope) |
| Activity | Partial | Needs DWD `drive.activity.readonly`; response sets `data_source` + `action_category` / `is_fallback` |

---

## Server env (collab API)

```bash
GOOGLE_SERVICE_ACCOUNT_FILE=./secrets/drive-sa.json
GOOGLE_DRIVE_SA_SCOPES=https://www.googleapis.com/auth/drive.readonly,https://www.googleapis.com/auth/admin.directory.user.readonly,https://www.googleapis.com/auth/calendar,https://www.googleapis.com/auth/drive.activity.readonly
DRIVE_INDEX_ADMIN_EMAIL=master@admedia.com
DRIVE_IMPERSONATE_DOMAINS=admedia.com
DRIVE_OWNER_INDEX_PATH=./data/drive-owner-index.json
```

## HelloMCP `.env` (Drive URLs)

```bash
GDRIVE_SEARCH_URL=http://localhost:6010/internal/v1/tools/gdrive_search_files
GDRIVE_READ_URL=http://localhost:6010/internal/v1/tools/gdrive_read_file
GDRIVE_QUERY_SHEET_URL=http://localhost:6010/internal/v1/tools/gdrive_query_sheet
GDRIVE_LIST_WORKSPACES_URL=http://localhost:6010/internal/v1/tools/gdrive_list_workspaces
GDRIVE_DRIVE_OVERVIEW_URL=http://localhost:6010/internal/v1/tools/gdrive_drive_overview
GDRIVE_USER_DRIVE_INFO_URL=http://localhost:6010/internal/v1/tools/gdrive_user_drive_info
GDRIVE_LOOKUP_OWNED_FILE_URL=http://localhost:6010/internal/v1/tools/gdrive_lookup_owned_file
GDRIVE_FIND_DUPLICATES_URL=http://localhost:6010/internal/v1/tools/gdrive_find_duplicates
GDRIVE_LIST_RECENT_ACTIVITY_URL=http://localhost:6010/internal/v1/tools/gdrive_list_recent_activity
GDRIVE_LIST_PERMISSIONS_URL=http://localhost:6010/internal/v1/tools/gdrive_list_permissions
GDRIVE_LIST_REVISIONS_URL=http://localhost:6010/internal/v1/tools/gdrive_list_revisions
GDRIVE_LIST_COMMENTS_URL=http://localhost:6010/internal/v1/tools/gdrive_list_comments
GDRIVE_ORG_ID=00000000-0000-0000-0000-000000000001
GDRIVE_USER_EMAIL=yogesh.kaurav@admedia.com
```

---

## Setup

```bash
BASE=http://localhost:6010
ORG=00000000-0000-0000-0000-000000000001
USER_EMAIL=yogesh.kaurav@admedia.com
```

---

## 1. Search entire Drive

```bash
curl -sS -X POST "$BASE/internal/v1/tools/gdrive_search_files" \
  -H 'Content-Type: application/json' \
  -H "X-Lucos-Org-Id: $ORG" \
  -H "X-Lucos-User-Email: $USER_EMAIL" \
  --data-binary '{"environment":"staging","args":{"user":"yogesh.kaurav@admedia.com","query":"standup","limit":25}}'
```

---

## 2. Search inside a folder (direct children)

```bash
curl -sS -X POST "$BASE/internal/v1/tools/gdrive_search_files" \
  -H 'Content-Type: application/json' \
  -H "X-Lucos-Org-Id: $ORG" \
  --data-binary '{"environment":"staging","args":{"user":"yogesh.kaurav@admedia.com","folder_id":"FOLDER_ID","limit":100}}'
```

Or `"folder_name":"My Project"`.

---

## 3. Recursive folder traversal

```bash
curl -sS -X POST "$BASE/internal/v1/tools/gdrive_search_files" \
  -H 'Content-Type: application/json' \
  -H "X-Lucos-Org-Id: $ORG" \
  --data-binary '{"environment":"staging","args":{"user":"yogesh.kaurav@admedia.com","folder_id":"FOLDER_ID","recursive":true,"max_depth":4,"max_total":200,"query":""}}'
```

---

## 4. Org-wide mime (ppt / video / exe / …)

```bash
curl -sS -X POST "$BASE/internal/v1/tools/gdrive_search_files" \
  -H 'Content-Type: application/json' \
  -H "X-Lucos-Org-Id: $ORG" \
  --data-binary '{"environment":"staging","args":{"mime_type":"presentation","limit":50}}'
```

Also: `video`, `image`, `audio`, `exe`, `pdf`, or raw MIME.

---

## 5. Owned by / last edited by

```bash
curl -sS -X POST "$BASE/internal/v1/tools/gdrive_search_files" \
  -H 'Content-Type: application/json' \
  -H "X-Lucos-Org-Id: $ORG" \
  --data-binary '{"environment":"staging","args":{"query":"owned by nathan","limit":25}}'

curl -sS -X POST "$BASE/internal/v1/tools/gdrive_search_files" \
  -H 'Content-Type: application/json' \
  -H "X-Lucos-Org-Id: $ORG" \
  --data-binary '{"environment":"staging","args":{"modified_by":"saiudayteja","limit":50}}'
```

---

## 6. Read document (cursors)

```bash
curl -sS -X POST "$BASE/internal/v1/tools/gdrive_read_file" \
  -H 'Content-Type: application/json' \
  -H "X-Lucos-Org-Id: $ORG" \
  --data-binary '{"environment":"staging","args":{"file_id":"FILE_ID","offset":0}}'
```

---

## 7. Query sheet (JSON rows)

```bash
curl -sS -X POST "$BASE/internal/v1/tools/gdrive_query_sheet" \
  -H 'Content-Type: application/json' \
  -H "X-Lucos-Org-Id: $ORG" \
  --data-binary '{"environment":"staging","args":{"file_id":"SHEET_ID","sheet_name":"Issues","limit":100}}'
```

---

## 8. Lookup owned file (owner index)

```bash
curl -sS -X POST "$BASE/internal/v1/tools/gdrive_lookup_owned_file" \
  -H 'Content-Type: application/json' \
  -H "X-Lucos-Org-Id: $ORG" \
  --data-binary '{"environment":"staging","args":{"query":"Adcenter Revamp","limit":25}}'
```

---

## 9. User overview / activity / duplicates

```bash
curl -sS -X POST "$BASE/internal/v1/tools/gdrive_user_drive_info" \
  -H 'Content-Type: application/json' \
  -H "X-Lucos-Org-Id: $ORG" \
  --data-binary '{"environment":"staging","args":{"user":"manikandan","sample_limit":8}}'

curl -sS -X POST "$BASE/internal/v1/tools/gdrive_list_recent_activity" \
  -H 'Content-Type: application/json' \
  -H "X-Lucos-Org-Id: $ORG" \
  --data-binary '{"environment":"staging","args":{"user":"manikandan","limit":25}}'

curl -sS -X POST "$BASE/internal/v1/tools/gdrive_find_duplicates" \
  -H 'Content-Type: application/json' \
  -H "X-Lucos-Org-Id: $ORG" \
  --data-binary '{"environment":"staging","args":{"user":"yogesh.kaurav@admedia.com","limit":300}}'
```

---

## 10. Date filters (created / modified after)

```bash
curl -sS -X POST "$BASE/internal/v1/tools/gdrive_search_files" \
  -H 'Content-Type: application/json' \
  -H "X-Lucos-Org-Id: $ORG" \
  --data-binary '{"environment":"staging","args":{"user":"yogesh.kaurav@admedia.com","modified_after":"2026-08-01","limit":25}}'
```

---

## 11. Permissions / revisions / comments

```bash
curl -sS -X POST "$BASE/internal/v1/tools/gdrive_list_permissions" \
  -H 'Content-Type: application/json' \
  -H "X-Lucos-Org-Id: $ORG" \
  --data-binary '{"environment":"staging","args":{"user":"yogesh.kaurav@admedia.com","file_id":"FILE_ID"}}'

curl -sS -X POST "$BASE/internal/v1/tools/gdrive_list_revisions" \
  -H 'Content-Type: application/json' \
  -H "X-Lucos-Org-Id: $ORG" \
  --data-binary '{"environment":"staging","args":{"user":"yogesh.kaurav@admedia.com","file_id":"FILE_ID"}}'

curl -sS -X POST "$BASE/internal/v1/tools/gdrive_list_comments" \
  -H 'Content-Type: application/json' \
  -H "X-Lucos-Org-Id: $ORG" \
  --data-binary '{"environment":"staging","args":{"user":"yogesh.kaurav@admedia.com","file_id":"FILE_ID"}}'
```

---

## Notes for ChatGPT

- Prefer `user=` / `as_user=` for another person’s Drive.
- Folder inventory: `folder_id` + `recursive=true`.
- Full read: follow `next_offset` (HelloMCP auto-paginates).
- Org-wide “all ppt/exe under Admedia Drive”: `mime_type` only (empty query).
- Always show Owners + Last edited by + Modified in listings.
- Summary under Summaries + transcript under Transcripts = paired (not misplaced).
- Activity: check `data_source` / `is_fallback` — fallback is modifiedTime, not views/opens.
- Restart HelloMCP after `.env` / tool changes.