From a29658b5b717a5f2dbc807a070f146776af17866 Mon Sep 17 00:00:00 2001 From: Dotta <34892728+cryppadotta@users.noreply.github.com> Date: Tue, 17 Nov 2026 08:13:01 -0600 Subject: [PATCH] feat(google-workspace): REST-backed Gmail tools in server/src/google-workspace-rest-tools (#22000) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## 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 --- .../src/google-workspace-rest-tools/README.md | 278 ++++++++++++++++++ .../allowlist.test.ts | 45 +++ .../boundary.test.ts | 57 ++++ .../src/google-workspace-rest-tools/errors.ts | 49 +++ .../fixtures/fake-google.ts | 29 ++ .../gmail/address.test.ts | 60 ++++ .../gmail/address.ts | 138 +++++++++ .../gmail/create-draft.test.ts | 150 ++++++++++ .../gmail/create-draft.ts | 165 +++++++++++ .../gmail/fixtures/gmail-rest.ts | 95 ++++++ .../gmail/get-message.test.ts | 147 +++++++++ .../gmail/get-message.ts | 93 ++++++ .../gmail/index.ts | 6 + .../gmail/message.ts | 163 ++++++++++ .../google-workspace-rest-tools/gmail/mime.ts | 96 ++++++ .../gmail/schemas.ts | 28 ++ .../gmail/search-threads.test.ts | 95 ++++++ .../gmail/search-threads.ts | 155 ++++++++++ .../google-http.test.ts | 208 +++++++++++++ .../google-http.ts | 229 +++++++++++++++ .../src/google-workspace-rest-tools/index.ts | 11 + .../server.test.ts | 65 ++++ .../src/google-workspace-rest-tools/server.ts | 32 ++ .../src/google-workspace-rest-tools/tool.ts | 46 +++ .../src/google-workspace-rest-tools/tools.ts | 39 +++ 25 files changed, 2479 insertions(+) create mode 100644 server/src/google-workspace-rest-tools/README.md create mode 100644 server/src/google-workspace-rest-tools/allowlist.test.ts create mode 100644 server/src/google-workspace-rest-tools/boundary.test.ts create mode 100644 server/src/google-workspace-rest-tools/errors.ts create mode 100644 server/src/google-workspace-rest-tools/fixtures/fake-google.ts create mode 100644 server/src/google-workspace-rest-tools/gmail/address.test.ts create mode 100644 server/src/google-workspace-rest-tools/gmail/address.ts create mode 100644 server/src/google-workspace-rest-tools/gmail/create-draft.test.ts create mode 100644 server/src/google-workspace-rest-tools/gmail/create-draft.ts create mode 100644 server/src/google-workspace-rest-tools/gmail/fixtures/gmail-rest.ts create mode 100644 server/src/google-workspace-rest-tools/gmail/get-message.test.ts create mode 100644 server/src/google-workspace-rest-tools/gmail/get-message.ts create mode 100644 server/src/google-workspace-rest-tools/gmail/index.ts create mode 100644 server/src/google-workspace-rest-tools/gmail/message.ts create mode 100644 server/src/google-workspace-rest-tools/gmail/mime.ts create mode 100644 server/src/google-workspace-rest-tools/gmail/schemas.ts create mode 100644 server/src/google-workspace-rest-tools/gmail/search-threads.test.ts create mode 100644 server/src/google-workspace-rest-tools/gmail/search-threads.ts create mode 100644 server/src/google-workspace-rest-tools/google-http.test.ts create mode 100644 server/src/google-workspace-rest-tools/google-http.ts create mode 100644 server/src/google-workspace-rest-tools/index.ts create mode 100644 server/src/google-workspace-rest-tools/server.test.ts create mode 100644 server/src/google-workspace-rest-tools/server.ts create mode 100644 server/src/google-workspace-rest-tools/tool.ts create mode 100644 server/src/google-workspace-rest-tools/tools.ts diff --git a/server/src/google-workspace-rest-tools/README.md b/server/src/google-workspace-rest-tools/README.md new file mode 100644 index 00000000000..b874f46c499 --- /dev/null +++ b/server/src/google-workspace-rest-tools/README.md @@ -0,0 +1,278 @@ +# Google Workspace REST tools + +Paperclip's own implementation of the tools that Google's hosted Workspace MCP +servers expose (for example `https://gmailmcp.googleapis.com/mcp/v1`), backed +by Google's generally available REST APIs. + +It lives in this one folder, `server/src/google-workspace-rest-tools/`, inside +the server package. It is not a separate npm package, so nothing new is +published. + +This release has three Gmail tools: `get_message`, `search_threads` and +`create_draft`. There is no send tool, and none may be added. + +## Why this exists, and why it is temporary + +Google's Workspace MCP servers are a Developer Preview and cannot be offered to +the public. On 2026-11-17 the owner decided that Paperclip will launch on its +own tools over the REST APIs. The tools are built so Paperclip can switch to +Google's MCP servers later without a rewrite, and they live in this one folder +so they can be deleted cleanly when that happens. + +## Boundary rules + +- **One entry point.** Other server code may import only `index.ts`. +- **Isolated imports, enforced by `boundary.test.ts`.** Source files import + only files in this folder, Node built-ins, `@modelcontextprotocol/sdk` and + `zod` (both existing server dependencies). Test files and `fixtures/` may + also import `vitest` and `@paperclipai/shared`. Nothing in this folder + imports other server code. In this release nothing else in the server + imports this folder; the test also checks that, and the switch PR relaxes + that one check. +- **Same tools as Google's MCP servers.** Same tool names, same input fields, + same result shape. Names, field names, types and enums come from Google's + published reference (Gmail: + , recorded + 2026-11-17). Where REST cannot match, the difference is listed below. +- **Public surface is MCP only.** `index.ts` exports tool definitions (`Tool`), + results (`CallToolResult`), an MCP server, and the MCP error thrown for token + problems. No Google REST type is exported. +- **Knows nothing about Paperclip.** No company, connection, grant, policy, + audit, approval or screening code. Input is a service, a tool name, + arguments and an access token. Output is an MCP result. Authorization, scope + checks, approval, audit and injection screening stay with their current + owners in the gateway. +- **Stores nothing.** No tokens, no content, no cache. The access token is used + for one call and dropped. +- **One file calls Google.** `google-http.ts` is the only place that calls + `googleapis.com`. It sets the bearer header, allows only listed hosts, + bounds each request (20 s deadline, 20 MB response, including the body + read), maps Google errors, and retries a read (GET) once after a network + error or HTTP 502/503/504. **It never retries a write.** A write that fails + after it was sent (network error, dropped connection, timeout, caller + cancellation, HTTP 5xx, or a success answer that is too large or not JSON) + says that the change may or may not have been made. +- **One tool, one file.** Each tool in `gmail/` is a set of pure functions + (arguments to REST request, REST response to MCP result) plus a short `run` + that sequences them. The pure functions are unit tested without network. +- **`server.ts` is thin MCP wiring:** `tools/list` and `tools/call`. +- **The allowlist stays where it is.** `toolScopes` in + `packages/shared/src/google-workspace-connectors.ts` is the single list of + allowed Google tools. `allowlist.test.ts` fails if this folder implements a + tool that is not on it, if a tool's read-only hint disagrees with the + allowlist's write flag, or if a description names a tool this folder does + not list. + +### Errors + +| Google answer | Result | +| --- | --- | +| 401 | Throws `GoogleWorkspaceAuthError` (`reason: "unauthenticated"`, JSON-RPC `data: { code: "unauthenticated", httpStatus: 401 }`) | +| 403 with insufficient scope (`ACCESS_TOKEN_SCOPE_INSUFFICIENT`, `insufficientPermissions`, or `WWW-Authenticate: error="insufficient_scope"`) | Throws `GoogleWorkspaceAuthError` (`reason: "insufficient_scope"`, `data.code: "insufficient_scope"`, the value the gateway already recognizes) | +| 403 API not enabled (`SERVICE_DISABLED`, `accessNotConfigured`) | Tool error result, without the project number | +| Other 403, 404, 400, 429, 5xx, timeout, network failure | Tool error result (`isError: true`) with a short message | +| Invalid arguments | Tool error result, no request sent | +| Unknown tool | Throws `McpError` `InvalidParams` | + +Token problems are thrown, not returned, so a caller can refresh the token or +ask the user to reconnect exactly as it does for Google's MCP servers. + +## How it plugs in (seam trace) + +Traced on `origin/master` at `ca34aca777`. + +### Today's dispatch path + +1. **Tool name to target.** `googleWorkspaceToolTarget(name)` in + `packages/shared/src/google-workspace-connectors.ts` turns `gmail__get_message` + into `{ service, upstreamName, leaf, serverUrl, appSlug, requiredScopes, write }`. + `serverUrl` comes from the closed `SERVICE_PROFILES` registry. +2. **Discovery (`tools/list`).** `remoteTools()` in + `server/src/services/tool-access/catalog/discovery.ts` (Google branch near + line 130) lists each granted service by calling itself with + `profile.serverUrl`, prefixes names with `googleWorkspaceToolName(service, …)`, + and filters by the granted scopes. It speaks MCP over HTTP through + `requestRemoteHttpEndpoint`, negotiating a protocol era per endpoint + (`mcpEraKey`, saved on the connection by `saveMcpNegotiation` in + `server/src/services/tool-access/mcp-protocol-config.ts`). +3. **Call (`tools/call`).** `executeRemoteHttpTool()` in + `server/src/services/tool-gateway.ts` (near line 7784) computes + `workspaceTarget`, refuses a tool whose scopes are not granted + (`oauth_insufficient_scope`), sets `endpoint = workspaceTarget.serverUrl`, + builds headers with the user's `Authorization: Bearer ` from + `resolveCredentialHeaders`, rechecks the grant before every dispatch, and + posts JSON-RPC through `guardedRemoteHttpFetch` + (`server/src/services/remote-http-fetch.ts`, behind + `server/src/services/tool-access/remote-http.ts`). A 401 forces a token + refresh and asks for an explicit retry; `isInsufficientConnectionScope` + (`server/src/services/connection-permission-errors.ts`) maps a scope + failure. The MCP result goes through `completeRemoteMcpCall` → + `normalizeMcpToolResult`. Prompt-injection screening, audit and invocation + records happen in the caller of `executeRemoteHttpTool`, so they apply to any + result it returns. +4. **MCP Tasks.** The background task path (near line 7578) also reads + `workspaceTarget.serverUrl`. It only runs for calls a remote server turned + into a task; REST calls never do. + +The gateway speaks MCP `2026-07-28` (stateless) first, then the legacy +handshake versions `2025-11-25`, `2025-06-18`, `2025-03-26` and `2024-11-05` +(`server/src/services/mcp-http.ts`). The MCP SDK the server uses (1.31) speaks +the legacy versions only, so over HTTP every new session would pay a failed +modern probe plus an `initialize` round trip. + +### Recommendation: call it in process + +The code already runs in the server process, so the gateway calls +`callGoogleWorkspaceRestTool()` and `listGoogleWorkspaceRestTools()` directly, +the way it already runs other REST-backed tool sets (`restConnectorFor` in +`server/src/services/connectors/rest-registry.ts` and +`nativeProviderCatalogFor` in `server/src/services/native-provider-catalogs.ts`). +No loopback or hosted MCP endpoint. + +- **Speed.** Measured locally: about 13 µs of overhead per call with a stubbed + fetch. The MCP SDK and zod are already loaded by the server, so there is no + extra cold-start cost beyond this folder's own modules. An HTTP hop would + add a connection, JSON-RPC framing, and the protocol probe and handshake + above to every call. `tools/list` becomes a static list: no network, no token. +- **Token handling.** The token stays in the server process and goes only to + Google. +- **Self-hosted and Cloud run the same code.** Nothing to deploy, configure or + publish. A loopback endpoint would not work on authenticated public + deployments: `allowPrivateRemoteEndpoints()` refuses loopback addresses there. +- **Egress stays guarded.** The gateway passes its `guardedRemoteHttpFetch` as + the `fetch` option, so calls to Google go through the same egress policy as + today. +- **Swap-back is unchanged.** Tool names, inputs and results are Google's, so + the catalog, policies, approvals and audit records written under + `paperclip_rest` stay valid under `google_mcp`. + +`createGoogleWorkspaceRestServer()` (a standard MCP server that reads the token +from the transport's auth info) stays available if an HTTP or stdio +deployment is ever needed; the in-process path does not use it. + +### The switch (follow-up PR, not this one) + +One per-service setting in `packages/shared/src/google-workspace-connectors.ts`: + +```ts +export const GOOGLE_WORKSPACE_TOOL_TRANSPORT: Record = { + gmail: "paperclip_rest", drive: "google_mcp", /* … */ +}; +``` + +`googleWorkspaceToolTarget()` returns it as `transport`. Files the follow-up +touches: + +- `packages/shared/src/google-workspace-connectors.ts`: the setting above, and + `transport` on the target. +- One new server adapter outside this folder, for example + `server/src/services/google-workspace-rest-dispatch.ts`, the only importer of + `server/src/google-workspace-rest-tools/index.ts`. It strips `Bearer ` from + the resolved `Authorization` header, passes the guarded fetch and the call's + deadline signal, and maps `GoogleWorkspaceAuthError` to the gateway's existing + outcomes (`unauthenticated` to the forced refresh plus + `oauth_refreshed_retry_required`; `insufficient_scope` to + `oauth_insufficient_scope`). +- `server/src/services/tool-gateway.ts`, `executeRemoteHttpTool`: after the + grant checks and before `endpoint` is chosen, when + `workspaceTarget.transport === "paperclip_rest"`, recheck the grant (as + `dispatchRemote` does), call the adapter, and return through + `normalizeMcpToolResult(result, "mcp_http", false, sourceTemplateKey)`. +- `server/src/services/tool-access/catalog/discovery.ts`, the Google branch of + `remoteTools`: for a `paperclip_rest` service, use the adapter's static tool + list instead of an HTTP `tools/list`. +- `boundary.test.ts`: allow that one adapter as the only importer. + +No dependency, workspace, Docker or release change is needed. Everything else +(picker, scopes, grant checks, allowlist, approval, audit, injection +screening, risk classification in `catalog/descriptors.ts`) only knows tool +names and scopes and needs no change. + +## Known differences from Google's MCP tools + +- **Descriptions** are our own wording; names, fields, types, enums, required + fields and annotations follow Google's reference. Until a tool lands here, + descriptions do not mention it: Google's text points to `get_thread` and + `list_labels`, ours points to `get_message` and does not name a label tool. + A contract test against a recorded `tools/list` from Google's servers is + planned once a listing is recorded on the enrolled internal account. +- **Result envelope.** Results carry the object both as `structuredContent` + and as JSON text. Google's exact envelope has not been recorded yet. +- **`date`** is the UTC calendar date of Gmail's `internalDate`. Google does + not say which time zone it uses. +- **`sender` and recipients** are plain addresses parsed from the headers; + display names are dropped. Bodies are decoded as UTF-8. +- **Large bodies.** Gmail can store a body part separately and return only + its `attachmentId`. With `FULL_CONTENT`, `get_message` reads those bytes + (`users.messages.attachments.get`) before it answers. The first `text/plain` + and first `text/html` body parts are found depth first through nested + multiparts. If a body part cannot be read, the call returns a tool error that + starts with "Could not read the full body of this message"; it never returns + a result without the body. Google's reference does not say what its tool + does here. +- **Addresses** come from `gmail/address.ts`, a small single-pass tokenizer + over RFC 5322 address lists. It tracks quoted strings with escapes, nested + comments, angle brackets and square-bracket domain literals (so + `ops@[IPv6:2001:db8::1]` stays whole), drops comments and display names, + returns the members of groups without the group name, and returns nothing + for an empty group such as `undisclosed-recipients:;`. Malformed input gives + a best-effort list and never throws. Google's reference does not say how its + tools parse these headers. +- **`labelIds`** keeps user labels and the system labels Google lists (INBOX, + SPAM, TRASH, UNREAD, STARRED, IMPORTANT, SENT, DRAFT, CHAT); category labels + are dropped. +- **`search_threads`** makes one `threads.list` call and then one + `threads.get` per thread (10 at a time), so a 50-thread page is 51 requests. + A thread deleted between the two calls is left out. `pageSize` above 50 is + capped at 50. Drafts are excluded by adding `-in:draft` unless the query + itself uses `in:draft`, `is:draft` or `in:anywhere` outside quoted text; + `includeTrash` uses `includeSpamTrash` plus `-in:spam`, with the same rule + for `in:spam`. When terms are added, the caller's query is wrapped in + parentheses first. Google's reference documents the default exclusions but + not how its tool applies them. +- **`create_draft`**: for a reply, the draft is threaded (`threadId`, + `In-Reply-To`, `References`) and an empty subject becomes `Re: `, + but the original message is not quoted under the new body as Google's tool + does, and recipients are not filled in from the original: pass `to`. The + result is built from the request and Google's `drafts.create` answer, + without a second read; `date` is the creation date (UTC). Attachments are + refused, as Google's tool currently does. Long subjects and recipient lists + are folded onto continuation lines (RFC 5322); non-ASCII subjects and single + words longer than 900 characters become RFC 2047 encoded-words. Google's + reference sets no length limits. +- **Errors** for Google failures are tool error results with our own short + messages, not Google's raw error text (except for 400 and 403 messages, + trimmed to one line). + +## Open questions + +- The Gmail allowlist in `toolScopes` names `get_draft`, `list_threads` and + `search_messages`, which Google's published Gmail MCP reference does not list + (it lists `create_draft`, `get_message`, `get_thread`, `label_message`, + `label_thread`, `list_drafts`, `list_labels`, `search_threads`, + `unlabel_message` and `unlabel_thread`). Those three have no Google schema to + copy, so they would not survive a switch back to `google_mcp`. +- Whether an OAuth client marked as an AI-powered agent may call the REST APIs. +- Each Google Cloud project behind a connection needs the REST APIs enabled + (Gmail now; Drive, Docs, Sheets, Slides and Calendar as their tools land). + Without that, calls return the `api_disabled` tool error. +- With `paperclip_rest`, `tools/list` no longer proves the token works. A live + health check needs a cheap REST probe (for example Gmail `users.getProfile`). + +## Removal procedure + +1. Set every service in `GOOGLE_WORKSPACE_TOOL_TRANSPORT` to `google_mcp`. +2. Delete this folder, `server/src/google-workspace-rest-tools/`. +3. Delete the server adapter that imports it and its two call sites (gateway + and discovery). +4. Check that the build, typecheck and tests pass, then delete the setting + itself if nothing else uses it. + +## Development + +```sh +cd server && npx vitest run src/google-workspace-rest-tools +``` + +Test fixtures in `fixtures/` and `gmail/fixtures/` are synthetic, in the shape +of Google's REST responses. They contain no real mail, addresses or IDs. diff --git a/server/src/google-workspace-rest-tools/allowlist.test.ts b/server/src/google-workspace-rest-tools/allowlist.test.ts new file mode 100644 index 00000000000..3abf2a0b212 --- /dev/null +++ b/server/src/google-workspace-rest-tools/allowlist.test.ts @@ -0,0 +1,45 @@ +import { googleWorkspaceToolName, googleWorkspaceToolTarget } from "@paperclipai/shared"; +import { describe, expect, it } from "vitest"; +import { GOOGLE_WORKSPACE_REST_SERVICES, listGoogleWorkspaceRestTools } from "./tools.js"; + +describe("tool allowlist", () => { + for (const service of GOOGLE_WORKSPACE_REST_SERVICES) { + for (const tool of listGoogleWorkspaceRestTools(service)) { + it(`${service} ${tool.name} is on the reviewed allowlist, with matching read/write intent`, () => { + const target = googleWorkspaceToolTarget(googleWorkspaceToolName(service, tool.name)); + expect(target, `${tool.name} is not in toolScopes.${service}`).not.toBeNull(); + expect(target!.leaf).toBe(tool.name); + expect(tool.annotations?.readOnlyHint).toBe(!target!.write); + }); + } + } + + it("mentions only tools this package lists in any description", () => { + for (const service of GOOGLE_WORKSPACE_REST_SERVICES) { + const tools = listGoogleWorkspaceRestTools(service); + const names = new Set(tools.map((tool) => tool.name)); + const descriptions: string[] = []; + const collect = (value: unknown) => { + if (Array.isArray(value)) value.forEach(collect); + else if (value && typeof value === "object") { + for (const [key, item] of Object.entries(value)) { + if (key === "description" && typeof item === "string") descriptions.push(item); + else collect(item); + } + } + }; + tools.forEach(collect); + const mentioned = descriptions.flatMap((text) => text.match(/\b[a-z]+(?:_[a-z]+)+\b(?!:)/g) ?? []); + expect(mentioned.filter((name) => !names.has(name))).toEqual([]); + } + }); + + it("implements no send tool", () => { + const names = GOOGLE_WORKSPACE_REST_SERVICES.flatMap((service) => listGoogleWorkspaceRestTools(service).map((tool) => tool.name)); + expect(names.filter((name) => /send/i.test(name))).toEqual([]); + }); + + it("implements the Gmail tools of this release", () => { + expect(listGoogleWorkspaceRestTools("gmail").map((tool) => tool.name)).toEqual(["get_message", "search_threads", "create_draft"]); + }); +}); diff --git a/server/src/google-workspace-rest-tools/boundary.test.ts b/server/src/google-workspace-rest-tools/boundary.test.ts new file mode 100644 index 00000000000..d5c14cc6f26 --- /dev/null +++ b/server/src/google-workspace-rest-tools/boundary.test.ts @@ -0,0 +1,57 @@ +import { readdirSync, readFileSync } from "node:fs"; +import { builtinModules } from "node:module"; +import path from "node:path"; +import { fileURLToPath } from "node:url"; +import { describe, expect, it } from "vitest"; + +const folder = path.dirname(fileURLToPath(import.meta.url)); +const serverSrc = path.dirname(folder); + +function typescriptFiles(directory: string): string[] { + return readdirSync(directory, { withFileTypes: true }).flatMap((entry) => { + if (entry.name === "node_modules") return []; + const full = path.join(directory, entry.name); + if (entry.isDirectory()) return typescriptFiles(full); + return entry.name.endsWith(".ts") ? [full] : []; + }); +} + +function importSpecifiers(source: string): string[] { + const patterns = [/\bfrom\s+["']([^"']+)["']/g, /\bimport\s*\(\s*["']([^"']+)["']\s*\)/g, /^\s*import\s+["']([^"']+)["']/gm]; + return patterns.flatMap((pattern) => [...source.matchAll(pattern)].map((match) => match[1]!)); +} + +const builtins = new Set(builtinModules); +const isBuiltin = (specifier: string) => specifier.startsWith("node:") || builtins.has(specifier); +const isTestSupport = (file: string) => file.endsWith(".test.ts") || file.split(path.sep).includes("fixtures"); + +function disallowedImports(file: string): string[] { + return importSpecifiers(readFileSync(file, "utf8")).filter((specifier) => { + if (specifier.startsWith(".")) { + const target = path.resolve(path.dirname(file), specifier); + return !(target === folder || target.startsWith(`${folder}${path.sep}`)); + } + if (isBuiltin(specifier)) return false; + if (specifier === "@modelcontextprotocol/sdk" || specifier.startsWith("@modelcontextprotocol/sdk/")) return false; + if (specifier === "zod") return false; + if (isTestSupport(file) && (specifier === "vitest" || specifier === "@paperclipai/shared")) return false; + return true; + }); +} + +describe("google-workspace-rest-tools boundary", () => { + it("imports only its own files, Node built-ins, the MCP SDK and zod", () => { + const violations = typescriptFiles(folder) + .map((file) => ({ file: path.relative(folder, file), imports: disallowedImports(file) })) + .filter((entry) => entry.imports.length > 0); + expect(violations).toEqual([]); + }); + + it("is not imported by any other server code yet", () => { + const importers = typescriptFiles(serverSrc) + .filter((file) => !file.startsWith(`${folder}${path.sep}`)) + .filter((file) => importSpecifiers(readFileSync(file, "utf8")).some((specifier) => specifier.includes("google-workspace-rest-tools"))) + .map((file) => path.relative(serverSrc, file)); + expect(importers).toEqual([]); + }); +}); diff --git a/server/src/google-workspace-rest-tools/errors.ts b/server/src/google-workspace-rest-tools/errors.ts new file mode 100644 index 00000000000..be01d8e9fac --- /dev/null +++ b/server/src/google-workspace-rest-tools/errors.ts @@ -0,0 +1,49 @@ +import { McpError } from "@modelcontextprotocol/sdk/types.js"; + +export const GOOGLE_AUTH_ERROR_CODE = -32050; + +export type GoogleAuthFailure = "unauthenticated" | "insufficient_scope"; + +export class GoogleWorkspaceAuthError extends McpError { + readonly reason: GoogleAuthFailure; + readonly httpStatus: 401 | 403; + + constructor(reason: GoogleAuthFailure) { + const httpStatus = reason === "unauthenticated" ? 401 : 403; + super( + GOOGLE_AUTH_ERROR_CODE, + reason === "unauthenticated" + ? "Google did not accept the access token. Reconnect Google Workspace." + : "Google Workspace has not granted the permission this action needs. Reconnect Google Workspace and allow it.", + { code: reason, httpStatus }, + ); + this.name = "GoogleWorkspaceAuthError"; + this.reason = reason; + this.httpStatus = httpStatus; + } +} + +export type GoogleToolErrorKind = + | "invalid_argument" + | "not_found" + | "permission_denied" + | "api_disabled" + | "rate_limited" + | "unavailable" + | "timeout" + | "network" + | "invalid_response" + | "unsupported" + | "incomplete"; + +export class GoogleToolError extends Error { + readonly kind: GoogleToolErrorKind; + readonly httpStatus: number | null; + + constructor(kind: GoogleToolErrorKind, message: string, httpStatus: number | null = null) { + super(message); + this.name = "GoogleToolError"; + this.kind = kind; + this.httpStatus = httpStatus; + } +} diff --git a/server/src/google-workspace-rest-tools/fixtures/fake-google.ts b/server/src/google-workspace-rest-tools/fixtures/fake-google.ts new file mode 100644 index 00000000000..c992720a3b4 --- /dev/null +++ b/server/src/google-workspace-rest-tools/fixtures/fake-google.ts @@ -0,0 +1,29 @@ +import type { GoogleFetch } from "../google-http.js"; + +export interface RecordedCall { + method: string; + url: URL; + headers: Record; + body: unknown; +} + +export type Route = (call: RecordedCall) => Response | Promise; + +export function json(body: unknown, status = 200, headers: Record = {}): Response { + return new Response(JSON.stringify(body), { status, headers: { "content-type": "application/json", ...headers } }); +} + +export function fakeGoogle(route: Route): { fetch: GoogleFetch; calls: RecordedCall[] } { + const calls: RecordedCall[] = []; + const fetch: GoogleFetch = async (url, init) => { + const call: RecordedCall = { + method: init.method ?? "GET", + url: new URL(url), + headers: Object.fromEntries(new Headers(init.headers).entries()), + body: typeof init.body === "string" ? JSON.parse(init.body) : undefined, + }; + calls.push(call); + return route(call); + }; + return { fetch, calls }; +} diff --git a/server/src/google-workspace-rest-tools/gmail/address.test.ts b/server/src/google-workspace-rest-tools/gmail/address.test.ts new file mode 100644 index 00000000000..5d5e41b2e05 --- /dev/null +++ b/server/src/google-workspace-rest-tools/gmail/address.test.ts @@ -0,0 +1,60 @@ +import { describe, expect, it } from "vitest"; +import { parseAddressList } from "./address.js"; + +const cases: Array<[string, string | undefined, string[]]> = [ + ["no header", undefined, []], + ["empty header", "", []], + ["plain address", "a@example.test", ["a@example.test"]], + ["display name with angle address", "Avery Example ", ["avery@example.test"]], + ["quoted display name with a comma", "\"Doe, Drew\" ", ["drew@example.test"]], + ["quoted display name with a colon", "\"Odd: name\" ", ["d@example.test"]], + ["quoted display name with an escaped quote", "\"Al \\\"Ace\\\" Ray\" ", ["al@example.test"]], + ["quoted local part with a space, bare", "\"john doe\"@example.test", ["\"john doe\"@example.test"]], + ["quoted local part with a space, in angle brackets", "John <\"john doe\"@example.test>", ["\"john doe\"@example.test"]], + ["quoted local part with an escaped quote, bare", "\"a\\\"b\"@example.test", ["\"a\\\"b\"@example.test"]], + ["quoted local part with an escaped quote, in angle brackets", "<\"a\\\"b\"@example.test>", ["\"a\\\"b\"@example.test"]], + ["quoted local part with an escaped backslash, bare", "\"a\\\\b c\"@example.test", ["\"a\\\\b c\"@example.test"]], + ["quoted local part with an escaped backslash, in angle brackets", "X <\"a\\\\b c\"@example.test>", ["\"a\\\\b c\"@example.test"]], + ["bare address with folding space around the at-sign", "a @ example.test", ["a@example.test"]], + ["trailing comment", "Avery (work)", ["avery@example.test"]], + ["nested comment", "blake@example.test (Blake, (home: desk))", ["blake@example.test"]], + ["comment with an escaped parenthesis", "c@example.test (a \\) b)", ["c@example.test"]], + ["group with two members", "Team: a@example.test, Bea ;", ["a@example.test", "b@example.test"]], + ["empty group", "undisclosed-recipients:;", []], + ["group then a mailbox", "Team: a@example.test;, c@example.test", ["a@example.test", "c@example.test"]], + ["IPv6 domain literal, bare", "ops@[IPv6:2001:db8::1]", ["ops@[IPv6:2001:db8::1]"]], + ["IPv6 domain literal, in angle brackets", "Ops ", ["ops@[IPv6:2001:db8::1]"]], + ["IPv6 domain literal inside a group", "Lab: ops@[IPv6:2001:db8::1];", ["ops@[IPv6:2001:db8::1]"]], + ["source route in angle brackets", "<@relay.example.test:e@example.test>", ["e@example.test"]], + [ + "mixed list", + "\"Doe, Drew\" , e@example.test (x), Team: f@example.test, \"G: H\" ;, ops@[IPv6:2001:db8::1]", + ["drew@example.test", "e@example.test", "f@example.test", "g@example.test", "ops@[IPv6:2001:db8::1]"], + ], + ["unclosed angle bracket", "Avery ", ["avery@example.test"]], + ["unclosed comment", "a@example.test (oops", ["a@example.test"]], + ["unclosed domain literal", "ops@[IPv6:2001:db8::1", ["ops@[IPv6:2001:db8::1"]], + ["stray separators", ",,;; ,", []], + ["name without an address", "Just A Name", []], +]; + +describe("parseAddressList", () => { + it.each(cases)("%s", (_name, header, expected) => { + expect(parseAddressList(header)).toEqual(expected); + }); + + it("never throws on arbitrary input", () => { + const alphabet = ["a", "@", ".", ",", ";", ":", "<", ">", "(", ")", "[", "]", "\"", "\\", " ", "é"]; + let seed = 7; + for (let round = 0; round < 2000; round += 1) { + let text = ""; + for (let index = 0; index < 24; index += 1) { + seed = (seed * 1103515245 + 12345) % 2147483648; + text += alphabet[seed % alphabet.length]; + } + expect(() => parseAddressList(text)).not.toThrow(); + expect(Array.isArray(parseAddressList(text))).toBe(true); + } + }); +}); diff --git a/server/src/google-workspace-rest-tools/gmail/address.ts b/server/src/google-workspace-rest-tools/gmail/address.ts new file mode 100644 index 00000000000..02f5471e960 --- /dev/null +++ b/server/src/google-workspace-rest-tools/gmail/address.ts @@ -0,0 +1,138 @@ +interface Mailbox { + outside: string; + angle: string; + hasAngle: boolean; +} + +const emptyMailbox = (): Mailbox => ({ outside: "", angle: "", hasAngle: false }); + +function withoutRoute(angle: string): string { + if (!angle.startsWith("@")) return angle; + let bracket = false; + for (let index = 0; index < angle.length; index += 1) { + const char = angle[index]; + if (char === "[") bracket = true; + else if (char === "]") bracket = false; + else if (char === ":" && !bracket) return angle.slice(index + 1); + } + return angle; +} + +function withoutUnquotedSpace(text: string): string { + let result = ""; + let quoted = false; + let escaped = false; + for (const char of text) { + if (escaped) { + escaped = false; + result += char; + continue; + } + if (quoted && char === "\\") { + escaped = true; + result += char; + continue; + } + if (char === "\"") quoted = !quoted; + if (!quoted && /\s/.test(char)) continue; + result += char; + } + return result; +} + +function mailboxAddress(mailbox: Mailbox): string | null { + if (mailbox.hasAngle) { + const address = withoutRoute(mailbox.angle.trim()).trim(); + return address.length > 0 ? address : null; + } + const address = withoutUnquotedSpace(mailbox.outside); + const enclosed = /<([^<>]*@[^<>]*)>?/.exec(address); + if (enclosed) return enclosed[1]!.trim(); + return address.includes("@") && !/[<>]/.test(address) ? address : null; +} + +export function parseAddressList(value: string | undefined): string[] { + if (!value) return []; + const addresses: string[] = []; + let mailbox = emptyMailbox(); + let quoted = false; + let comment = 0; + let angle = false; + let bracket = false; + let escaped = false; + + const append = (text: string) => { + if (angle) mailbox.angle += text; + else mailbox.outside += text; + }; + const finish = () => { + const address = mailboxAddress(mailbox); + if (address) addresses.push(address); + mailbox = emptyMailbox(); + }; + + for (const char of value) { + if (escaped) { + escaped = false; + if (comment === 0) append(char); + continue; + } + if (char === "\\" && (quoted || comment > 0 || bracket)) { + escaped = true; + if (comment === 0) append(char); + continue; + } + if (comment > 0) { + if (char === "(") comment += 1; + else if (char === ")") comment -= 1; + continue; + } + if (quoted) { + append(char); + if (char === "\"") quoted = false; + continue; + } + if (bracket) { + append(char); + if (char === "]") bracket = false; + continue; + } + if (char === "(") { + comment = 1; + append(" "); + continue; + } + if (char === "\"") { + quoted = true; + append(char); + continue; + } + if (char === "[") { + bracket = true; + append(char); + continue; + } + if (angle) { + if (char === ">") angle = false; + else append(char); + continue; + } + if (char === "<") { + angle = true; + mailbox.hasAngle = true; + mailbox.angle = ""; + continue; + } + if (char === ":") { + mailbox = emptyMailbox(); + continue; + } + if (char === "," || char === ";") { + finish(); + continue; + } + append(char); + } + finish(); + return addresses; +} diff --git a/server/src/google-workspace-rest-tools/gmail/create-draft.test.ts b/server/src/google-workspace-rest-tools/gmail/create-draft.test.ts new file mode 100644 index 00000000000..91dc80e5897 --- /dev/null +++ b/server/src/google-workspace-rest-tools/gmail/create-draft.test.ts @@ -0,0 +1,150 @@ +import { describe, expect, it } from "vitest"; +import { createGoogleHttp } from "../google-http.js"; +import { fakeGoogle, json } from "../fixtures/fake-google.js"; +import { createDraft, createDraftRequest, createDraftResult, replyContext } from "./create-draft.js"; +import { CREATED_DRAFT, REPLY_ORIGINAL } from "./fixtures/gmail-rest.js"; + +function decodedRaw(request: ReturnType): string { + const raw = (request.body as { message: { raw: string } }).message.raw; + return Buffer.from(raw, "base64url").toString("utf8"); +} + +function decodedParts(mime: string): string[] { + return [...mime.matchAll(/Content-Transfer-Encoding: base64\r\n\r\n([A-Za-z0-9+/=\r\n]+)/g)] + .map((match) => Buffer.from(match[1]!.replace(/\r\n/g, ""), "base64").toString("utf8")); +} + +describe("create_draft request", () => { + it("creates a draft (never sends) with a plain-text body", () => { + const request = createDraftRequest({ to: ["blake@example.test"], subject: "Hello", body: "Hi Blake" }, undefined, "b1"); + expect(request).toMatchObject({ method: "POST", host: "gmail.googleapis.com", path: "/gmail/v1/users/me/drafts" }); + const mime = decodedRaw(request); + expect(mime).toContain("To: blake@example.test\r\n"); + expect(mime).toContain("Subject: Hello\r\n"); + expect(mime).toContain("Content-Type: text/plain; charset=\"UTF-8\""); + expect(decodedParts(mime)).toEqual(["Hi Blake"]); + expect((request.body as { message: Record }).message).not.toHaveProperty("threadId"); + }); + + it("sends both bodies as multipart/alternative and encodes a non-ASCII subject", () => { + const mime = decodedRaw(createDraftRequest({ + to: ["a@example.test"], cc: ["c@example.test"], bcc: ["d@example.test"], + subject: "Plan für Q4", body: "plain", htmlBody: "

rich

", + }, undefined, "b2")); + expect(mime).toContain("Cc: c@example.test\r\n"); + expect(mime).toContain("Bcc: d@example.test\r\n"); + expect(mime).toContain(`Subject: =?UTF-8?B?${Buffer.from("Plan für Q4").toString("base64")}?=`); + expect(mime).toContain("Content-Type: multipart/alternative; boundary=\"b2\""); + expect(decodedParts(mime)).toEqual(["plain", "

rich

"]); + }); + + it("folds a long non-ASCII subject into encoded-words of at most 75 characters", () => { + const subject = "Résumé für das Quartal ".repeat(6).trim(); + const mime = decodedRaw(createDraftRequest({ to: ["a@example.test"], subject, body: "x" }, undefined, "b4")); + const folded = /Subject: ((?:=\?UTF-8\?B\?[A-Za-z0-9+/=]+\?=(?:\r\n )?)+)\r\n/.exec(mime)![1]!; + const words = folded.split("\r\n "); + expect(words.length).toBeGreaterThan(1); + for (const word of words) expect(word.length).toBeLessThanOrEqual(75); + const decoded = words.map((word) => Buffer.from(word.slice(10, -2), "base64").toString("utf8")).join(""); + expect(decoded).toBe(subject); + }); + + it("folds long ASCII subjects and long recipient lists to RFC 5322 line limits", () => { + const subject = Array.from({ length: 140 }, (_, index) => `word${index}`).join(" "); + const to = Array.from({ length: 100 }, (_, index) => `person.number${index}@example.test`); + const mime = decodedRaw(createDraftRequest({ to, subject, body: "x" }, undefined, "b5")); + const headerBlock = mime.slice(0, mime.indexOf("\r\n\r\n") + 2); + for (const line of headerBlock.split("\r\n").slice(0, -1)) { + expect(line.length).toBeLessThanOrEqual(78); + expect(line.trim().length).toBeGreaterThan(0); + } + const unfolded = headerBlock.replace(/\r\n /g, " "); + expect(unfolded).toContain(`Subject: ${subject}\r\n`); + expect(unfolded).toContain(`To: ${to.join(", ")}\r\n`); + }); + + it("encodes a single ASCII token too long for one line", () => { + const subject = "x".repeat(990); + const mime = decodedRaw(createDraftRequest({ subject }, undefined, "b6")); + const headerBlock = mime.slice(0, mime.indexOf("\r\n\r\n") + 2); + for (const line of headerBlock.split("\r\n")) expect(line.length).toBeLessThanOrEqual(78); + const words = /Subject: ([\s\S]*?)\r\n(?! )/.exec(headerBlock)![1]!.split("\r\n "); + expect(words.map((word) => Buffer.from(word.slice(10, -2), "base64").toString("utf8")).join("")).toBe(subject); + }); + + it("threads a reply and defaults the subject to Re:", () => { + const reply = replyContext(REPLY_ORIGINAL); + expect(reply).toEqual({ + threadId: "18c0ffee00000000", + inReplyTo: "", + references: " ", + subject: "Quarterly plan", + }); + const request = createDraftRequest({ to: ["avery@example.test"], body: "Looks good" }, reply, "b3"); + expect((request.body as { message: Record }).message.threadId).toBe("18c0ffee00000000"); + const mime = decodedRaw(request); + expect(mime).toContain("Subject: Re: Quarterly plan\r\n"); + expect(mime).toContain("In-Reply-To: \r\n"); + expect(mime).toContain("References: \r\n"); + }); + + it("drops malformed threading headers from the original message", () => { + const reply = replyContext({ threadId: "t1", payload: { headers: [{ name: "Message-ID", value: "\r\nBcc: x@example.test" }] } }); + expect(reply.inReplyTo).toBeUndefined(); + expect(reply.references).toBeUndefined(); + }); +}); + +describe("create_draft result", () => { + it("returns Google's MCP Draft", () => { + const input = { to: ["blake@example.test"], subject: "Hello", body: "Hi" }; + expect(createDraftResult(CREATED_DRAFT, input, undefined, new Date("2026-11-17T12:00:00Z")).structuredContent).toEqual({ + id: "r-1234567890123456789", subject: "Hello", threadId: "18c0ffee00000000", + toRecipients: ["blake@example.test"], ccRecipients: [], bccRecipients: [], plaintextBody: "Hi", date: "2026-11-17", + }); + }); +}); + +describe("create_draft tool", () => { + it("looks up the original for a reply, then makes exactly one drafts.create call", async () => { + const { fetch, calls } = fakeGoogle(({ method }) => json(method === "GET" ? REPLY_ORIGINAL : CREATED_DRAFT)); + const result = await createDraft.call({ to: ["avery@example.test"], body: "Looks good", replyToMessageId: "18c0ffee00000001" }, + createGoogleHttp({ accessToken: "t", fetch })); + expect(result.isError).toBeUndefined(); + expect(calls.map((call) => `${call.method} ${call.url.pathname}`)).toEqual([ + "GET /gmail/v1/users/me/messages/18c0ffee00000001", + "POST /gmail/v1/users/me/drafts", + ]); + expect(calls.some((call) => call.url.pathname.includes("send"))).toBe(false); + }); + + it("rejects header injection and display-name recipients before calling Google", async () => { + const { fetch, calls } = fakeGoogle(() => json(CREATED_DRAFT)); + const http = createGoogleHttp({ accessToken: "t", fetch }); + for (const args of [ + { subject: "Hi\r\nBcc: x@example.test" }, + { to: ["Blake "] }, + { to: ["blake@example.test\r\nBcc: x@example.test"] }, + { cc: ["a@example.test, b@example.test"] }, + { replyToMessageId: "../send" }, + ]) { + const result = await createDraft.call(args, http); + expect(result.isError).toBe(true); + } + expect(calls).toHaveLength(0); + }); + + it("refuses attachments, as Google's tool does today", async () => { + const { fetch, calls } = fakeGoogle(() => json(CREATED_DRAFT)); + const result = await createDraft.call({ to: ["a@example.test"], attachments: [{ content: "aGk=" }] }, createGoogleHttp({ accessToken: "t", fetch })); + expect(result).toEqual({ isError: true, content: [{ type: "text", text: "Drafts with attachments are not supported yet." }] }); + expect(calls).toHaveLength(0); + }); + + it("does not retry the write when Google fails", async () => { + const { fetch, calls } = fakeGoogle(() => json({}, 503)); + const result = await createDraft.call({ to: ["a@example.test"] }, createGoogleHttp({ accessToken: "t", fetch, retryDelayMs: 0 })); + expect(result.isError).toBe(true); + expect(calls).toHaveLength(1); + }); +}); diff --git a/server/src/google-workspace-rest-tools/gmail/create-draft.ts b/server/src/google-workspace-rest-tools/gmail/create-draft.ts new file mode 100644 index 00000000000..435a0a77410 --- /dev/null +++ b/server/src/google-workspace-rest-tools/gmail/create-draft.ts @@ -0,0 +1,165 @@ +import { randomBytes } from "node:crypto"; +import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js"; +import { z } from "zod"; +import { GoogleToolError } from "../errors.js"; +import type { GoogleRequest } from "../google-http.js"; +import { compact, defineTool, structuredResult } from "../tool.js"; +import { gmailId, header, type GmailRestMessage } from "./message.js"; +import { buildDraftMime } from "./mime.js"; + +const plainEmail = z.string().regex(/^[^\s<>@,;"()\\]+@[^\s<>@,;"()\\]+\.[^\s<>@,;"()\\]+$/, "Must be a plain email address such as user@example.com"); +const addressList = z.array(plainEmail).max(100).optional(); + +const args = z.object({ + to: addressList, + cc: addressList, + bcc: addressList, + subject: z.string().max(998).regex(/^[^\r\n]*$/, "Subject must be a single line").optional(), + body: z.string().optional(), + htmlBody: z.string().optional(), + replyToMessageId: gmailId.optional(), + attachments: z.array(z.object({ + id: z.string().optional(), + filename: z.string().optional(), + mimeType: z.string().optional(), + content: z.string(), + inline: z.boolean().optional(), + })).optional(), +}); +export type CreateDraftArgs = z.infer; + +interface GmailRestDraft { id?: string; message?: { id?: string; threadId?: string } } + +export interface ReplyContext { + threadId?: string; + inReplyTo?: string; + references?: string; + subject: string; +} + +const MESSAGE_ID_TOKEN = /^<[^<>\s]+>$/; + +export function replyLookupRequest(messageId: string): GoogleRequest { + return { + method: "GET", + host: "gmail.googleapis.com", + path: `/gmail/v1/users/me/messages/${messageId}`, + query: { format: "metadata", metadataHeaders: ["Message-ID", "References", "Subject"] }, + }; +} + +export function replyContext(original: GmailRestMessage): ReplyContext { + const messageId = header(original.payload, "Message-ID")?.trim(); + const inReplyTo = messageId && MESSAGE_ID_TOKEN.test(messageId) ? messageId : undefined; + const references = [...(header(original.payload, "References") ?? "").split(/\s+/), inReplyTo ?? ""] + .filter((token) => MESSAGE_ID_TOKEN.test(token)); + const subject = (header(original.payload, "Subject") ?? "").replace(/[\r\n]+/g, " ").trim(); + return { + threadId: original.threadId, + inReplyTo, + references: references.length ? [...new Set(references)].join(" ") : undefined, + subject, + }; +} + +export function draftSubject(input: CreateDraftArgs, reply?: ReplyContext): string { + if (input.subject) return input.subject; + if (!reply?.subject) return ""; + return /^re:/i.test(reply.subject) ? reply.subject : `Re: ${reply.subject}`; +} + +export function assertDraftSupported(input: CreateDraftArgs): void { + if (input.attachments?.length) throw new GoogleToolError("unsupported", "Drafts with attachments are not supported yet."); +} + +export function createDraftRequest(input: CreateDraftArgs, reply: ReplyContext | undefined, boundary: string): GoogleRequest { + const mime = buildDraftMime({ + to: input.to ?? [], cc: input.cc ?? [], bcc: input.bcc ?? [], + subject: draftSubject(input, reply), + body: input.body, + htmlBody: input.htmlBody, + inReplyTo: reply?.inReplyTo, + references: reply?.references, + boundary, + }); + return { + method: "POST", + host: "gmail.googleapis.com", + path: "/gmail/v1/users/me/drafts", + body: { message: compact({ raw: Buffer.from(mime, "utf8").toString("base64url"), threadId: reply?.threadId }) }, + }; +} + +export function createDraftResult(draft: GmailRestDraft, input: CreateDraftArgs, reply: ReplyContext | undefined, now: Date): CallToolResult { + return structuredResult(compact({ + id: draft.id ?? "", + subject: draftSubject(input, reply), + threadId: draft.message?.threadId, + toRecipients: input.to ?? [], + ccRecipients: input.cc ?? [], + bccRecipients: input.bcc ?? [], + plaintextBody: input.body, + date: now.toISOString().slice(0, 10), + htmlBody: input.htmlBody, + })); +} + +const recipients = (description: string) => ({ type: "array", items: { type: "string" }, description }); + +export const createDraft = defineTool({ + definition: { + name: "create_draft", + description: "Creates a draft email in the signed-in user's Gmail and returns it. It does not send. To draft a reply, pass the original message's ID as replyToMessageId. Attachments are not supported yet.", + inputSchema: { + type: "object", + properties: { + to: recipients("Optional. To recipients, each a plain email address such as user@example.com. \"Name \" is not supported."), + cc: recipients("Optional. Cc recipients, each a plain email address."), + bcc: recipients("Optional. Bcc recipients, each a plain email address."), + subject: { type: "string", description: "Optional. The subject line. Empty when not given." }, + body: { type: "string", description: "Optional. The plain-text body. When htmlBody is also given, this is the plain-text alternative." }, + htmlBody: { type: "string", description: "The HTML body, used as the rich-text version." }, + replyToMessageId: { type: "string", description: "Optional. The ID of the message this draft replies to." }, + attachments: { + type: "array", + description: "Optional. Attachments, at most 25 MB in total. Not supported yet.", + items: { + type: "object", + properties: { + id: { type: "string", description: "Output only. An external attachment ID." }, + filename: { type: "string", description: "Optional. The file name shown to recipients." }, + mimeType: { type: "string", description: "Optional. IANA media type. Default application/octet-stream." }, + content: { type: "string", description: "Required. The base64-encoded content." }, + inline: { type: "boolean", description: "Optional. Show inline in the HTML body. Default false." }, + }, + required: ["content"], + }, + }, + }, + }, + outputSchema: { + type: "object", + properties: { + id: { type: "string", description: "The draft ID." }, + subject: { type: "string", description: "The draft's subject line." }, + threadId: { type: "string", description: "The ID of the thread the draft belongs to." }, + toRecipients: recipients("To recipient email addresses."), + ccRecipients: recipients("Cc recipient email addresses."), + bccRecipients: recipients("Bcc recipient email addresses."), + plaintextBody: { type: "string", description: "The plain-text body, if any." }, + date: { type: "string", description: "The draft date, ISO 8601 (YYYY-MM-DD)." }, + htmlBody: { type: "string", description: "The HTML body, if any." }, + }, + }, + annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false }, + }, + args, + async run(input, http) { + assertDraftSupported(input); + const reply = input.replyToMessageId + ? replyContext(await http.send(replyLookupRequest(input.replyToMessageId))) + : undefined; + const draft = await http.send(createDraftRequest(input, reply, `paperclip-${randomBytes(12).toString("hex")}`)); + return createDraftResult(draft, input, reply, new Date()); + }, +}); diff --git a/server/src/google-workspace-rest-tools/gmail/fixtures/gmail-rest.ts b/server/src/google-workspace-rest-tools/gmail/fixtures/gmail-rest.ts new file mode 100644 index 00000000000..aa5133f2f8a --- /dev/null +++ b/server/src/google-workspace-rest-tools/gmail/fixtures/gmail-rest.ts @@ -0,0 +1,95 @@ +const b64 = (text: string) => Buffer.from(text, "utf8").toString("base64url"); + +export const FULL_MESSAGE = { + id: "18c0ffee00000001", + threadId: "18c0ffee00000000", + labelIds: ["INBOX", "UNREAD", "CATEGORY_PERSONAL", "Label_42"], + snippet: "Here is the quarterly plan we discussed", + internalDate: "1763337600000", + sizeEstimate: 4096, + historyId: "9001", + payload: { + partId: "", + mimeType: "multipart/mixed", + filename: "", + headers: [ + { name: "From", value: "\"Avery Example\" " }, + { name: "To", value: "Blake , casey@example.test" }, + { name: "Cc", value: "\"Doe, Drew\" " }, + { name: "Subject", value: "Quarterly plan" }, + { name: "Date", value: "Mon, 17 Nov 2025 00:00:00 +0000" }, + { name: "Message-ID", value: "" }, + ], + body: { size: 0 }, + parts: [ + { + partId: "0", + mimeType: "multipart/alternative", + filename: "", + headers: [{ name: "Content-Type", value: "multipart/alternative; boundary=\"alt\"" }], + body: { size: 0 }, + parts: [ + { partId: "0.0", mimeType: "text/plain", filename: "", headers: [], body: { size: 38, data: b64("Here is the quarterly plan we discussed.") } }, + { partId: "0.1", mimeType: "text/html", filename: "", headers: [], body: { size: 45, data: b64("

Here is the quarterly plan.

") } }, + ], + }, + { + partId: "1", + mimeType: "application/pdf", + filename: "plan.pdf", + headers: [{ name: "Content-Disposition", value: "attachment; filename=\"plan.pdf\"" }], + body: { attachmentId: "ANGjdJ_fake_attachment_1", size: 2048 }, + }, + ], + }, +}; + +export const METADATA_MESSAGE = { + id: "18c0ffee00000002", + threadId: "18c0ffee00000000", + labelIds: ["SENT", "CATEGORY_UPDATES"], + snippet: "Thanks, looks good", + internalDate: "1763424000000", + payload: { + mimeType: "text/plain", + headers: [ + { name: "From", value: "blake@example.test" }, + { name: "To", value: "avery@example.test" }, + { name: "Subject", value: "Re: Quarterly plan" }, + { name: "Date", value: "Tue, 18 Nov 2025 00:00:00 +0000" }, + ], + }, +}; + +export const THREAD_LIST = { + threads: [ + { id: "18c0ffee00000000", snippet: "Thanks, looks good", historyId: "9002" }, + { id: "18c0ffee00000010", snippet: "Lunch?", historyId: "9003" }, + ], + nextPageToken: "page-2-token", + resultSizeEstimate: 201, +}; + +export const THREAD_ONE = { + id: "18c0ffee00000000", + historyId: "9002", + messages: [{ ...FULL_MESSAGE, payload: { mimeType: "multipart/mixed", headers: FULL_MESSAGE.payload.headers } }, METADATA_MESSAGE], +}; + +export const REPLY_ORIGINAL = { + id: "18c0ffee00000001", + threadId: "18c0ffee00000000", + payload: { + mimeType: "multipart/mixed", + headers: [ + { name: "Message-ID", value: "" }, + { name: "References", value: "" }, + { name: "Subject", value: "Quarterly plan" }, + ], + }, +}; + +export const CREATED_DRAFT = { + id: "r-1234567890123456789", + message: { id: "18c0ffee00000099", threadId: "18c0ffee00000000", labelIds: ["DRAFT"] }, +}; diff --git a/server/src/google-workspace-rest-tools/gmail/get-message.test.ts b/server/src/google-workspace-rest-tools/gmail/get-message.test.ts new file mode 100644 index 00000000000..cb2254e5071 --- /dev/null +++ b/server/src/google-workspace-rest-tools/gmail/get-message.test.ts @@ -0,0 +1,147 @@ +import { describe, expect, it } from "vitest"; +import { createGoogleHttp } from "../google-http.js"; +import { fakeGoogle, json } from "../fixtures/fake-google.js"; +import { FULL_MESSAGE, METADATA_MESSAGE } from "./fixtures/gmail-rest.js"; +import { getMessage, getMessageRequest, getMessageResult } from "./get-message.js"; + +describe("get_message request", () => { + it("reads the full message by default and for FULL_CONTENT", () => { + for (const messageFormat of [undefined, "FULL_CONTENT", "MESSAGE_FORMAT_UNSPECIFIED"] as const) { + expect(getMessageRequest({ messageId: "18c0ffee00000001", messageFormat })).toEqual({ + method: "GET", host: "gmail.googleapis.com", path: "/gmail/v1/users/me/messages/18c0ffee00000001", query: { format: "full" }, + }); + } + }); + + it("reads only summary headers for MINIMAL and METADATA_ONLY", () => { + for (const messageFormat of ["MINIMAL", "METADATA_ONLY"] as const) { + expect(getMessageRequest({ messageId: "abc", messageFormat }).query).toEqual({ + format: "metadata", metadataHeaders: ["From", "To", "Cc", "Subject", "Date"], + }); + } + }); +}); + +describe("get_message result", () => { + it("maps a full message to Google's MCP Message", () => { + const result = getMessageResult(FULL_MESSAGE, { messageId: FULL_MESSAGE.id }); + expect(result.structuredContent).toEqual({ + id: "18c0ffee00000001", + snippet: "Here is the quarterly plan we discussed", + subject: "Quarterly plan", + sender: "avery@example.test", + toRecipients: ["blake@example.test", "casey@example.test"], + ccRecipients: ["drew@example.test"], + date: "2025-11-17", + plaintextBody: "Here is the quarterly plan we discussed.", + htmlBody: "

Here is the quarterly plan.

", + attachmentIds: ["ANGjdJ_fake_attachment_1"], + attachments: [{ id: "ANGjdJ_fake_attachment_1", mimeType: "application/pdf", filename: "plan.pdf" }], + labelIds: ["INBOX", "UNREAD", "Label_42"], + }); + expect(JSON.parse((result.content[0] as { text: string }).text)).toEqual(result.structuredContent); + }); + + it("leaves bodies out of MINIMAL and subject and snippet out of METADATA_ONLY", () => { + const minimal = getMessageResult(METADATA_MESSAGE, { messageId: METADATA_MESSAGE.id, messageFormat: "MINIMAL" }).structuredContent; + expect(minimal).toEqual({ + id: "18c0ffee00000002", snippet: "Thanks, looks good", subject: "Re: Quarterly plan", sender: "blake@example.test", + toRecipients: ["avery@example.test"], ccRecipients: [], date: "2025-11-18", labelIds: ["SENT"], + }); + const metadata = getMessageResult(METADATA_MESSAGE, { messageId: METADATA_MESSAGE.id, messageFormat: "METADATA_ONLY" }).structuredContent; + expect(metadata).not.toHaveProperty("subject"); + expect(metadata).not.toHaveProperty("snippet"); + expect(metadata).not.toHaveProperty("plaintextBody"); + }); + + it("reads the first plain and HTML bodies from nested multiparts", () => { + const b64 = (text: string) => Buffer.from(text, "utf8").toString("base64url"); + const nested = { + id: "n1", + payload: { + mimeType: "multipart/mixed", + parts: [{ + mimeType: "multipart/related", + parts: [{ + mimeType: "multipart/alternative", + parts: [ + { mimeType: "text/plain", body: { data: b64("plain ü") } }, + { mimeType: "text/html", body: { data: b64("

html

") } }, + ], + }, { mimeType: "image/png", filename: "logo.png", headers: [{ name: "Content-Disposition", value: "inline" }], body: { attachmentId: "img1" } }], + }, { mimeType: "text/plain", filename: "notes.txt", body: { attachmentId: "att2" } }], + }, + }; + expect(getMessageResult(nested, { messageId: "n1" }).structuredContent).toMatchObject({ + plaintextBody: "plain ü", + htmlBody: "

html

", + attachmentIds: ["img1", "att2"], + }); + }); +}); + +describe("get_message with a body Gmail stores separately", () => { + const large = "A long body line.\n".repeat(5000); + const message = { + id: "big1", + snippet: "A long body line.", + payload: { + mimeType: "multipart/alternative", + headers: [{ name: "Subject", value: "Large" }], + parts: [ + { mimeType: "text/plain", body: { size: large.length, attachmentId: "ANGjdJ_body_plain" } }, + { mimeType: "text/html", body: { size: 12, data: Buffer.from("

short

").toString("base64url") } }, + ], + }, + }; + + it("fetches the body bytes before returning FULL_CONTENT", async () => { + const { fetch, calls } = fakeGoogle(({ url }) => (url.pathname.includes("/attachments/") + ? json({ size: large.length, data: Buffer.from(large).toString("base64url") }) + : json(message))); + const result = await getMessage.call({ messageId: "big1" }, createGoogleHttp({ accessToken: "t", fetch })); + expect(result.isError).toBeUndefined(); + expect((result.structuredContent as { plaintextBody: string }).plaintextBody).toBe(large); + expect((result.structuredContent as { htmlBody: string }).htmlBody).toBe("

short

"); + expect(calls.map((call) => call.url.pathname)).toEqual([ + "/gmail/v1/users/me/messages/big1", + "/gmail/v1/users/me/messages/big1/attachments/ANGjdJ_body_plain", + ]); + }); + + it("does not fetch body bytes for MINIMAL", async () => { + const { fetch, calls } = fakeGoogle(() => json(message)); + await getMessage.call({ messageId: "big1", messageFormat: "MINIMAL" }, createGoogleHttp({ accessToken: "t", fetch })); + expect(calls).toHaveLength(1); + }); + + it("returns an explicit error, never a body-less success, when the body cannot be read", async () => { + const { fetch } = fakeGoogle(({ url }) => (url.pathname.includes("/attachments/") ? json({ error: { code: 500 } }, 500) : json(message))); + const result = await getMessage.call({ messageId: "big1" }, createGoogleHttp({ accessToken: "t", fetch, retryDelayMs: 0 })); + expect(result.isError).toBe(true); + expect(result.structuredContent).toBeUndefined(); + expect((result.content[0] as { text: string }).text).toMatch(/^Could not read the full body of this message/); + }); + + it("refuses to map a separately stored body that was not fetched", () => { + expect(() => getMessageResult(message, { messageId: "big1" })).toThrow(/full body/); + }); +}); + +describe("get_message tool", () => { + it("rejects message IDs that could change the request path", async () => { + const { fetch, calls } = fakeGoogle(() => json(FULL_MESSAGE)); + const http = createGoogleHttp({ accessToken: "t", fetch }); + for (const messageId of ["..", "a/b", "a?b", ""]) { + const result = await getMessage.call({ messageId }, http); + expect(result.isError).toBe(true); + } + expect(calls).toHaveLength(0); + }); + + it("returns a tool error result when the message is missing", async () => { + const { fetch } = fakeGoogle(() => json({ error: { code: 404, message: "Requested entity was not found." } }, 404)); + const result = await getMessage.call({ messageId: "missing1" }, createGoogleHttp({ accessToken: "t", fetch })); + expect(result).toEqual({ isError: true, content: [{ type: "text", text: "Google could not find that item." }] }); + }); +}); diff --git a/server/src/google-workspace-rest-tools/gmail/get-message.ts b/server/src/google-workspace-rest-tools/gmail/get-message.ts new file mode 100644 index 00000000000..11438ebd799 --- /dev/null +++ b/server/src/google-workspace-rest-tools/gmail/get-message.ts @@ -0,0 +1,93 @@ +import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js"; +import { z } from "zod"; +import { GoogleToolError } from "../errors.js"; +import type { GoogleHttp, GoogleRequest } from "../google-http.js"; +import { defineTool, structuredResult } from "../tool.js"; +import { + bodyAttachmentRequest, + externalBodyIds, + gmailId, + SUMMARY_HEADERS, + toMcpMessage, + type GmailRestAttachment, + type GmailRestMessage, + type MessageDetail, +} from "./message.js"; +import { messageSchema } from "./schemas.js"; + +const MESSAGE_FORMATS = ["MESSAGE_FORMAT_UNSPECIFIED", "MINIMAL", "FULL_CONTENT", "METADATA_ONLY"] as const; + +const args = z.object({ + messageId: gmailId, + messageFormat: z.enum(MESSAGE_FORMATS).optional(), +}); +export type GetMessageArgs = z.infer; + +export function messageDetail(format: GetMessageArgs["messageFormat"]): MessageDetail { + if (format === "MINIMAL") return "minimal"; + if (format === "METADATA_ONLY") return "metadata_only"; + return "full"; +} + +export function getMessageRequest(input: GetMessageArgs): GoogleRequest { + const detail = messageDetail(input.messageFormat); + return { + method: "GET", + host: "gmail.googleapis.com", + path: `/gmail/v1/users/me/messages/${input.messageId}`, + query: detail === "full" ? { format: "full" } : { format: "metadata", metadataHeaders: SUMMARY_HEADERS }, + }; +} + +export function getMessageResult( + message: GmailRestMessage, + input: GetMessageArgs, + externalBodies?: ReadonlyMap, +): CallToolResult { + return structuredResult(toMcpMessage(message, messageDetail(input.messageFormat), externalBodies)); +} + +async function readExternalBodies(message: GmailRestMessage, input: GetMessageArgs, http: GoogleHttp): Promise> { + const bodies = new Map(); + if (messageDetail(input.messageFormat) !== "full") return bodies; + for (const attachmentId of externalBodyIds(message.payload)) { + let answer: GmailRestAttachment; + try { + answer = await http.send(bodyAttachmentRequest(input.messageId, attachmentId)); + } catch (error) { + if (error instanceof GoogleToolError) { + throw new GoogleToolError("incomplete", `Could not read the full body of this message. ${error.message}`, error.httpStatus); + } + throw error; + } + if (typeof answer.data !== "string") throw new GoogleToolError("incomplete", "Could not read the full body of this message."); + bodies.set(attachmentId, answer.data); + } + return bodies; +} + +export const getMessage = defineTool({ + definition: { + name: "get_message", + description: "Gets one email message from the signed-in user's Gmail by message ID.", + inputSchema: { + type: "object", + properties: { + messageId: { type: "string", description: "Required. The ID of the message to get." }, + messageFormat: { + type: "string", + enum: [...MESSAGE_FORMATS], + description: "Optional. How much of the message to return. MINIMAL: snippet and the Subject, From, To, Cc and Date headers. FULL_CONTENT (default): MINIMAL plus the body and attachments. METADATA_ONLY: no subject, snippet, body or attachment names.", + }, + }, + required: ["messageId"], + }, + outputSchema: messageSchema, + annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false }, + }, + args, + async run(input, http) { + const message = await http.send(getMessageRequest(input)); + return getMessageResult(message, input, await readExternalBodies(message, input, http)); + }, +}); diff --git a/server/src/google-workspace-rest-tools/gmail/index.ts b/server/src/google-workspace-rest-tools/gmail/index.ts new file mode 100644 index 00000000000..98b7e8ab8fe --- /dev/null +++ b/server/src/google-workspace-rest-tools/gmail/index.ts @@ -0,0 +1,6 @@ +import type { RestTool } from "../tool.js"; +import { createDraft } from "./create-draft.js"; +import { getMessage } from "./get-message.js"; +import { searchThreads } from "./search-threads.js"; + +export const GMAIL_TOOLS: readonly RestTool[] = [getMessage, searchThreads, createDraft]; diff --git a/server/src/google-workspace-rest-tools/gmail/message.ts b/server/src/google-workspace-rest-tools/gmail/message.ts new file mode 100644 index 00000000000..7e728456fd7 --- /dev/null +++ b/server/src/google-workspace-rest-tools/gmail/message.ts @@ -0,0 +1,163 @@ +import { z } from "zod"; +import { GoogleToolError } from "../errors.js"; +import type { GoogleRequest } from "../google-http.js"; +import { compact } from "../tool.js"; +import { parseAddressList } from "./address.js"; + +export interface GmailHeader { name?: string; value?: string } +export interface GmailMessagePart { + partId?: string; + mimeType?: string; + filename?: string; + headers?: GmailHeader[]; + body?: { attachmentId?: string; size?: number; data?: string }; + parts?: GmailMessagePart[]; +} +export interface GmailRestMessage { + id?: string; + threadId?: string; + labelIds?: string[]; + snippet?: string; + internalDate?: string; + payload?: GmailMessagePart; +} +export interface GmailRestAttachment { size?: number; data?: string } + +export type MessageDetail = "metadata_only" | "minimal" | "full"; + +export const SUMMARY_HEADERS = ["From", "To", "Cc", "Subject", "Date"] as const; + +export interface McpGmailMessage extends Record { + id: string; + snippet?: string; + subject?: string; + sender?: string; + toRecipients?: string[]; + ccRecipients?: string[]; + date?: string; + plaintextBody?: string; + attachmentIds?: string[]; + htmlBody?: string; + attachments?: Array<{ id: string; mimeType: string; filename: string }>; + labelIds?: string[]; +} + +const REPORTED_SYSTEM_LABELS = new Set(["INBOX", "SPAM", "TRASH", "UNREAD", "STARRED", "IMPORTANT", "SENT", "DRAFT", "CHAT"]); + +export const gmailId = z.string().regex(/^[A-Za-z0-9_-]{1,256}$/, "Must be a Gmail ID"); +const ATTACHMENT_ID = /^[A-Za-z0-9_-]{1,4096}$/; + +export function header(part: GmailMessagePart | undefined, name: string): string | undefined { + const lower = name.toLowerCase(); + return part?.headers?.find((item) => item.name?.toLowerCase() === lower)?.value; +} + +export function isoDate(internalDate: string | undefined): string | undefined { + if (!internalDate || !/^\d+$/.test(internalDate)) return undefined; + const date = new Date(Number(internalDate)); + return Number.isNaN(date.getTime()) ? undefined : date.toISOString().slice(0, 10); +} + +export function decodeBase64Url(data: string): string { + return Buffer.from(data, "base64url").toString("utf8"); +} + +export function reportedLabelIds(labelIds: readonly string[] | undefined): string[] { + return (labelIds ?? []).filter((id) => id.startsWith("Label_") || REPORTED_SYSTEM_LABELS.has(id)); +} + +function isAttachment(part: GmailMessagePart): boolean { + const disposition = header(part, "Content-Disposition") ?? ""; + return Boolean(part.filename) || /^\s*attachment\b/i.test(disposition); +} + +interface MessageParts { + plain?: GmailMessagePart; + html?: GmailMessagePart; + attachments: Array<{ id: string; mimeType: string; filename: string }>; +} + +export function messageParts(payload: GmailMessagePart | undefined): MessageParts { + const found: MessageParts = { attachments: [] }; + const visit = (part: GmailMessagePart) => { + if (part.parts?.length) { + for (const child of part.parts) visit(child); + return; + } + if (isAttachment(part)) { + if (part.body?.attachmentId) { + found.attachments.push({ + id: part.body.attachmentId, + mimeType: part.mimeType ?? "application/octet-stream", + filename: part.filename ?? "", + }); + } + return; + } + const mimeType = (part.mimeType ?? "").toLowerCase(); + const hasBody = part.body?.data !== undefined || Boolean(part.body?.attachmentId); + if (!hasBody) return; + if (mimeType === "text/plain" && !found.plain) found.plain = part; + else if (mimeType === "text/html" && !found.html) found.html = part; + }; + if (payload) visit(payload); + return found; +} + +export function externalBodyIds(payload: GmailMessagePart | undefined): string[] { + const { plain, html } = messageParts(payload); + return [plain, html] + .filter((part): part is GmailMessagePart => Boolean(part && part.body?.data === undefined && part.body?.attachmentId)) + .map((part) => part.body!.attachmentId!); +} + +export function bodyAttachmentRequest(messageId: string, attachmentId: string): GoogleRequest { + if (!ATTACHMENT_ID.test(attachmentId)) throw new GoogleToolError("incomplete", "Gmail returned a message body this tool cannot read."); + return { + method: "GET", + host: "gmail.googleapis.com", + path: `/gmail/v1/users/me/messages/${messageId}/attachments/${attachmentId}`, + }; +} + +export interface MessageContent { + plaintextBody?: string; + htmlBody?: string; + attachments: Array<{ id: string; mimeType: string; filename: string }>; +} + +export function messageContent(payload: GmailMessagePart | undefined, externalBodies: ReadonlyMap = new Map()): MessageContent { + const { plain, html, attachments } = messageParts(payload); + const text = (part: GmailMessagePart | undefined): string | undefined => { + if (!part) return undefined; + if (part.body?.data !== undefined) return decodeBase64Url(part.body.data); + const data = externalBodies.get(part.body?.attachmentId ?? ""); + if (data === undefined) throw new GoogleToolError("incomplete", "Could not read the full body of this message."); + return decodeBase64Url(data); + }; + return { plaintextBody: text(plain), htmlBody: text(html), attachments }; +} + +export function toMcpMessage( + message: GmailRestMessage, + detail: MessageDetail, + externalBodies?: ReadonlyMap, +): McpGmailMessage { + const payload = message.payload; + const withText = detail !== "metadata_only"; + const content = detail === "full" ? messageContent(payload, externalBodies) : undefined; + return compact({ + id: message.id ?? "", + snippet: withText ? message.snippet ?? "" : undefined, + subject: withText ? header(payload, "Subject") ?? "" : undefined, + sender: parseAddressList(header(payload, "From"))[0], + toRecipients: parseAddressList(header(payload, "To")), + ccRecipients: parseAddressList(header(payload, "Cc")), + date: isoDate(message.internalDate), + plaintextBody: content?.plaintextBody, + htmlBody: content?.htmlBody, + attachmentIds: content ? content.attachments.map((attachment) => attachment.id) : undefined, + attachments: content?.attachments, + labelIds: reportedLabelIds(message.labelIds), + }); +} diff --git a/server/src/google-workspace-rest-tools/gmail/mime.ts b/server/src/google-workspace-rest-tools/gmail/mime.ts new file mode 100644 index 00000000000..a485b85a748 --- /dev/null +++ b/server/src/google-workspace-rest-tools/gmail/mime.ts @@ -0,0 +1,96 @@ +export interface DraftMime { + to: readonly string[]; + cc: readonly string[]; + bcc: readonly string[]; + subject: string; + body?: string; + htmlBody?: string; + inReplyTo?: string; + references?: string; + boundary: string; +} + +const CRLF = "\r\n"; +export const PREFERRED_LINE_LENGTH = 78; +const MAX_ASCII_TOKEN = 900; +const ENCODED_WORD_BYTES = 39; + +function assertSingleLine(name: string, value: string): string { + if (/[\r\n]/.test(value)) throw new Error(`${name} must be a single line`); + return value; +} + +export function foldHeader(name: string, tokens: readonly string[], separator: string): string { + let line = `${name}:`; + const lines: string[] = []; + tokens.forEach((token, index) => { + const piece = index === tokens.length - 1 ? token : `${token}${separator}`; + if (piece.trim() !== "" && line.length + 1 + piece.length > PREFERRED_LINE_LENGTH && line.trim() !== `${name}:`) { + lines.push(line); + line = ""; + } + line += ` ${piece}`; + }); + lines.push(line); + return lines.join(CRLF); +} + +function encodedWords(value: string): string[] { + const words: string[] = []; + let chunk = ""; + for (const char of value) { + if (Buffer.byteLength(chunk + char, "utf8") > ENCODED_WORD_BYTES) { + words.push(chunk); + chunk = ""; + } + chunk += char; + } + if (chunk) words.push(chunk); + return words.map((word) => `=?UTF-8?B?${Buffer.from(word, "utf8").toString("base64")}?=`); +} + +export function subjectHeader(subject: string): string { + assertSingleLine("Subject", subject); + const words = subject.split(" "); + const plain = /^[\x20-\x7e]*$/.test(subject) && words.every((word) => word.length <= MAX_ASCII_TOKEN); + if (plain) { + if (`Subject: ${subject}`.length <= PREFERRED_LINE_LENGTH) return `Subject: ${subject}`; + return foldHeader("Subject", words, ""); + } + return foldHeader("Subject", encodedWords(subject), ""); +} + +function textPart(mimeType: "text/plain" | "text/html", text: string): string { + const encoded = (Buffer.from(text, "utf8").toString("base64").match(/.{1,76}/g) ?? [""]).join(CRLF); + return [`Content-Type: ${mimeType}; charset="UTF-8"`, "Content-Transfer-Encoding: base64", "", encoded].join(CRLF); +} + +export function buildDraftMime(input: DraftMime): string { + assertSingleLine("Boundary", input.boundary); + for (const address of [...input.to, ...input.cc, ...input.bcc]) assertSingleLine("Address", address); + const headers = [ + "MIME-Version: 1.0", + input.to.length ? foldHeader("To", input.to, ",") : null, + input.cc.length ? foldHeader("Cc", input.cc, ",") : null, + input.bcc.length ? foldHeader("Bcc", input.bcc, ",") : null, + subjectHeader(input.subject), + input.inReplyTo ? `In-Reply-To: ${assertSingleLine("In-Reply-To", input.inReplyTo)}` : null, + input.references ? foldHeader("References", assertSingleLine("References", input.references).split(" "), "") : null, + ].filter((line): line is string => line !== null); + + if (input.htmlBody !== undefined && input.body !== undefined) { + return [ + ...headers, + `Content-Type: multipart/alternative; boundary="${input.boundary}"`, + "", + `--${input.boundary}`, + textPart("text/plain", input.body), + `--${input.boundary}`, + textPart("text/html", input.htmlBody), + `--${input.boundary}--`, + "", + ].join(CRLF); + } + const part = input.htmlBody !== undefined ? textPart("text/html", input.htmlBody) : textPart("text/plain", input.body ?? ""); + return [...headers, part, ""].join(CRLF); +} diff --git a/server/src/google-workspace-rest-tools/gmail/schemas.ts b/server/src/google-workspace-rest-tools/gmail/schemas.ts new file mode 100644 index 00000000000..01ea4ed11cc --- /dev/null +++ b/server/src/google-workspace-rest-tools/gmail/schemas.ts @@ -0,0 +1,28 @@ +const stringArray = (description: string) => ({ type: "array", items: { type: "string" }, description }); + +export const attachmentMetadataSchema = { + type: "object", + properties: { + id: { type: "string", description: "The attachment ID." }, + mimeType: { type: "string", description: "The attachment's MIME type." }, + filename: { type: "string", description: "The attachment's file name." }, + }, +} as const; + +export const messageSchema = { + type: "object", + properties: { + id: { type: "string", description: "The message ID." }, + snippet: { type: "string", description: "A short excerpt of the message body." }, + subject: { type: "string", description: "The subject header." }, + sender: { type: "string", description: "The sender's email address." }, + toRecipients: stringArray("To recipient email addresses."), + ccRecipients: stringArray("Cc recipient email addresses."), + date: { type: "string", description: "The message date, ISO 8601 (YYYY-MM-DD)." }, + plaintextBody: { type: "string", description: "The plain-text body. Only with FULL_CONTENT." }, + attachmentIds: stringArray("Attachment IDs. Only with FULL_CONTENT."), + htmlBody: { type: "string", description: "The HTML body. Only with FULL_CONTENT." }, + attachments: { type: "array", items: attachmentMetadataSchema, description: "Attachments. Only with FULL_CONTENT." }, + labelIds: stringArray("User label IDs and the system labels INBOX, SPAM, TRASH, UNREAD, STARRED, IMPORTANT, SENT, DRAFT and CHAT."), + }, +} as const; diff --git a/server/src/google-workspace-rest-tools/gmail/search-threads.test.ts b/server/src/google-workspace-rest-tools/gmail/search-threads.test.ts new file mode 100644 index 00000000000..9a1ef2dfafe --- /dev/null +++ b/server/src/google-workspace-rest-tools/gmail/search-threads.test.ts @@ -0,0 +1,95 @@ +import { describe, expect, it } from "vitest"; +import { GoogleWorkspaceAuthError } from "../errors.js"; +import { createGoogleHttp } from "../google-http.js"; +import { fakeGoogle, json } from "../fixtures/fake-google.js"; +import { THREAD_LIST, THREAD_ONE } from "./fixtures/gmail-rest.js"; +import { effectiveQuery, listThreadsRequest, searchThreads, searchThreadsResult } from "./search-threads.js"; + +describe("search_threads request", () => { + it("excludes drafts unless the query asks for them", () => { + expect(effectiveQuery({})).toBe("-in:draft"); + expect(effectiveQuery({ query: "from:avery@example.test" })).toBe("(from:avery@example.test) -in:draft"); + expect(effectiveQuery({ query: "from:a@example.test OR from:b@example.test" })).toBe("(from:a@example.test OR from:b@example.test) -in:draft"); + expect(effectiveQuery({ query: "in:draft subject:plan" })).toBe("in:draft subject:plan"); + expect(effectiveQuery({ query: "-in:draft is:unread" })).toBe("-in:draft is:unread"); + expect(effectiveQuery({ query: "in:anywhere plan" })).toBe("in:anywhere plan"); + }); + + it("ignores operator-looking text inside quotes", () => { + expect(effectiveQuery({ query: "subject:\"go in:draft mode\"" })).toBe("(subject:\"go in:draft mode\") -in:draft"); + expect(effectiveQuery({ query: "\"in:spam\" report", includeTrash: true })).toBe("(\"in:spam\" report) -in:draft -in:spam"); + expect(effectiveQuery({ query: "\"quoted\" in:draft" })).toBe("\"quoted\" in:draft"); + }); + + it("adds trash but not spam for includeTrash", () => { + expect(effectiveQuery({ includeTrash: true })).toBe("-in:draft -in:spam"); + expect(listThreadsRequest({ includeTrash: true }).query).toMatchObject({ includeSpamTrash: true }); + expect(listThreadsRequest({}).query?.includeSpamTrash).toBeUndefined(); + }); + + it("defaults the page size to 20 and caps it at 50", () => { + expect(listThreadsRequest({}).query?.maxResults).toBe(20); + expect(listThreadsRequest({ pageSize: 500 }).query?.maxResults).toBe(50); + expect(listThreadsRequest({ pageSize: 5, pageToken: "page-2-token" }).query).toMatchObject({ maxResults: 5, pageToken: "page-2-token" }); + }); +}); + +describe("search_threads result", () => { + it("maps threads to Google's MCP SearchThreadsResponse", () => { + const result = searchThreadsResult(THREAD_LIST, [THREAD_ONE, null], {}); + expect(result.structuredContent).toEqual({ + threads: [{ + id: "18c0ffee00000000", + messages: [ + { + id: "18c0ffee00000001", snippet: "Here is the quarterly plan we discussed", subject: "Quarterly plan", + sender: "avery@example.test", toRecipients: ["blake@example.test", "casey@example.test"], + ccRecipients: ["drew@example.test"], date: "2025-11-17", labelIds: ["INBOX", "UNREAD", "Label_42"], + }, + { + id: "18c0ffee00000002", snippet: "Thanks, looks good", subject: "Re: Quarterly plan", sender: "blake@example.test", + toRecipients: ["avery@example.test"], ccRecipients: [], date: "2025-11-18", labelIds: ["SENT"], + }, + ], + }], + nextPageToken: "page-2-token", + resultCountEstimate: "201", + }); + }); + + it("leaves snippet and subject out of THREAD_VIEW_METADATA_ONLY", () => { + const result = searchThreadsResult(THREAD_LIST, [THREAD_ONE], { view: "THREAD_VIEW_METADATA_ONLY" }); + const message = (result.structuredContent as { threads: Array<{ messages: Array> }> }).threads[0]!.messages[0]!; + expect(message).not.toHaveProperty("snippet"); + expect(message).not.toHaveProperty("subject"); + expect(message.sender).toBe("avery@example.test"); + }); + + it("returns an empty page without nextPageToken", () => { + expect(searchThreadsResult({ resultSizeEstimate: 0 }, [], {}).structuredContent).toEqual({ threads: [], resultCountEstimate: "0" }); + }); +}); + +describe("search_threads tool", () => { + it("lists, then reads each thread's metadata, skipping a thread deleted in between", async () => { + const { fetch, calls } = fakeGoogle(({ url }) => { + if (url.pathname.endsWith("/threads")) return json(THREAD_LIST); + if (url.pathname.endsWith("/threads/18c0ffee00000000")) return json(THREAD_ONE); + return json({ error: { code: 404 } }, 404); + }); + const result = await searchThreads.call({ query: "plan" }, createGoogleHttp({ accessToken: "t", fetch })); + expect(result.isError).toBeUndefined(); + expect((result.structuredContent as { threads: unknown[] }).threads).toHaveLength(1); + expect(calls.map((call) => `${call.method} ${call.url.pathname}`)).toEqual([ + "GET /gmail/v1/users/me/threads", + "GET /gmail/v1/users/me/threads/18c0ffee00000000", + "GET /gmail/v1/users/me/threads/18c0ffee00000010", + ]); + expect(calls[1]!.url.searchParams.get("format")).toBe("metadata"); + }); + + it("surfaces an auth failure on a thread read instead of a partial page", async () => { + const { fetch } = fakeGoogle(({ url }) => (url.pathname.endsWith("/threads") ? json(THREAD_LIST) : json({}, 401))); + await expect(searchThreads.call({}, createGoogleHttp({ accessToken: "t", fetch }))).rejects.toBeInstanceOf(GoogleWorkspaceAuthError); + }); +}); diff --git a/server/src/google-workspace-rest-tools/gmail/search-threads.ts b/server/src/google-workspace-rest-tools/gmail/search-threads.ts new file mode 100644 index 00000000000..d148c9badda --- /dev/null +++ b/server/src/google-workspace-rest-tools/gmail/search-threads.ts @@ -0,0 +1,155 @@ +import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js"; +import { z } from "zod"; +import { GoogleToolError } from "../errors.js"; +import type { GoogleHttp, GoogleRequest } from "../google-http.js"; +import { compact, defineTool, structuredResult } from "../tool.js"; +import { SUMMARY_HEADERS, toMcpMessage, type GmailRestMessage, type McpGmailMessage, type MessageDetail } from "./message.js"; +import { messageSchema } from "./schemas.js"; + +const THREAD_VIEWS = ["THREAD_VIEW_UNSPECIFIED", "THREAD_VIEW_MINIMAL", "THREAD_VIEW_METADATA_ONLY"] as const; +export const DEFAULT_PAGE_SIZE = 20; +export const MAX_PAGE_SIZE = 50; +const THREAD_FETCH_CONCURRENCY = 10; + +const args = z.object({ + pageSize: z.number().int().positive().optional(), + pageToken: z.string().max(2048).optional(), + query: z.string().max(4096).optional(), + includeTrash: z.boolean().optional(), + view: z.enum(THREAD_VIEWS).optional(), +}); +export type SearchThreadsArgs = z.infer; + +interface GmailThreadList { + threads?: Array<{ id?: string }>; + nextPageToken?: string; + resultSizeEstimate?: number; +} +interface GmailRestThread { id?: string; messages?: GmailRestMessage[] } + +export function unquotedOperators(query: string): string { + return query.replace(/"[^"]*"?/g, " "); +} + +export function effectiveQuery(input: SearchThreadsArgs): string { + const query = (input.query ?? "").trim(); + const operators = unquotedOperators(query); + const added: string[] = []; + if (!/(^|[\s({])-?(in|is):(drafts?|anywhere)\b/i.test(operators)) added.push("-in:draft"); + if (input.includeTrash && !/(^|[\s({])-?(in|is):(spam|anywhere)\b/i.test(operators)) added.push("-in:spam"); + if (!query) return added.join(" "); + if (added.length === 0) return query; + return [`(${query})`, ...added].join(" "); +} + +export function threadDetail(view: SearchThreadsArgs["view"]): MessageDetail { + return view === "THREAD_VIEW_METADATA_ONLY" ? "metadata_only" : "minimal"; +} + +export function listThreadsRequest(input: SearchThreadsArgs): GoogleRequest { + return { + method: "GET", + host: "gmail.googleapis.com", + path: "/gmail/v1/users/me/threads", + query: { + q: effectiveQuery(input), + maxResults: Math.min(input.pageSize ?? DEFAULT_PAGE_SIZE, MAX_PAGE_SIZE), + pageToken: input.pageToken || undefined, + includeSpamTrash: input.includeTrash ? true : undefined, + }, + }; +} + +export function threadIds(list: GmailThreadList): string[] { + return (list.threads ?? []).map((thread) => thread.id).filter((id): id is string => typeof id === "string" && /^[A-Za-z0-9_-]+$/.test(id)); +} + +export function getThreadRequest(threadId: string): GoogleRequest { + return { + method: "GET", + host: "gmail.googleapis.com", + path: `/gmail/v1/users/me/threads/${threadId}`, + query: { format: "metadata", metadataHeaders: SUMMARY_HEADERS }, + }; +} + +export function searchThreadsResult(list: GmailThreadList, threads: Array, input: SearchThreadsArgs): CallToolResult { + const detail = threadDetail(input.view); + const mapped = threads.filter((thread): thread is GmailRestThread => thread !== null).map((thread) => ({ + id: thread.id ?? "", + messages: (thread.messages ?? []).map((message): McpGmailMessage => toMcpMessage(message, detail)), + })); + return structuredResult(compact({ + threads: mapped, + nextPageToken: list.nextPageToken || undefined, + resultCountEstimate: typeof list.resultSizeEstimate === "number" ? String(list.resultSizeEstimate) : undefined, + })); +} + +async function readThreads(ids: string[], http: GoogleHttp): Promise> { + const results: Array = new Array(ids.length).fill(null); + let next = 0; + let failed = false; + const worker = async () => { + while (!failed && next < ids.length) { + const index = next++; + try { + results[index] = await http.send(getThreadRequest(ids[index]!)); + } catch (error) { + if (error instanceof GoogleToolError && error.kind === "not_found") continue; + failed = true; + throw error; + } + } + }; + await Promise.all(Array.from({ length: Math.min(THREAD_FETCH_CONCURRENCY, ids.length) }, worker)); + return results; +} + +export const searchThreads = defineTool({ + definition: { + name: "search_threads", + description: "Lists the signed-in user's Gmail threads that match an optional Gmail search query, one page at a time. Returns thread IDs with message summaries, not full bodies; use get_message with a message ID for a full message. A thread matches when any of its messages matches.", + inputSchema: { + type: "object", + properties: { + pageSize: { type: "integer", description: "Optional. Most threads to return. Default 20, maximum 50." }, + pageToken: { type: "string", description: "Optional. The nextPageToken from a previous call. Leave empty for the first page." }, + query: { + type: "string", + description: "Optional. A Gmail search query (for example `from:user@example.com newer_than:7d has:attachment`). Convert natural language to Gmail syntax first. `label:` takes label IDs, not display names. Without a query, all threads except spam and trash are listed. Drafts are excluded unless the query includes in:draft.", + }, + includeTrash: { type: "boolean", description: "Optional. Include threads in Trash. Default false." }, + view: { + type: "string", + enum: [...THREAD_VIEWS], + description: "Optional. THREAD_VIEW_MINIMAL (default) returns id, snippet, subject, sender, recipients, date and labels. THREAD_VIEW_METADATA_ONLY leaves out snippet and subject.", + }, + }, + }, + outputSchema: { + type: "object", + properties: { + threads: { + type: "array", + description: "Matching threads.", + items: { + type: "object", + properties: { + id: { type: "string", description: "The thread ID." }, + messages: { type: "array", items: messageSchema, description: "The thread's messages, oldest first." }, + }, + }, + }, + nextPageToken: { type: "string", description: "Pass as pageToken to get the next page. Present only when there are more results." }, + resultCountEstimate: { type: "string", description: "Estimated number of results; treat as a lower bound." }, + }, + }, + annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false }, + }, + args, + async run(input, http) { + const list = await http.send(listThreadsRequest(input)); + return searchThreadsResult(list, await readThreads(threadIds(list), http), input); + }, +}); diff --git a/server/src/google-workspace-rest-tools/google-http.test.ts b/server/src/google-workspace-rest-tools/google-http.test.ts new file mode 100644 index 00000000000..a1929345bfb --- /dev/null +++ b/server/src/google-workspace-rest-tools/google-http.test.ts @@ -0,0 +1,208 @@ +import { describe, expect, it } from "vitest"; +import { GoogleToolError, GoogleWorkspaceAuthError } from "./errors.js"; +import { fakeGoogle, json } from "./fixtures/fake-google.js"; +import { createGoogleHttp, googleRequestUrl, MAX_RESPONSE_BYTES, type GoogleRequest } from "./google-http.js"; + +const GET: GoogleRequest = { method: "GET", host: "gmail.googleapis.com", path: "/gmail/v1/users/me/labels" }; +const POST: GoogleRequest = { method: "POST", host: "gmail.googleapis.com", path: "/gmail/v1/users/me/drafts", body: { message: { raw: "eA" } } }; + +function client(route: Parameters[0], timeoutMs?: number) { + const fake = fakeGoogle(route); + return { http: createGoogleHttp({ accessToken: "test-token", fetch: fake.fetch, retryDelayMs: 0, timeoutMs }), calls: fake.calls }; +} + +async function failure(promise: Promise): Promise { + try { + await promise; + } catch (error) { + return error; + } + throw new Error("expected a failure"); +} + +describe("googleRequestUrl", () => { + it("builds an https googleapis.com URL with repeated array parameters", () => { + const url = new URL(googleRequestUrl({ ...GET, query: { format: "metadata", metadataHeaders: ["From", "To"], skip: undefined, max: 5 } })); + expect(url.origin).toBe("https://gmail.googleapis.com"); + expect(url.searchParams.getAll("metadataHeaders")).toEqual(["From", "To"]); + expect(url.searchParams.get("max")).toBe("5"); + expect(url.searchParams.has("skip")).toBe(false); + }); + + it("refuses hosts outside the allowlist and relative paths", () => { + expect(() => googleRequestUrl({ ...GET, host: "evil.example.test" as never })).toThrow(/not allowed/); + expect(() => googleRequestUrl({ ...GET, path: "//evil.example.test/x" })).toThrow(/absolute/); + }); +}); + +describe("createGoogleHttp", () => { + it("sends the bearer token and JSON body, and parses the JSON answer", async () => { + const { http, calls } = client(() => json({ id: "r-1" })); + await expect(http.send(POST)).resolves.toEqual({ id: "r-1" }); + expect(calls[0]!.headers.authorization).toBe("Bearer test-token"); + expect(calls[0]!.headers["content-type"]).toBe("application/json"); + expect(calls[0]!.body).toEqual({ message: { raw: "eA" } }); + }); + + it("maps 401 to an unauthenticated auth error", async () => { + const { http } = client(() => json({ error: { code: 401, status: "UNAUTHENTICATED" } }, 401)); + const error = await failure(http.send(GET)); + expect(error).toBeInstanceOf(GoogleWorkspaceAuthError); + expect((error as GoogleWorkspaceAuthError).reason).toBe("unauthenticated"); + expect((error as GoogleWorkspaceAuthError).data).toEqual({ code: "unauthenticated", httpStatus: 401 }); + }); + + it("maps 403 insufficient scope, from the body or the WWW-Authenticate header, to an insufficient_scope auth error", async () => { + const fromBody = client(() => json({ error: { code: 403, status: "PERMISSION_DENIED", details: [{ reason: "ACCESS_TOKEN_SCOPE_INSUFFICIENT" }] } }, 403)); + const fromLegacyBody = client(() => json({ error: { code: 403, errors: [{ reason: "insufficientPermissions" }] } }, 403)); + const fromHeader = client(() => json({}, 403, { "www-authenticate": "Bearer error=\"insufficient_scope\", scope=\"x\"" })); + for (const { http } of [fromBody, fromLegacyBody, fromHeader]) { + const error = await failure(http.send(GET)); + expect(error).toBeInstanceOf(GoogleWorkspaceAuthError); + expect((error as GoogleWorkspaceAuthError).reason).toBe("insufficient_scope"); + expect((error as GoogleWorkspaceAuthError).data).toEqual({ code: "insufficient_scope", httpStatus: 403 }); + } + }); + + it("keeps other 403s apart from scope errors", async () => { + const disabled = await failure(client(() => json({ error: { code: 403, details: [{ reason: "SERVICE_DISABLED" }], message: "Gmail API has not been used in project 123" } }, 403)).http.send(GET)); + expect(disabled).toMatchObject({ kind: "api_disabled" }); + expect((disabled as Error).message).not.toContain("123"); + const denied = await failure(client(() => json({ error: { code: 403, message: "Delegation denied" } }, 403)).http.send(GET)); + expect(denied).toBeInstanceOf(GoogleToolError); + expect(denied).toMatchObject({ kind: "permission_denied", message: "Delegation denied" }); + }); + + it.each([ + [404, "not_found"], + [400, "invalid_argument"], + [429, "rate_limited"], + [500, "unavailable"], + ])("maps HTTP %i to %s", async (status, kind) => { + const error = await failure(client(() => json({ error: { code: status, message: "x" } }, status)).http.send(POST)); + expect(error).toMatchObject({ kind, httpStatus: status }); + }); + + it("retries a read once after 503, then succeeds", async () => { + let count = 0; + const { http, calls } = client(() => (count++ === 0 ? json({}, 503) : json({ labels: [] }))); + await expect(http.send(GET)).resolves.toEqual({ labels: [] }); + expect(calls).toHaveLength(2); + }); + + it("retries a read at most once", async () => { + const { http, calls } = client(() => json({}, 503)); + expect(await failure(http.send(GET))).toMatchObject({ kind: "unavailable" }); + expect(calls).toHaveLength(2); + }); + + it("never retries a write, after a 503 or a network failure", async () => { + const after503 = client(() => json({}, 503)); + expect(await failure(after503.http.send(POST))).toMatchObject({ kind: "unavailable" }); + expect(after503.calls).toHaveLength(1); + + const afterNetwork = client(() => { throw new TypeError("fetch failed"); }); + expect(await failure(afterNetwork.http.send(POST))).toMatchObject({ kind: "network" }); + expect(afterNetwork.calls).toHaveLength(1); + }); + + it("warns that a failed write may have been applied, for network errors, 5xx and caller cancellation", async () => { + const network = await failure(client(() => { throw new TypeError("fetch failed"); }).http.send(POST)); + expect((network as Error).message).toMatch(/may or may not have been made/); + const unavailable = await failure(client(() => json({}, 503)).http.send(POST)); + expect((unavailable as Error).message).toMatch(/may or may not have been made/); + + const controller = new AbortController(); + const cancelled = createGoogleHttp({ + accessToken: "test-token", + signal: controller.signal, + fetch: (_url, init) => new Promise((_resolve, reject) => { + init.signal?.addEventListener("abort", () => reject(init.signal?.reason)); + controller.abort(); + }), + }); + const error = await failure(cancelled.send(POST)); + expect(error).toMatchObject({ kind: "timeout" }); + expect((error as Error).message).toMatch(/may or may not have been made/); + + const readFailure = await failure(client(() => { throw new TypeError("fetch failed"); }).http.send(GET)); + expect((readFailure as Error).message).not.toMatch(/may or may not/); + }); + + it("warns that a write may have been applied when Google's success answer is unusable", async () => { + const html = await failure(client(() => new Response("ok", { status: 200 })).http.send(POST)); + expect(html).toMatchObject({ kind: "invalid_response" }); + expect((html as Error).message).toMatch(/may or may not have been made/); + + const oversized = await failure(client(() => new Response("{}", { headers: { "content-length": String(MAX_RESPONSE_BYTES + 1) } })).http.send(POST)); + expect(oversized).toMatchObject({ kind: "invalid_response" }); + expect((oversized as Error).message).toMatch(/may or may not have been made/); + + const readHtml = await failure(client(() => new Response("")).http.send(GET)); + expect((readHtml as Error).message).not.toMatch(/may or may not/); + }); + + it("treats a connection that drops while the body streams like any network failure", async () => { + const dropping = () => new Response(new ReadableStream({ + start(controller) { + controller.enqueue(new TextEncoder().encode("{\"partial\":")); + controller.error(new TypeError("terminated")); + }, + }), { status: 200 }); + + let reads = 0; + const read = client(() => (reads++ === 0 ? dropping() : json({ ok: true }))); + await expect(read.http.send(GET)).resolves.toEqual({ ok: true }); + expect(read.calls).toHaveLength(2); + + const write = client(() => dropping()); + const error = await failure(write.http.send(POST)); + expect(error).toBeInstanceOf(GoogleToolError); + expect(error).toMatchObject({ kind: "network" }); + expect((error as Error).message).toMatch(/may or may not have been made/); + expect(write.calls).toHaveLength(1); + }); + + it("retries a read once after a network failure", async () => { + let count = 0; + const { http, calls } = client(() => { + if (count++ === 0) throw new TypeError("fetch failed"); + return json({ ok: true }); + }); + await expect(http.send(GET)).resolves.toEqual({ ok: true }); + expect(calls).toHaveLength(2); + }); + + it("stops a request at its deadline and says a write's outcome is unknown", async () => { + let calls = 0; + const slow = createGoogleHttp({ + accessToken: "test-token", + retryDelayMs: 0, + timeoutMs: 20, + fetch: (_url, init) => new Promise((_resolve, reject) => { + calls += 1; + init.signal?.addEventListener("abort", () => reject(init.signal?.reason)); + }), + }); + const error = await failure(slow.send(POST)); + expect(error).toMatchObject({ kind: "timeout" }); + expect((error as Error).message).toMatch(/may or may not/); + expect(calls).toBe(1); + }); + + it("sends nothing to a disallowed host, and does not treat it as a network failure", async () => { + const { http, calls } = client(() => json({})); + const error = await failure(http.send({ ...GET, host: "evil.example.test" as never })); + expect(error).not.toBeInstanceOf(GoogleToolError); + expect(calls).toHaveLength(0); + }); + + it("rejects an oversized response", async () => { + const declared = client(() => new Response("{}", { headers: { "content-length": String(MAX_RESPONSE_BYTES + 1) } })); + expect(await failure(declared.http.send(GET))).toMatchObject({ kind: "invalid_response" }); + }); + + it("rejects a non-JSON success body", async () => { + expect(await failure(client(() => new Response("")).http.send(GET))).toMatchObject({ kind: "invalid_response" }); + }); +}); diff --git a/server/src/google-workspace-rest-tools/google-http.ts b/server/src/google-workspace-rest-tools/google-http.ts new file mode 100644 index 00000000000..0357b763d4a --- /dev/null +++ b/server/src/google-workspace-rest-tools/google-http.ts @@ -0,0 +1,229 @@ +import { GoogleToolError, GoogleWorkspaceAuthError } from "./errors.js"; + +export const GOOGLE_API_HOSTS = ["gmail.googleapis.com"] as const; +export type GoogleApiHost = (typeof GOOGLE_API_HOSTS)[number]; + +export type QueryValue = string | number | boolean | readonly string[] | undefined; + +export interface GoogleRequest { + method: "GET" | "POST"; + host: GoogleApiHost; + path: string; + query?: Record; + body?: unknown; +} + +export type GoogleFetch = (url: string, init: RequestInit) => Promise; + +export interface GoogleHttpOptions { + accessToken: string; + fetch?: GoogleFetch; + signal?: AbortSignal; + timeoutMs?: number; + retryDelayMs?: number; +} + +export interface GoogleHttp { + send(request: GoogleRequest): Promise; +} + +interface GoogleAnswer { + status: number; + headers: Headers; + text: string; +} + +export const DEFAULT_TIMEOUT_MS = 20_000; +export const MAX_RESPONSE_BYTES = 20 * 1024 * 1024; +const RETRYABLE_READ_STATUSES = new Set([502, 503, 504]); +const DEFAULT_RETRY_DELAY_MS = 250; +const MAX_ERROR_MESSAGE_LENGTH = 300; +export const UNCERTAIN_WRITE = "The change may or may not have been made; check before trying again."; + +export function googleRequestUrl(request: GoogleRequest): string { + if (!GOOGLE_API_HOSTS.includes(request.host)) throw new Error(`Host is not allowed: ${request.host}`); + if (!request.path.startsWith("/") || request.path.startsWith("//")) throw new Error("Request path must be absolute"); + const url = new URL(`https://${request.host}${request.path}`); + for (const [key, value] of Object.entries(request.query ?? {})) { + if (value === undefined) continue; + if (Array.isArray(value)) for (const item of value) url.searchParams.append(key, item); + else url.searchParams.set(key, String(value)); + } + return url.toString(); +} + +function isWrite(request: GoogleRequest): boolean { + return request.method !== "GET"; +} + +function withWriteWarning(request: GoogleRequest, message: string): string { + return isWrite(request) ? `${message} ${UNCERTAIN_WRITE}` : message; +} + +export function createGoogleHttp(options: GoogleHttpOptions): GoogleHttp { + const doFetch = options.fetch ?? ((url, init) => fetch(url, init)); + const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS; + const retryDelayMs = options.retryDelayMs ?? DEFAULT_RETRY_DELAY_MS; + + async function attempt(request: GoogleRequest): Promise { + const signal = AbortSignal.any([AbortSignal.timeout(timeoutMs), ...(options.signal ? [options.signal] : [])]); + const headers: Record = { + Authorization: `Bearer ${options.accessToken}`, + Accept: "application/json", + }; + if (request.body !== undefined) headers["Content-Type"] = "application/json"; + const url = googleRequestUrl(request); + try { + const response = await doFetch(url, { + method: request.method, + headers, + body: request.body === undefined ? undefined : JSON.stringify(request.body), + signal, + redirect: "error", + }); + return { status: response.status, headers: response.headers, text: await readBounded(response) }; + } catch (error) { + if (error instanceof GoogleToolError) { + throw new GoogleToolError(error.kind, withWriteWarning(request, error.message), error.httpStatus); + } + if (options.signal?.aborted) throw new GoogleToolError("timeout", withWriteWarning(request, "The request was cancelled.")); + if (isAbort(error)) throw new GoogleToolError("timeout", withWriteWarning(request, "Google did not answer in time.")); + throw new GoogleToolError("network", withWriteWarning(request, "Could not reach Google.")); + } + } + + return { + async send(request: GoogleRequest): Promise { + let answer: GoogleAnswer; + for (let tries = 0; ; tries += 1) { + const mayRetry = !isWrite(request) && tries === 0; + try { + answer = await attempt(request); + } catch (error) { + if (mayRetry && error instanceof GoogleToolError && error.kind === "network") { + await delay(retryDelayMs, options.signal); + continue; + } + throw error; + } + if (mayRetry && RETRYABLE_READ_STATUSES.has(answer.status)) { + await delay(retryDelayMs, options.signal); + continue; + } + break; + } + if (answer.status < 200 || answer.status >= 300) throw googleError(answer, answer.text, request); + if (answer.text.length === 0) return {} as T; + try { + return JSON.parse(answer.text) as T; + } catch { + throw new GoogleToolError("invalid_response", withWriteWarning(request, "Google returned a response that is not JSON."), answer.status); + } + }, + }; +} + +async function readBounded(response: Response): Promise { + const declared = Number(response.headers.get("content-length") ?? "0"); + if (declared > MAX_RESPONSE_BYTES) { + await response.body?.cancel().catch(() => undefined); + throw new GoogleToolError("invalid_response", "Google's response is too large.", response.status); + } + if (!response.body) return ""; + const reader = response.body.getReader(); + const chunks: Uint8Array[] = []; + let size = 0; + for (;;) { + const { done, value } = await reader.read(); + if (done) break; + size += value.byteLength; + if (size > MAX_RESPONSE_BYTES) { + await reader.cancel().catch(() => undefined); + throw new GoogleToolError("invalid_response", "Google's response is too large.", response.status); + } + chunks.push(value); + } + return Buffer.concat(chunks).toString("utf8"); +} + +interface GoogleErrorBody { + error?: { + code?: number; + message?: string; + status?: string; + errors?: Array<{ reason?: string }>; + details?: Array<{ reason?: string }>; + } | string; +} + +export function googleError( + response: { status: number; headers: Pick }, + text: string, + request?: GoogleRequest, +): Error { + const status = response.status; + let body: GoogleErrorBody = {}; + try { + body = JSON.parse(text) as GoogleErrorBody; + } catch { + body = {}; + } + const error = typeof body.error === "object" ? body.error : undefined; + const reasons = new Set([ + ...(error?.errors ?? []).map((item) => item.reason), + ...(error?.details ?? []).map((item) => item.reason), + typeof body.error === "string" ? body.error : undefined, + ].filter((reason): reason is string => typeof reason === "string")); + const authenticate = response.headers.get("www-authenticate") ?? ""; + + if (status === 401) return new GoogleWorkspaceAuthError("unauthenticated"); + if (status === 403 && ( + /\berror\s*=\s*"?insufficient_scope\b/i.test(authenticate) + || reasons.has("ACCESS_TOKEN_SCOPE_INSUFFICIENT") + || reasons.has("insufficientPermissions") + || reasons.has("insufficient_scope") + )) return new GoogleWorkspaceAuthError("insufficient_scope"); + + const message = safeMessage(error?.message); + if (status === 403 && (reasons.has("SERVICE_DISABLED") || reasons.has("accessNotConfigured"))) { + return new GoogleToolError("api_disabled", "This Google API is not enabled for the Google Cloud project behind this connection.", status); + } + if (status === 429 || reasons.has("RATE_LIMIT_EXCEEDED") || reasons.has("rateLimitExceeded") || reasons.has("userRateLimitExceeded")) { + return new GoogleToolError("rate_limited", "Google is rate limiting requests. Try again shortly.", status); + } + if (status === 403) return new GoogleToolError("permission_denied", message ?? "Google denied access to this item.", status); + if (status === 404) return new GoogleToolError("not_found", "Google could not find that item.", status); + if (status === 400 || status === 409 || status === 412 || status === 413) { + return new GoogleToolError("invalid_argument", message ?? "Google rejected the request.", status); + } + if (status >= 500) { + const unavailable = "Google is temporarily unavailable."; + return new GoogleToolError("unavailable", request && isWrite(request) ? withWriteWarning(request, unavailable) : `${unavailable} Try again shortly.`, status); + } + return new GoogleToolError("invalid_response", message ?? `Google returned HTTP ${status}.`, status); +} + +function safeMessage(value: unknown): string | undefined { + if (typeof value !== "string" || value.trim().length === 0) return undefined; + const oneLine = value.replace(/\s+/g, " ").trim(); + return oneLine.length > MAX_ERROR_MESSAGE_LENGTH ? `${oneLine.slice(0, MAX_ERROR_MESSAGE_LENGTH)}…` : oneLine; +} + +function isAbort(error: unknown): boolean { + return error instanceof Error && (error.name === "AbortError" || error.name === "TimeoutError"); +} + +function delay(ms: number, signal?: AbortSignal): Promise { + if (ms <= 0) return Promise.resolve(); + return new Promise((resolve, reject) => { + const onAbort = () => { + clearTimeout(timer); + reject(new GoogleToolError("timeout", "The request was cancelled.")); + }; + const timer = setTimeout(() => { + signal?.removeEventListener("abort", onAbort); + resolve(); + }, ms); + signal?.addEventListener("abort", onAbort, { once: true }); + }); +} diff --git a/server/src/google-workspace-rest-tools/index.ts b/server/src/google-workspace-rest-tools/index.ts new file mode 100644 index 00000000000..bdf216cd81b --- /dev/null +++ b/server/src/google-workspace-rest-tools/index.ts @@ -0,0 +1,11 @@ +export { + GOOGLE_WORKSPACE_REST_SERVICES, + callGoogleWorkspaceRestTool, + isGoogleWorkspaceRestService, + listGoogleWorkspaceRestTools, + type CallGoogleWorkspaceRestToolInput, + type GoogleWorkspaceRestService, +} from "./tools.js"; +export { createGoogleWorkspaceRestServer, type GoogleWorkspaceRestServerOptions } from "./server.js"; +export { GOOGLE_AUTH_ERROR_CODE, GoogleWorkspaceAuthError, type GoogleAuthFailure } from "./errors.js"; +export type { GoogleFetch } from "./google-http.js"; diff --git a/server/src/google-workspace-rest-tools/server.test.ts b/server/src/google-workspace-rest-tools/server.test.ts new file mode 100644 index 00000000000..55d0dc7c864 --- /dev/null +++ b/server/src/google-workspace-rest-tools/server.test.ts @@ -0,0 +1,65 @@ +import { Client } from "@modelcontextprotocol/sdk/client/index.js"; +import { InMemoryTransport } from "@modelcontextprotocol/sdk/inMemory.js"; +import { McpError } from "@modelcontextprotocol/sdk/types.js"; +import { describe, expect, it } from "vitest"; +import { fakeGoogle, json } from "./fixtures/fake-google.js"; +import { FULL_MESSAGE } from "./gmail/fixtures/gmail-rest.js"; +import { GOOGLE_AUTH_ERROR_CODE, callGoogleWorkspaceRestTool, createGoogleWorkspaceRestServer, GoogleWorkspaceAuthError } from "./index.js"; + +async function connect(route: Parameters[0], token?: string) { + const fake = fakeGoogle(route); + const server = createGoogleWorkspaceRestServer("gmail", { fetch: fake.fetch }); + const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair(); + const send = clientTransport.send.bind(clientTransport); + clientTransport.send = (message, options) => send(message, { ...options, ...(token ? { authInfo: { token, clientId: "test", scopes: [] } } : {}) }); + await server.connect(serverTransport); + const client = new Client({ name: "test", version: "1" }); + await client.connect(clientTransport); + return { client, calls: fake.calls }; +} + +describe("MCP server", () => { + it("lists the service's tools with input and output schemas", async () => { + const { client } = await connect(() => json({})); + const { tools } = await client.listTools(); + expect(tools.map((tool) => tool.name)).toEqual(["get_message", "search_threads", "create_draft"]); + for (const tool of tools) { + expect(tool.inputSchema.type).toBe("object"); + expect(tool.outputSchema?.type).toBe("object"); + } + }); + + it("calls a tool with the bearer token from the transport", async () => { + const { client, calls } = await connect(() => json(FULL_MESSAGE), "user-token"); + const result = await client.callTool({ name: "get_message", arguments: { messageId: FULL_MESSAGE.id } }); + expect(result.isError).toBeFalsy(); + expect((result.structuredContent as { subject: string }).subject).toBe("Quarterly plan"); + expect(calls[0]!.headers.authorization).toBe("Bearer user-token"); + }); + + it("answers a missing token and a refused token with a JSON-RPC auth error", async () => { + const missing = await connect(() => json(FULL_MESSAGE)); + await expect(missing.client.callTool({ name: "get_message", arguments: { messageId: "x1" } })) + .rejects.toMatchObject({ code: GOOGLE_AUTH_ERROR_CODE, data: { code: "unauthenticated", httpStatus: 401 } }); + + const scoped = await connect(() => json({ error: { details: [{ reason: "ACCESS_TOKEN_SCOPE_INSUFFICIENT" }] } }, 403), "narrow-token"); + const error = await scoped.client.callTool({ name: "get_message", arguments: { messageId: "x1" } }).catch((caught: unknown) => caught); + expect(error).toBeInstanceOf(McpError); + expect(error).toMatchObject({ code: GOOGLE_AUTH_ERROR_CODE, data: { code: "insufficient_scope", httpStatus: 403 } }); + }); +}); + +describe("callGoogleWorkspaceRestTool", () => { + it("is the in-process equivalent of tools/call", async () => { + const { fetch } = fakeGoogle(() => json(FULL_MESSAGE)); + const result = await callGoogleWorkspaceRestTool({ service: "gmail", name: "get_message", arguments: { messageId: FULL_MESSAGE.id, messageFormat: "MINIMAL" }, accessToken: "t", fetch }); + expect(result.structuredContent).toMatchObject({ id: FULL_MESSAGE.id, subject: "Quarterly plan" }); + }); + + it("throws for an unknown tool and for a refused token", async () => { + const { fetch } = fakeGoogle(() => json({}, 401)); + await expect(callGoogleWorkspaceRestTool({ service: "gmail", name: "send_message", accessToken: "t", fetch })).rejects.toThrow(/Unknown tool/); + await expect(callGoogleWorkspaceRestTool({ service: "gmail", name: "get_message", arguments: { messageId: "x1" }, accessToken: "t", fetch })) + .rejects.toBeInstanceOf(GoogleWorkspaceAuthError); + }); +}); diff --git a/server/src/google-workspace-rest-tools/server.ts b/server/src/google-workspace-rest-tools/server.ts new file mode 100644 index 00000000000..32daf3f2c68 --- /dev/null +++ b/server/src/google-workspace-rest-tools/server.ts @@ -0,0 +1,32 @@ +import { Server } from "@modelcontextprotocol/sdk/server/index.js"; +import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js"; +import { GoogleWorkspaceAuthError } from "./errors.js"; +import type { GoogleFetch } from "./google-http.js"; +import { callGoogleWorkspaceRestTool, listGoogleWorkspaceRestTools, type GoogleWorkspaceRestService } from "./tools.js"; + +export interface GoogleWorkspaceRestServerOptions { + fetch?: GoogleFetch; + timeoutMs?: number; +} + +export function createGoogleWorkspaceRestServer(service: GoogleWorkspaceRestService, options: GoogleWorkspaceRestServerOptions = {}): Server { + const server = new Server( + { name: `paperclip-google-workspace-rest-${service}`, version: "0.1.0" }, + { capabilities: { tools: {} } }, + ); + server.setRequestHandler(ListToolsRequestSchema, () => ({ tools: listGoogleWorkspaceRestTools(service) })); + server.setRequestHandler(CallToolRequestSchema, (request, extra) => { + const accessToken = extra.authInfo?.token; + if (!accessToken) throw new GoogleWorkspaceAuthError("unauthenticated"); + return callGoogleWorkspaceRestTool({ + service, + name: request.params.name, + arguments: request.params.arguments, + accessToken, + fetch: options.fetch, + signal: extra.signal, + timeoutMs: options.timeoutMs, + }); + }); + return server; +} diff --git a/server/src/google-workspace-rest-tools/tool.ts b/server/src/google-workspace-rest-tools/tool.ts new file mode 100644 index 00000000000..32faca90e40 --- /dev/null +++ b/server/src/google-workspace-rest-tools/tool.ts @@ -0,0 +1,46 @@ +import type { CallToolResult, Tool } from "@modelcontextprotocol/sdk/types.js"; +import type { z } from "zod"; +import { GoogleToolError } from "./errors.js"; +import type { GoogleHttp } from "./google-http.js"; + +export interface RestToolSpec { + definition: Tool; + args: z.ZodType; + run(args: Args, http: GoogleHttp): Promise; +} + +export interface RestTool { + definition: Tool; + call(rawArgs: unknown, http: GoogleHttp): Promise; +} + +export function defineTool(spec: RestToolSpec): RestTool { + return { + definition: spec.definition, + async call(rawArgs, http) { + const parsed = spec.args.safeParse(rawArgs ?? {}); + if (!parsed.success) { + const detail = parsed.error.issues.map((issue) => `${issue.path.join(".") || "arguments"}: ${issue.message}`).join("; "); + return { isError: true, content: [{ type: "text", text: `Invalid arguments for ${spec.definition.name}: ${detail}` }] }; + } + try { + return await spec.run(parsed.data, http); + } catch (error) { + if (error instanceof GoogleToolError) return toolErrorResult(error); + throw error; + } + }, + }; +} + +export function structuredResult(value: Record): CallToolResult { + return { content: [{ type: "text", text: JSON.stringify(value) }], structuredContent: value }; +} + +export function toolErrorResult(error: GoogleToolError): CallToolResult { + return { isError: true, content: [{ type: "text", text: error.message }] }; +} + +export function compact>(value: T): T { + return Object.fromEntries(Object.entries(value).filter(([, item]) => item !== undefined)) as T; +} diff --git a/server/src/google-workspace-rest-tools/tools.ts b/server/src/google-workspace-rest-tools/tools.ts new file mode 100644 index 00000000000..6a4301bcb0c --- /dev/null +++ b/server/src/google-workspace-rest-tools/tools.ts @@ -0,0 +1,39 @@ +import type { CallToolResult, Tool } from "@modelcontextprotocol/sdk/types.js"; +import { McpError, ErrorCode } from "@modelcontextprotocol/sdk/types.js"; +import { GoogleWorkspaceAuthError } from "./errors.js"; +import { GMAIL_TOOLS } from "./gmail/index.js"; +import { createGoogleHttp, type GoogleFetch } from "./google-http.js"; +import type { RestTool } from "./tool.js"; + +export const GOOGLE_WORKSPACE_REST_SERVICES = ["gmail"] as const; +export type GoogleWorkspaceRestService = (typeof GOOGLE_WORKSPACE_REST_SERVICES)[number]; + +const TOOLS: Record = { + gmail: GMAIL_TOOLS, +}; + +export function isGoogleWorkspaceRestService(value: string): value is GoogleWorkspaceRestService { + return (GOOGLE_WORKSPACE_REST_SERVICES as readonly string[]).includes(value); +} + +export function listGoogleWorkspaceRestTools(service: GoogleWorkspaceRestService): Tool[] { + return TOOLS[service].map((tool) => tool.definition); +} + +export interface CallGoogleWorkspaceRestToolInput { + service: GoogleWorkspaceRestService; + name: string; + arguments?: Record; + accessToken: string; + fetch?: GoogleFetch; + signal?: AbortSignal; + timeoutMs?: number; +} + +export async function callGoogleWorkspaceRestTool(input: CallGoogleWorkspaceRestToolInput): Promise { + const tool = TOOLS[input.service].find((candidate) => candidate.definition.name === input.name); + if (!tool) throw new McpError(ErrorCode.InvalidParams, `Unknown tool: ${input.name}`); + if (!input.accessToken) throw new GoogleWorkspaceAuthError("unauthenticated"); + const http = createGoogleHttp({ accessToken: input.accessToken, fetch: input.fetch, signal: input.signal, timeoutMs: input.timeoutMs }); + return tool.call(input.arguments, http); +}