diff --git a/server/src/google-workspace-rest-tools/README.md b/server/src/google-workspace-rest-tools/README.md index a60061d1edb..54329a5298f 100644 --- a/server/src/google-workspace-rest-tools/README.md +++ b/server/src/google-workspace-rest-tools/README.md @@ -8,9 +8,11 @@ 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. It also has all -nine allowlisted Calendar tools (see "Calendar tools" below). +Gmail has all nine allowlisted tools: `get_message`, `get_thread`, +`search_threads`, `list_threads`, `search_messages`, `get_draft`, +`list_drafts`, `list_labels` and `create_draft`. Only `create_draft` writes. +There is no send, trash, delete or label-changing tool, and none may be added. +It also has all nine allowlisted Calendar tools (see "Calendar tools" below). ## Why this exists, and why it is temporary @@ -166,25 +168,32 @@ median of 18.2 ms on either transport. ## 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. + fields and annotations follow Google's reference. Descriptions name only + tools this folder implements (`allowlist.test.ts` checks this), so + `list_labels` points to `list_threads` rather than to Google's label-changing + tools. 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. +- **Same message everywhere.** `get_message`, `get_thread`, `search_threads`, + `list_threads` and `search_messages` all map messages with `toMcpMessage` in + `gmail/message.ts`, so one message looks the same from any of them at the + same format. `get_draft` and `list_drafts` share `toMcpDraft`. - **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. + its `attachmentId`. Whenever bodies are returned (`FULL_CONTENT` for + `get_message`, `get_thread` and `search_messages`; `DRAFT_VIEW_FULL` for + `get_draft` and `list_drafts`), the tool reads those bytes + (`users.messages.attachments.get`, 10 at a time) before it answers. The first + `text/plain` and first `text/html` body parts are found depth first through + nested multiparts. If any body part cannot be read, the whole call returns a + tool error that starts with "Could not read the full body of this message"; + it never returns a result, or a page, with a body missing. One call reads at + most 20 such bodies (see "Google requests per call"). Google's reference + does not say what its tools do 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 @@ -196,6 +205,12 @@ median of 18.2 ms on either transport. - **`labelIds`** keeps user labels and the system labels Google lists (INBOX, SPAM, TRASH, UNREAD, STARRED, IMPORTANT, SENT, DRAFT, CHAT); category labels are dropped. +- **`label:` in search queries.** Google's `search_threads` reference says its + query accepts label IDs, not display names. Gmail search (the `q` parameter + that REST passes to Gmail) uses label names, with spaces written as hyphens, + as in Gmail's own search operators (`label:friends`). REST parameters named + `labelIds` take IDs. Our query descriptions describe the REST behavior, and + `allowlist.test.ts` checks that no description says `label:` takes IDs. - **`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 @@ -215,10 +230,93 @@ median of 18.2 ms on either transport. 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. +- **`get_thread`** makes one `threads.get` call (`format=full`, or summary + headers only for `MINIMAL` and `METADATA_ONLY`), then reads separately stored + bodies. Messages keep Gmail's order, oldest first. +- **`list_drafts`** makes one `drafts.list` call and then one `drafts.get` per + draft (10 at a time). A draft deleted between the two calls is left out. + The query is passed to Gmail unchanged. `pageSize` above 50 is capped at 50. + Google's annotation `idempotentHint: false` is copied as published. +- **`list_labels`** makes one `labels.list` call. Gmail's REST list has no + paging, so `pageSize` (default 100, maximum 500, neither set by Google) and + `pageToken` (a position in the list sorted by name, then ID) are applied in + this folder. `threadsTotal` and `threadsUnread` are left out: REST returns + them only from `labels.get`, one request per label. A label with only one + of its two colors set is returned without `color`. - **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). +### Google requests per call + +Reads that fan out run at most 10 at a time; the first failure stops new +requests. The 20 s timeout in `google-http.ts` applies to each request +attempt, not to the whole call, so a call that fans out can take longer than +20 s. Every request also stops when the caller's `signal` aborts; a caller +that needs a bound on the whole call passes a signal with that deadline (the +gateway passes its call deadline). +Each read may be retried once by `google-http.ts`, which the counts below do +not include. "Bodies" are separately stored bodies (at most two per message, +plain and HTML, and none for most mail). One call reads at most 20 of them +(`MAX_SEPARATE_BODIES_PER_CALL` in `gmail/message.ts`). When the messages in a +call need more, the call reads none and returns a tool error that starts with +"Could not read the full body of every message" and says to ask for fewer +results or to use `get_message`. + +Quota units come from Gmail's published per-method costs +(, recorded +2026-11-17): `messages.get` and `drafts.get` 20 (60 with `format=full`), +`threads.get` 40 (120 with `format=full`), `messages.attachments.get` 20, +`threads.list` 10, `messages.list` and `drafts.list` 5, `labels.list` 1, +`drafts.create` 10. Gmail allows 6,000 units per user per minute. + +| Tool | Requests at the maximum page size | Worst-case quota units | +| --- | --- | --- | +| `get_message` | 1 + up to 2 bodies = 3 | 60 + 40 = 100 | +| `get_thread` | 1 + up to 20 bodies = 21 | 120 + 400 = 520 | +| `search_threads` | 1 + 50 = 51 | 10 + 50 × 40 = 2,010 | +| `list_threads` | 1 + 50 = 51 | 2,010 | +| `search_messages` | 51; with `FULL_CONTENT` 1 + 50 + 20 = 71 | 1,005; with `FULL_CONTENT` 5 + 50 × 60 + 400 = 3,405 | +| `get_draft` | 1 + up to 2 bodies = 3 | 60 + 40 = 100 | +| `list_drafts` | 51; with `DRAFT_VIEW_FULL` (the default) 71 | 1,005; with `DRAFT_VIEW_FULL` 3,405 | +| `list_labels` | 1 | 1 | +| `create_draft` | 1, or 2 for a reply | 10, or 30 for a reply | + +The worst single call (3,405 units) fits inside the 6,000-unit per-user +minute. At the default page size of 20 the worst is 1,605 units. Concurrency +does not change the total: the 10 parallel reads only spread one call's fixed +units over less time. A second maximal call in the same minute can exceed the +per-user quota; Google then answers 429, which becomes the `rate_limited` tool +error ("Google is rate limiting requests. Try again shortly."). Gmail's quota +page states no per-user concurrency limit. + +### Not verified against Google's servers + +The allowlist in `toolScopes` names `get_draft`, `list_threads` and +`search_messages`, but Google's published Gmail MCP reference does not list +them (it lists `create_draft`, `get_message`, `get_thread`, `label_message`, +`label_thread`, `list_drafts`, `list_labels`, `search_threads`, +`unlabel_message` and `unlabel_thread`). Their inputs and results are our +design, built from the documented sibling tools, and may not match what +Google's servers return if they ever expose tools with these names: + +- **`get_draft`**: input `draftId` (required) and `view` (`DraftView` from + `list_drafts`); result is one `Draft`, the shape `list_drafts` and + `create_draft` return. One `drafts.get`, plus bodies. +- **`list_threads`**: input `pageSize`, `pageToken`, `includeTrash` and `view` + as in `search_threads`, plus `labelIds` (at most 20; a thread must have all + of them) instead of `query`; result is `search_threads`'s. Drafts are + excluded unless `DRAFT` is among the labels; spam and trash are included + when `SPAM` or `TRASH` is among them. +- **`search_messages`**: input as `search_threads`, with `messageFormat` from + `get_message` instead of `view`; result is `{ messages, nextPageToken, + resultCountEstimate }` with `get_message`'s `Message`. Unlike `get_message`, + the default (and `MESSAGE_FORMAT_UNSPECIFIED`) is `MINIMAL`, so a search does + not pull every body. One `messages.list`, then one `messages.get` per message, + plus bodies with `FULL_CONTENT`. + +A switch back to `google_mcp` would drop these three unless Google adds them. + ## Calendar tools Names, input fields, enums, result shapes and annotations come from Google's @@ -361,12 +459,6 @@ earliest first; working hours and out-of-office settings are not read. ## 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). diff --git a/server/src/google-workspace-rest-tools/allowlist.test.ts b/server/src/google-workspace-rest-tools/allowlist.test.ts index d4031c63d97..ff1159b27d0 100644 --- a/server/src/google-workspace-rest-tools/allowlist.test.ts +++ b/server/src/google-workspace-rest-tools/allowlist.test.ts @@ -34,19 +34,45 @@ describe("tool allowlist", () => { } }); + it("describes the search label: operator as taking label names, never label IDs", () => { + const queries = listGoogleWorkspaceRestTools("gmail") + .map((tool) => (tool.inputSchema.properties as Record | undefined)?.query?.description) + .filter((text): text is string => typeof text === "string"); + expect(queries.length).toBeGreaterThanOrEqual(3); + expect(queries.filter((item) => item.includes("label:"))).toHaveLength(2); + for (const text of queries.filter((item) => item.includes("label:"))) { + expect(text).toMatch(/`label:` takes a label name/); + } + const everything = JSON.stringify(listGoogleWorkspaceRestTools("gmail")); + expect(everything).not.toMatch(/label:`? takes label IDs/i); + }); + 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 every Gmail tool on the allowlist (9 of 9) and nothing else", () => { + const allowlisted = [ + "get_message", "get_thread", "get_draft", "list_drafts", "list_labels", + "search_threads", "list_threads", "search_messages", "create_draft", + ]; + for (const name of allowlisted) expect(googleWorkspaceToolTarget(googleWorkspaceToolName("gmail", name)), name).not.toBeNull(); + for (const name of ["label_message", "label_thread", "unlabel_message", "trash_message", "send_message"]) { + expect(googleWorkspaceToolTarget(googleWorkspaceToolName("gmail", name)), name).toBeNull(); + } + expect(listGoogleWorkspaceRestTools("gmail").map((tool) => tool.name).sort()).toEqual([...allowlisted].sort()); + }); + + it("implements only read tools besides create_draft", () => { + const writes = listGoogleWorkspaceRestTools("gmail").filter((tool) => tool.annotations?.readOnlyHint !== true).map((tool) => tool.name); + expect(writes).toEqual(["create_draft"]); + }); + it("implements every allowlisted Calendar tool (9 of 9)", () => { const allowlisted = ["list_calendars", "get_event", "list_events", "search_events", "suggest_time", "create_event", "update_event", "delete_event", "respond_to_event"]; for (const name of allowlisted) expect(googleWorkspaceToolTarget(googleWorkspaceToolName("calendar", name)), name).not.toBeNull(); expect(googleWorkspaceToolTarget(googleWorkspaceToolName("calendar", "unlisted_tool"))).toBeNull(); expect(listGoogleWorkspaceRestTools("calendar").map((tool) => tool.name).sort()).toEqual([...allowlisted].sort()); }); - - 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/gmail/fixtures/gmail-rest.ts b/server/src/google-workspace-rest-tools/gmail/fixtures/gmail-rest.ts index aa5133f2f8a..810683b35b3 100644 --- a/server/src/google-workspace-rest-tools/gmail/fixtures/gmail-rest.ts +++ b/server/src/google-workspace-rest-tools/gmail/fixtures/gmail-rest.ts @@ -93,3 +93,61 @@ export const CREATED_DRAFT = { id: "r-1234567890123456789", message: { id: "18c0ffee00000099", threadId: "18c0ffee00000000", labelIds: ["DRAFT"] }, }; + +export const FULL_THREAD = { + id: "18c0ffee00000000", + historyId: "9002", + messages: [FULL_MESSAGE, { ...METADATA_MESSAGE, payload: { ...METADATA_MESSAGE.payload, body: { size: 18, data: b64("Thanks, looks good") } } }], +}; + +export const MESSAGE_LIST = { + messages: [ + { id: "18c0ffee00000002", threadId: "18c0ffee00000000" }, + { id: "18c0ffee00000001", threadId: "18c0ffee00000000" }, + ], + nextPageToken: "messages-page-2", + resultSizeEstimate: 37, +}; + +export const FULL_DRAFT = { + id: "r-1234567890123456789", + message: { + id: "18c0ffee00000099", + threadId: "18c0ffee00000000", + labelIds: ["DRAFT"], + snippet: "Draft reply", + internalDate: "1763510400000", + payload: { + mimeType: "multipart/alternative", + headers: [ + { name: "To", value: "Avery " }, + { name: "Cc", value: "casey@example.test" }, + { name: "Bcc", value: "\"Ops\" " }, + { name: "Subject", value: "Re: Quarterly plan" }, + ], + parts: [ + { mimeType: "text/plain", body: { size: 11, data: b64("Draft reply") } }, + { mimeType: "text/html", body: { size: 18, data: b64("

Draft reply

") } }, + ], + }, + }, +}; + +export const DRAFT_LIST = { + drafts: [ + { id: "r-1234567890123456789", message: { id: "18c0ffee00000099", threadId: "18c0ffee00000000" } }, + { id: "r-2000000000000000001", message: { id: "18c0ffee000000a0", threadId: "18c0ffee000000a0" } }, + ], + nextPageToken: "drafts-page-2", + resultSizeEstimate: 2, +}; + +export const LABEL_LIST = { + labels: [ + { id: "INBOX", name: "INBOX", type: "system", messageListVisibility: "hide", labelListVisibility: "labelShow" }, + { id: "Label_7", name: "Receipts", type: "user", color: { textColor: "#000000", backgroundColor: "#4a86e8" } }, + { id: "CATEGORY_UPDATES", name: "CATEGORY_UPDATES", type: "system" }, + { id: "Label_42", name: "Projects", type: "user" }, + { id: "Label_3", name: "Projects/Plan", type: "user", color: { backgroundColor: "#ffffff" } }, + ], +}; diff --git a/server/src/google-workspace-rest-tools/gmail/get-draft.test.ts b/server/src/google-workspace-rest-tools/gmail/get-draft.test.ts new file mode 100644 index 00000000000..ef551ddbbcf --- /dev/null +++ b/server/src/google-workspace-rest-tools/gmail/get-draft.test.ts @@ -0,0 +1,90 @@ +import { describe, expect, it } from "vitest"; +import { createGoogleHttp } from "../google-http.js"; +import { fakeGoogle, json } from "../fixtures/fake-google.js"; +import { FULL_DRAFT } from "./fixtures/gmail-rest.js"; +import { getDraft, getDraftResult, readDraftRequest } from "./get-draft.js"; + +describe("get_draft request", () => { + it("reads the full draft by default", () => { + for (const view of [undefined, "DRAFT_VIEW_FULL", "DRAFT_VIEW_UNSPECIFIED"] as const) { + expect(readDraftRequest("r-1", view)).toEqual({ + method: "GET", host: "gmail.googleapis.com", path: "/gmail/v1/users/me/drafts/r-1", query: { format: "full" }, + }); + } + }); + + it("reads only headers for DRAFT_VIEW_METADATA_ONLY", () => { + expect(readDraftRequest("r-1", "DRAFT_VIEW_METADATA_ONLY").query).toEqual({ + format: "metadata", metadataHeaders: ["To", "Cc", "Bcc", "Subject", "Date"], + }); + }); +}); + +describe("get_draft result", () => { + it("maps a full draft to the Draft shape create_draft and list_drafts return", () => { + const result = getDraftResult(FULL_DRAFT, { draftId: FULL_DRAFT.id }); + expect(result.structuredContent).toEqual({ + id: "r-1234567890123456789", + subject: "Re: Quarterly plan", + threadId: "18c0ffee00000000", + toRecipients: ["avery@example.test"], + ccRecipients: ["casey@example.test"], + bccRecipients: ["ops@example.test"], + plaintextBody: "Draft reply", + date: "2025-11-19", + htmlBody: "

Draft reply

", + }); + expect(JSON.parse((result.content[0] as { text: string }).text)).toEqual(result.structuredContent); + }); + + it("leaves subject and bodies out of DRAFT_VIEW_METADATA_ONLY", () => { + const result = getDraftResult(FULL_DRAFT, { draftId: FULL_DRAFT.id, view: "DRAFT_VIEW_METADATA_ONLY" }).structuredContent; + expect(result).not.toHaveProperty("subject"); + expect(result).not.toHaveProperty("plaintextBody"); + expect(result).not.toHaveProperty("htmlBody"); + expect(result).toMatchObject({ id: "r-1234567890123456789", bccRecipients: ["ops@example.test"] }); + }); + + it("returns an empty subject and no bodies for an empty draft", () => { + expect(getDraftResult({ id: "r-2", message: { id: "m2", payload: { mimeType: "text/plain", headers: [] } } }, { draftId: "r-2" }).structuredContent).toEqual({ + id: "r-2", subject: "", toRecipients: [], ccRecipients: [], bccRecipients: [], + }); + }); +}); + +describe("get_draft with a body Gmail stores separately", () => { + const large = "Draft paragraph.\n".repeat(5000); + const draft = { + id: "r-3", + message: { id: "m3", payload: { mimeType: "text/plain", headers: [{ name: "Subject", value: "Long" }], body: { size: large.length, attachmentId: "ANGjdJ_draft" } } }, + }; + + it("fetches the body bytes before answering", async () => { + const { fetch, calls } = fakeGoogle(({ url }) => (url.pathname.includes("/attachments/") ? json({ data: Buffer.from(large).toString("base64url") }) : json(draft))); + const result = await getDraft.call({ draftId: "r-3" }, createGoogleHttp({ accessToken: "t", fetch })); + expect((result.structuredContent as { plaintextBody: string }).plaintextBody).toBe(large); + expect(calls.map((call) => call.url.pathname)).toEqual(["/gmail/v1/users/me/drafts/r-3", "/gmail/v1/users/me/messages/m3/attachments/ANGjdJ_draft"]); + }); + + it("returns an explicit error when the body cannot be read", async () => { + const { fetch } = fakeGoogle(({ url }) => (url.pathname.includes("/attachments/") ? json({ error: { code: 403, message: "Denied" } }, 403) : json(draft))); + const result = await getDraft.call({ draftId: "r-3" }, createGoogleHttp({ accessToken: "t", fetch })); + expect(result.isError).toBe(true); + expect((result.content[0] as { text: string }).text).toMatch(/^Could not read the full body of this message/); + }); + + it("does not fetch bodies for DRAFT_VIEW_METADATA_ONLY", async () => { + const { fetch, calls } = fakeGoogle(() => json(draft)); + await getDraft.call({ draftId: "r-3", view: "DRAFT_VIEW_METADATA_ONLY" }, createGoogleHttp({ accessToken: "t", fetch })); + expect(calls).toHaveLength(1); + }); +}); + +describe("get_draft tool", () => { + it("rejects draft IDs that could change the request path", async () => { + const { fetch, calls } = fakeGoogle(() => json(FULL_DRAFT)); + const http = createGoogleHttp({ accessToken: "t", fetch }); + for (const draftId of ["..", "a/b", "a?b", ""]) expect((await getDraft.call({ draftId }, http)).isError).toBe(true); + expect(calls).toHaveLength(0); + }); +}); diff --git a/server/src/google-workspace-rest-tools/gmail/get-draft.ts b/server/src/google-workspace-rest-tools/gmail/get-draft.ts new file mode 100644 index 00000000000..257856ffbd1 --- /dev/null +++ b/server/src/google-workspace-rest-tools/gmail/get-draft.ts @@ -0,0 +1,85 @@ +import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js"; +import { z } from "zod"; +import type { GoogleHttp, GoogleRequest } from "../google-http.js"; +import { compact, defineTool, structuredResult } from "../tool.js"; +import { parseAddressList } from "./address.js"; +import { gmailId, header, isoDate, messageContent, readMessageBodies, type GmailRestMessage, type MessageBodies } from "./message.js"; +import { draftSchema } from "./schemas.js"; + +export const DRAFT_VIEWS = ["DRAFT_VIEW_UNSPECIFIED", "DRAFT_VIEW_METADATA_ONLY", "DRAFT_VIEW_FULL"] as const; +export type DraftView = (typeof DRAFT_VIEWS)[number]; +export const DRAFT_HEADERS = ["To", "Cc", "Bcc", "Subject", "Date"] as const; + +const args = z.object({ + draftId: gmailId, + view: z.enum(DRAFT_VIEWS).optional(), +}); +export type GetDraftArgs = z.infer; + +export interface GmailRestDraftFull { id?: string; message?: GmailRestMessage } + +export function isFullDraftView(view: DraftView | undefined): boolean { + return view !== "DRAFT_VIEW_METADATA_ONLY"; +} + +export function readDraftRequest(draftId: string, view: DraftView | undefined): GoogleRequest { + return { + method: "GET", + host: "gmail.googleapis.com", + path: `/gmail/v1/users/me/drafts/${draftId}`, + query: isFullDraftView(view) ? { format: "full" } : { format: "metadata", metadataHeaders: DRAFT_HEADERS }, + }; +} + +export function toMcpDraft(draft: GmailRestDraftFull, view: DraftView | undefined, bodies: MessageBodies = new Map()): Record { + const message = draft.message ?? {}; + const payload = message.payload; + const full = isFullDraftView(view); + const content = full ? messageContent(payload, bodies.get(message.id ?? "")) : undefined; + return compact({ + id: draft.id ?? "", + subject: full ? header(payload, "Subject") ?? "" : undefined, + threadId: message.threadId, + toRecipients: parseAddressList(header(payload, "To")), + ccRecipients: parseAddressList(header(payload, "Cc")), + bccRecipients: parseAddressList(header(payload, "Bcc")), + plaintextBody: content?.plaintextBody, + date: isoDate(message.internalDate), + htmlBody: content?.htmlBody, + }); +} + +export async function readDraftBodies(drafts: readonly GmailRestDraftFull[], view: DraftView | undefined, http: GoogleHttp): Promise { + if (!isFullDraftView(view)) return undefined; + return readMessageBodies(drafts.map((draft) => draft.message ?? {}), http); +} + +export function getDraftResult(draft: GmailRestDraftFull, input: GetDraftArgs, bodies?: MessageBodies): CallToolResult { + return structuredResult(toMcpDraft({ ...draft, id: draft.id ?? input.draftId }, input.view, bodies)); +} + +export const getDraft = defineTool({ + definition: { + name: "get_draft", + description: "Gets one draft email from the signed-in user's Gmail by draft ID. Draft IDs come from list_drafts.", + inputSchema: { + type: "object", + properties: { + draftId: { type: "string", description: "Required. The ID of the draft to get." }, + view: { + type: "string", + enum: [...DRAFT_VIEWS], + description: "Optional. DRAFT_VIEW_FULL (default) returns recipients, subject and bodies. DRAFT_VIEW_METADATA_ONLY leaves out the subject and bodies.", + }, + }, + required: ["draftId"], + }, + outputSchema: draftSchema, + annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false }, + }, + args, + async run(input, http) { + const draft = await http.send(readDraftRequest(input.draftId, input.view)); + return getDraftResult(draft, input, await readDraftBodies([draft], input.view, http)); + }, +}); diff --git a/server/src/google-workspace-rest-tools/gmail/get-message.ts b/server/src/google-workspace-rest-tools/gmail/get-message.ts index 11438ebd799..db5c31c6c1c 100644 --- a/server/src/google-workspace-rest-tools/gmail/get-message.ts +++ b/server/src/google-workspace-rest-tools/gmail/get-message.ts @@ -1,21 +1,18 @@ 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, + readMessageBodies, 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; +export const MESSAGE_FORMATS =["MESSAGE_FORMAT_UNSPECIFIED", "MINIMAL", "FULL_CONTENT", "METADATA_ONLY"] as const; const args = z.object({ messageId: gmailId, @@ -47,23 +44,10 @@ export function getMessageResult( 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; +async function readExternalBodies(message: GmailRestMessage, input: GetMessageArgs, http: GoogleHttp): Promise | undefined> { + if (messageDetail(input.messageFormat) !== "full") return undefined; + const bodies = await readMessageBodies([{ ...message, id: input.messageId }], http); + return bodies.get(input.messageId); } export const getMessage = defineTool({ diff --git a/server/src/google-workspace-rest-tools/gmail/get-thread.test.ts b/server/src/google-workspace-rest-tools/gmail/get-thread.test.ts new file mode 100644 index 00000000000..93312421dbb --- /dev/null +++ b/server/src/google-workspace-rest-tools/gmail/get-thread.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, FULL_THREAD } from "./fixtures/gmail-rest.js"; +import { getMessageResult } from "./get-message.js"; +import { getThread, getThreadResult, readThreadRequest } from "./get-thread.js"; + +describe("get_thread request", () => { + it("reads the full thread by default and for FULL_CONTENT", () => { + for (const messageFormat of [undefined, "FULL_CONTENT", "MESSAGE_FORMAT_UNSPECIFIED"] as const) { + expect(readThreadRequest({ threadId: "18c0ffee00000000", messageFormat })).toEqual({ + method: "GET", host: "gmail.googleapis.com", path: "/gmail/v1/users/me/threads/18c0ffee00000000", query: { format: "full" }, + }); + } + }); + + it("reads only summary headers for MINIMAL and METADATA_ONLY", () => { + for (const messageFormat of ["MINIMAL", "METADATA_ONLY"] as const) { + expect(readThreadRequest({ threadId: "t1", messageFormat }).query).toEqual({ + format: "metadata", metadataHeaders: ["From", "To", "Cc", "Subject", "Date"], + }); + } + }); +}); + +describe("get_thread result", () => { + it("maps each message exactly as get_message does", () => { + const result = getThreadResult(FULL_THREAD, { threadId: FULL_THREAD.id }); + const thread = result.structuredContent as { id: string; messages: unknown[] }; + expect(thread.id).toBe("18c0ffee00000000"); + expect(thread.messages[0]).toEqual(getMessageResult(FULL_MESSAGE, { messageId: FULL_MESSAGE.id }).structuredContent); + expect(thread.messages[1]).toMatchObject({ id: "18c0ffee00000002", plaintextBody: "Thanks, looks good", attachmentIds: [] }); + 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 = getThreadResult(FULL_THREAD, { threadId: "t", messageFormat: "MINIMAL" }).structuredContent as { messages: Array> }; + expect(minimal.messages[0]).not.toHaveProperty("plaintextBody"); + expect(minimal.messages[0]!.subject).toBe("Quarterly plan"); + const metadata = getThreadResult(FULL_THREAD, { threadId: "t", messageFormat: "METADATA_ONLY" }).structuredContent as { messages: Array> }; + expect(metadata.messages[0]).not.toHaveProperty("subject"); + expect(metadata.messages[0]).not.toHaveProperty("snippet"); + }); + + it("returns an empty message list for a thread without messages", () => { + expect(getThreadResult({ id: "t" }, { threadId: "t" }).structuredContent).toEqual({ id: "t", messages: [] }); + }); +}); + +describe("get_thread with bodies Gmail stores separately", () => { + const large = "Line of a long reply.\n".repeat(4000); + const thread = { + id: "th1", + messages: [ + { id: "m1", payload: { mimeType: "text/plain", body: { size: 5, data: Buffer.from("short").toString("base64url") } } }, + { + id: "m2", + payload: { + mimeType: "multipart/alternative", + parts: [ + { mimeType: "text/plain", body: { size: large.length, attachmentId: "ANGjdJ_m2_plain" } }, + { mimeType: "text/html", body: { size: large.length, attachmentId: "ANGjdJ_m2_html" } }, + ], + }, + }, + ], + }; + + it("fetches each separately stored body before answering", async () => { + const { fetch, calls } = fakeGoogle(({ url }) => { + if (url.pathname.endsWith("/attachments/ANGjdJ_m2_plain")) return json({ data: Buffer.from(large).toString("base64url") }); + if (url.pathname.endsWith("/attachments/ANGjdJ_m2_html")) return json({ data: Buffer.from(`
${large}
`).toString("base64url") }); + return json(thread); + }); + const result = await getThread.call({ threadId: "th1" }, createGoogleHttp({ accessToken: "t", fetch })); + const messages = (result.structuredContent as { messages: Array<{ plaintextBody?: string; htmlBody?: string }> }).messages; + expect(messages[0]!.plaintextBody).toBe("short"); + expect(messages[1]!.plaintextBody).toBe(large); + expect(messages[1]!.htmlBody).toBe(`
${large}
`); + expect(calls.map((call) => call.url.pathname).sort()).toEqual([ + "/gmail/v1/users/me/messages/m2/attachments/ANGjdJ_m2_html", + "/gmail/v1/users/me/messages/m2/attachments/ANGjdJ_m2_plain", + "/gmail/v1/users/me/threads/th1", + ]); + }); + + it("makes one request for MINIMAL", async () => { + const { fetch, calls } = fakeGoogle(() => json(thread)); + await getThread.call({ threadId: "th1", messageFormat: "MINIMAL" }, createGoogleHttp({ accessToken: "t", fetch })); + expect(calls).toHaveLength(1); + }); + + it("returns an explicit error, never a partial thread, when a body cannot be read", async () => { + const { fetch } = fakeGoogle(({ url }) => (url.pathname.includes("/attachments/") ? json({ error: { code: 404 } }, 404) : json(thread))); + const result = await getThread.call({ threadId: "th1" }, createGoogleHttp({ accessToken: "t", fetch })); + 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("reads at most 20 separately stored bodies per call and fails explicitly beyond that", async () => { + const stored = (count: number) => ({ + id: "th2", + messages: Array.from({ length: count }, (_, index) => ({ + id: `m${index}`, + payload: { mimeType: "text/plain", body: { size: 9000, attachmentId: `ANGjdJ_${index}` } }, + })), + }); + const atLimit = fakeGoogle(({ url }) => (url.pathname.includes("/attachments/") ? json({ data: Buffer.from("body").toString("base64url") }) : json(stored(20)))); + expect((await getThread.call({ threadId: "th2" }, createGoogleHttp({ accessToken: "t", fetch: atLimit.fetch }))).isError).toBeUndefined(); + expect(atLimit.calls).toHaveLength(21); + + const overLimit = fakeGoogle(() => json(stored(21))); + const result = await getThread.call({ threadId: "th2" }, createGoogleHttp({ accessToken: "t", fetch: overLimit.fetch })); + 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 every message: they need 21 separate body reads/); + expect(overLimit.calls).toHaveLength(1); + }); + + it("refuses a separately stored body on a message without a usable ID", async () => { + const broken = { id: "th1", messages: [{ id: "../x", payload: thread.messages[1]!.payload }] }; + const { fetch, calls } = fakeGoogle(() => json(broken)); + const result = await getThread.call({ threadId: "th1" }, createGoogleHttp({ accessToken: "t", fetch })); + expect(result.isError).toBe(true); + expect(calls).toHaveLength(1); + }); +}); + +describe("get_thread tool", () => { + it("rejects thread IDs that could change the request path", async () => { + const { fetch, calls } = fakeGoogle(() => json(FULL_THREAD)); + const http = createGoogleHttp({ accessToken: "t", fetch }); + for (const threadId of ["..", "a/b", "a?b", ""]) expect((await getThread.call({ threadId }, http)).isError).toBe(true); + expect(calls).toHaveLength(0); + }); + + it("stops when the caller cancels", async () => { + const controller = new AbortController(); + const { fetch } = fakeGoogle(async () => { + controller.abort(); + throw Object.assign(new Error("aborted"), { name: "AbortError" }); + }); + const result = await getThread.call({ threadId: "th1" }, createGoogleHttp({ accessToken: "t", fetch, signal: controller.signal })); + expect(result).toEqual({ isError: true, content: [{ type: "text", text: "The request was cancelled." }] }); + }); +}); diff --git a/server/src/google-workspace-rest-tools/gmail/get-thread.ts b/server/src/google-workspace-rest-tools/gmail/get-thread.ts new file mode 100644 index 00000000000..68f053a6c04 --- /dev/null +++ b/server/src/google-workspace-rest-tools/gmail/get-thread.ts @@ -0,0 +1,66 @@ +import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js"; +import { z } from "zod"; +import type { GoogleRequest } from "../google-http.js"; +import { defineTool, structuredResult } from "../tool.js"; +import { MESSAGE_FORMATS, messageDetail } from "./get-message.js"; +import { gmailId, readMessageBodies, SUMMARY_HEADERS, toMcpMessage, type GmailRestMessage, type MessageBodies } from "./message.js"; +import { messageSchema } from "./schemas.js"; + +const args = z.object({ + threadId: gmailId, + messageFormat: z.enum(MESSAGE_FORMATS).optional(), +}); +export type GetThreadArgs = z.infer; + +export interface GmailRestFullThread { id?: string; messages?: GmailRestMessage[] } + +export function readThreadRequest(input: GetThreadArgs): GoogleRequest { + const detail = messageDetail(input.messageFormat); + return { + method: "GET", + host: "gmail.googleapis.com", + path: `/gmail/v1/users/me/threads/${input.threadId}`, + query: detail === "full" ? { format: "full" } : { format: "metadata", metadataHeaders: SUMMARY_HEADERS }, + }; +} + +export function getThreadResult(thread: GmailRestFullThread, input: GetThreadArgs, bodies: MessageBodies = new Map()): CallToolResult { + const detail = messageDetail(input.messageFormat); + return structuredResult({ + id: thread.id ?? input.threadId, + messages: (thread.messages ?? []).map((message) => toMcpMessage(message, detail, bodies.get(message.id ?? ""))), + }); +} + +export const getThread = defineTool({ + definition: { + name: "get_thread", + description: "Gets one email thread from the signed-in user's Gmail by thread ID, with its messages oldest first.", + inputSchema: { + type: "object", + properties: { + threadId: { type: "string", description: "Required. The ID of the thread to get." }, + messageFormat: { + type: "string", + enum: [...MESSAGE_FORMATS], + description: "Optional. How much of each message to return. MINIMAL: snippet and the Subject, From, To, Cc and Date headers. FULL_CONTENT (default): MINIMAL plus the bodies and attachments. METADATA_ONLY: no subject, snippet, body or attachment names.", + }, + }, + required: ["threadId"], + }, + outputSchema: { + type: "object", + properties: { + id: { type: "string", description: "The thread ID." }, + messages: { type: "array", items: messageSchema, description: "The thread's messages, oldest first." }, + }, + }, + annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false }, + }, + args, + async run(input, http) { + const thread = await http.send(readThreadRequest(input)); + const bodies = messageDetail(input.messageFormat) === "full" ? await readMessageBodies(thread.messages ?? [], http) : undefined; + return getThreadResult(thread, input, bodies); + }, +}); diff --git a/server/src/google-workspace-rest-tools/gmail/index.ts b/server/src/google-workspace-rest-tools/gmail/index.ts index 98b7e8ab8fe..201e9090b37 100644 --- a/server/src/google-workspace-rest-tools/gmail/index.ts +++ b/server/src/google-workspace-rest-tools/gmail/index.ts @@ -1,6 +1,22 @@ import type { RestTool } from "../tool.js"; import { createDraft } from "./create-draft.js"; +import { getDraft } from "./get-draft.js"; import { getMessage } from "./get-message.js"; +import { getThread } from "./get-thread.js"; +import { listDrafts } from "./list-drafts.js"; +import { listLabels } from "./list-labels.js"; +import { listThreads } from "./list-threads.js"; +import { searchMessages } from "./search-messages.js"; import { searchThreads } from "./search-threads.js"; -export const GMAIL_TOOLS: readonly RestTool[] = [getMessage, searchThreads, createDraft]; +export const GMAIL_TOOLS: readonly RestTool[] = [ + getMessage, + searchThreads, + createDraft, + getThread, + getDraft, + listDrafts, + listLabels, + listThreads, + searchMessages, +]; diff --git a/server/src/google-workspace-rest-tools/gmail/list-drafts.test.ts b/server/src/google-workspace-rest-tools/gmail/list-drafts.test.ts new file mode 100644 index 00000000000..59256bb0401 --- /dev/null +++ b/server/src/google-workspace-rest-tools/gmail/list-drafts.test.ts @@ -0,0 +1,72 @@ +import { describe, expect, it } from "vitest"; +import { createGoogleHttp } from "../google-http.js"; +import { fakeGoogle, json } from "../fixtures/fake-google.js"; +import { DRAFT_LIST, FULL_DRAFT } from "./fixtures/gmail-rest.js"; +import { getDraftResult } from "./get-draft.js"; +import { listDrafts, listDraftsRequest, listDraftsResult } from "./list-drafts.js"; + +describe("list_drafts request", () => { + it("passes the query as is and defaults the page size to 20, capped at 50", () => { + expect(listDraftsRequest({})).toEqual({ + method: "GET", host: "gmail.googleapis.com", path: "/gmail/v1/users/me/drafts", + query: { q: undefined, maxResults: 20, pageToken: undefined }, + }); + expect(listDraftsRequest({ query: " to:avery@example.test ", pageSize: 80, pageToken: "drafts-page-2" }).query).toEqual({ + q: "to:avery@example.test", maxResults: 50, pageToken: "drafts-page-2", + }); + }); +}); + +describe("list_drafts result", () => { + it("maps each draft exactly as get_draft does", () => { + const result = listDraftsResult(DRAFT_LIST, [FULL_DRAFT, null], {}); + expect(result.structuredContent).toEqual({ + drafts: [getDraftResult(FULL_DRAFT, { draftId: FULL_DRAFT.id }).structuredContent], + nextPageToken: "drafts-page-2", + }); + }); + + it("returns an empty page without nextPageToken", () => { + expect(listDraftsResult({}, [], {}).structuredContent).toEqual({ drafts: [] }); + }); +}); + +describe("list_drafts tool", () => { + it("lists, then reads each draft, skipping one deleted in between", async () => { + const { fetch, calls } = fakeGoogle(({ url }) => { + if (url.pathname.endsWith("/drafts")) return json(DRAFT_LIST); + if (url.pathname.endsWith(`/drafts/${FULL_DRAFT.id}`)) return json(FULL_DRAFT); + return json({ error: { code: 404 } }, 404); + }); + const result = await listDrafts.call({}, createGoogleHttp({ accessToken: "t", fetch })); + expect((result.structuredContent as { drafts: Array<{ id: string }> }).drafts.map((draft) => draft.id)).toEqual([FULL_DRAFT.id]); + expect(calls.map((call) => call.url.pathname)).toEqual([ + "/gmail/v1/users/me/drafts", + "/gmail/v1/users/me/drafts/r-1234567890123456789", + "/gmail/v1/users/me/drafts/r-2000000000000000001", + ]); + expect(calls[1]!.url.searchParams.get("format")).toBe("full"); + }); + + it("fails explicitly when a separately stored draft body cannot be read", async () => { + const stored = { id: "r-9", message: { id: "m9", payload: { mimeType: "text/html", body: { size: 9000, attachmentId: "ANGjdJ_html" } } } }; + const { fetch } = fakeGoogle(({ url }) => { + if (url.pathname.endsWith("/drafts")) return json({ drafts: [{ id: "r-9" }] }); + if (url.pathname.includes("/attachments/")) return json({ error: { code: 503 } }, 503); + return json(stored); + }); + const result = await listDrafts.call({}, createGoogleHttp({ accessToken: "t", fetch, retryDelayMs: 0 })); + expect(result.isError).toBe(true); + expect((result.content[0] as { text: string }).text).toMatch(/^Could not read the full body of this message/); + }); + + it("makes at most 51 requests at the maximum page size when no body is stored separately", async () => { + const ids = Array.from({ length: 70 }, (_, index) => `r-${index}`); + const { fetch, calls } = fakeGoogle(({ url }) => (url.pathname.endsWith("/drafts") + ? json({ drafts: ids.slice(0, Number(url.searchParams.get("maxResults"))).map((id) => ({ id })) }) + : json({ id: url.pathname.split("/").pop(), message: { id: "m", payload: { mimeType: "text/plain", body: { data: "" } } } }))); + const result = await listDrafts.call({ pageSize: 70 }, createGoogleHttp({ accessToken: "t", fetch })); + expect((result.structuredContent as { drafts: unknown[] }).drafts).toHaveLength(50); + expect(calls).toHaveLength(51); + }); +}); diff --git a/server/src/google-workspace-rest-tools/gmail/list-drafts.ts b/server/src/google-workspace-rest-tools/gmail/list-drafts.ts new file mode 100644 index 00000000000..f601dfeafc9 --- /dev/null +++ b/server/src/google-workspace-rest-tools/gmail/list-drafts.ts @@ -0,0 +1,85 @@ +import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js"; +import { z } from "zod"; +import type { GoogleHttp, GoogleRequest } from "../google-http.js"; +import { compact, defineTool, structuredResult } from "../tool.js"; +import { DRAFT_VIEWS, readDraftBodies, readDraftRequest, toMcpDraft, type DraftView, type GmailRestDraftFull } from "./get-draft.js"; +import type { MessageBodies } from "./message.js"; +import { mapLimited, unlessMissing } from "./parallel.js"; +import { draftSchema } from "./schemas.js"; +import { DEFAULT_PAGE_SIZE, MAX_PAGE_SIZE } from "./search-threads.js"; + +const args = z.object({ + pageSize: z.number().int().positive().optional(), + pageToken: z.string().max(2048).optional(), + query: z.string().max(4096).optional(), + view: z.enum(DRAFT_VIEWS).optional(), +}); +export type ListDraftsArgs = z.infer; + +interface GmailDraftList { + drafts?: Array<{ id?: string }>; + nextPageToken?: string; +} + +export function listDraftsRequest(input: ListDraftsArgs): GoogleRequest { + return { + method: "GET", + host: "gmail.googleapis.com", + path: "/gmail/v1/users/me/drafts", + query: { + q: input.query?.trim() || undefined, + maxResults: Math.min(input.pageSize ?? DEFAULT_PAGE_SIZE, MAX_PAGE_SIZE), + pageToken: input.pageToken || undefined, + }, + }; +} + +export function draftIds(list: GmailDraftList): string[] { + return (list.drafts ?? []).map((draft) => draft.id).filter((id): id is string => typeof id === "string" && /^[A-Za-z0-9_-]{1,256}$/.test(id)); +} + +export function listDraftsResult(list: GmailDraftList, drafts: Array, input: ListDraftsArgs, bodies?: MessageBodies): CallToolResult { + return structuredResult(compact({ + drafts: drafts.filter((draft): draft is GmailRestDraftFull => draft !== null).map((draft) => toMcpDraft(draft, input.view, bodies)), + nextPageToken: list.nextPageToken || undefined, + })); +} + +async function readDrafts(ids: string[], view: DraftView | undefined, http: GoogleHttp): Promise> { + return mapLimited(ids, (draftId) => unlessMissing(http.send(readDraftRequest(draftId, view)))); +} + +export const listDrafts = defineTool({ + definition: { + name: "list_drafts", + description: "Lists the signed-in user's Gmail drafts one page at a time, optionally filtered by a Gmail search query. Returns recipients, subject and bodies by default.", + inputSchema: { + type: "object", + properties: { + pageSize: { type: "integer", description: "Optional. Most drafts 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 `to:user@example.com newer_than:7d`)." }, + view: { + type: "string", + enum: [...DRAFT_VIEWS], + description: "Optional. DRAFT_VIEW_FULL (default) returns recipients, subject and bodies. DRAFT_VIEW_METADATA_ONLY leaves out the subject and bodies.", + }, + }, + }, + outputSchema: { + type: "object", + properties: { + drafts: { type: "array", items: draftSchema, description: "The drafts on this page." }, + nextPageToken: { type: "string", description: "Pass as pageToken to get the next page. Present only when there are more results." }, + }, + }, + annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: false, openWorldHint: false }, + }, + args, + async run(input, http) { + const list = await http.send(listDraftsRequest(input)); + const drafts = await readDrafts(draftIds(list), input.view, http); + const bodies = await readDraftBodies(drafts.filter((draft): draft is GmailRestDraftFull => draft !== null), input.view, http); + return listDraftsResult(list, drafts, input, bodies); + }, +}); diff --git a/server/src/google-workspace-rest-tools/gmail/list-labels.test.ts b/server/src/google-workspace-rest-tools/gmail/list-labels.test.ts new file mode 100644 index 00000000000..5fec41afb1b --- /dev/null +++ b/server/src/google-workspace-rest-tools/gmail/list-labels.test.ts @@ -0,0 +1,57 @@ +import { describe, expect, it } from "vitest"; +import { createGoogleHttp } from "../google-http.js"; +import { fakeGoogle, json } from "../fixtures/fake-google.js"; +import { LABEL_LIST } from "./fixtures/gmail-rest.js"; +import { listLabels, listLabelsRequest, listLabelsResult } from "./list-labels.js"; + +describe("list_labels request", () => { + it("reads the label list in one request", () => { + expect(listLabelsRequest()).toEqual({ method: "GET", host: "gmail.googleapis.com", path: "/gmail/v1/users/me/labels" }); + }); +}); + +describe("list_labels result", () => { + it("returns user labels only, sorted by name, with complete colors", () => { + expect(listLabelsResult(LABEL_LIST, {}).structuredContent).toEqual({ + labels: [ + { labelId: "Label_42", name: "Projects" }, + { labelId: "Label_3", name: "Projects/Plan" }, + { labelId: "Label_7", name: "Receipts", color: { textColor: "#000000", backgroundColor: "#4a86e8" } }, + ], + }); + }); + + it("pages through the list", () => { + const first = listLabelsResult(LABEL_LIST, { pageSize: 2 }).structuredContent as { labels: Array<{ labelId: string }>; nextPageToken: string }; + expect(first.labels.map((label) => label.labelId)).toEqual(["Label_42", "Label_3"]); + expect(first.nextPageToken).toBe("2"); + expect(listLabelsResult(LABEL_LIST, { pageSize: 2, pageToken: first.nextPageToken }).structuredContent).toEqual({ + labels: [{ labelId: "Label_7", name: "Receipts", color: { textColor: "#000000", backgroundColor: "#4a86e8" } }], + }); + expect(listLabelsResult(LABEL_LIST, { pageToken: "99" }).structuredContent).toEqual({ labels: [] }); + }); + + it("caps the page size at 500", () => { + const labels = Array.from({ length: 600 }, (_, index) => ({ id: `Label_${index}`, name: `L${String(index).padStart(3, "0")}`, type: "user" })); + const page = listLabelsResult({ labels }, { pageSize: 10_000 }).structuredContent as { labels: unknown[]; nextPageToken: string }; + expect(page.labels).toHaveLength(500); + expect(page.nextPageToken).toBe("500"); + }); +}); + +describe("list_labels tool", () => { + it("makes one request and rejects a page token it did not issue", async () => { + const { fetch, calls } = fakeGoogle(() => json(LABEL_LIST)); + const http = createGoogleHttp({ accessToken: "t", fetch }); + expect((await listLabels.call({}, http)).isError).toBeUndefined(); + expect(calls).toHaveLength(1); + expect((await listLabels.call({ pageToken: "abc" }, http)).isError).toBe(true); + expect(calls).toHaveLength(1); + }); + + it("treats an empty page token as the first page", async () => { + const { fetch } = fakeGoogle(() => json(LABEL_LIST)); + const result = await listLabels.call({ pageToken: "", pageSize: 1 }, createGoogleHttp({ accessToken: "t", fetch })); + expect(result.structuredContent).toEqual({ labels: [{ labelId: "Label_42", name: "Projects" }], nextPageToken: "1" }); + }); +}); diff --git a/server/src/google-workspace-rest-tools/gmail/list-labels.ts b/server/src/google-workspace-rest-tools/gmail/list-labels.ts new file mode 100644 index 00000000000..e4568842cb2 --- /dev/null +++ b/server/src/google-workspace-rest-tools/gmail/list-labels.ts @@ -0,0 +1,95 @@ +import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js"; +import { z } from "zod"; +import type { GoogleRequest } from "../google-http.js"; +import { compact, defineTool, structuredResult } from "../tool.js"; + +export const DEFAULT_LABEL_PAGE_SIZE = 100; +export const MAX_LABEL_PAGE_SIZE = 500; + +const args = z.object({ + pageSize: z.number().int().positive().optional(), + pageToken: z.string().regex(/^\d{0,6}$/,"Must be the nextPageToken from a previous call").optional(), +}); +export type ListLabelsArgs = z.infer; + +interface GmailRestLabel { + id?: string; + name?: string; + type?: string; + color?: { textColor?: string; backgroundColor?: string }; +} +interface GmailLabelList { labels?: GmailRestLabel[] } + +export function listLabelsRequest(): GoogleRequest { + return { method: "GET", host: "gmail.googleapis.com", path: "/gmail/v1/users/me/labels" }; +} + +function byNameThenId(a: { labelId: string; name: string }, b: { labelId: string; name: string }): number { + if (a.name !== b.name) return a.name < b.name ? -1 : 1; + if (a.labelId !== b.labelId) return a.labelId < b.labelId ? -1 : 1; + return 0; +} + +export function listLabelsResult(list: GmailLabelList, input: ListLabelsArgs): CallToolResult { + const labels = (list.labels ?? []) + .filter((label) => label.type === "user" && typeof label.id === "string" && typeof label.name === "string") + .map((label) => compact({ + labelId: label.id!, + name: label.name!, + color: label.color?.textColor && label.color.backgroundColor + ? { textColor: label.color.textColor, backgroundColor: label.color.backgroundColor } + : undefined, + })) + .sort(byNameThenId); + const start = Number(input.pageToken ?? "0"); + const end = start + Math.min(input.pageSize ?? DEFAULT_LABEL_PAGE_SIZE, MAX_LABEL_PAGE_SIZE); + return structuredResult(compact({ + labels: labels.slice(start, end), + nextPageToken: end < labels.length ? String(end) : undefined, + })); +} + +export const listLabels = defineTool({ + definition: { + name: "list_labels", + description: "Lists the user-defined labels in the signed-in user's Gmail with their IDs and names, sorted by name. Use the IDs with list_threads, and the names (spaces written as hyphens) with `label:` in search queries. System labels are not listed; their IDs are INBOX, SPAM, TRASH, UNREAD, STARRED, IMPORTANT, SENT, DRAFT and CHAT.", + inputSchema: { + type: "object", + properties: { + pageSize: { type: "integer", description: "Optional. Most labels to return. Default 100, maximum 500." }, + pageToken: { type: "string", description: "Optional. The nextPageToken from a previous call. Leave empty for the first page." }, + }, + }, + outputSchema: { + type: "object", + properties: { + labels: { + type: "array", + description: "User labels.", + items: { + type: "object", + properties: { + labelId: { type: "string", description: "The label ID." }, + name: { type: "string", description: "The label's display name." }, + color: { + type: "object", + description: "The label's color, if set.", + properties: { + textColor: { type: "string", description: "Text color, hex such as #000000." }, + backgroundColor: { type: "string", description: "Background color, hex such as #4a86e8." }, + }, + }, + }, + required: ["labelId", "name"], + }, + }, + nextPageToken: { type: "string", description: "Pass as pageToken to get the next page. Present only when there are more results." }, + }, + }, + annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false }, + }, + args, + async run(input, http) { + return listLabelsResult(await http.send(listLabelsRequest()), input); + }, +}); diff --git a/server/src/google-workspace-rest-tools/gmail/list-threads.test.ts b/server/src/google-workspace-rest-tools/gmail/list-threads.test.ts new file mode 100644 index 00000000000..fd0d55de4b1 --- /dev/null +++ b/server/src/google-workspace-rest-tools/gmail/list-threads.test.ts @@ -0,0 +1,60 @@ +import { describe, expect, it } from "vitest"; +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 { listThreads, listThreadsQuery, listThreadsToolRequest } from "./list-threads.js"; +import { searchThreadsResult } from "./search-threads.js"; + +describe("list_threads request", () => { + it("lists threads without drafts, spam or trash by default", () => { + expect(listThreadsToolRequest({})).toEqual({ + method: "GET", host: "gmail.googleapis.com", path: "/gmail/v1/users/me/threads", + query: { q: "-in:draft", includeSpamTrash: undefined, labelIds: undefined, maxResults: 20, pageToken: undefined }, + }); + }); + + it("passes label filters and keeps the label's own drafts, spam or trash", () => { + expect(listThreadsToolRequest({ labelIds: ["INBOX", "Label_42"] }).query).toMatchObject({ labelIds: ["INBOX", "Label_42"], q: "-in:draft" }); + expect(listThreadsQuery({ labelIds: ["DRAFT"] })).toEqual({ q: undefined, includeSpamTrash: undefined }); + expect(listThreadsQuery({ labelIds: ["SPAM"] })).toEqual({ q: "-in:draft", includeSpamTrash: true }); + expect(listThreadsQuery({ labelIds: ["TRASH"] })).toEqual({ q: "-in:draft -in:spam", includeSpamTrash: true }); + expect(listThreadsQuery({ includeTrash: true })).toEqual({ q: "-in:draft -in:spam", includeSpamTrash: true }); + }); + + it("defaults the page size to 20 and caps it at 50", () => { + expect(listThreadsToolRequest({ pageSize: 500 }).query?.maxResults).toBe(50); + expect(listThreadsToolRequest({ pageSize: 5, pageToken: "page-2-token" }).query).toMatchObject({ maxResults: 5, pageToken: "page-2-token" }); + }); +}); + +describe("list_threads tool", () => { + it("returns the same shape as search_threads", 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 listThreads.call({ labelIds: ["INBOX"] }, createGoogleHttp({ accessToken: "t", fetch })); + expect(result.structuredContent).toEqual(searchThreadsResult(THREAD_LIST, [THREAD_ONE], {}).structuredContent); + expect(calls).toHaveLength(3); + expect(calls[0]!.url.searchParams.getAll("labelIds")).toEqual(["INBOX"]); + }); + + it("makes at most 51 requests at the maximum page size", async () => { + const ids = Array.from({ length: 80 }, (_, index) => `t${index}`); + const { fetch, calls } = fakeGoogle(({ url }) => (url.pathname.endsWith("/threads") + ? json({ threads: ids.slice(0, Number(url.searchParams.get("maxResults"))).map((id) => ({ id })) }) + : json({ id: url.pathname.split("/").pop(), messages: [] }))); + const result = await listThreads.call({ pageSize: 1000 }, createGoogleHttp({ accessToken: "t", fetch })); + expect((result.structuredContent as { threads: unknown[] }).threads).toHaveLength(50); + expect(calls).toHaveLength(51); + }); + + it("refuses label IDs that are not Gmail IDs and too many labels", async () => { + const { fetch, calls } = fakeGoogle(() => json({})); + const http = createGoogleHttp({ accessToken: "t", fetch }); + expect((await listThreads.call({ labelIds: ["a&b=c"] }, http)).isError).toBe(true); + expect((await listThreads.call({ labelIds: Array.from({ length: 21 }, (_, index) => `Label_${index}`) }, http)).isError).toBe(true); + expect(calls).toHaveLength(0); + }); +}); diff --git a/server/src/google-workspace-rest-tools/gmail/list-threads.ts b/server/src/google-workspace-rest-tools/gmail/list-threads.ts new file mode 100644 index 00000000000..5d8efc039a7 --- /dev/null +++ b/server/src/google-workspace-rest-tools/gmail/list-threads.ts @@ -0,0 +1,96 @@ +import { z } from "zod"; +import type { GoogleRequest } from "../google-http.js"; +import { defineTool } from "../tool.js"; +import { + DEFAULT_PAGE_SIZE, + MAX_PAGE_SIZE, + readThreads, + searchThreadsResult, + THREAD_VIEWS, + threadIds, + type GmailThreadList, +} from "./search-threads.js"; +import { messageSchema } from "./schemas.js"; + +export const MAX_LABEL_FILTERS = 20; + +const args = z.object({ + pageSize: z.number().int().positive().optional(), + pageToken: z.string().max(2048).optional(), + labelIds: z.array(z.string().regex(/^[A-Za-z0-9_-]{1,256}$/, "Must be a Gmail label ID")).max(MAX_LABEL_FILTERS).optional(), + includeTrash: z.boolean().optional(), + view: z.enum(THREAD_VIEWS).optional(), +}); +export type ListThreadsArgs = z.infer; + +export function listThreadsQuery(input: ListThreadsArgs): { q?: string; includeSpamTrash?: true } { + const labels = new Set(input.labelIds ?? []); + const includeSpamTrash = Boolean(input.includeTrash) || labels.has("SPAM") || labels.has("TRASH"); + const excluded: string[] = []; + if (!labels.has("DRAFT")) excluded.push("-in:draft"); + if (includeSpamTrash && !labels.has("SPAM")) excluded.push("-in:spam"); + return { q: excluded.join(" ") || undefined, includeSpamTrash: includeSpamTrash ? true : undefined }; +} + +export function listThreadsToolRequest(input: ListThreadsArgs): GoogleRequest { + return { + method: "GET", + host: "gmail.googleapis.com", + path: "/gmail/v1/users/me/threads", + query: { + ...listThreadsQuery(input), + labelIds: input.labelIds?.length ? input.labelIds : undefined, + maxResults: Math.min(input.pageSize ?? DEFAULT_PAGE_SIZE, MAX_PAGE_SIZE), + pageToken: input.pageToken || undefined, + }, + }; +} + +export const listThreads = defineTool({ + definition: { + name: "list_threads", + description: "Lists the signed-in user's Gmail threads, newest first, one page at a time, optionally only threads that have every given label. Returns thread IDs with message summaries, not full bodies; use get_thread with a thread ID for full messages. To filter by words, senders or dates, use search_threads.", + 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." }, + labelIds: { + type: "array", + items: { type: "string" }, + description: "Optional. Only threads with all of these label IDs, at most 20. User label IDs come from list_labels; system label IDs are INBOX, SPAM, TRASH, UNREAD, STARRED, IMPORTANT, SENT, DRAFT and CHAT. Drafts are excluded unless DRAFT is given.", + }, + 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: "The threads on this page.", + 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(listThreadsToolRequest(input)); + return searchThreadsResult(list, await readThreads(threadIds(list), http), { view: input.view }); + }, +}); diff --git a/server/src/google-workspace-rest-tools/gmail/message.ts b/server/src/google-workspace-rest-tools/gmail/message.ts index 7e728456fd7..ec601561c6f 100644 --- a/server/src/google-workspace-rest-tools/gmail/message.ts +++ b/server/src/google-workspace-rest-tools/gmail/message.ts @@ -1,8 +1,9 @@ import { z } from "zod"; import { GoogleToolError } from "../errors.js"; -import type { GoogleRequest } from "../google-http.js"; +import type { GoogleHttp, GoogleRequest } from "../google-http.js"; import { compact } from "../tool.js"; import { parseAddressList } from "./address.js"; +import { mapLimited } from "./parallel.js"; export interface GmailHeader { name?: string; value?: string } export interface GmailMessagePart { @@ -44,7 +45,8 @@ export interface McpGmailMessage extends Record { 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 MESSAGE_ID = /^[A-Za-z0-9_-]{1,256}$/; +export const gmailId = z.string().regex(MESSAGE_ID, "Must be a Gmail ID"); const ATTACHMENT_ID = /^[A-Za-z0-9_-]{1,4096}$/; export function header(part: GmailMessagePart | undefined, name: string): string | undefined { @@ -112,7 +114,9 @@ export function externalBodyIds(payload: GmailMessagePart | undefined): string[] } 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."); + if (!ATTACHMENT_ID.test(attachmentId) || !MESSAGE_ID.test(messageId)) { + throw new GoogleToolError("incomplete", "Gmail returned a message body this tool cannot read."); + } return { method: "GET", host: "gmail.googleapis.com", @@ -120,6 +124,40 @@ export function bodyAttachmentRequest(messageId: string, attachmentId: string): }; } +export type MessageBodies = ReadonlyMap>; + +export const MAX_SEPARATE_BODIES_PER_CALL = 20; + +export async function readMessageBodies(messages: readonly GmailRestMessage[], http: GoogleHttp): Promise { + const jobs = messages.flatMap((message) => externalBodyIds(message.payload).map((attachmentId) => ({ messageId: message.id ?? "", attachmentId }))); + if (jobs.length > MAX_SEPARATE_BODIES_PER_CALL) { + throw new GoogleToolError( + "incomplete", + `Could not read the full body of every message: they need ${jobs.length} separate body reads and one call makes at most ${MAX_SEPARATE_BODIES_PER_CALL}. Ask for fewer results, or read the messages one at a time with get_message.`, + ); + } + const answers = await mapLimited(jobs, async ({ messageId, attachmentId }) => { + let answer: GmailRestAttachment; + try { + answer = await http.send(bodyAttachmentRequest(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."); + return answer.data; + }); + const bodies = new Map>(); + jobs.forEach(({ messageId, attachmentId }, index) => { + const forMessage = bodies.get(messageId) ?? new Map(); + forMessage.set(attachmentId, answers[index]!); + bodies.set(messageId, forMessage); + }); + return bodies; +} + export interface MessageContent { plaintextBody?: string; htmlBody?: string; diff --git a/server/src/google-workspace-rest-tools/gmail/parallel.test.ts b/server/src/google-workspace-rest-tools/gmail/parallel.test.ts new file mode 100644 index 00000000000..02bcac92621 --- /dev/null +++ b/server/src/google-workspace-rest-tools/gmail/parallel.test.ts @@ -0,0 +1,39 @@ +import { describe, expect, it } from "vitest"; +import { GoogleToolError } from "../errors.js"; +import { mapLimited, unlessMissing } from "./parallel.js"; + +describe("mapLimited", () => { + it("keeps order and never runs more than the limit at once", async () => { + let running = 0; + let peak = 0; + const results = await mapLimited(Array.from({ length: 25 }, (_, index) => index), async (value) => { + running += 1; + peak = Math.max(peak, running); + await new Promise((resolve) => setTimeout(resolve, 1)); + running -= 1; + return value * 2; + }, 10); + expect(results).toEqual(Array.from({ length: 25 }, (_, index) => index * 2)); + expect(peak).toBe(10); + }); + + it("stops starting new reads after a failure", async () => { + const started: number[] = []; + await expect(mapLimited(Array.from({ length: 30 }, (_, index) => index), async (value) => { + started.push(value); + if (value === 0) throw new Error("boom"); + await new Promise((resolve) => setTimeout(resolve, 5)); + return value; + }, 2)).rejects.toThrow("boom"); + await new Promise((resolve) => setTimeout(resolve, 20)); + expect(started.length).toBeLessThanOrEqual(3); + }); +}); + +describe("unlessMissing", () => { + it("turns not_found into null and rethrows everything else", async () => { + await expect(unlessMissing(Promise.reject(new GoogleToolError("not_found", "gone", 404)))).resolves.toBeNull(); + await expect(unlessMissing(Promise.reject(new GoogleToolError("unavailable", "down", 503)))).rejects.toThrow("down"); + await expect(unlessMissing(Promise.resolve(1))).resolves.toBe(1); + }); +}); diff --git a/server/src/google-workspace-rest-tools/gmail/parallel.ts b/server/src/google-workspace-rest-tools/gmail/parallel.ts new file mode 100644 index 00000000000..4122cc97b03 --- /dev/null +++ b/server/src/google-workspace-rest-tools/gmail/parallel.ts @@ -0,0 +1,31 @@ +import { GoogleToolError } from "../errors.js"; + +export const GMAIL_READ_CONCURRENCY = 10; + +export async function mapLimited(items: readonly T[], read: (item: T) => Promise, limit = GMAIL_READ_CONCURRENCY): Promise { + const results = new Array(items.length); + let next = 0; + let failed = false; + const worker = async () => { + while (!failed && next < items.length) { + const index = next++; + try { + results[index] = await read(items[index]!); + } catch (error) { + failed = true; + throw error; + } + } + }; + await Promise.all(Array.from({ length: Math.min(limit, items.length) }, worker)); + return results; +} + +export async function unlessMissing(read: Promise): Promise { + try { + return await read; + } catch (error) { + if (error instanceof GoogleToolError && error.kind === "not_found") return null; + throw error; + } +} diff --git a/server/src/google-workspace-rest-tools/gmail/schemas.ts b/server/src/google-workspace-rest-tools/gmail/schemas.ts index 01ea4ed11cc..80b4d72adbe 100644 --- a/server/src/google-workspace-rest-tools/gmail/schemas.ts +++ b/server/src/google-workspace-rest-tools/gmail/schemas.ts @@ -26,3 +26,18 @@ export const messageSchema = { labelIds: stringArray("User label IDs and the system labels INBOX, SPAM, TRASH, UNREAD, STARRED, IMPORTANT, SENT, DRAFT and CHAT."), }, } as const; + +export const draftSchema = { + type: "object", + properties: { + id: { type: "string", description: "The draft ID." }, + subject: { type: "string", description: "The draft's subject line. Not with DRAFT_VIEW_METADATA_ONLY." }, + threadId: { type: "string", description: "The ID of the thread the draft belongs to." }, + toRecipients: stringArray("To recipient email addresses."), + ccRecipients: stringArray("Cc recipient email addresses."), + bccRecipients: stringArray("Bcc recipient email addresses."), + plaintextBody: { type: "string", description: "The plain-text body, if any. Not with DRAFT_VIEW_METADATA_ONLY." }, + date: { type: "string", description: "The draft date, ISO 8601 (YYYY-MM-DD)." }, + htmlBody: { type: "string", description: "The HTML body, if any. Not with DRAFT_VIEW_METADATA_ONLY." }, + }, +} as const; diff --git a/server/src/google-workspace-rest-tools/gmail/search-messages.test.ts b/server/src/google-workspace-rest-tools/gmail/search-messages.test.ts new file mode 100644 index 00000000000..dc2430a37b0 --- /dev/null +++ b/server/src/google-workspace-rest-tools/gmail/search-messages.test.ts @@ -0,0 +1,98 @@ +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 { FULL_MESSAGE, MESSAGE_LIST, METADATA_MESSAGE } from "./fixtures/gmail-rest.js"; +import { getMessageResult } from "./get-message.js"; +import { listMessagesRequest, searchMessageFormat, searchMessages, searchMessagesResult } from "./search-messages.js"; + +describe("search_messages request", () => { + it("lists messages with the same draft and spam rules as search_threads", () => { + expect(listMessagesRequest({ query: "from:avery@example.test" })).toEqual({ + method: "GET", host: "gmail.googleapis.com", path: "/gmail/v1/users/me/messages", + query: { q: "(from:avery@example.test) -in:draft", maxResults: 20, pageToken: undefined, includeSpamTrash: undefined }, + }); + expect(listMessagesRequest({ includeTrash: true }).query).toMatchObject({ q: "-in:draft -in:spam", includeSpamTrash: true }); + expect(listMessagesRequest({ query: "in:draft" }).query?.q).toBe("in:draft"); + }); + + it("defaults the page size to 20, caps it at 50, and defaults to summaries", () => { + expect(listMessagesRequest({ pageSize: 500, pageToken: "p2" }).query).toMatchObject({ maxResults: 50, pageToken: "p2" }); + expect(searchMessageFormat(undefined)).toBe("MINIMAL"); + expect(searchMessageFormat("MESSAGE_FORMAT_UNSPECIFIED")).toBe("MINIMAL"); + expect(searchMessageFormat("FULL_CONTENT")).toBe("FULL_CONTENT"); + }); +}); + +describe("search_messages result", () => { + it("maps each message exactly as get_message does", () => { + const result = searchMessagesResult(MESSAGE_LIST, [METADATA_MESSAGE, null, FULL_MESSAGE], { messageFormat: "FULL_CONTENT" }); + expect(result.structuredContent).toEqual({ + messages: [ + getMessageResult(METADATA_MESSAGE, { messageId: METADATA_MESSAGE.id }).structuredContent, + getMessageResult(FULL_MESSAGE, { messageId: FULL_MESSAGE.id }).structuredContent, + ], + nextPageToken: "messages-page-2", + resultCountEstimate: "37", + }); + }); + + it("returns an empty page without nextPageToken", () => { + expect(searchMessagesResult({ resultSizeEstimate: 0 }, [], {}).structuredContent).toEqual({ messages: [], resultCountEstimate: "0" }); + }); +}); + +describe("search_messages tool", () => { + it("lists, then reads each message's summary headers, skipping one deleted in between", async () => { + const { fetch, calls } = fakeGoogle(({ url }) => { + if (url.pathname.endsWith("/messages")) return json(MESSAGE_LIST); + if (url.pathname.endsWith("/messages/18c0ffee00000002")) return json(METADATA_MESSAGE); + return json({ error: { code: 404 } }, 404); + }); + const result = await searchMessages.call({ query: "plan" }, createGoogleHttp({ accessToken: "t", fetch })); + expect(result.structuredContent).toEqual({ + messages: [getMessageResult(METADATA_MESSAGE, { messageId: METADATA_MESSAGE.id, messageFormat: "MINIMAL" }).structuredContent], + nextPageToken: "messages-page-2", + resultCountEstimate: "37", + }); + expect(calls.slice(1).map((call) => call.url.searchParams.get("format"))).toEqual(["metadata", "metadata"]); + }); + + it("fetches separately stored bodies for FULL_CONTENT and fails explicitly when one cannot be read", async () => { + const stored = { + id: "18c0ffee00000002", + payload: { mimeType: "text/plain", body: { size: 9000, attachmentId: "ANGjdJ_stored" } }, + }; + const body = "x".repeat(9000); + const route = (attachment: () => Response) => fakeGoogle(({ url }) => { + if (url.pathname.endsWith("/messages")) return json({ messages: [{ id: "18c0ffee00000002" }] }); + if (url.pathname.includes("/attachments/")) return attachment(); + return json(stored); + }); + const ok = route(() => json({ data: Buffer.from(body).toString("base64url") })); + const full = await searchMessages.call({ messageFormat: "FULL_CONTENT" }, createGoogleHttp({ accessToken: "t", fetch: ok.fetch })); + expect((full.structuredContent as { messages: Array<{ plaintextBody: string }> }).messages[0]!.plaintextBody).toBe(body); + expect(ok.calls).toHaveLength(3); + expect(ok.calls[1]!.url.searchParams.get("format")).toBe("full"); + + const broken = route(() => json({ size: 9000 })); + const failed = await searchMessages.call({ messageFormat: "FULL_CONTENT" }, createGoogleHttp({ accessToken: "t", fetch: broken.fetch })); + expect(failed.isError).toBe(true); + expect((failed.content[0] as { text: string }).text).toMatch(/^Could not read the full body of this message/); + }); + + it("makes at most 51 requests at the maximum page size with summaries", async () => { + const ids = Array.from({ length: 80 }, (_, index) => `m${index}`); + const { fetch, calls } = fakeGoogle(({ url }) => (url.pathname.endsWith("/messages") + ? json({ messages: ids.slice(0, Number(url.searchParams.get("maxResults"))).map((id) => ({ id })) }) + : json({ id: url.pathname.split("/").pop() }))); + const result = await searchMessages.call({ pageSize: 99 }, createGoogleHttp({ accessToken: "t", fetch })); + expect((result.structuredContent as { messages: unknown[] }).messages).toHaveLength(50); + expect(calls).toHaveLength(51); + }); + + it("surfaces an auth failure on a message read instead of a partial page", async () => { + const { fetch } = fakeGoogle(({ url }) => (url.pathname.endsWith("/messages") ? json(MESSAGE_LIST) : json({}, 401))); + await expect(searchMessages.call({}, createGoogleHttp({ accessToken: "t", fetch }))).rejects.toBeInstanceOf(GoogleWorkspaceAuthError); + }); +}); diff --git a/server/src/google-workspace-rest-tools/gmail/search-messages.ts b/server/src/google-workspace-rest-tools/gmail/search-messages.ts new file mode 100644 index 00000000000..eb73dab6ef1 --- /dev/null +++ b/server/src/google-workspace-rest-tools/gmail/search-messages.ts @@ -0,0 +1,108 @@ +import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js"; +import { z } from "zod"; +import type { GoogleHttp, GoogleRequest } from "../google-http.js"; +import { compact, defineTool, structuredResult } from "../tool.js"; +import { getMessageRequest, MESSAGE_FORMATS, messageDetail } from "./get-message.js"; +import { readMessageBodies, toMcpMessage, type GmailRestMessage, type MessageBodies } from "./message.js"; +import { mapLimited, unlessMissing } from "./parallel.js"; +import { messageSchema } from "./schemas.js"; +import { DEFAULT_PAGE_SIZE, effectiveQuery, MAX_PAGE_SIZE } from "./search-threads.js"; + +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(), + messageFormat: z.enum(MESSAGE_FORMATS).optional(), +}); +export type SearchMessagesArgs = z.infer; + +interface GmailMessageList { + messages?: Array<{ id?: string; threadId?: string }>; + nextPageToken?: string; + resultSizeEstimate?: number; +} + +export function searchMessageFormat(format: SearchMessagesArgs["messageFormat"]): Exclude { + return format === undefined || format === "MESSAGE_FORMAT_UNSPECIFIED" ? "MINIMAL" : format; +} + +export function listMessagesRequest(input: SearchMessagesArgs): GoogleRequest { + return { + method: "GET", + host: "gmail.googleapis.com", + path: "/gmail/v1/users/me/messages", + 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 messageIds(list: GmailMessageList): string[] { + return (list.messages ?? []).map((message) => message.id).filter((id): id is string => typeof id === "string" && /^[A-Za-z0-9_-]{1,256}$/.test(id)); +} + +export function searchMessagesResult( + list: GmailMessageList, + messages: Array, + input: SearchMessagesArgs, + bodies: MessageBodies = new Map(), +): CallToolResult { + const detail = messageDetail(searchMessageFormat(input.messageFormat)); + return structuredResult(compact({ + messages: messages + .filter((message): message is GmailRestMessage => message !== null) + .map((message) => toMcpMessage(message, detail, bodies.get(message.id ?? ""))), + nextPageToken: list.nextPageToken || undefined, + resultCountEstimate: typeof list.resultSizeEstimate === "number" ? String(list.resultSizeEstimate) : undefined, + })); +} + +async function readMessages(ids: string[], input: SearchMessagesArgs, http: GoogleHttp): Promise> { + const messageFormat = searchMessageFormat(input.messageFormat); + return mapLimited(ids, (messageId) => unlessMissing(http.send(getMessageRequest({ messageId, messageFormat })))); +} + +export const searchMessages = defineTool({ + definition: { + name: "search_messages", + description: "Lists the signed-in user's Gmail messages that match an optional Gmail search query, newest first, one page at a time. Returns message summaries by default; set messageFormat to FULL_CONTENT for bodies, or use get_message with a message ID.", + inputSchema: { + type: "object", + properties: { + pageSize: { type: "integer", description: "Optional. Most messages 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 a label name with spaces written as hyphens (for example `label:client-work`), not a label ID; list_labels lists the names. Without a query, all messages except spam and trash are listed. Drafts are excluded unless the query includes in:draft.", + }, + includeTrash: { type: "boolean", description: "Optional. Include messages in Trash. Default false." }, + messageFormat: { + type: "string", + enum: [...MESSAGE_FORMATS], + description: "Optional. How much of each message to return. MINIMAL (default): snippet and the Subject, From, To, Cc and Date headers. FULL_CONTENT: MINIMAL plus the bodies and attachments. METADATA_ONLY: no subject, snippet, body or attachment names.", + }, + }, + }, + outputSchema: { + type: "object", + properties: { + messages: { type: "array", items: messageSchema, description: "Matching messages, newest 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(listMessagesRequest(input)); + const messages = await readMessages(messageIds(list), input, http); + const full = messageDetail(searchMessageFormat(input.messageFormat)) === "full"; + const bodies = full ? await readMessageBodies(messages.filter((message): message is GmailRestMessage => message !== null), http) : undefined; + return searchMessagesResult(list, messages, input, bodies); + }, +}); diff --git a/server/src/google-workspace-rest-tools/gmail/search-threads.ts b/server/src/google-workspace-rest-tools/gmail/search-threads.ts index d148c9badda..3e2244fb6ae 100644 --- a/server/src/google-workspace-rest-tools/gmail/search-threads.ts +++ b/server/src/google-workspace-rest-tools/gmail/search-threads.ts @@ -6,7 +6,7 @@ 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 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; @@ -20,12 +20,12 @@ const args = z.object({ }); export type SearchThreadsArgs = z.infer; -interface GmailThreadList { +export interface GmailThreadList { threads?: Array<{ id?: string }>; nextPageToken?: string; resultSizeEstimate?: number; } -interface GmailRestThread { id?: string; messages?: GmailRestMessage[] } +export interface GmailRestThread { id?: string; messages?: GmailRestMessage[] } export function unquotedOperators(query: string): string { return query.replace(/"[^"]*"?/g, " "); @@ -86,7 +86,7 @@ export function searchThreadsResult(list: GmailThreadList, threads: Array> { +export async function readThreads(ids: string[], http: GoogleHttp): Promise> { const results: Array = new Array(ids.length).fill(null); let next = 0; let failed = false; @@ -109,7 +109,7 @@ async function readThreads(ids: string[], http: GoogleHttp): Promise { 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"]); + expect(tools.map((tool) => tool.name)).toEqual([ + "get_message", "search_threads", "create_draft", "get_thread", "get_draft", "list_drafts", "list_labels", "list_threads", "search_messages", + ]); for (const tool of tools) { expect(tool.inputSchema.type).toBe("object"); expect(tool.outputSchema?.type).toBe("object");