Files
PaperClipAI/server/src
DottaandClaude Opus 5.5 1d3b4201e3 feat(google-workspace): remaining Gmail read tools in the REST tool set (#22014)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work
> - Agents use Gmail through the built-in Google Workspace connector
> - Google's hosted Gmail MCP server is a Developer Preview, so
Paperclip launches on its own REST-backed tool set in
`server/src/google-workspace-rest-tools/` (#22000)
> - That folder has 3 of the 9 Gmail tools on the reviewed allowlist
(`toolScopes.gmail`)
> - Agents cannot read a whole thread, list drafts, list labels or
search single messages
> - This pull request adds the 6 missing read tools, with the same
names, inputs and results as Google's MCP tools where Google documents
them
> - The benefit is that Gmail is complete on the REST transport, and a
message looks the same from every tool

## Linked Issues or Issue Description

Refs #22000

**Problem**
The REST-backed Gmail tool set implements only `get_message`,
`search_threads` and `create_draft`. The allowlist also names
`get_thread`, `get_draft`, `list_drafts`, `list_labels`, `list_threads`
and `search_messages`.

**Proposed solution**
Implement the 6 read tools in the folder. Follow the existing patterns:
one file per tool, pure request and result functions, synthetic unit
tests.

**Why it matters**
Google's reviewers compare an email in Paperclip with the same email in
Gmail. Full threads and drafts must show complete bodies.

## What Changed

- Add `get_thread`, `list_drafts` and `list_labels`. Their schemas come
from Google's Gmail MCP reference.
- Add `get_draft`, `list_threads` and `search_messages`. Google's
reference does not list them, so their schemas copy the sibling tools.
The README lists them under "Not verified against Google's servers".
- Move separately stored body reads from `get_message` into
`readMessageBodies` in `gmail/message.ts`. All tools that return bodies
use it. A body that cannot be read fails the call with "Could not read
the full body of this message".
- Add `gmail/parallel.ts`: a 10-at-a-time read pool that stops after the
first failure, and a helper that skips items deleted between list and
get.
- Cap page sizes (50 for threads, messages and drafts; 500 for labels,
which Gmail returns in one request). The README has a table of Google
requests per call at the maximum page size.
- Update descriptions: `search_threads` now points to `get_thread` and
`list_labels`. The `label:` search operator takes label names (spaces as
hyphens), not IDs. This corrects the wording in the original tools.
Google's MCP reference says IDs; the README records the difference, and
a test prevents drift.
- Cap separately stored body reads at 20 per call. The README lists
requests and quota units per call at the maximum page size.
- `allowlist.test.ts` now asserts that Gmail implements all 9
allowlisted tools and that only `create_draft` writes.

## Verification

- `cd server && npx vitest run src/google-workspace-rest-tools`: 15
files, 156 tests pass. Tests use synthetic fixtures and a fake `fetch`
only.
- `cd server && npx tsc --noEmit -p .`: passes.
- `pnpm verify`: exit 2 (the README is a broad input). Required CI
supplies the broad coverage.
- Tests prove: each tool maps messages exactly as `get_message` does;
separately stored bodies are fetched; a failed body read is an explicit
error; request counts at the maximum page size (51); invalid IDs send no
request; caller cancellation stops the call.

## Risks

- Low risk. Nothing outside the folder imports it yet
(`boundary.test.ts`).
- `get_draft`, `list_threads` and `search_messages` have no Google
schema. A switch back to Google's MCP servers would drop them unless
Google adds them.
- `list_labels` leaves out `threadsTotal` and `threadsUnread`: REST
returns them only with one request per label.
- One call reads at most 20 separately stored bodies. Beyond that it
returns an explicit "Could not read the full body of every message"
error and fetches none. The worst single call is 71 requests and 3,405
Gmail quota units (per-user limit: 6,000 per minute). A second maximal
call in the same minute can get a `rate_limited` tool error.

## Model Used

- Claude Opus 5.5 (`claude-opus-5-5`), Anthropic, via Claude Code with
tool use (file edits, shell, web fetch of Google's public reference).

## 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 09:51:17 -06:00
..
…
…
…
…
…