Files
PaperClipAI/server
DottaandClaude Opus 5.5 c366a606b1 feat(google-workspace): REST-backed Sheets tools in server/src/google-workspace-rest-tools (#22027)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work
> - Agents reach Google Workspace through the built-in Google connector
and its tool gateway
> - Google's hosted Workspace MCP servers are a Developer Preview, so
Paperclip will launch on its own tools over Google's REST APIs
(`server/src/google-workspace-rest-tools/`)
> - Gmail and Calendar are there; Sheets has no REST tools yet, so a
Sheets grant has no tools when the connector runs on REST
> - This pull request adds the six Sheets tools that `toolScopes.sheets`
allows, with the same names, inputs and result shapes as Google's Sheets
MCP tools
> - The benefit is that Sheets can switch to `paperclip_rest`, and later
back to Google's MCP servers, without a rewrite

## Linked Issues or Issue Description

Refs #22000
Refs #22017

**Subsystem affected**
Google Workspace REST tool set,
`server/src/google-workspace-rest-tools/`.

**Problem or motivation**
The REST tool set has no Sheets tools. Agents with a Sheets grant cannot
read or write spreadsheets when the connector runs on REST.

**Proposed solution**
One file per tool under `sheets/`, with pure argument-to-request and
response-to-result functions. Names, fields and annotations come from
Google's Sheets MCP reference
(https://developers.google.com/workspace/sheets/api/reference/mcp). Each
tool uses only the scopes its allowlist entry permits. The README lists
the endpoint, scope and Google documentation URL for each tool, the
value handling, the bounds, and every difference from Google's tools.

**Alternatives considered**
Reuse `packages/google-sheets-mcp-server`. It has its own tool names and
shapes, and the folder's boundary test forbids the import.

## What Changed

- `sheets/get-values.ts`: `get_values` over `spreadsheets.values.get`,
formatted values, rows first (the REST defaults, sent explicitly).
Google's answer is returned unchanged (`range`, `values`).
- `sheets/get-spreadsheet.ts`: `get_spreadsheet` over `spreadsheets.get`
with `includeGridData`, `ranges` and `fields`. `commentsIncluded: true`
is refused because REST cannot return comments.
- `sheets/update-values.ts` and `sheets/update-formulas.ts`:
`spreadsheets.values.update` with `valueInputOption` `RAW` and
`USER_ENTERED`. Each description names its option.
- `sheets/insert-dimension.ts`: one `insertDimension` request through
`spreadsheets.batchUpdate`.
- `sheets/update-spreadsheet.ts`: `spreadsheets.batchUpdate` with the 64
request types Google documents that REST supports. Comment and data
source requests, unknown request types and `writeControl` are refused
before sending. The tool is marked `destructiveHint: true` because
Google's list includes `deleteSheet`, `deleteDimension`, `deleteRange`
and other removing operations.
- `sheets/range.ts`: A1 and R1C1 range validation, sheet-name quoting,
and range descriptions for write results.
- Bounds: at most 50,000 cells read or written per call and 450,000
characters per read result (under the gateway's 1 MB limit). Over a
limit, the tool returns an error that asks for a narrower range. It
never returns a cut-off result.
- Write results: Google's REST response under `content`, plus a `status`
sentence that names the changed ranges and the number of cells.
- `google-http.ts`: allows `sheets.googleapis.com` only under
`/v4/spreadsheets/`.
- `probe.ts`: Sheets has no probe, because every Sheets read needs a
spreadsheet ID.
- `tools.ts`, `allowlist.test.ts`, `README.md`: register the service,
check Sheets 6 of 6, and document the tools.

## Verification

- `cd server && npx vitest run src/google-workspace-rest-tools`: 34
files, 647 tests pass. The Sheets tests use synthetic fixtures and a
fake fetch. There is no network and no real spreadsheet.
- Table-driven tests cover ranges (accepted and refused, quoting round
trips), request building for each tool, result shapes, cell and size
bounds, the uncertain-outcome warning on failed writes without a retry,
the host path restriction, the absent probe, and each tool's scopes.
- `npx tsc --noEmit -p server`: no errors in
`server/src/google-workspace-rest-tools/`. Other errors in this local
run come from workspace packages that were not built.
- `pnpm verify`: exit 2 (the README is a broad input). Required CI
supplies the broad coverage.

## Risks

- Low risk. Nothing calls these tools until Sheets is set to
`paperclip_rest` in `GOOGLE_WORKSPACE_TOOL_TRANSPORT`. That setting
stays `google_mcp`.
- Google's reference does not name the value input option of
`update_values` or the render option of `get_values`. This PR uses `RAW`
and formatted values. A recorded comparison on Google's servers can
confirm both. The README lists this.
- `update_spreadsheet` accepts the removing operations that Google
documents, such as `deleteSheet`. Approval and audit stay with the
gateway.

## Model Used

- Claude Opus 5.5 (`claude-opus-5-5`), Anthropic, through Claude Code
with tool use (shell, file edits, web fetch).

## 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 10:59:22 -06:00
..