Files
PaperClipAI/server
DottaandClaude Opus 5.5 ceaf574421 feat(google-workspace): REST-backed Drive tools in server/src/google-workspace-rest-tools (#22028)
## 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>
2026-11-17 12:06:00 -06:00
..