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