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 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>