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 Google Workspace through the built-in Google connector and its tool gateway > - Google's hosted Workspace MCP servers are a Developer Preview, so Paperclip launches on its own tools over Google's REST APIs (`server/src/google-workspace-rest-tools/`, added in #22000 with three Gmail tools) > - Calendar has nine allowlisted tools and none of them exist in the REST tool set yet > - The tools must keep Google's MCP names, inputs and results, so Paperclip can switch back to Google's servers later > - This pull request adds the nine Calendar tools, and the HTTP support they need, inside the isolated folder > - The benefit is that agents can read and change calendars with exactly the scopes the allowlist grants ## Linked Issues or Issue Description Refs #22000 **Feature description** Add the nine Calendar tools that `toolScopes.calendar` allows to the REST-backed Google Workspace tool set: `list_calendars`, `get_event`, `list_events`, `search_events`, `suggest_time`, `create_event`, `update_event`, `delete_event` and `respond_to_event`. **Problem it solves** The REST tool set has only Gmail tools. A Calendar grant has no tools when the connector runs on REST. **Proposed solution** One file per tool under `calendar/`, with pure argument-to-request and response-to-result functions. Names, fields and annotations come from Google's Calendar MCP reference. Each tool uses only the scopes its allowlist entry permits. The README lists the endpoint and scope for each tool, the time rules, the notification defaults, the `suggest_time` algorithm, and every difference from Google's tools. ## What Changed - `calendar/`: nine tools, shared event mapping (`event.ts`), input building (`event-input.ts`), JSON schemas, synthetic fixtures, and `probeCalendar()` (one `calendarList.list` with `maxResults=1`) for a health check. - `calendar/time.ts`: time zone arithmetic with `Intl` only. It reads offset-less times in a given IANA zone, handles DST gaps and repeated hours (Temporal `compatible` rule), and never guesses a zone. - `google-http.ts`: adds `www.googleapis.com` to the allowed hosts, but only under `/calendar/v3/` (checked after URL normalization). Adds PATCH, PUT and DELETE. All are writes: never retried, and failures after dispatch carry the uncertain-outcome warning. A POST marked `readOnly` (free/busy) is a read. Adds `If-Match`. Maps 412 to "nothing was changed" and 410 to not found. - `tools.ts`: registers the `calendar` service. - `allowlist.test.ts`: asserts Calendar is fully implemented (9 of 9). - `README.md`: Calendar section (endpoints and scopes, time handling, notifications, `suggest_time`, differences) and two open questions. ## Verification - `cd server && npx vitest run src/google-workspace-rest-tools`: 19 files, 330 tests pass. Of these, about 210 are new Calendar tests in 11 files, plus new `google-http` tests for PATCH, PUT, DELETE, read-only POST, `If-Match`, 410, 412 and the path restriction, and the 9-of-9 allowlist assertion. Table-driven tests cover all-day versus timed events, IANA zones with 30-minute and half-hour offsets, DST gaps and repeated hours in New York, London and Lord Howe, recurring series and single occurrences, pagination (including `startTimeDesc` paging), free/busy fallback, notification mapping, and write failures (no retry, uncertain-outcome warning). All fixtures are synthetic; no network. - `cd server && npx tsc --noEmit -p .`: passes. - `pnpm verify`: exit 2 (the README is a broad input), so required CI supplies broad coverage. ## Risks - Low risk. Nothing outside the folder imports it yet, so no runtime path changes until the gateway wiring lands. - Write tools follow Google's documented notification defaults: `create_event`, `update_event` and `delete_event` email all attendees by default; `respond_to_event` emails external attendees by default. Tool descriptions say this, and `NONE` sends nothing. - `freeBusy.query` does not accept `calendar.events`. A read and write grant has no free/busy scope, so `suggest_time` falls back to reading each attendee's calendar. That fallback cannot see coworkers who share only free/busy. The README proposes adding `calendar.events.freebusy` to the `calendar.write` profile. - `delete_event` refuses a whole recurring series on purpose: it deletes single events and single occurrences only, and sends no delete for a series ID. This differs from REST and from Google's tool. `update_event` and `respond_to_event` on a series ID change the whole series; their descriptions say so, and the result shows series (`recurrence`) or occurrence (`recurringEventId`). - `list_events` page tokens carry the first page's time range, so later pages stay consistent. > For core feature work, check [`ROADMAP.md`](ROADMAP.md) first and discuss it in `#dev` before opening the PR. Feature PRs that overlap with planned core work may need to be redirected — check the roadmap first. See `CONTRIBUTING.md`. ## Model Used - Claude Opus 5.5 (`claude-opus-5-5`), Anthropic, 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 - [ ] 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>