mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-11-22 20:29:18 +01:00
feat(google-workspace): remaining Gmail read tools in the REST tool set (#22014)
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work > - Agents use Gmail through the built-in Google Workspace connector > - Google's hosted Gmail MCP server is a Developer Preview, so Paperclip launches on its own REST-backed tool set in `server/src/google-workspace-rest-tools/` (#22000) > - That folder has 3 of the 9 Gmail tools on the reviewed allowlist (`toolScopes.gmail`) > - Agents cannot read a whole thread, list drafts, list labels or search single messages > - This pull request adds the 6 missing read tools, with the same names, inputs and results as Google's MCP tools where Google documents them > - The benefit is that Gmail is complete on the REST transport, and a message looks the same from every tool ## Linked Issues or Issue Description Refs #22000 **Problem** The REST-backed Gmail tool set implements only `get_message`, `search_threads` and `create_draft`. The allowlist also names `get_thread`, `get_draft`, `list_drafts`, `list_labels`, `list_threads` and `search_messages`. **Proposed solution** Implement the 6 read tools in the folder. Follow the existing patterns: one file per tool, pure request and result functions, synthetic unit tests. **Why it matters** Google's reviewers compare an email in Paperclip with the same email in Gmail. Full threads and drafts must show complete bodies. ## What Changed - Add `get_thread`, `list_drafts` and `list_labels`. Their schemas come from Google's Gmail MCP reference. - Add `get_draft`, `list_threads` and `search_messages`. Google's reference does not list them, so their schemas copy the sibling tools. The README lists them under "Not verified against Google's servers". - Move separately stored body reads from `get_message` into `readMessageBodies` in `gmail/message.ts`. All tools that return bodies use it. A body that cannot be read fails the call with "Could not read the full body of this message". - Add `gmail/parallel.ts`: a 10-at-a-time read pool that stops after the first failure, and a helper that skips items deleted between list and get. - Cap page sizes (50 for threads, messages and drafts; 500 for labels, which Gmail returns in one request). The README has a table of Google requests per call at the maximum page size. - Update descriptions: `search_threads` now points to `get_thread` and `list_labels`. The `label:` search operator takes label names (spaces as hyphens), not IDs. This corrects the wording in the original tools. Google's MCP reference says IDs; the README records the difference, and a test prevents drift. - Cap separately stored body reads at 20 per call. The README lists requests and quota units per call at the maximum page size. - `allowlist.test.ts` now asserts that Gmail implements all 9 allowlisted tools and that only `create_draft` writes. ## Verification - `cd server && npx vitest run src/google-workspace-rest-tools`: 15 files, 156 tests pass. Tests use synthetic fixtures and a fake `fetch` only. - `cd server && npx tsc --noEmit -p .`: passes. - `pnpm verify`: exit 2 (the README is a broad input). Required CI supplies the broad coverage. - Tests prove: each tool maps messages exactly as `get_message` does; separately stored bodies are fetched; a failed body read is an explicit error; request counts at the maximum page size (51); invalid IDs send no request; caller cancellation stops the call. ## Risks - Low risk. Nothing outside the folder imports it yet (`boundary.test.ts`). - `get_draft`, `list_threads` and `search_messages` have no Google schema. A switch back to Google's MCP servers would drop them unless Google adds them. - `list_labels` leaves out `threadsTotal` and `threadsUnread`: REST returns them only with one request per label. - One call reads at most 20 separately stored bodies. Beyond that it returns an explicit "Could not read the full body of every message" error and fetches none. The worst single call is 71 requests and 3,405 Gmail quota units (per-user limit: 6,000 per minute). A second maximal call in the same minute can get a `rate_limited` tool error. ## Model Used - Claude Opus 5.5 (`claude-opus-5-5`), Anthropic, via Claude Code with tool use (file edits, shell, web fetch of Google's public reference). ## Checklist - [x] I have included a thinking path that traces from project context to this change - [x] I have specified the model used (with version and capability details) - [x] I have checked ROADMAP.md and confirmed this PR does not duplicate planned core work - [x] I have searched GitHub for duplicate or related PRs and linked them above - [x] I have either (a) linked existing issues with `Fixes: #` / `Closes #` / `Refs #` OR (b) described the issue in-PR following the relevant issue template - [x] I have not referenced internal/instance-local Paperclip issues or links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip` URLs) - [x] My branch name describes the change (e.g. `docs/...`, `fix/...`) and contains no internal Paperclip ticket id or instance-derived details - [x] I have run tests locally and they pass - [x] I have added or updated tests where applicable - [x] I have updated relevant documentation to reflect my changes - [x] I have considered and documented any risks above - [ ] All Paperclip CI gates are green - [ ] Greptile is 5/5 with no open P2s, recommendations, or follow-ups - [x] I will address all Greptile and reviewer comments before requesting merge 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
1 parent
c652c813bc
commit
1d3b4201e3
23 files changed
+1418
-58
No files matched your search
@@ -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
|
||||
(<https://developers.google.com/workspace/gmail/api/reference/quota>, 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).
|
||||
|
||||
@@ -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<string, { description?: string }> | 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"]);
|
||||
});
|
||||
});
|
||||
@@ -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 <avery@example.test>" },
|
||||
{ name: "Cc", value: "casey@example.test" },
|
||||
{ name: "Bcc", value: "\"Ops\" <ops@example.test>" },
|
||||
{ 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("<p>Draft reply</p>") } },
|
||||
],
|
||||
},
|
||||
},
|
||||
};
|
||||
|
||||
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" } },
|
||||
],
|
||||
};
|
||||
@@ -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: "<p>Draft reply</p>",
|
||||
});
|
||||
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);
|
||||
});
|
||||
});
|
||||
@@ -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<typeof args>;
|
||||
|
||||
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<string, unknown> {
|
||||
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<MessageBodies | undefined> {
|
||||
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<GmailRestDraftFull>(readDraftRequest(input.draftId, input.view));
|
||||
return getDraftResult(draft, input, await readDraftBodies([draft], input.view, http));
|
||||
},
|
||||
});
|
||||
@@ -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<Map<string, string>> {
|
||||
const bodies = new Map<string, string>();
|
||||
if (messageDetail(input.messageFormat) !== "full") return bodies;
|
||||
for (const attachmentId of externalBodyIds(message.payload)) {
|
||||
let answer: GmailRestAttachment;
|
||||
try {
|
||||
answer = await http.send<GmailRestAttachment>(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<ReadonlyMap<string, string> | 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({
|
||||
|
||||
@@ -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<Record<string, unknown>> };
|
||||
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<Record<string, unknown>> };
|
||||
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(`<pre>${large}</pre>`).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(`<pre>${large}</pre>`);
|
||||
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." }] });
|
||||
});
|
||||
});
|
||||
@@ -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<typeof args>;
|
||||
|
||||
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<GmailRestFullThread>(readThreadRequest(input));
|
||||
const bodies = messageDetail(input.messageFormat) === "full" ? await readMessageBodies(thread.messages ?? [], http) : undefined;
|
||||
return getThreadResult(thread, input, bodies);
|
||||
},
|
||||
});
|
||||
@@ -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,
|
||||
];
|
||||
@@ -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);
|
||||
});
|
||||
});
|
||||
@@ -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<typeof args>;
|
||||
|
||||
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<GmailRestDraftFull | null>, 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<Array<GmailRestDraftFull | null>> {
|
||||
return mapLimited(ids, (draftId) => unlessMissing(http.send<GmailRestDraftFull>(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<GmailDraftList>(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);
|
||||
},
|
||||
});
|
||||
@@ -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" });
|
||||
});
|
||||
});
|
||||
@@ -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<typeof args>;
|
||||
|
||||
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<GmailLabelList>(listLabelsRequest()), input);
|
||||
},
|
||||
});
|
||||
@@ -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);
|
||||
});
|
||||
});
|
||||
@@ -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<typeof args>;
|
||||
|
||||
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<GmailThreadList>(listThreadsToolRequest(input));
|
||||
return searchThreadsResult(list, await readThreads(threadIds(list), http), { view: input.view });
|
||||
},
|
||||
});
|
||||
@@ -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<string, unknown> {
|
||||
|
||||
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<string, ReadonlyMap<string, string>>;
|
||||
|
||||
export const MAX_SEPARATE_BODIES_PER_CALL = 20;
|
||||
|
||||
export async function readMessageBodies(messages: readonly GmailRestMessage[], http: GoogleHttp): Promise<MessageBodies> {
|
||||
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<GmailRestAttachment>(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<string, Map<string, string>>();
|
||||
jobs.forEach(({ messageId, attachmentId }, index) => {
|
||||
const forMessage = bodies.get(messageId) ?? new Map<string, string>();
|
||||
forMessage.set(attachmentId, answers[index]!);
|
||||
bodies.set(messageId, forMessage);
|
||||
});
|
||||
return bodies;
|
||||
}
|
||||
|
||||
export interface MessageContent {
|
||||
plaintextBody?: string;
|
||||
htmlBody?: string;
|
||||
|
||||
@@ -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);
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,31 @@
|
||||
import { GoogleToolError } from "../errors.js";
|
||||
|
||||
export const GMAIL_READ_CONCURRENCY = 10;
|
||||
|
||||
export async function mapLimited<T, R>(items: readonly T[], read: (item: T) => Promise<R>, limit = GMAIL_READ_CONCURRENCY): Promise<R[]> {
|
||||
const results = new Array<R>(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<R>(read: Promise<R>): Promise<R | null> {
|
||||
try {
|
||||
return await read;
|
||||
} catch (error) {
|
||||
if (error instanceof GoogleToolError && error.kind === "not_found") return null;
|
||||
throw error;
|
||||
}
|
||||
}
|
||||
@@ -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;
|
||||
@@ -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);
|
||||
});
|
||||
});
|
||||
@@ -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<typeof args>;
|
||||
|
||||
interface GmailMessageList {
|
||||
messages?: Array<{ id?: string; threadId?: string }>;
|
||||
nextPageToken?: string;
|
||||
resultSizeEstimate?: number;
|
||||
}
|
||||
|
||||
export function searchMessageFormat(format: SearchMessagesArgs["messageFormat"]): Exclude<SearchMessagesArgs["messageFormat"], undefined> {
|
||||
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<GmailRestMessage | null>,
|
||||
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<Array<GmailRestMessage | null>> {
|
||||
const messageFormat = searchMessageFormat(input.messageFormat);
|
||||
return mapLimited(ids, (messageId) => unlessMissing(http.send<GmailRestMessage>(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<GmailMessageList>(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);
|
||||
},
|
||||
});
|
||||
@@ -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<typeof args>;
|
||||
|
||||
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<GmailR
|
||||
}));
|
||||
}
|
||||
|
||||
async function readThreads(ids: string[], http: GoogleHttp): Promise<Array<GmailRestThread | null>> {
|
||||
export async function readThreads(ids: string[], http: GoogleHttp): Promise<Array<GmailRestThread | null>> {
|
||||
const results: Array<GmailRestThread | null> = new Array(ids.length).fill(null);
|
||||
let next = 0;
|
||||
let failed = false;
|
||||
@@ -109,7 +109,7 @@ async function readThreads(ids: string[], http: GoogleHttp): Promise<Array<Gmail
|
||||
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.",
|
||||
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_thread with a thread ID for full messages. A thread matches when any of its messages matches.",
|
||||
inputSchema: {
|
||||
type: "object",
|
||||
properties: {
|
||||
@@ -117,7 +117,7 @@ export const searchThreads = defineTool({
|
||||
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.",
|
||||
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 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: {
|
||||
|
||||
@@ -22,7 +22,9 @@ 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"]);
|
||||
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");
|
||||
|
||||
Reference in new issue
Block a user