Files
PaperClipAI/server
DottaandClaude Opus 5.5 c41ca4a992 feat(google-workspace): REST-backed Calendar tools in server/src/google-workspace-rest-tools (#22017)
## 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>
2026-11-17 15:01:29 +00:00
..