mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-11-18 06:01:49 +01:00
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work > - Agents use Google Workspace through the tool gateway, and Paperclip is replacing Google's preview MCP servers with its own tools over Google's REST APIs (`server/src/google-workspace-rest-tools/`) > - Gmail and Calendar are done there. Drive has no REST tools yet, so Drive cannot switch to the REST transport > - Drive is the hard service: file content must be exported or downloaded, kept under a size cap, and never sent to another host; search needs a safe query; writes run under the narrow `drive.file` scope > - This pull request adds the eight allowlisted Drive tools, with the same names, inputs and result shapes as Google's Drive MCP tools > - The benefit is that Drive can switch to `paperclip_rest` once the switch is approved, with no broader scope and no new dependency ## Linked Issues or Issue Description Refs #22000, #22014, #22016, #22017 (earlier parts of the same REST tool set). Related open PRs in the same folder: #22027 (Sheets). **What problem does this solve?** The REST tool set has no Drive tools. `googleWorkspaceRestTransportGaps()` blocks a Drive switch while any allowlisted Drive tool is missing. **Proposed solution** Add `drive/` with the eight tools on the allowlist (`toolScopes.drive`), a Drive probe, and the Drive paths in `google-http.ts`. **Alternatives considered** Converting PDFs and Office files to Google Docs to extract text. That is a write, so the read tool does not do it. ## What Changed - `drive/`: `search_files`, `list_recent_files`, `get_file_metadata`, `get_file_permissions`, `read_file_content`, `download_file_content` (reads, `drive.readonly`), `create_file`, `copy_file` (writes, `drive.file`). One file per tool, pure request and result functions, table-driven tests with synthetic fixtures. - `drive/query.ts`: parses Google's MCP search syntax into a tree, checks terms and operators, and writes a new Drive `q` string with every value re-escaped. Adds `trashed = false` unless the query uses `trashed`. Unsupported terms are errors, not ignored. - Content: Google Docs are exported as Markdown (read) or plain text (download), Sheets as CSV of the first sheet (the read text says so), Slides as plain text. Binary files are downloaded and base64 encoded. Every Drive read result is bounded after serialization to 250,000 bytes (the payload is carried twice, in text and structured content); a larger result is an error that says how to read less, never cut-short content. `exportMimeType` must be a format Google lists for the file type, and every request uses the caller's `fileId`. `create_file` and `copy_file` are annotated as non-idempotent writes; an annotations test checks all eight tools. - `google-http.ts`: per-host path prefix lists, required for every host (`www.googleapis.com` → `/calendar/v3/`, `/drive/v3/`, `/upload/drive/v3/`; `sheets.googleapis.com` → `/v4/spreadsheets/`; `gmail.googleapis.com` → `/gmail/v1/users/me/`, which had no prefix before, so any path was accepted on that host); a bounded `download()` for raw bytes; raw upload bodies for multipart uploads; `redirect: "manual"` with any 3xx turned into a tool error; Drive error reasons `exportSizeLimitExceeded` and `appNotAuthorizedToFile` mapped to clear messages. - `google-http.test.ts`: the host and path allowlist test is now one table with Sheets rows (allows `/v4/spreadsheets/{id}` and `/v4/spreadsheets/{id}:batchUpdate`; rejects `/v4/spreadsheets`, `/v4/other`, `/v4/spreadsheets/../other`, and the Sheets path on `www.googleapis.com`) and a structural check that every host in `GOOGLE_API_HOSTS` has at least one allowed and one rejected row. - `errors.ts`: new `too_large` kind. `probe.ts`: Drive probe (`about.get`, `fields=kind`), allowed by `drive.readonly` or `drive.file`. - `allowlist.test.ts`: Drive 8 of 8; only `create_file` and `copy_file` write; no update, delete, trash, move or share tool. - README: Drive section with an endpoint-and-scope table (one Google reference URL per row), content formats, size caps, requests per call, and differences from Google's tools. - Outside the folder, one line: `server/src/services/google-workspace-rest-dispatch.test.ts` used `drive` as its example of an unimplemented service. It now uses `chat`. After merging master (#22026), this file and `google-workspace-rest-transport.test.ts` pass with Drive added; no other change was needed. ## Verification - `cd server && npx vitest run src/google-workspace-rest-tools`: 46 files with the dispatch and transport tests (after merging master with Sheets), 992 tests pass. - `cd server && npx tsc --noEmit -p .`: no errors in the folder. - `pnpm verify`: exit 2 (README is a broad input); required CI supplies the broad checks. - Not run: live calls to Google. All tests use synthetic responses. ## Risks - `copy_file` under `drive.file`: Google does not document whether a token with `drive.readonly` + `drive.file` can copy a file the app never created or opened. If not, the tool returns a clear error and nothing is copied. A live check on the test account is needed before the switch. - `google-http.ts` now uses `redirect: "manual"` for every request. A redirect from Gmail or Calendar was a retried network error before and is now a clear tool error. Google's APIs do not redirect these calls. - Drive stays on `google_mcp`; nothing calls these tools until the switch is flipped. ## Model Used - Claude Opus 5.5 (`claude-opus-5-5`), Anthropic, via Claude Code with tool use (shell, file edits, web fetch of Google's public docs). ## Checklist - [x] I have included a thinking path that traces from project context to this change - [x] I have specified the model used (with version and capability details) - [x] I have checked ROADMAP.md and confirmed this PR does not duplicate planned core work - [x] I have searched GitHub for duplicate or related PRs and linked them above - [x] I have either (a) linked existing issues with `Fixes: #` / `Closes #` / `Refs #` OR (b) described the issue in-PR following the relevant issue template - [x] I have not referenced internal/instance-local Paperclip issues or links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip` URLs) - [x] My branch name describes the change (e.g. `docs/...`, `fix/...`) and contains no internal Paperclip ticket id or instance-derived details - [x] I have run tests locally and they pass - [x] I have added or updated tests where applicable - [x] I have updated relevant documentation to reflect my changes - [x] I have considered and documented any risks above - [ ] All Paperclip CI gates are green - [ ] Greptile is 5/5 with no open P2s, recommendations, or follow-ups - [x] I will address all Greptile and reviewer comments before requesting merge 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>