Files
PaperClipAI/server
DottaandClaude Opus 5.5 a29658b5b7 feat(google-workspace): REST-backed Gmail tools in server/src/google-workspace-rest-tools (#22000)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work
> - Agents use Google Workspace through the built-in Google Workspace
connector
> - Today the connector sends each tool call to Google's hosted
Workspace MCP servers
> - Those servers are a Developer Preview, so we cannot offer them to
the public
> - The owner decided to launch on our own tools over Google's GA REST
APIs, with the same tool names, inputs and results, in one folder that
we can delete later
> - This pull request adds that folder inside the server, with its first
three Gmail tools, and a written trace of where it will plug in
> - The benefit is a public-ready Gmail path that we can switch back to
Google's MCP servers with one setting, with no new package to publish

## Linked Issues or Issue Description

Refs #21996 (plan and working memory for the Google Workspace connector,
section 9)
Refs #15412 (an earlier community Gmail REST MCP server; this code
follows Google's MCP tool contract instead)

**Subsystem affected**
Connections: the Google Workspace connector and the tool gateway.

**Problem or motivation**
Google's Workspace MCP servers are a Developer Preview. We cannot launch
the Google Workspace connector to the public on them.

**Proposed solution**
Add `server/src/google-workspace-rest-tools/`. It exposes the same tools
as Google's MCP servers over the GA REST APIs. It knows nothing about
Paperclip. A later pull request selects it per service with one switch.

**Alternatives considered**
A separate npm package (it would have to be published, because the
server is published) and a loopback or hosted HTTP MCP endpoint. The
README explains why an in-process call is better: speed, token handling,
and the egress guard, which refuses loopback addresses on public
deployments.

## What Changed

- New folder `server/src/google-workspace-rest-tools/` inside the
existing server package. No new npm package, no new dependency, no
workspace, Docker, lockfile or release change. Every changed file is in
this folder.
- `index.ts` is the only entry point. `boundary.test.ts` enforces that
the folder imports only its own files, Node built-ins,
`@modelcontextprotocol/sdk` and `zod` (both existing server
dependencies; tests may also import `vitest` and `@paperclipai/shared`),
and that no other server code imports the folder yet.
- `google-http.ts` is the only code that calls `googleapis.com`. It sets
the bearer header, allows only listed hosts, has a 20 s deadline and a
20 MB response limit, and retries a read once. It never retries a write.
Every write that fails after it is sent says that the change may or may
not have been made.
- Token errors are thrown as `GoogleWorkspaceAuthError` (an `McpError`).
401 gives `unauthenticated`. 403 insufficient scope gives
`insufficient_scope`, the code the gateway already recognizes. Other
Google errors become tool error results.
- Gmail tools `get_message`, `search_threads` and `create_draft`. Names,
fields, types and enums follow Google's Gmail MCP reference.
`create_draft` calls only `drafts.create`. There is no send tool.
- `get_message` reads bodies that Gmail stores as attachments, and
returns an explicit error, never a body-less `FULL_CONTENT` result.
Address lists are parsed by a single-pass RFC 5322 tokenizer
(`gmail/address.ts`, table-driven tests including IPv6 domain literals
and malformed input); quoted search text and long draft headers are
handled.
- `server.ts`: a thin MCP server (`tools/list`, `tools/call`).
`callGoogleWorkspaceRestTool()` is the in-process equivalent.
- `allowlist.test.ts` fails if a tool is not in `toolScopes` in
`packages/shared/src/google-workspace-connectors.ts`, if its read-only
hint disagrees with the allowlist, or if a description names a tool the
folder does not list.
- `README.md`: purpose, boundary rules, the dispatch trace, the
recommended in-process seam and the files the switch PR touches, known
differences from Google's tools, and the removal procedure (delete the
folder, set the switch to `google_mcp`).
- No code comments. Explanations are in the README.

## Verification

- `cd server && npx vitest run src/google-workspace-rest-tools`: 8
files, 98 tests pass. Tests use synthetic REST fixtures and a fake
fetch. No network.
- Each review fix has a test that fails on the revision before it (10
tests red on `d65b51d245`, 3 more red on `5d7d52ec86`). The boundary
test fails when a probe file in the folder imports `../errors.js`.
- `tsc --noEmit` with the server's `tsconfig.json` settings over the
folder passes.
- `pnpm check:module-boundaries` passes.
- `pnpm verify` exits 2 because a new file under `server/src` is a broad
input. Required CI supplies the broad coverage.
- Local timing probe with a stubbed fetch: about 13 µs overhead per
call.

## Risks

- Low risk. Nothing imports the folder yet, so runtime behavior does not
change.
- The tool descriptions are our own wording. A contract test against a
recorded `tools/list` from Google's servers comes in a later pull
request.
- The allowlist names three Gmail tools (`get_draft`, `list_threads`,
`search_messages`) that Google's published Gmail MCP reference does not
list. The README flags this.

## Model Used

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

## 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
- [x] All Paperclip CI gates are green
- [x] 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 08:13:01 -06:00
..