diff --git a/server/src/google-workspace-rest-tools/README.md b/server/src/google-workspace-rest-tools/README.md index 581bb5530d1..1ef341571d9 100644 --- a/server/src/google-workspace-rest-tools/README.md +++ b/server/src/google-workspace-rest-tools/README.md @@ -13,8 +13,9 @@ Gmail has all nine allowlisted tools: `get_message`, `get_thread`, `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), -both Docs tools and both Slides tools (see "Docs and Slides tools" below), and -all six allowlisted Sheets tools (see "Sheets tools" below). +all eight allowlisted Drive tools (see "Drive tools" below), both Docs tools +and both Slides tools (see "Docs and Slides tools" below), and all six +allowlisted Sheets tools (see "Sheets tools" below). ## Why this exists, and why it is temporary @@ -59,11 +60,16 @@ so they can be deleted cleanly when that happens. says that the change may or may not have been made. Every method other than GET (POST, PATCH, PUT, DELETE) is a write; the only exception is a POST the request marks `readOnly` (Calendar's free/busy query). `www.googleapis.com` - is allowed only under `/calendar/v3/`, `docs.googleapis.com` only under - `/v1/documents/`, `slides.googleapis.com` only under `/v1/presentations/` - and `sheets.googleapis.com` only under `/v4/spreadsheets/`, checked after - URL normalization. -- **One tool, one file.** Each tool in `gmail/`, `calendar/`, `docs/`, `slides/` and `sheets/` is a set of pure functions + is allowed only under the prefixes `GOOGLE_API_PATH_PREFIXES` lists for it + (`/calendar/v3/`, `/drive/v3/`, `/upload/drive/v3/`), `docs.googleapis.com` + only under `/v1/documents/`, `slides.googleapis.com` only under + `/v1/presentations/`, `sheets.googleapis.com` only under `/v4/spreadsheets/` + and `gmail.googleapis.com` only under `/gmail/v1/users/me/`; every allowed host + must have a prefix list (the type requires it, and `google-http.test.ts` + requires an allowed and a rejected path for each). Paths are checked after URL + normalization, so `..` and `%2e%2e` segments cannot leave them. Redirects are + never followed: requests use `redirect: "manual"` and any 3xx is a tool error. +- **One tool, one file.** Each tool in `gmail/`, `calendar/`, `drive/`, `docs/`, `slides/` and `sheets/` is a set of pure functions (arguments to REST request, REST response to MCP result) plus a short `run` that sequences them. The pure functions are unit tested without network. - **`server.ts` is thin MCP wiring:** `tools/list` and `tools/call`. @@ -81,6 +87,9 @@ so they can be deleted cleanly when that happens. | 401 | Throws `GoogleWorkspaceAuthError` (`reason: "unauthenticated"`, JSON-RPC `data: { code: "unauthenticated", httpStatus: 401 }`) | | 403 with insufficient scope (`ACCESS_TOKEN_SCOPE_INSUFFICIENT`, `insufficientPermissions`, or `WWW-Authenticate: error="insufficient_scope"`) | Throws `GoogleWorkspaceAuthError` (`reason: "insufficient_scope"`, `data.code: "insufficient_scope"`, the value the gateway already recognizes) | | 403 API not enabled (`SERVICE_DISABLED`, `accessNotConfigured`) | Tool error result, without the project number | +| 403 `exportSizeLimitExceeded` (Drive) | Tool error: the file is over Google's 10 MB export limit | +| 403 `appNotAuthorizedToFile` (Drive) | Tool error saying `drive.file` covers only files this app created or opened, without the app's project number | +| Any 3xx redirect | Tool error; the redirect is not followed | | Other 403, 404, 400, 429, 5xx, timeout, network failure | Tool error result (`isError: true`) with a short message | | Invalid arguments | Tool error result, no request sent | | Unknown tool | Throws `McpError` `InvalidParams` | @@ -145,6 +154,7 @@ plain constant: no environment variable, instance setting or database row. | Calendar | one `calendarList.list` entry | `calendar.calendarlist.readonly`, `calendar.readonly` | | Calendar | one event of the primary calendar | `calendar.events.readonly`, `calendar.events`, `calendar.readonly` | | Calendar | one minute of `freeBusy.query` on the primary calendar | `calendar.events.freebusy` | + | Drive | `about.get` with `fields=kind` | `drive.readonly`, `drive.file` | Docs and Slides have no probe: every read of either API needs a document or presentation ID, and Google does not document what a made-up ID returns, so @@ -482,6 +492,175 @@ earliest first; working hours and out-of-office settings are not read. comes from REST `transparency`; `conferenceUrl` from `hangoutLink` or the video entry point. +## Drive tools + +Names, input fields, result shapes and annotations come from Google's Drive +MCP reference +(, recorded +2026-11-17) and the `tools/list` of Google's hosted Drive MCP server on the +same date, which adds `snippetVerbosity`, `includeRichMetadata`, +`revisionId`, `pregeneratedId` and `inheritedPermissionsDisabled` to the +published pages. All calls go to the Drive REST API v3 at +`https://www.googleapis.com/drive/v3/` (uploads at +`https://www.googleapis.com/upload/drive/v3/`). The allowlist gives the six +reads `drive.readonly` and the two writes `drive.file`. Each REST method below +accepts that scope according to its reference page (recorded 2026-11-17), so +no broader scope is needed or requested. + +| Tool | REST calls | Scope it runs under | Google reference | +| --- | --- | --- | --- | +| `search_files` | `files.list` | `drive.readonly` | | +| `list_recent_files` | `files.list` | `drive.readonly` | | +| `get_file_metadata` | `files.get` | `drive.readonly` | | +| `get_file_permissions` | `permissions.list` | `drive.readonly` | | +| `read_file_content` | `files.get`, then `files.export` (Google files) or `files.get` with `alt=media` (text files); with comments, `comments.list` | `drive.readonly` | , | +| `download_file_content` | `files.get`, then `files.export`, `files.get` with `alt=media`, or `revisions.get` with `alt=media` | `drive.readonly` | | +| `create_file` | `files.create` (metadata only, or `uploadType=multipart` on the upload path) | `drive.file` | | +| `copy_file` | `files.copy` | `drive.file` | | +| (probe) | `about.get` | `drive.readonly` or `drive.file` | | + +### What `drive.file` allows + +`files.copy` accepts only `drive`, `drive.appdata`, `drive.file` and +`drive.photos.readonly`; `drive.readonly` cannot copy. Google's scope guide +() +says `drive.file` covers files "that you open with an app or that the user +shares with an app". So with `drive.file`: + +- `create_file` creates new files and folders in My Drive, and in folders this + app created or was given. +- `copy_file` copies files this app created or was given. Whether Google also + lets it copy a file the same token can only read through `drive.readonly` is + not documented and has not been tried against Google (see open questions). + When Google refuses, the tool error says that `drive.file` covers only files + this app created or opened, and that nothing was created. The same applies + to a `parentId` the app cannot use. +- Neither tool changes, moves, shares, trashes or deletes an existing file, and + no tool in this folder does. + +### Content + +| File | `read_file_content` | `download_file_content` default | +| --- | --- | --- | +| Google Doc | `files.export` as `text/markdown` | `text/plain` | +| Google Sheet | `text/csv` of the first sheet, after a line saying only the first sheet is shown | `text/csv`, first sheet only (the description says so and names the XLSX type for every sheet) | +| Google Slides | `text/plain` | `text/plain` | +| Google Drawing | not supported | `image/svg+xml` | +| Apps Script | not supported | `application/vnd.google-apps.script+json` | +| Other Google types (folder, form, site, shortcut) | not supported | tool error | +| `text/*`, JSON, XML, YAML, `+json` and `+xml` types | the stored bytes as UTF-8 | the stored bytes | +| Anything else (PDF, Office, images, video) | not supported | the stored bytes | + +`exportMimeType` picks the export format for Google files and is ignored for +other files, as in Google's reference. It must be one of the formats Google's +export table lists for that file type (`EXPORT_FORMATS` in +`drive/content.ts`, from +); +anything else is refused before a request is sent. Every request uses the +`fileId` the caller passed, never an ID taken from Google's answer. `download_file_content` returns +`{ id, title, mimeType, content }`: `content` is base64 and `mimeType` is the +type of the returned bytes (the export format for Google files). +"Not supported" means `fileContent: ""` with `textFormattingNotSupported: +true`, the field Google's result has for this case. Text that is not valid +UTF-8 is also not supported. + +**Size cap.** Every Drive read bounds its final serialized result (the whole +`CallToolResult`, which carries the payload twice: as `structuredContent` and +as its JSON text) to 250,000 bytes (the folder's shared `MAX_RESULT_BYTES`, +checked by `boundedStructuredResult`, both in `tool.ts`). That is about 90 KB of file +bytes for `download_file_content` (base64 adds a third) and about 120 KB of +plain text for `read_file_content`. Content is also never read past 250,000 +bytes (`MAX_CONTENT_BYTES`), since more could never fit: a stored file whose +metadata size is larger is refused before any download, and exports and +revisions are read through `GoogleHttp.download`, which stops at the cap. Both +limits are far under Google's 10 MB export limit +() +and the 20 MB `MAX_RESPONSE_BYTES`. A refused result is an error that says +nothing was returned and how to ask for less (a smaller `pageSize`, no +`includeRichMetadata` or `includeComments`, another export format, or +`read_file_content` for a Google file's text). It never returns cut-short +content. Google's `exportSizeLimitExceeded` answer gives a similar error. `create_file` +uploads at most 5 MB, the limit for one multipart upload. + +**Redirects.** `files.export` and `alt=media` downloads are answered by +`www.googleapis.com` itself. `google-http.ts` never follows a redirect (it +sends `redirect: "manual"`, and the gateway's guarded fetch never follows +one either), so a download Google redirects elsewhere is a tool error, not a +request to a host outside the allowlist. + +### Search + +`search_files` takes Google's MCP query language (`title contains 'x' and +modifiedTime > '...'`). `drive/query.ts` tokenizes and parses it into a tree, +checks each term and operator against the list Google publishes, and writes a +new Drive `q` string from the tree. Values are always re-quoted with `'` and +`\` escaped, so text inside a value can never become an operator; tests cover +quote, backslash and parenthesis injection. Mapping: `title` → `name`; +`parentId = 'x'` → `'x' in parents`; `owner = 'x'` → `'x' in owners`; `!=` on +those → `not ...`; `visibility = 'anyone'` or `'domain'` → both of Drive's +`...CanFind` and `...WithLink` values; other terms pass through. `creator`, +`sharedFrom`, `sharedTo`, `followUp`, `folderProperties` and +`visibility = 'external'` have no Drive `q` equivalent and are refused with an +error rather than ignored. Unless the query uses `trashed`, +`and trashed = false` is added, as Google's tool does. + +Drive's `name contains` is a prefix match ("HelloWorld" matches `'Hello'`, not +`'World'`), so `title contains` is too; the query help says so and suggests +`fullText contains` for a word inside a title. When Google answers +`incompleteSearch: true` (it could not search every corpus), both list tools +return `incompleteSearch: true` so an agent does not take a short list as +proof that a file does not exist. Google's MCP result has no such field. + +### Google requests per call + +`search_files`, `list_recent_files` and `get_file_metadata`: 1. +`get_file_permissions`: 1 per 100 permissions, at most 10 (more is an error). +`download_file_content`: 2 (1 when the stored size is over the cap). +`read_file_content`: 1 for unsupported types, otherwise 2, plus 1 per 100 +comment threads with `includeComments`, at most 10 (more is an error, never a +partial list). `create_file` and `copy_file`: 1. Page size for `search_files` +and `list_recent_files`: default 10, at most 100 (Drive allows 1,000). Reads +may be retried once by `google-http.ts`. Writes never are, and any failure +after a write was sent says it may or may not have happened. + +### Differences from Google's Drive MCP tools + +- **No content snippets.** REST has no generated snippet, so `contentSnippet` + is never returned. `excludeContentSnippets` and `snippetVerbosity` are + accepted (and still may not both be set) but change nothing. +- **Rich metadata.** `includeRichMetadata` adds `ownerName`, + `lastModifyingUserName`, `lastModifyingUserEmail` and `visibility`. + `visibility` comes from the file's `anyone` and `domain` permissions and is + absent when Google does not show the user the file's sharing. + `lastCommentedTime` is not returned; REST has no such field. +- **Text, not extraction.** Google's `read_file_content` also reads PDFs, + Office files, images and video transcripts. REST can only do that by + converting the file into a new Google file, which is a write, so those types + return `textFormattingNotSupported: true`. +- **Spreadsheets** read as CSV of the first sheet only, since Drive's text + exports of a spreadsheet hold only the first sheet. Every sheet needs the + Sheets API. +- **Comments** are listed in `unanchoredComments` and never placed in the + text, so `contentAnchoredComments` is always empty; REST anchors are opaque. +- **`revisionId`** works only for files that are not Google files. +- **`list_recent_files` `orderBy`** maps to Drive's `recency desc`, + `modifiedTime desc` and `modifiedByMeTime desc`; other values fall back to + recency, as Google documents. +- **`search_files` `orderBy`** accepts `modifiedTime` and `viewedByMeTime`, + with `asc` or `desc`; anything else is an error. Without it, Drive's own + order is used, which may differ from Google's relevance order. +- **Shared drives.** Lists include shared-drive items the user can see + (`includeItemsFromAllDrives`), within Drive's default `user` corpus. +- **`create_file` conversion** uses a fixed table (text, Markdown, HTML, RTF, + Word and OpenDocument text to Docs; CSV, TSV, Excel and OpenDocument sheets + to Sheets; PowerPoint and OpenDocument presentations to Slides) instead of + reading Drive's `importFormats`. Without content, only Docs, Sheets, Slides + and folders can be created. +- **`copy_file`** sends no name or folder unless given, so the copy's default + name and folder are the REST defaults. Folders cannot be copied. +- **`pregeneratedId`** is passed to Drive as the new file's `id`. This folder + has no tool that generates IDs. + ## Docs and Slides tools Names and input fields come from Google's MCP references @@ -696,7 +875,7 @@ annotations. kinds and forms that read another file (see "Allowed request kinds"). - At least one request is required. - Descriptions are our own wording. The `documentId` description does not - name Drive's file ID field, since the Drive tool is not in this folder. + name Drive's file ID field. ## Sheets tools @@ -855,6 +1034,10 @@ says `false`. users get the `events.list` fallback, which cannot see coworkers who share only free/busy. Adding `calendar.events.freebusy` (already one of the 14 submitted scopes) to the `calendar.write` profile would fix that. +- Whether `files.copy` with a token that holds `drive.readonly` and + `drive.file` can copy a file the app never created or opened. Google's scope + pages do not say; one live call on the test account will tell. If it cannot, + `copy_file` copies only files this app created or that were opened with it. ## Removal procedure diff --git a/server/src/google-workspace-rest-tools/allowlist.test.ts b/server/src/google-workspace-rest-tools/allowlist.test.ts index 7823bdd0cee..4dbf6898aa5 100644 --- a/server/src/google-workspace-rest-tools/allowlist.test.ts +++ b/server/src/google-workspace-rest-tools/allowlist.test.ts @@ -76,6 +76,22 @@ describe("tool allowlist", () => { expect(listGoogleWorkspaceRestTools("calendar").map((tool) => tool.name).sort()).toEqual([...allowlisted].sort()); }); + it("implements every allowlisted Drive tool (8 of 8), with only create_file and copy_file writing", () => { + const allowlisted = ["download_file_content", "get_file_metadata", "get_file_permissions", "list_recent_files", "read_file_content", "search_files", "copy_file", "create_file"]; + for (const name of allowlisted) expect(googleWorkspaceToolTarget(googleWorkspaceToolName("drive", name)), name).not.toBeNull(); + const tools = listGoogleWorkspaceRestTools("drive"); + expect(tools.map((tool) => tool.name).sort()).toEqual([...allowlisted].sort()); + expect(tools.filter((tool) => tool.annotations?.readOnlyHint !== true).map((tool) => tool.name).sort()).toEqual(["copy_file", "create_file"]); + }); + + it("implements no Drive tool that updates, deletes, trashes, moves or shares a file", () => { + const names = listGoogleWorkspaceRestTools("drive").map((tool) => tool.name); + expect(names.filter((name) => /update|delete|trash|move|share|permission_|rename|empty/i.test(name))).toEqual([]); + for (const name of ["update_file", "trash_file", "share_file", "delete_file"]) { + expect(googleWorkspaceToolTarget(googleWorkspaceToolName("drive", name)), name).toBeNull(); + } + }); + it.each([ ["docs", ["read_doc", "update_doc"], ["update_doc"]], ["slides", ["read_presentation", "update_presentation"], ["update_presentation"]], @@ -119,3 +135,4 @@ describe("tool allowlist", () => { expect(listGoogleWorkspaceRestTools("sheets").map((tool) => tool.name).sort()).toEqual([...allowlisted].sort()); }); }); + diff --git a/server/src/google-workspace-rest-tools/drive/annotations.test.ts b/server/src/google-workspace-rest-tools/drive/annotations.test.ts new file mode 100644 index 00000000000..eaca475c901 --- /dev/null +++ b/server/src/google-workspace-rest-tools/drive/annotations.test.ts @@ -0,0 +1,21 @@ +import { describe, expect, it } from "vitest"; +import { DRIVE_TOOLS } from "./index.js"; + +const READS = ["search_files", "list_recent_files", "get_file_metadata", "get_file_permissions", "read_file_content", "download_file_content"]; +const CREATES = ["create_file", "copy_file"]; + +describe("Drive tool annotations", () => { + it("covers every Drive tool", () => { + expect(DRIVE_TOOLS.map((tool) => tool.definition.name).sort()).toEqual([...READS, ...CREATES].sort()); + }); + + it.each(READS)("%s is a read-only, idempotent, non-destructive tool", (name) => { + const tool = DRIVE_TOOLS.find((candidate) => candidate.definition.name === name)!; + expect(tool.definition.annotations).toEqual({ readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false }); + }); + + it.each(CREATES)("%s is a write that is not idempotent; it only creates new files, so it is not destructive", (name) => { + const tool = DRIVE_TOOLS.find((candidate) => candidate.definition.name === name)!; + expect(tool.definition.annotations).toEqual({ readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true }); + }); +}); diff --git a/server/src/google-workspace-rest-tools/drive/content.ts b/server/src/google-workspace-rest-tools/drive/content.ts new file mode 100644 index 00000000000..90bf91c74e0 --- /dev/null +++ b/server/src/google-workspace-rest-tools/drive/content.ts @@ -0,0 +1,97 @@ +import { GoogleToolError } from "../errors.js"; +import type { GoogleHttp, GoogleRequest } from "../google-http.js"; +import { + DRIVE_HOST, + filePath, + getFileRequest, + GOOGLE_DOC, + GOOGLE_DRAWING, + GOOGLE_SCRIPT, + GOOGLE_SHEET, + GOOGLE_SLIDES, + isGoogleType, + MAX_CONTENT_BYTES, + type RestFile, +} from "./file.js"; + +export const CONTENT_META_FIELDS = "id,name,mimeType,size"; + +const PDF = "application/pdf"; +export const EXPORT_FORMATS: Readonly> = { + [GOOGLE_DOC]: [ + "text/plain", "text/markdown", "text/html", "application/rtf", PDF, "application/epub+zip", "application/zip", + "application/vnd.oasis.opendocument.text", "application/vnd.openxmlformats-officedocument.wordprocessingml.document", + ], + [GOOGLE_SHEET]: [ + "text/csv", "text/tab-separated-values", PDF, "application/zip", + "application/vnd.oasis.opendocument.spreadsheet", "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet", + ], + [GOOGLE_SLIDES]: [ + "text/plain", PDF, "application/vnd.oasis.opendocument.presentation", + "application/vnd.openxmlformats-officedocument.presentationml.presentation", + ], + [GOOGLE_DRAWING]: ["image/svg+xml", "image/png", "image/jpeg", PDF], + [GOOGLE_SCRIPT]: ["application/vnd.google-apps.script+json"], +}; + +export interface ContentPlan { + request: GoogleRequest; + contentType: string; +} + +export function contentMetaRequest(id: string): GoogleRequest { + return getFileRequest(id, CONTENT_META_FIELDS); +} + +export function exportRequest(id: string, mimeType: string): GoogleRequest { + return { method: "GET", host: DRIVE_HOST, path: `${filePath(id)}/export`, query: { mimeType } }; +} + +export function mediaRequest(id: string, revision?: string): GoogleRequest { + const path = revision ? `${filePath(id)}/revisions/${encodeURIComponent(revision)}` : filePath(id); + return { method: "GET", host: DRIVE_HOST, path, query: { alt: "media", supportsAllDrives: revision ? undefined : true } }; +} + +export function tooLargeContent(advice: string, size?: number): GoogleToolError { + const what = size === undefined ? "This file's content is" : `This file is ${size} bytes,`; + return new GoogleToolError("too_large", `${what} more than the ${MAX_CONTENT_BYTES} bytes this tool returns, so nothing was returned. ${advice}`); +} + +export function assertWithinCap(file: RestFile, advice: string): void { + const size = Number(file.size ?? "0"); + if (size > MAX_CONTENT_BYTES) throw tooLargeContent(advice, size); +} + +export function exportFormat(mimeType: string, requested: string | undefined): string { + const formats = EXPORT_FORMATS[mimeType]; + if (!formats) throw new GoogleToolError("unsupported", `Files of type ${mimeType} have no content to download.`); + if (requested === undefined) return formats[0]!; + if (!formats.includes(requested)) { + throw new GoogleToolError("invalid_argument", `This file cannot be exported as ${requested}. Use one of: ${formats.join(", ")}.`); + } + return requested; +} + +export function downloadPlan(id: string, file: RestFile, exportMimeType: string | undefined, revision: string | undefined, advice: string): ContentPlan { + const mimeType = file.mimeType ?? "application/octet-stream"; + if (isGoogleType(mimeType)) { + const target = exportFormat(mimeType, exportMimeType); + if (revision) throw new GoogleToolError("unsupported", "Earlier revisions of Google Docs, Sheets, Slides and other Google files cannot be downloaded with this tool. Omit revisionId to export the current version."); + return { request: exportRequest(id, target), contentType: target }; + } + if (!revision) assertWithinCap(file, advice); + return { request: mediaRequest(id, revision), contentType: mimeType }; +} + +export async function readContentMeta(id: string, http: GoogleHttp): Promise { + return http.send(contentMetaRequest(id)); +} + +export async function fetchContent(plan: ContentPlan, http: GoogleHttp, advice: string): Promise { + try { + return (await http.download(plan.request, MAX_CONTENT_BYTES)).data; + } catch (error) { + if (error instanceof GoogleToolError && error.kind === "too_large" && error.httpStatus !== 403) throw tooLargeContent(advice); + throw error; + } +} diff --git a/server/src/google-workspace-rest-tools/drive/copy-file.test.ts b/server/src/google-workspace-rest-tools/drive/copy-file.test.ts new file mode 100644 index 00000000000..7702dfa27ec --- /dev/null +++ b/server/src/google-workspace-rest-tools/drive/copy-file.test.ts @@ -0,0 +1,58 @@ +import { describe, expect, it } from "vitest"; +import { fakeGoogle, json } from "../fixtures/fake-google.js"; +import { createGoogleHttp } from "../google-http.js"; +import { copyFile, copyFileRequest } from "./copy-file.js"; +import { DOC } from "./fixtures/drive-rest.js"; + +describe("copy_file request", () => { + it.each([ + [{ fileId: "f1" }, {}], + [{ fileId: "f1", title: "" }, {}], + [{ fileId: "f1", title: "Copy", parentId: "folder1" }, { name: "Copy", parents: ["folder1"] }], + [{ fileId: "f1", pregeneratedId: "gen1" }, { id: "gen1" }], + ])("%#: copies %j with body %j", (input, body) => { + expect(copyFileRequest(input)).toEqual({ + method: "POST", + host: "www.googleapis.com", + path: "/drive/v3/files/f1/copy", + query: { fields: expect.stringContaining("webViewLink"), supportsAllDrives: true }, + body, + }); + }); +}); + +describe("copy_file tool", () => { + it("returns the new copy", async () => { + const { fetch, calls } = fakeGoogle(() => json({ ...DOC, id: "copy0001synthetic", name: "Copy of Quarterly plan" })); + const result = await copyFile.call({ fileId: DOC.id }, createGoogleHttp({ accessToken: "t", fetch })); + expect(calls.map((call) => `${call.method} ${call.url.pathname}`)).toEqual(["POST /drive/v3/files/doc0001synthetic/copy"]); + expect(result.structuredContent).toMatchObject({ id: "copy0001synthetic", title: "Copy of Quarterly plan" }); + }); + + it("explains that drive.file may not cover the source, and says nothing was copied", async () => { + const { fetch } = fakeGoogle(() => json({ error: { code: 404, message: "File not found: f1." } }, 404)); + const result = await copyFile.call({ fileId: "f1" }, createGoogleHttp({ accessToken: "t", fetch })); + expect((result.content[0] as { text: string }).text).toBe( + "Google could not find the file, or this connection cannot use it: with drive.file access it can only use files and folders that this app created or that were opened with it. Nothing was created.", + ); + const denied = fakeGoogle(() => json({ error: { code: 403, message: "The user has not granted the app 99 write access", errors: [{ reason: "appNotAuthorizedToFile" }] } }, 403)); + const refused = await copyFile.call({ fileId: "f1", parentId: "p1" }, createGoogleHttp({ accessToken: "t", fetch: denied.fetch })); + expect((refused.content[0] as { text: string }).text).toMatch(/^This connection can change only files that this app created/); + }); + + it("never retries a copy and warns that it may have happened", async () => { + const { fetch, calls } = fakeGoogle(() => json({ error: { code: 502 } }, 502)); + const result = await copyFile.call({ fileId: "f1" }, createGoogleHttp({ accessToken: "t", fetch, retryDelayMs: 0 })); + expect(calls).toHaveLength(1); + expect((result.content[0] as { text: string }).text).toMatch(/may or may not have been made/); + }); + + it("refuses bad IDs without calling Google", async () => { + const { fetch, calls } = fakeGoogle(() => json({})); + const http = createGoogleHttp({ accessToken: "t", fetch }); + for (const args of [{}, { fileId: "../files" }, { fileId: "f1", parentId: "a b" }]) { + expect((await copyFile.call(args, http)).isError).toBe(true); + } + expect(calls).toHaveLength(0); + }); +}); diff --git a/server/src/google-workspace-rest-tools/drive/copy-file.ts b/server/src/google-workspace-rest-tools/drive/copy-file.ts new file mode 100644 index 00000000000..c00184a034b --- /dev/null +++ b/server/src/google-workspace-rest-tools/drive/copy-file.ts @@ -0,0 +1,58 @@ +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"; +import { DRIVE_HOST, fileFields, fileId, fileIdInput, filePath, fileSchema, toMcpFile, writeScopeHint, type RestFile } from "./file.js"; + +const args = z.object({ + fileId, + title: z.string().max(1024).optional(), + parentId: fileId.optional(), + pregeneratedId: fileId.optional(), +}); +export type CopyFileArgs = z.infer; + +export function copyFileRequest(input: CopyFileArgs): GoogleRequest { + return { + method: "POST", + host: DRIVE_HOST, + path: `${filePath(input.fileId)}/copy`, + query: { fields: fileFields(), supportsAllDrives: true }, + body: compact({ + name: input.title || undefined, + parents: input.parentId ? [input.parentId] : undefined, + id: input.pregeneratedId, + }), + }; +} + +export function copyFileResult(file: RestFile): CallToolResult { + return structuredResult(toMcpFile(file)); +} + +export const copyFile = defineTool({ + definition: { + name: "copy_file", + description: "Copies a Drive file into a new file and returns the copy. The original is not changed. Folders cannot be copied. Without title the copy gets Google's default name; without parentId Google places it next to the original when it can. Writes use Drive file access (drive.file), so Google may refuse a file or folder that this app did not create or open; the call then returns an error and nothing is copied.", + inputSchema: { + type: "object", + properties: { + fileId: fileIdInput("ID of the file to copy."), + title: { type: "string", description: "Optional. Title of the copy. Default: Google's default copy name." }, + parentId: { type: "string", description: "Optional. ID of the folder for the copy. Default: the original's folder." }, + pregeneratedId: { type: "string", description: "Optional. A Drive-generated ID to give the copy. Not for Google Docs, Sheets or Slides." }, + }, + required: ["fileId"], + }, + outputSchema: fileSchema, + annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true }, + }, + args, + async run(input, http) { + try { + return copyFileResult(await http.send(copyFileRequest(input))); + } catch (error) { + throw writeScopeHint(error, input.parentId ? "the file or the target folder" : "the file"); + } + }, +}); diff --git a/server/src/google-workspace-rest-tools/drive/create-file.test.ts b/server/src/google-workspace-rest-tools/drive/create-file.test.ts new file mode 100644 index 00000000000..976235c2fa9 --- /dev/null +++ b/server/src/google-workspace-rest-tools/drive/create-file.test.ts @@ -0,0 +1,112 @@ +import { describe, expect, it } from "vitest"; +import { fakeGoogle, json } from "../fixtures/fake-google.js"; +import { createGoogleHttp } from "../google-http.js"; +import { createFile, createFileRequest, createPlan, decodeBase64, multipartBody, type CreateFileArgs } from "./create-file.js"; + +const DOC_TYPE = "application/vnd.google-apps.document"; +const created = { id: "new0001synthetic", name: "Notes", mimeType: DOC_TYPE, parents: ["root0001"], webViewLink: "https://docs.example.test/d/new0001synthetic" }; + +describe("create plan", () => { + it.each<[string, CreateFileArgs, unknown]>([ + ["an empty Google Doc", { title: "Notes", contentMimeType: DOC_TYPE }, { metadata: { name: "Notes", mimeType: DOC_TYPE } }], + ["an empty Sheet via the deprecated mimeType", { title: "S", mimeType: "application/vnd.google-apps.spreadsheet" }, { metadata: { name: "S", mimeType: "application/vnd.google-apps.spreadsheet" } }], + ["a folder in a parent, without inherited sharing", { title: "F", contentMimeType: "application/vnd.google-apps.folder", parentId: "parent1", inheritedPermissionsDisabled: true }, { metadata: { name: "F", mimeType: "application/vnd.google-apps.folder", parents: ["parent1"], inheritedPermissionsDisabled: true } }], + ["a folder with a pregenerated ID", { title: "F", contentMimeType: "application/vnd.google-apps.folder", pregeneratedId: "gen1" }, { metadata: { name: "F", mimeType: "application/vnd.google-apps.folder", id: "gen1" } }], + ["text converted to a Doc", { title: "T", contentMimeType: "text/plain", textContent: "hi" }, { metadata: { name: "T", mimeType: DOC_TYPE }, media: { contentType: "text/plain", data: Buffer.from("hi") } }], + ["Markdown converted to a Doc", { title: "M", contentMimeType: "text/markdown", textContent: "# x" }, { metadata: { name: "M", mimeType: DOC_TYPE }, media: { contentType: "text/markdown", data: Buffer.from("# x") } }], + ["CSV converted to a Sheet", { title: "C", contentMimeType: "text/csv", textContent: "a,b" }, { metadata: { name: "C", mimeType: "application/vnd.google-apps.spreadsheet" }, media: { contentType: "text/csv", data: Buffer.from("a,b") } }], + ["text kept as text", { title: "T", contentMimeType: "text/plain", textContent: "hi", disableConversionToGoogleType: true }, { metadata: { name: "T", mimeType: "text/plain" }, media: { contentType: "text/plain", data: Buffer.from("hi") } }], + ["bytes with no Google equivalent", { title: "P", contentMimeType: "image/png", base64Content: "iVBORw==" }, { metadata: { name: "P", mimeType: "image/png" }, media: { contentType: "image/png", data: Buffer.from("iVBORw==", "base64") } }], + ["the deprecated content field", { title: "P", contentMimeType: "application/pdf", content: "JVBERg==" }, { metadata: { name: "P", mimeType: "application/pdf" }, media: { contentType: "application/pdf", data: Buffer.from("%PDF") } }], + ["unconverted bytes with a pregenerated ID", { title: "P", contentMimeType: "image/png", base64Content: "AA==", pregeneratedId: "gen2", disableConversionToGoogleType: true }, { metadata: { name: "P", mimeType: "image/png", id: "gen2" }, media: { contentType: "image/png", data: Buffer.from([0]) } }], + ])("plans %s", (_name, input, expected) => { + expect(createPlan(input)).toEqual(expected); + }); + + it.each<[string, CreateFileArgs, RegExp]>([ + ["two contents", { title: "T", contentMimeType: "text/plain", textContent: "a", base64Content: "YQ==" }, /only one of/], + ["no content and no type", { title: "T" }, /Without content, contentMimeType must be/], + ["no content with a plain type", { title: "T", contentMimeType: "text/plain" }, /Without content/], + ["content without a type", { title: "T", textContent: "a" }, /contentMimeType is required/], + ["content typed as a Google file", { title: "T", contentMimeType: DOC_TYPE, textContent: "a" }, /not a Google file type/], + ["a pregenerated ID for a Doc", { title: "T", contentMimeType: DOC_TYPE, pregeneratedId: "gen1" }, /pregeneratedId cannot be used/], + ["a pregenerated ID with conversion", { title: "T", contentMimeType: "text/plain", textContent: "a", pregeneratedId: "gen1" }, /set disableConversionToGoogleType/], + ["inherited sharing off for a Doc", { title: "T", contentMimeType: DOC_TYPE, inheritedPermissionsDisabled: true }, /folders only/], + ["invalid base64", { title: "T", contentMimeType: "image/png", base64Content: "not base64!" }, /not valid base64/], + ["content over 5 MB", { title: "T", contentMimeType: "text/plain", textContent: "é".repeat(2.5 * 1024 * 1024 + 1) }, /at most 5 MB/], + ])("refuses %s", (_name, input, message) => { + expect(() => createPlan(input)).toThrow(message); + }); + + it("decodes standard and URL-safe base64, ignoring whitespace", () => { + expect(decodeBase64("aGVs\nbG8=")).toEqual(Buffer.from("hello")); + expect(decodeBase64("-_8")).toEqual(Buffer.from([0xfb, 0xff])); + expect(() => decodeBase64("abcde")).toThrow(/not valid base64/); + }); + + it("builds a multipart/related body with the metadata first and the bytes unchanged", () => { + const body = multipartBody({ name: "x" }, { contentType: "image/png", data: Buffer.from([0, 255, 13, 10]) }, "BOUNDARY"); + expect(body).toEqual(Buffer.concat([ + Buffer.from("--BOUNDARY\r\nContent-Type: application/json; charset=UTF-8\r\n\r\n{\"name\":\"x\"}\r\n--BOUNDARY\r\nContent-Type: image/png\r\n\r\n"), + Buffer.from([0, 255, 13, 10]), + Buffer.from("\r\n--BOUNDARY--\r\n"), + ])); + }); + + it("creates empty Google files with a metadata-only POST and uploads content to the upload path", () => { + expect(createFileRequest(createPlan({ title: "N", contentMimeType: DOC_TYPE }), "b")).toMatchObject({ + method: "POST", host: "www.googleapis.com", path: "/drive/v3/files", body: { name: "N", mimeType: DOC_TYPE }, + }); + const upload = createFileRequest(createPlan({ title: "N", contentMimeType: "text/plain", textContent: "x" }), "b"); + expect(upload).toMatchObject({ + method: "POST", host: "www.googleapis.com", path: "/upload/drive/v3/files", + query: { uploadType: "multipart", supportsAllDrives: true }, + upload: { contentType: "multipart/related; boundary=b" }, + }); + expect(upload.body).toBeUndefined(); + }); +}); + +describe("create_file tool", () => { + it("uploads text and returns the new file", async () => { + const { fetch, calls } = fakeGoogle(() => json(created)); + const result = await createFile.call({ title: "Notes", contentMimeType: "text/plain", textContent: "hello" }, createGoogleHttp({ accessToken: "t", fetch })); + expect(calls).toHaveLength(1); + expect(calls[0]!.url.pathname).toBe("/upload/drive/v3/files"); + expect(calls[0]!.headers["content-type"]).toMatch(/^multipart\/related; boundary=[0-9a-f]{32}$/); + const raw = calls[0]!.raw!.toString("utf8"); + expect(raw).toContain("{\"name\":\"Notes\",\"mimeType\":\"application/vnd.google-apps.document\"}"); + expect(raw).toContain("Content-Type: text/plain\r\n\r\nhello\r\n"); + expect(result.structuredContent).toEqual({ + id: "new0001synthetic", title: "Notes", parentId: "root0001", mimeType: DOC_TYPE, viewUrl: "https://docs.example.test/d/new0001synthetic", canAddChildren: false, + }); + }); + + it("never retries and says the file may exist after a failure once sent", async () => { + const { fetch, calls } = fakeGoogle(() => json({ error: { code: 503 } }, 503)); + const result = await createFile.call({ title: "N", contentMimeType: DOC_TYPE }, createGoogleHttp({ accessToken: "t", fetch, retryDelayMs: 0 })); + expect(calls).toHaveLength(1); + expect((result.content[0] as { text: string }).text).toMatch(/may or may not have been made/); + const network = fakeGoogle(() => { throw new TypeError("fetch failed"); }); + const dropped = await createFile.call({ title: "N", contentMimeType: "text/plain", textContent: "x" }, createGoogleHttp({ accessToken: "t", fetch: network.fetch, retryDelayMs: 0 })); + expect(network.calls).toHaveLength(1); + expect((dropped.content[0] as { text: string }).text).toMatch(/may or may not have been made/); + }); + + it("explains a parent folder the app cannot use", async () => { + const { fetch } = fakeGoogle(() => json({ error: { code: 404, message: "File not found: parent1." } }, 404)); + const result = await createFile.call({ title: "N", contentMimeType: DOC_TYPE, parentId: "parent1" }, createGoogleHttp({ accessToken: "t", fetch })); + expect((result.content[0] as { text: string }).text).toBe( + "Google could not find the parent folder, or this connection cannot use it: with drive.file access it can only use files and folders that this app created or that were opened with it. Nothing was created.", + ); + }); + + it("sends nothing for invalid input", async () => { + const { fetch, calls } = fakeGoogle(() => json(created)); + const http = createGoogleHttp({ accessToken: "t", fetch }); + for (const args of [{}, { title: "" }, { title: "T", contentMimeType: "text/plain\r\nX: y", textContent: "a" }, { title: "T", contentMimeType: DOC_TYPE, parentId: "../x" }]) { + expect((await createFile.call(args, http)).isError).toBe(true); + } + expect(calls).toHaveLength(0); + }); +}); diff --git a/server/src/google-workspace-rest-tools/drive/create-file.ts b/server/src/google-workspace-rest-tools/drive/create-file.ts new file mode 100644 index 00000000000..e70a04b9994 --- /dev/null +++ b/server/src/google-workspace-rest-tools/drive/create-file.ts @@ -0,0 +1,160 @@ +import { randomBytes } from "node:crypto"; +import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js"; +import { z } from "zod"; +import { GoogleToolError } from "../errors.js"; +import { formatBytes, type GoogleRequest } from "../google-http.js"; +import { compact, defineTool, structuredResult } from "../tool.js"; +import { + DRIVE_BASE, + DRIVE_HOST, + DRIVE_UPLOAD_BASE, + fileFields, + fileId, + fileSchema, + GOOGLE_DOC, + GOOGLE_FOLDER, + GOOGLE_SHEET, + GOOGLE_SLIDES, + isGoogleType, + MAX_UPLOAD_BYTES, + mimeTypeArg, + toMcpFile, + writeScopeHint, + type RestFile, +} from "./file.js"; + +const MAX_BASE64_LENGTH = Math.ceil(MAX_UPLOAD_BYTES / 3) * 4 + 1024; +const base64Arg = z.string().max(MAX_BASE64_LENGTH * 2); + +const args = z.object({ + title: z.string().min(1).max(1024), + contentMimeType: mimeTypeArg.optional(), + mimeType: mimeTypeArg.optional(), + base64Content: base64Arg.optional(), + textContent: z.string().max(MAX_UPLOAD_BYTES).optional(), + content: base64Arg.optional(), + parentId: fileId.optional(), + disableConversionToGoogleType: z.boolean().optional(), + inheritedPermissionsDisabled: z.boolean().optional(), + pregeneratedId: fileId.optional(), +}); +export type CreateFileArgs = z.infer; + +export const EMPTY_CREATABLE = new Set([GOOGLE_DOC, GOOGLE_SHEET, GOOGLE_SLIDES, GOOGLE_FOLDER]); + +export const CONVERSIONS: Readonly> = { + "text/plain": GOOGLE_DOC, + "text/html": GOOGLE_DOC, + "text/markdown": GOOGLE_DOC, + "application/rtf": GOOGLE_DOC, + "text/rtf": GOOGLE_DOC, + "application/msword": GOOGLE_DOC, + "application/vnd.openxmlformats-officedocument.wordprocessingml.document": GOOGLE_DOC, + "application/vnd.oasis.opendocument.text": GOOGLE_DOC, + "text/csv": GOOGLE_SHEET, + "text/tab-separated-values": GOOGLE_SHEET, + "application/vnd.ms-excel": GOOGLE_SHEET, + "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet": GOOGLE_SHEET, + "application/vnd.oasis.opendocument.spreadsheet": GOOGLE_SHEET, + "application/vnd.ms-powerpoint": GOOGLE_SLIDES, + "application/vnd.openxmlformats-officedocument.presentationml.presentation": GOOGLE_SLIDES, + "application/vnd.oasis.opendocument.presentation": GOOGLE_SLIDES, +}; + +function invalid(message: string): GoogleToolError { + return new GoogleToolError("invalid_argument", `${message} Nothing was created.`); +} + +export function decodeBase64(value: string): Buffer { + const compacted = value.replace(/\s+/g, "").replace(/-/g, "+").replace(/_/g, "/"); + if (!/^[A-Za-z0-9+/]*={0,2}$/.test(compacted) || compacted.replace(/=+$/, "").length % 4 === 1) { + throw invalid("base64Content is not valid base64."); + } + return Buffer.from(compacted, "base64"); +} + +export interface CreatePlan { metadata: RestFile & { id?: string; inheritedPermissionsDisabled?: boolean }; media?: { contentType: string; data: Buffer } } + +export function createPlan(input: CreateFileArgs): CreatePlan { + const given = [input.base64Content, input.textContent, input.content].filter((value) => value !== undefined); + if (given.length > 1) throw invalid("Pass only one of textContent, base64Content and content."); + const contentType = input.contentMimeType ?? input.mimeType; + const parents = input.parentId ? [input.parentId] : undefined; + const base = { name: input.title, parents, id: input.pregeneratedId }; + if (given.length === 0) { + if (!contentType || !EMPTY_CREATABLE.has(contentType)) { + throw invalid(`Without content, contentMimeType must be one of ${[...EMPTY_CREATABLE].join(", ")}.`); + } + if (input.pregeneratedId && contentType !== GOOGLE_FOLDER) throw invalid("pregeneratedId cannot be used for Google Docs, Sheets or Slides."); + if (input.inheritedPermissionsDisabled && contentType !== GOOGLE_FOLDER) throw invalid("inheritedPermissionsDisabled applies to folders only."); + return { metadata: compact({ ...base, mimeType: contentType, inheritedPermissionsDisabled: input.inheritedPermissionsDisabled || undefined }) }; + } + if (!contentType) throw invalid("contentMimeType is required when content is given."); + if (isGoogleType(contentType)) throw invalid("contentMimeType must be the type of the uploaded content, not a Google file type."); + if (input.inheritedPermissionsDisabled) throw invalid("inheritedPermissionsDisabled applies to folders only."); + const data = input.textContent !== undefined ? Buffer.from(input.textContent, "utf8") : decodeBase64((input.base64Content ?? input.content)!); + if (data.byteLength > MAX_UPLOAD_BYTES) { + throw new GoogleToolError("too_large", `The content is ${data.byteLength} bytes; this tool uploads at most ${formatBytes(MAX_UPLOAD_BYTES)}. Nothing was created.`); + } + const target = input.disableConversionToGoogleType ? undefined : CONVERSIONS[contentType]; + if (input.pregeneratedId && target) throw invalid("With pregeneratedId and content, set disableConversionToGoogleType to true."); + return { metadata: compact({ ...base, mimeType: target ?? contentType }), media: { contentType, data } }; +} + +export function multipartBody(metadata: object, media: { contentType: string; data: Buffer }, boundary: string): Buffer { + return Buffer.concat([ + Buffer.from(`--${boundary}\r\nContent-Type: application/json; charset=UTF-8\r\n\r\n${JSON.stringify(metadata)}\r\n--${boundary}\r\nContent-Type: ${media.contentType}\r\n\r\n`, "utf8"), + media.data, + Buffer.from(`\r\n--${boundary}--\r\n`, "utf8"), + ]); +} + +export function createFileRequest(plan: CreatePlan, boundary: string): GoogleRequest { + const query = { fields: fileFields(), supportsAllDrives: true }; + if (!plan.media) return { method: "POST", host: DRIVE_HOST, path: `${DRIVE_BASE}/files`, query, body: plan.metadata }; + return { + method: "POST", + host: DRIVE_HOST, + path: `${DRIVE_UPLOAD_BASE}/files`, + query: { uploadType: "multipart", ...query }, + upload: { contentType: `multipart/related; boundary=${boundary}`, data: multipartBody(plan.metadata, plan.media, boundary) }, + }; +} + +export function createFileResult(file: RestFile): CallToolResult { + return structuredResult(toMcpFile(file)); +} + +export const createFile = defineTool({ + definition: { + name: "create_file", + description: "Creates a new file in Google Drive and returns it. It never changes or replaces an existing file. Prefer textContent for text; use base64Content for other bytes. Content is at most 5 MB. contentMimeType is required with content. By default, content Google can convert becomes a Google file: text, Markdown, HTML, RTF and Word files become Google Docs; CSV, TSV and Excel files become Sheets; PowerPoint files become Slides. Set disableConversionToGoogleType to keep the uploaded type. Without content, contentMimeType must be application/vnd.google-apps.document, application/vnd.google-apps.spreadsheet, application/vnd.google-apps.presentation or application/vnd.google-apps.folder. With Drive file access (drive.file), parentId must be a folder this app created or was given.", + inputSchema: { + type: "object", + properties: { + title: { type: "string", description: "Required. Title of the new file." }, + contentMimeType: { type: "string", description: "MIME type of the uploaded content; required when content is given. Without content, the Google file type to create." }, + textContent: { type: "string", description: "Optional. UTF-8 text to upload. Do not combine with base64Content." }, + base64Content: { type: "string", description: "Optional. Base64-encoded bytes to upload. Do not combine with textContent." }, + content: { type: "string", description: "Deprecated: use base64Content or textContent. Base64-encoded content." }, + mimeType: { type: "string", description: "Deprecated: use contentMimeType." }, + parentId: { type: "string", description: "Optional. ID of the folder to create the file in. Default: My Drive." }, + disableConversionToGoogleType: { type: "boolean", description: "Optional. Keep the uploaded MIME type instead of converting to a Google Docs, Sheets or Slides file. Default: false." }, + inheritedPermissionsDisabled: { type: "boolean", description: "Optional. For a new folder: do not inherit the parent folder's sharing." }, + pregeneratedId: { type: "string", description: "Optional. A Drive-generated ID to give the new file. Only for folders and files that are not converted (set disableConversionToGoogleType)." }, + }, + required: ["title"], + }, + outputSchema: fileSchema, + annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true }, + }, + args, + async run(input, http) { + const request = createFileRequest(createPlan(input), randomBytes(16).toString("hex")); + try { + return createFileResult(await http.send(request)); + } catch (error) { + throw input.parentId ? writeScopeHint(error, "the parent folder") : error; + } + }, +}); diff --git a/server/src/google-workspace-rest-tools/drive/download-file-content.test.ts b/server/src/google-workspace-rest-tools/drive/download-file-content.test.ts new file mode 100644 index 00000000000..61549a49956 --- /dev/null +++ b/server/src/google-workspace-rest-tools/drive/download-file-content.test.ts @@ -0,0 +1,145 @@ +import { describe, expect, it } from "vitest"; +import { GoogleToolError } from "../errors.js"; +import { fakeGoogle, json } from "../fixtures/fake-google.js"; +import { createGoogleHttp } from "../google-http.js"; +import { MAX_RESULT_BYTES, serializedResultBytes } from "../tool.js"; +import { downloadPlan } from "./content.js"; +import { downloadFileContent } from "./download-file-content.js"; +import { MAX_CONTENT_BYTES, READ_LESS, type RestFile } from "./file.js"; +import { DOC, DRAWING, FOLDER, FORM, HUGE_PDF, PDF, SHEET, SLIDES, TEXT_FILE } from "./fixtures/drive-rest.js"; + +const plan = (file: RestFile, exportMimeType?: string, revision?: string) => downloadPlan(file.id!, file, exportMimeType, revision, READ_LESS.download); +const target = (file: RestFile, exportMimeType?: string, revision?: string) => { + const planned = plan(file, exportMimeType, revision); + const query = Object.entries(planned.request.query ?? {}).filter(([, value]) => value !== undefined).map(([key, value]) => [key, String(value)]); + return `${planned.request.path}?${new URLSearchParams(query).toString()} as ${planned.contentType}`; +}; + +describe("download plan", () => { + it.each([ + [DOC, undefined, undefined, "/drive/v3/files/doc0001synthetic/export?mimeType=text%2Fplain as text/plain"], + [SHEET, undefined, undefined, "/drive/v3/files/sheet0001synthetic/export?mimeType=text%2Fcsv as text/csv"], + [SLIDES, undefined, undefined, "/drive/v3/files/slides0001synthetic/export?mimeType=text%2Fplain as text/plain"], + [DRAWING, undefined, undefined, "/drive/v3/files/draw0001synthetic/export?mimeType=image%2Fsvg%2Bxml as image/svg+xml"], + [DOC, "application/pdf", undefined, "/drive/v3/files/doc0001synthetic/export?mimeType=application%2Fpdf as application/pdf"], + [DOC, "text/markdown", undefined, "/drive/v3/files/doc0001synthetic/export?mimeType=text%2Fmarkdown as text/markdown"], + [SHEET, "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet", undefined, "/drive/v3/files/sheet0001synthetic/export?mimeType=application%2Fvnd.openxmlformats-officedocument.spreadsheetml.sheet as application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"], + [PDF, undefined, undefined, "/drive/v3/files/pdf0001synthetic?alt=media&supportsAllDrives=true as application/pdf"], + [PDF, "text/plain", undefined, "/drive/v3/files/pdf0001synthetic?alt=media&supportsAllDrives=true as application/pdf"], + [TEXT_FILE, undefined, "rev0001", "/drive/v3/files/text0001synthetic/revisions/rev0001?alt=media as text/plain"], + [HUGE_PDF, undefined, "rev0002", "/drive/v3/files/pdf0002synthetic/revisions/rev0002?alt=media as application/pdf"], + ] as const)("%#: %s with export %s, revision %s", (file, exportMimeType, revision, expected) => { + expect(target(file, exportMimeType, revision)).toBe(expected); + }); + + it.each([ + [FOLDER, undefined, undefined, /have no content to download/], + [FORM, undefined, undefined, /have no content to download/], + [DOC, undefined, "rev0001", /Earlier revisions/], + [HUGE_PDF, undefined, undefined, /This file is 10485761 bytes, more than the 250000 bytes/], + [DOC, "image/png", undefined, /cannot be exported as image\/png. Use one of: text\/plain/], + [SHEET, "text/plain", undefined, /cannot be exported as text\/plain/], + [SLIDES, "application/x-anything", undefined, /cannot be exported/], + ] as const)("%#: refuses %s", (file, exportMimeType, revision, message) => { + expect(() => plan(file, exportMimeType, revision)).toThrow(GoogleToolError); + expect(() => plan(file, exportMimeType, revision)).toThrow(message); + }); + + it("always addresses the file the caller named, not an ID from Google's answer", () => { + expect(downloadPlan("callerFile1", { ...PDF, id: "otherFile9" }, undefined, undefined, "").request.path).toBe("/drive/v3/files/callerFile1"); + expect(downloadPlan("callerFile1", { ...DOC, id: "otherFile9" }, undefined, undefined, "").request.path).toBe("/drive/v3/files/callerFile1/export"); + }); +}); + +describe("download_file_content tool", () => { + it("reads metadata, downloads the bytes, and returns them as base64 with the file's type", async () => { + const bytes = Buffer.from([0x25, 0x50, 0x44, 0x46, 0x00, 0xff]); + const { fetch, calls } = fakeGoogle(({ url }) => (url.searchParams.get("alt") === "media" + ? new Response(bytes, { headers: { "content-type": "application/pdf" } }) + : json(PDF))); + const result = await downloadFileContent.call({ fileId: PDF.id }, createGoogleHttp({ accessToken: "t", fetch })); + expect(calls.map((call) => call.url.pathname)).toEqual(["/drive/v3/files/pdf0001synthetic", "/drive/v3/files/pdf0001synthetic"]); + expect(calls[0]!.url.searchParams.get("fields")).toBe("id,name,mimeType,size"); + expect(calls[1]!.headers.accept).toBe("*/*"); + expect(result.structuredContent).toEqual({ id: PDF.id, title: "report.pdf", mimeType: "application/pdf", content: bytes.toString("base64") }); + }); + + it("downloads only the file the caller named, even if Google's metadata names another", async () => { + const { fetch, calls } = fakeGoogle(({ url }) => (url.searchParams.get("alt") === "media" ? new Response("x") : json({ ...TEXT_FILE, id: "otherFile9" }))); + const result = await downloadFileContent.call({ fileId: "callerFile1" }, createGoogleHttp({ accessToken: "t", fetch })); + expect(calls.map((call) => call.url.pathname)).toEqual(["/drive/v3/files/callerFile1", "/drive/v3/files/callerFile1"]); + expect(result.structuredContent).toMatchObject({ id: "callerFile1" }); + }); + + it("exports a Google Doc as plain text by default and reports the export type", async () => { + const { fetch, calls } = fakeGoogle(({ url }) => (url.pathname.endsWith("/export") ? new Response("Hello\n") : json(DOC))); + const result = await downloadFileContent.call({ fileId: DOC.id }, createGoogleHttp({ accessToken: "t", fetch })); + expect(calls[1]!.url.searchParams.get("mimeType")).toBe("text/plain"); + expect(result.structuredContent).toMatchObject({ mimeType: "text/plain", content: Buffer.from("Hello\n").toString("base64") }); + }); + + it("refuses a file whose stored size is over the cap without downloading it, and says what to do instead", async () => { + const { fetch, calls } = fakeGoogle(() => json(HUGE_PDF)); + const result = await downloadFileContent.call({ fileId: HUGE_PDF.id }, createGoogleHttp({ accessToken: "t", fetch })); + expect(calls).toHaveLength(1); + expect(result).toEqual({ isError: true, content: [{ type: "text", text: `This file is 10485761 bytes, more than the 250000 bytes this tool returns, so nothing was returned. ${READ_LESS.download}` }] }); + }); + + it("refuses an export that streams past the cap, and never returns a cut-short result", async () => { + const { fetch } = fakeGoogle(({ url }) => (url.pathname.endsWith("/export") + ? new Response(new ReadableStream({ + start(controller) { + controller.enqueue(new Uint8Array(MAX_CONTENT_BYTES)); + controller.enqueue(new Uint8Array(1)); + controller.close(); + }, + })) + : json(SHEET))); + const result = await downloadFileContent.call({ fileId: SHEET.id }, createGoogleHttp({ accessToken: "t", fetch })); + expect(result).toEqual({ isError: true, content: [{ type: "text", text: `This file's content is more than the 250000 bytes this tool returns, so nothing was returned. ${READ_LESS.download}` }] }); + }); + + it("bounds the final serialized result: the largest file that fits is returned, one byte more is refused", async () => { + const run = async (size: number) => { + const { fetch } = fakeGoogle(({ url }) => (url.searchParams.get("alt") === "media" + ? new Response(new Uint8Array(size).fill(0xff)) + : json({ ...PDF, size: String(size) }))); + return downloadFileContent.call({ fileId: PDF.id }, createGoogleHttp({ accessToken: "t", fetch })); + }; + let largest = 0; + for (let step = 1 << 17; step >= 1; step >>= 1) { + if (!(await run(largest + step)).isError) largest += step; + } + const fits = await run(largest); + expect(serializedResultBytes(fits)).toBeLessThanOrEqual(MAX_RESULT_BYTES); + expect(serializedResultBytes(fits)).toBeGreaterThan(MAX_RESULT_BYTES - 16); + const over = await run(largest + 3); + expect((over.content[0] as { text: string }).text).toMatch(/^The result is \d+ bytes, more than the 250000 bytes this tool returns, so nothing was returned\. This tool cannot return part of a file/); + }); + + it("reports Google's export size limit as too large", async () => { + const { fetch } = fakeGoogle(({ url }) => (url.pathname.endsWith("/export") + ? json({ error: { code: 403, errors: [{ reason: "exportSizeLimitExceeded" }] } }, 403) + : json(DOC))); + const result = await downloadFileContent.call({ fileId: DOC.id, exportMimeType: "application/pdf" }, createGoogleHttp({ accessToken: "t", fetch })); + expect(result).toEqual({ isError: true, content: [{ type: "text", text: "This file is larger than Google's 10 MB export limit. Nothing was returned." }] }); + }); + + it("does not follow a redirect to another host", async () => { + const { fetch, calls } = fakeGoogle(({ url }) => (url.searchParams.get("alt") === "media" + ? new Response(null, { status: 302, headers: { location: "https://content.example.test/blob" } }) + : json(PDF))); + const result = await downloadFileContent.call({ fileId: PDF.id }, createGoogleHttp({ accessToken: "t", fetch })); + expect(result).toEqual({ isError: true, content: [{ type: "text", text: "Google answered with a redirect, which is not followed." }] }); + expect(calls.every((call) => call.url.host === "www.googleapis.com")).toBe(true); + }); + + it("refuses bad arguments without calling Google", async () => { + const { fetch, calls } = fakeGoogle(() => json(DOC)); + const http = createGoogleHttp({ accessToken: "t", fetch }); + for (const args of [{}, { fileId: "a/b" }, { fileId: DOC.id, exportMimeType: "text/plain\r\nX-Evil: 1" }, { fileId: DOC.id, revisionId: "../x" }]) { + expect((await downloadFileContent.call(args, http)).isError).toBe(true); + } + expect(calls).toHaveLength(0); + }); +}); diff --git a/server/src/google-workspace-rest-tools/drive/download-file-content.ts b/server/src/google-workspace-rest-tools/drive/download-file-content.ts new file mode 100644 index 00000000000..e323fad7d60 --- /dev/null +++ b/server/src/google-workspace-rest-tools/drive/download-file-content.ts @@ -0,0 +1,45 @@ +import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js"; +import { z } from "zod"; +import { defineTool } from "../tool.js"; +import { downloadPlan, fetchContent, readContentMeta } from "./content.js"; +import { boundedResult, fileId, fileIdInput, mimeTypeArg, READ_LESS, revisionId, type RestFile } from "./file.js"; + +const args = z.object({ fileId, exportMimeType: mimeTypeArg.optional(), revisionId: revisionId.optional() }); +export type DownloadFileContentArgs = z.infer; + +export function downloadFileContentResult(id: string, file: RestFile, contentType: string, data: Buffer): CallToolResult { + return boundedResult({ id, title: file.name ?? "", mimeType: contentType, content: data.toString("base64") }, READ_LESS.download); +} + +export const downloadFileContent = defineTool({ + definition: { + name: "download_file_content", + description: "Downloads a Drive file's content as base64. Google Docs, Sheets, Slides, Drawings and Apps Script files are exported: by default Docs and Slides as text/plain, Sheets as text/csv (first sheet only; pass exportMimeType application/vnd.openxmlformats-officedocument.spreadsheetml.sheet for every sheet), Drawings as image/svg+xml, Apps Script as JSON. Other files are returned as stored. The whole result is at most 250,000 bytes (about 90 KB of file content, since base64 is larger and the result carries it twice); a larger file is refused with an error, never cut short. For a readable text version of a document, use read_file_content.", + inputSchema: { + type: "object", + properties: { + fileId: fileIdInput("ID of the file to download."), + exportMimeType: { type: "string", description: "Optional. For Google Docs, Sheets, Slides, Drawings and Apps Script files, the MIME type to export to, one of the formats Google lists for that file type (for example application/pdf or text/markdown for a Doc). Ignored for other files. Default: a text format." }, + revisionId: { type: "string", description: "Optional. ID of an earlier revision of this file to download. Only for files that are not Google Docs, Sheets, Slides or other Google files. Default: the current version." }, + }, + required: ["fileId"], + }, + outputSchema: { + type: "object", + properties: { + id: { type: "string", description: "The file's ID." }, + title: { type: "string", description: "The file's title." }, + mimeType: { type: "string", description: "MIME type of the returned content: the export format for Google files, otherwise the file's own type." }, + content: { type: "string", description: "The content, base64 encoded." }, + }, + required: ["id", "title", "mimeType", "content"], + }, + annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false }, + }, + args, + async run(input, http) { + const file = await readContentMeta(input.fileId, http); + const plan = downloadPlan(input.fileId, file, input.exportMimeType, input.revisionId, READ_LESS.download); + return downloadFileContentResult(input.fileId, file, plan.contentType, await fetchContent(plan, http, READ_LESS.download)); + }, +}); diff --git a/server/src/google-workspace-rest-tools/drive/file.ts b/server/src/google-workspace-rest-tools/drive/file.ts new file mode 100644 index 00000000000..a7d0881a01c --- /dev/null +++ b/server/src/google-workspace-rest-tools/drive/file.ts @@ -0,0 +1,203 @@ +import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js"; +import { z } from "zod"; +import { GoogleToolError } from "../errors.js"; +import type { GoogleRequest } from "../google-http.js"; +import { boundedStructuredResult, compact, MAX_RESULT_BYTES } from "../tool.js"; + +export const DRIVE_HOST = "www.googleapis.com" as const; +export const DRIVE_BASE = "/drive/v3"; +export const DRIVE_UPLOAD_BASE = "/upload/drive/v3"; + +export const MAX_CONTENT_BYTES = MAX_RESULT_BYTES; +export const MAX_UPLOAD_BYTES = 5 * 1024 * 1024; +export const DEFAULT_PAGE_SIZE = 10; +export const MAX_PAGE_SIZE = 100; + +export const GOOGLE_DOC = "application/vnd.google-apps.document"; +export const GOOGLE_SHEET = "application/vnd.google-apps.spreadsheet"; +export const GOOGLE_SLIDES = "application/vnd.google-apps.presentation"; +export const GOOGLE_DRAWING = "application/vnd.google-apps.drawing"; +export const GOOGLE_SCRIPT = "application/vnd.google-apps.script"; +export const GOOGLE_FOLDER = "application/vnd.google-apps.folder"; +export const GOOGLE_APPS_PREFIX = "application/vnd.google-apps."; + +export const fileId = z.string().regex(/^[A-Za-z0-9_-]{1,256}$/, "Must be a Drive file ID"); +export const revisionId = z.string().regex(/^[A-Za-z0-9_-]{1,256}$/, "Must be a Drive revision ID"); +export const mimeTypeArg = z.string().max(255).regex(/^[A-Za-z0-9][A-Za-z0-9!#$&^_.+-]*\/[A-Za-z0-9][A-Za-z0-9!#$&^_.+-]*$/, "Must be a MIME type such as text/plain"); +export const pageSizeArg = z.number().int().min(1).optional(); +export const pageTokenArg = z.string().max(4096).optional(); + +export const SNIPPET_VERBOSITIES = ["UNSPECIFIED", "BRIEF", "MEDIUM", "DETAILED", "MAX_ALLOWED"] as const; +export const snippetArgs = { + excludeContentSnippets: z.boolean().optional(), + snippetVerbosity: z.enum(SNIPPET_VERBOSITIES).optional(), +}; + +export function assertSnippetArgs(input: { excludeContentSnippets?: boolean; snippetVerbosity?: string }): void { + if (input.excludeContentSnippets === true && input.snippetVerbosity !== undefined) { + throw new GoogleToolError("invalid_argument", "Set either excludeContentSnippets or snippetVerbosity, not both."); + } +} + +export function pageSize(value: number | undefined): number { + return Math.min(value ?? DEFAULT_PAGE_SIZE, MAX_PAGE_SIZE); +} + +export function filePath(id: string): string { + return `${DRIVE_BASE}/files/${encodeURIComponent(id)}`; +} + +export interface RestUser { displayName?: string; emailAddress?: string } +export interface RestPermission { + id?: string; type?: string; role?: string; emailAddress?: string; displayName?: string; domain?: string; + allowFileDiscovery?: boolean; view?: string; deleted?: boolean; +} +export interface RestFile { + id?: string; name?: string; mimeType?: string; parents?: string[]; size?: string; description?: string; + fileExtension?: string; webViewLink?: string; sharedWithMeTime?: string; createdTime?: string; + modifiedTime?: string; viewedByMeTime?: string; owners?: RestUser[]; lastModifyingUser?: RestUser; + capabilities?: { canAddChildren?: boolean }; permissions?: RestPermission[]; trashed?: boolean; +} +export interface RestFileList { files?: RestFile[]; nextPageToken?: string; incompleteSearch?: boolean } + +const BASE_FIELDS = "id,name,mimeType,parents,size,description,fileExtension,webViewLink,sharedWithMeTime,createdTime,modifiedTime,viewedByMeTime,owners(emailAddress),capabilities(canAddChildren)"; +const RICH_FIELDS = "owners(emailAddress,displayName),lastModifyingUser(displayName,emailAddress),permissions(type,allowFileDiscovery)"; + +export function fileFields(rich = false): string { + return rich ? `${BASE_FIELDS.replace(",owners(emailAddress)", "")},${RICH_FIELDS}` : BASE_FIELDS; +} + +export function listFields(rich = false): string { + return `nextPageToken,incompleteSearch,files(${fileFields(rich)})`; +} + +export function getFileRequest(id: string, fields: string): GoogleRequest { + return { method: "GET", host: DRIVE_HOST, path: filePath(id), query: { fields, supportsAllDrives: true } }; +} + +export function visibility(permissions: RestPermission[] | undefined): string | undefined { + if (!permissions) return undefined; + const live = permissions.filter((permission) => !permission.deleted); + const anyone = live.filter((permission) => permission.type === "anyone"); + if (anyone.some((permission) => permission.allowFileDiscovery)) return "anyoneCanFind"; + if (anyone.length) return "anyoneWithLink"; + const domain = live.filter((permission) => permission.type === "domain"); + if (domain.some((permission) => permission.allowFileDiscovery)) return "domainCanFind"; + if (domain.length) return "domainWithLink"; + return "limited"; +} + +export function toMcpFile(file: RestFile, rich = false): Record { + const owner = file.owners?.[0]; + return compact({ + id: file.id ?? "", + title: file.name ?? "", + parentId: file.parents?.[0], + mimeType: file.mimeType, + fileSize: file.size, + description: file.description, + fileExtension: file.fileExtension, + viewUrl: file.webViewLink, + sharedWithMeTime: file.sharedWithMeTime, + createdTime: file.createdTime, + modifiedTime: file.modifiedTime, + viewedByMeTime: file.viewedByMeTime, + owner: owner?.emailAddress, + canAddChildren: file.mimeType === GOOGLE_FOLDER ? file.capabilities?.canAddChildren ?? false : false, + ownerName: rich ? owner?.displayName : undefined, + lastModifyingUserName: rich ? file.lastModifyingUser?.displayName : undefined, + lastModifyingUserEmail: rich ? file.lastModifyingUser?.emailAddress : undefined, + visibility: rich ? visibility(file.permissions) : undefined, + }); +} + +const str = (description: string) => ({ type: "string", description }); + +export const fileSchema = { + type: "object", + properties: { + id: str("The file's ID."), + title: str("The file's title."), + parentId: str("ID of the file's parent folder."), + mimeType: str("The file's MIME type."), + fileSize: str("Size in bytes (int64 as a string). Absent for Google Docs, Sheets, Slides and folders."), + description: str("The file's description."), + fileExtension: str("The original file extension. Only for files whose content is stored in Drive."), + contentSnippet: str("Not returned by this implementation."), + viewUrl: str("Link to open the file in a browser."), + sharedWithMeTime: str("When the file was shared with the user (RFC 3339)."), + createdTime: str("When the file was created (RFC 3339)."), + modifiedTime: str("When the file was last modified by anyone (RFC 3339)."), + viewedByMeTime: str("When the user last viewed the file (RFC 3339)."), + owner: str("Email address of the file's owner. Absent for files in shared drives."), + canAddChildren: { type: "boolean", description: "Whether the user can add files to this folder. Always false for files that are not folders." }, + ownerName: str("Owner's name. Only with includeRichMetadata."), + lastModifyingUserName: str("Name of the last person to modify the file. Only with includeRichMetadata."), + lastModifyingUserEmail: str("Email address of the last person to modify the file. Only with includeRichMetadata."), + visibility: str("Link sharing: anyoneCanFind, anyoneWithLink, domainCanFind, domainWithLink or limited. Only with includeRichMetadata, and only when the user can see the file's sharing."), + }, + required: ["id", "title"] as string[], +} as const; + +export const fileListSchema = { + type: "object", + properties: { + files: { type: "array", items: fileSchema, description: "The files." }, + nextPageToken: str("Pass as pageToken to get the next page. Absent on the last page."), + incompleteSearch: { type: "boolean", description: "True when Google could not search every place the user's files are, so matching files may be missing. Absent otherwise. Narrow the query or treat a missing file as not found yet, not as absent." }, + }, + required: ["files"] as string[], +} as const; + +export const fileIdInput = (purpose: string) => str(`Required. ${purpose} A Drive file ID, from search_files or list_recent_files.`); +export const snippetInputs = { + excludeContentSnippets: { type: "boolean", description: "Optional. Accepted for compatibility. This implementation never returns content snippets." }, + snippetVerbosity: { + type: "string", + enum: [...SNIPPET_VERBOSITIES], + description: "Optional. Accepted for compatibility. This implementation never returns content snippets. Must not be set when excludeContentSnippets is true.", + }, +}; +export const richMetadataInput = { + type: "boolean", + description: "Optional. When true, also returns ownerName, lastModifyingUserName, lastModifyingUserEmail and visibility. Default: false.", +}; + +export function listResult(list: RestFileList, rich = false): Record { + return compact({ + files: (list.files ?? []).map((file) => toMcpFile(file, rich)), + nextPageToken: list.nextPageToken || undefined, + incompleteSearch: list.incompleteSearch === true ? true : undefined, + }); +} + +export const READ_LESS = { + download: "This tool cannot return part of a file. For a Google Docs, Sheets or Slides file, read its text with read_file_content or choose a smaller export format with exportMimeType.", + read: "This tool cannot return part of a file. Read it without includeComments if that was set; larger files cannot be read with these tools.", + list: "Ask for fewer files with a smaller pageSize, or leave out includeRichMetadata.", + metadata: "Leave out includeRichMetadata.", + permissions: "This file has too many permissions to list with this tool.", +} as const; + +export function tooLargeMessage(bytes: number, advice: string): string { + return `The result is ${bytes} bytes, more than the ${MAX_RESULT_BYTES} bytes this tool returns, so nothing was returned. ${advice}`; +} + +export function boundedResult(value: Record, advice: string): CallToolResult { + return boundedStructuredResult(value, MAX_RESULT_BYTES, (bytes) => tooLargeMessage(bytes, advice)); +} + +export function isGoogleType(mimeType: string | undefined): boolean { + return Boolean(mimeType?.startsWith(GOOGLE_APPS_PREFIX)); +} + +export function writeScopeHint(error: unknown, what: string): unknown { + if (error instanceof GoogleToolError && error.kind === "not_found") { + return new GoogleToolError( + "not_found", + `Google could not find ${what}, or this connection cannot use it: with drive.file access it can only use files and folders that this app created or that were opened with it. Nothing was created.`, + error.httpStatus, + ); + } + return error; +} diff --git a/server/src/google-workspace-rest-tools/drive/fixtures/drive-rest.ts b/server/src/google-workspace-rest-tools/drive/fixtures/drive-rest.ts new file mode 100644 index 00000000000..89957064915 --- /dev/null +++ b/server/src/google-workspace-rest-tools/drive/fixtures/drive-rest.ts @@ -0,0 +1,33 @@ +import type { RestFile } from "../file.js"; + +export const DOC: RestFile = { + id: "doc0001synthetic", + name: "Quarterly plan", + mimeType: "application/vnd.google-apps.document", + parents: ["folder0001synthetic"], + description: "Synthetic test document", + webViewLink: "https://docs.example.test/document/d/doc0001synthetic/edit", + createdTime: "2026-10-01T09:00:00.000Z", + modifiedTime: "2026-11-02T10:30:00.000Z", + viewedByMeTime: "2026-11-03T08:00:00.000Z", + owners: [{ emailAddress: "owner@example.test", displayName: "Owner Example" }], + lastModifyingUser: { emailAddress: "editor@example.test", displayName: "Editor Example" }, + capabilities: { canAddChildren: false }, +}; + +export const SHEET: RestFile = { id: "sheet0001synthetic", name: "Budget", mimeType: "application/vnd.google-apps.spreadsheet" }; +export const SLIDES: RestFile = { id: "slides0001synthetic", name: "Deck", mimeType: "application/vnd.google-apps.presentation" }; +export const DRAWING: RestFile = { id: "draw0001synthetic", name: "Sketch", mimeType: "application/vnd.google-apps.drawing" }; +export const FORM: RestFile = { id: "form0001synthetic", name: "Survey", mimeType: "application/vnd.google-apps.form" }; + +export const FOLDER: RestFile = { + id: "folder0001synthetic", + name: "Projects", + mimeType: "application/vnd.google-apps.folder", + capabilities: { canAddChildren: true }, +}; + +export const TEXT_FILE: RestFile = { id: "text0001synthetic", name: "notes.txt", mimeType: "text/plain", size: "12", fileExtension: "txt" }; +export const JSON_FILE: RestFile = { id: "json0001synthetic", name: "data.json", mimeType: "application/json", size: "9" }; +export const PDF: RestFile = { id: "pdf0001synthetic", name: "report.pdf", mimeType: "application/pdf", size: "2048", fileExtension: "pdf" }; +export const HUGE_PDF: RestFile = { ...PDF, id: "pdf0002synthetic", size: String(10 * 1024 * 1024 + 1) }; diff --git a/server/src/google-workspace-rest-tools/drive/get-file-metadata.test.ts b/server/src/google-workspace-rest-tools/drive/get-file-metadata.test.ts new file mode 100644 index 00000000000..79921fbbe76 --- /dev/null +++ b/server/src/google-workspace-rest-tools/drive/get-file-metadata.test.ts @@ -0,0 +1,53 @@ +import { describe, expect, it } from "vitest"; +import { fakeGoogle, json } from "../fixtures/fake-google.js"; +import { createGoogleHttp } from "../google-http.js"; +import { visibility } from "./file.js"; +import { DOC, FOLDER } from "./fixtures/drive-rest.js"; +import { getFileMetadata } from "./get-file-metadata.js"; + +describe("visibility", () => { + it.each([ + [undefined, undefined], + [[], "limited"], + [[{ type: "user" }, { type: "group" }], "limited"], + [[{ type: "domain" }], "domainWithLink"], + [[{ type: "domain", allowFileDiscovery: true }], "domainCanFind"], + [[{ type: "domain", allowFileDiscovery: true }, { type: "anyone" }], "anyoneWithLink"], + [[{ type: "anyone", allowFileDiscovery: true }], "anyoneCanFind"], + [[{ type: "anyone", deleted: true }], "limited"], + ])("permissions %j are %s", (permissions, expected) => { + expect(visibility(permissions)).toBe(expected); + }); +}); + +describe("get_file_metadata", () => { + it("reads one file with the fields the MCP shape needs", async () => { + const { fetch, calls } = fakeGoogle(() => json(DOC)); + const result = await getFileMetadata.call({ fileId: DOC.id }, createGoogleHttp({ accessToken: "t", fetch })); + expect(calls[0]!.url.pathname).toBe("/drive/v3/files/doc0001synthetic"); + expect(calls[0]!.url.searchParams.get("supportsAllDrives")).toBe("true"); + expect(calls[0]!.url.searchParams.get("fields")).toContain("webViewLink"); + expect(result.structuredContent).toMatchObject({ id: DOC.id, title: "Quarterly plan", owner: "owner@example.test", viewUrl: DOC.webViewLink }); + expect(result.structuredContent).not.toHaveProperty("ownerName"); + expect(result.structuredContent).not.toHaveProperty("contentSnippet"); + }); + + it("reports canAddChildren for folders only", async () => { + const { fetch } = fakeGoogle(() => json(FOLDER)); + const result = await getFileMetadata.call({ fileId: FOLDER.id, includeRichMetadata: true }, createGoogleHttp({ accessToken: "t", fetch })); + expect(result.structuredContent).toMatchObject({ canAddChildren: true }); + const { fetch: docFetch } = fakeGoogle(() => json({ ...DOC, capabilities: { canAddChildren: true } })); + expect((await getFileMetadata.call({ fileId: DOC.id }, createGoogleHttp({ accessToken: "t", fetch: docFetch }))).structuredContent) + .toMatchObject({ canAddChildren: false }); + }); + + it("returns a tool error for a missing file and sends nothing for a bad ID", async () => { + const { fetch, calls } = fakeGoogle(() => json({ error: { code: 404 } }, 404)); + const http = createGoogleHttp({ accessToken: "t", fetch }); + expect(await getFileMetadata.call({ fileId: "missing1" }, http)).toEqual({ isError: true, content: [{ type: "text", text: "Google could not find that item." }] }); + for (const fileId of ["../about", "a/b", "a?alt=media", "", "x".repeat(257)]) { + expect((await getFileMetadata.call({ fileId }, http)).isError, fileId).toBe(true); + } + expect(calls).toHaveLength(1); + }); +}); diff --git a/server/src/google-workspace-rest-tools/drive/get-file-metadata.ts b/server/src/google-workspace-rest-tools/drive/get-file-metadata.ts new file mode 100644 index 00000000000..a63d76d585e --- /dev/null +++ b/server/src/google-workspace-rest-tools/drive/get-file-metadata.ts @@ -0,0 +1,49 @@ +import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js"; +import { z } from "zod"; +import { defineTool } from "../tool.js"; +import { + assertSnippetArgs, + boundedResult, + READ_LESS, + fileFields, + fileId, + fileIdInput, + fileSchema, + getFileRequest, + richMetadataInput, + snippetArgs, + snippetInputs, + toMcpFile, + type RestFile, +} from "./file.js"; + +const args = z.object({ fileId, includeRichMetadata: z.boolean().optional(), ...snippetArgs }); +export type GetFileMetadataArgs = z.infer; + +export function getFileMetadataResult(file: RestFile, rich: boolean): CallToolResult { + return boundedResult(toMcpFile(file, rich), READ_LESS.metadata); +} + +export const getFileMetadata = defineTool({ + definition: { + name: "get_file_metadata", + description: "Gets a Drive file's metadata: title, type, size, parent folder, owner, times and link. Returns no content snippet; use read_file_content for the text. If the file is not found, find it with search_files.", + inputSchema: { + type: "object", + properties: { + fileId: fileIdInput("ID of the file."), + includeRichMetadata: richMetadataInput, + ...snippetInputs, + }, + required: ["fileId"], + }, + outputSchema: fileSchema, + annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false }, + }, + args, + async run(input, http) { + assertSnippetArgs(input); + const rich = input.includeRichMetadata === true; + return getFileMetadataResult(await http.send(getFileRequest(input.fileId, fileFields(rich))), rich); + }, +}); diff --git a/server/src/google-workspace-rest-tools/drive/get-file-permissions.test.ts b/server/src/google-workspace-rest-tools/drive/get-file-permissions.test.ts new file mode 100644 index 00000000000..d81e4352c53 --- /dev/null +++ b/server/src/google-workspace-rest-tools/drive/get-file-permissions.test.ts @@ -0,0 +1,50 @@ +import { describe, expect, it } from "vitest"; +import { fakeGoogle, json } from "../fixtures/fake-google.js"; +import { createGoogleHttp } from "../google-http.js"; +import { getFilePermissions, permissionsRequest, toMcpPermission } from "./get-file-permissions.js"; + +describe("get_file_permissions mapping", () => { + it.each([ + [{ id: "p1", type: "user", role: "owner", emailAddress: "owner@example.test", displayName: "Owner" }, { role: "owner", type: "user", emailAddress: "owner@example.test", displayName: "Owner" }], + [{ type: "group", role: "writer", emailAddress: "team@example.test", displayName: "Team" }, { role: "writer", type: "group", emailAddress: "team@example.test", displayName: "Team" }], + [{ type: "domain", role: "reader", domain: "example.test" }, { role: "reader", type: "domain", displayName: "example.test" }], + [{ type: "anyone", role: "reader", view: "published" }, { role: "reader", type: "anyone", view: "published" }], + ])("maps %j", (permission, expected) => { + expect(toMcpPermission(permission)).toEqual(expected); + }); + + it("reads 100 at a time across shared drives", () => { + expect(permissionsRequest("file1", "tok")).toMatchObject({ + method: "GET", + path: "/drive/v3/files/file1/permissions", + query: { pageSize: 100, pageToken: "tok", supportsAllDrives: true }, + }); + }); +}); + +describe("get_file_permissions tool", () => { + it("follows pages and leaves out deleted permissions", async () => { + const { fetch, calls } = fakeGoogle(({ url }) => (url.searchParams.get("pageToken") + ? json({ permissions: [{ type: "anyone", role: "reader" }, { type: "user", role: "reader", deleted: true }] }) + : json({ permissions: [{ type: "user", role: "owner", emailAddress: "owner@example.test" }], nextPageToken: "p2" }))); + const result = await getFilePermissions.call({ fileId: "file1" }, createGoogleHttp({ accessToken: "t", fetch })); + expect(calls).toHaveLength(2); + expect(result.structuredContent).toEqual({ + permissions: [{ role: "owner", type: "user", emailAddress: "owner@example.test" }, { role: "reader", type: "anyone" }], + }); + }); + + it("refuses rather than returning part of a very long list", async () => { + let page = 0; + const { fetch, calls } = fakeGoogle(() => json({ permissions: [{ type: "user", role: "reader" }], nextPageToken: `p${++page}` })); + const result = await getFilePermissions.call({ fileId: "file1" }, createGoogleHttp({ accessToken: "t", fetch })); + expect(calls).toHaveLength(10); + expect(result).toEqual({ isError: true, content: [{ type: "text", text: "This file has more than 1000 permissions, more than this tool returns." }] }); + }); + + it("passes on Google's refusal when the user may not see sharing", async () => { + const { fetch } = fakeGoogle(() => json({ error: { code: 403, message: "The user does not have sufficient permissions for this file." } }, 403)); + const result = await getFilePermissions.call({ fileId: "file1" }, createGoogleHttp({ accessToken: "t", fetch })); + expect(result).toEqual({ isError: true, content: [{ type: "text", text: "The user does not have sufficient permissions for this file." }] }); + }); +}); diff --git a/server/src/google-workspace-rest-tools/drive/get-file-permissions.ts b/server/src/google-workspace-rest-tools/drive/get-file-permissions.ts new file mode 100644 index 00000000000..796f856baf9 --- /dev/null +++ b/server/src/google-workspace-rest-tools/drive/get-file-permissions.ts @@ -0,0 +1,94 @@ +import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js"; +import { z } from "zod"; +import { GoogleToolError } from "../errors.js"; +import type { GoogleHttp, GoogleRequest } from "../google-http.js"; +import { compact, defineTool } from "../tool.js"; +import { boundedResult, DRIVE_HOST, fileId, fileIdInput, filePath, READ_LESS, type RestPermission } from "./file.js"; + +const args = z.object({ fileId }); +export type GetFilePermissionsArgs = z.infer; + +export const PERMISSION_PAGE_SIZE = 100; +export const MAX_PERMISSION_PAGES = 10; +const ROLES = ["owner", "organizer", "fileOrganizer", "writer", "commenter", "reader"] as const; +const TYPES = ["user", "group", "domain", "anyone"] as const; +const VIEWS = ["published", "metadata"] as const; + +interface RestPermissionList { permissions?: RestPermission[]; nextPageToken?: string } + +export function permissionsRequest(id: string, pageToken?: string): GoogleRequest { + return { + method: "GET", + host: DRIVE_HOST, + path: `${filePath(id)}/permissions`, + query: { + pageSize: PERMISSION_PAGE_SIZE, + pageToken, + supportsAllDrives: true, + fields: "nextPageToken,permissions(type,role,emailAddress,displayName,domain,view,deleted)", + }, + }; +} + +export function toMcpPermission(permission: RestPermission): Record { + return compact({ + role: permission.role, + displayName: permission.displayName ?? (permission.type === "domain" ? permission.domain : undefined), + type: permission.type, + emailAddress: permission.emailAddress, + view: permission.view, + }); +} + +export function getFilePermissionsResult(permissions: RestPermission[]): CallToolResult { + return boundedResult({ permissions: permissions.filter((permission) => !permission.deleted).map(toMcpPermission) }, READ_LESS.permissions); +} + +export async function readPermissions(id: string, http: GoogleHttp): Promise { + const permissions: RestPermission[] = []; + let pageToken: string | undefined; + for (let page = 0; page < MAX_PERMISSION_PAGES; page += 1) { + const list = await http.send(permissionsRequest(id, pageToken)); + permissions.push(...(list.permissions ?? [])); + pageToken = list.nextPageToken || undefined; + if (!pageToken) return permissions; + } + throw new GoogleToolError("too_large", `This file has more than ${MAX_PERMISSION_PAGES * PERMISSION_PAGE_SIZE} permissions, more than this tool returns.`); +} + +export const getFilePermissions = defineTool({ + definition: { + name: "get_file_permissions", + description: "Lists who has access to a Drive file: each person, group, domain or link-sharing entry and its role. Google returns this only when the user may see the file's sharing.", + inputSchema: { + type: "object", + properties: { fileId: fileIdInput("ID of the file.") }, + required: ["fileId"], + }, + outputSchema: { + type: "object", + properties: { + permissions: { + type: "array", + description: "The file's permissions.", + items: { + type: "object", + properties: { + role: { type: "string", enum: [...ROLES], description: "The role granted." }, + displayName: { type: "string", description: "Name of the user or group, or the domain. Absent for anyone." }, + type: { type: "string", enum: [...TYPES], description: "Who the permission is for." }, + emailAddress: { type: "string", description: "Email address of the user or group." }, + view: { type: "string", enum: [...VIEWS], description: "The view the permission applies to, if any." }, + }, + }, + }, + }, + required: ["permissions"], + }, + annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false }, + }, + args, + async run(input, http) { + return getFilePermissionsResult(await readPermissions(input.fileId, http)); + }, +}); diff --git a/server/src/google-workspace-rest-tools/drive/index.ts b/server/src/google-workspace-rest-tools/drive/index.ts new file mode 100644 index 00000000000..5740f0c13fe --- /dev/null +++ b/server/src/google-workspace-rest-tools/drive/index.ts @@ -0,0 +1,19 @@ +import type { GoogleRequest } from "../google-http.js"; +import type { RestTool } from "../tool.js"; +import { copyFile } from "./copy-file.js"; +import { createFile } from "./create-file.js"; +import { downloadFileContent } from "./download-file-content.js"; +import { DRIVE_BASE, DRIVE_HOST } from "./file.js"; +import { getFileMetadata } from "./get-file-metadata.js"; +import { getFilePermissions } from "./get-file-permissions.js"; +import { listRecentFiles } from "./list-recent-files.js"; +import { readFileContent } from "./read-file-content.js"; +import { searchFiles } from "./search-files.js"; + +export const DRIVE_TOOLS: readonly RestTool[] = [ + searchFiles, listRecentFiles, getFileMetadata, getFilePermissions, readFileContent, downloadFileContent, createFile, copyFile, +]; + +export function driveProbeRequest(): GoogleRequest { + return { method: "GET", host: DRIVE_HOST, path: `${DRIVE_BASE}/about`, query: { fields: "kind" } }; +} diff --git a/server/src/google-workspace-rest-tools/drive/list-recent-files.test.ts b/server/src/google-workspace-rest-tools/drive/list-recent-files.test.ts new file mode 100644 index 00000000000..d127b2d5ecf --- /dev/null +++ b/server/src/google-workspace-rest-tools/drive/list-recent-files.test.ts @@ -0,0 +1,44 @@ +import { describe, expect, it } from "vitest"; +import { fakeGoogle, json } from "../fixtures/fake-google.js"; +import { createGoogleHttp } from "../google-http.js"; +import { PDF } from "./fixtures/drive-rest.js"; +import { listRecentFiles, listRecentFilesRequest, recentOrder } from "./list-recent-files.js"; + +describe("list_recent_files request", () => { + it.each([ + [undefined, "recency desc"], + ["recency", "recency desc"], + ["lastModified", "modifiedTime desc"], + ["lastModifiedByMe", "modifiedByMeTime desc"], + ["name", "recency desc"], + ["toString", "recency desc"], + ["", "recency desc"], + ])("orderBy %j sorts by %s", (orderBy, expected) => { + expect(recentOrder(orderBy)).toBe(expected); + }); + + it("lists files that are not trashed, 10 by default and at most 100", () => { + const request = listRecentFilesRequest({ pageToken: "p2" }); + expect(request).toMatchObject({ method: "GET", host: "www.googleapis.com", path: "/drive/v3/files" }); + expect(request.query).toMatchObject({ q: "trashed = false", orderBy: "recency desc", pageSize: 10, pageToken: "p2" }); + expect(listRecentFilesRequest({ pageSize: 1000 }).query?.pageSize).toBe(100); + }); +}); + +describe("list_recent_files tool", () => { + it("returns one page of files", async () => { + const { fetch, calls } = fakeGoogle(() => json({ files: [PDF] })); + const result = await listRecentFiles.call({ orderBy: "lastModified", pageSize: 5 }, createGoogleHttp({ accessToken: "t", fetch })); + expect(calls[0]!.url.searchParams.get("orderBy")).toBe("modifiedTime desc"); + expect(calls[0]!.url.searchParams.get("pageSize")).toBe("5"); + expect(result.structuredContent).toEqual({ + files: [{ id: "pdf0001synthetic", title: "report.pdf", mimeType: "application/pdf", fileSize: "2048", fileExtension: "pdf", canAddChildren: false }], + }); + }); + + it("turns Google failures into tool errors", async () => { + const { fetch } = fakeGoogle(() => json({ error: { code: 403, errors: [{ reason: "accessNotConfigured" }] } }, 403)); + const result = await listRecentFiles.call({}, createGoogleHttp({ accessToken: "t", fetch })); + expect(result).toMatchObject({ isError: true }); + }); +}); diff --git a/server/src/google-workspace-rest-tools/drive/list-recent-files.ts b/server/src/google-workspace-rest-tools/drive/list-recent-files.ts new file mode 100644 index 00000000000..b94a4f236bd --- /dev/null +++ b/server/src/google-workspace-rest-tools/drive/list-recent-files.ts @@ -0,0 +1,77 @@ +import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js"; +import { z } from "zod"; +import type { GoogleRequest } from "../google-http.js"; +import { defineTool } from "../tool.js"; +import { + assertSnippetArgs, + boundedResult, + READ_LESS, + DRIVE_BASE, + DRIVE_HOST, + fileListSchema, + listFields, + listResult, + pageSize, + pageSizeArg, + pageTokenArg, + snippetArgs, + snippetInputs, + type RestFileList, +} from "./file.js"; + +const args = z.object({ orderBy: z.string().max(64).optional(), pageSize: pageSizeArg, pageToken: pageTokenArg, ...snippetArgs }); +export type ListRecentFilesArgs = z.infer; + +const ORDERS: Readonly> = { + recency: "recency desc", + lastModified: "modifiedTime desc", + lastModifiedByMe: "modifiedByMeTime desc", +}; + +export function recentOrder(value: string | undefined): string { + return (value && Object.hasOwn(ORDERS, value) ? ORDERS[value] : undefined) ?? ORDERS.recency!; +} + +export function listRecentFilesRequest(input: ListRecentFilesArgs): GoogleRequest { + return { + method: "GET", + host: DRIVE_HOST, + path: `${DRIVE_BASE}/files`, + query: { + q: "trashed = false", + orderBy: recentOrder(input.orderBy), + pageSize: pageSize(input.pageSize), + pageToken: input.pageToken, + fields: listFields(), + supportsAllDrives: true, + includeItemsFromAllDrives: true, + }, + }; +} + +export function listRecentFilesResult(list: RestFileList): CallToolResult { + return boundedResult(listResult(list), READ_LESS.list); +} + +export const listRecentFiles = defineTool({ + definition: { + name: "list_recent_files", + description: "Lists the user's Drive files, most recent first, leaving out trashed files. orderBy recency (default) sorts by the latest of the file's times; lastModified by the last change by anyone; lastModifiedByMe by the user's last change. Another value falls back to recency. Default page size 10, at most 100. Pass nextPageToken as pageToken for more. Returns no content snippets.", + inputSchema: { + type: "object", + properties: { + orderBy: { type: "string", description: "Optional. recency (default), lastModified or lastModifiedByMe." }, + pageSize: { type: "integer", description: "Optional. Files per page. Default 10, at most 100." }, + pageToken: { type: "string", description: "Optional. nextPageToken from the previous page." }, + ...snippetInputs, + }, + }, + outputSchema: fileListSchema, + annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false }, + }, + args, + async run(input, http) { + assertSnippetArgs(input); + return listRecentFilesResult(await http.send(listRecentFilesRequest(input))); + }, +}); diff --git a/server/src/google-workspace-rest-tools/drive/query.test.ts b/server/src/google-workspace-rest-tools/drive/query.test.ts new file mode 100644 index 00000000000..e16066ed91d --- /dev/null +++ b/server/src/google-workspace-rest-tools/drive/query.test.ts @@ -0,0 +1,108 @@ +import { describe, expect, it } from "vitest"; +import { GoogleToolError } from "../errors.js"; +import { driveSearchQuery, quote, tokenize } from "./query.js"; + +describe("driveSearchQuery", () => { + it.each([ + [undefined, "trashed = false"], + ["", "trashed = false"], + [" ", "trashed = false"], + ["title contains 'hello'", "(name contains 'hello') and trashed = false"], + ["title = 'Plan'", "(name = 'Plan') and trashed = false"], + ["title != 'Plan'", "(name != 'Plan') and trashed = false"], + ["fullText contains 'launch'", "(fullText contains 'launch') and trashed = false"], + ["mimeType = 'application/pdf'", "(mimeType = 'application/pdf') and trashed = false"], + ["mimeType contains 'image/'", "(mimeType contains 'image/') and trashed = false"], + ["modifiedTime > '2024-01-01T00:00:00Z'", "(modifiedTime > '2024-01-01T00:00:00Z') and trashed = false"], + ["createdTime <= '2012-06-04T12:00:00-08:00'", "(createdTime <= '2012-06-04T12:00:00-08:00') and trashed = false"], + ["viewedByMeTime >= '2026-11-01T00:00:00.123Z'", "(viewedByMeTime >= '2026-11-01T00:00:00.123Z') and trashed = false"], + ["parentId = 'root'", "('root' in parents) and trashed = false"], + ["parentId != 'folder1'", "(not 'folder1' in parents) and trashed = false"], + ["owner = 'me'", "('me' in owners) and trashed = false"], + ["owner != 'test@example.org'", "(not 'test@example.org' in owners) and trashed = false"], + ["'me' in readers", "('me' in readers) and trashed = false"], + ["'colleague@example.org' in writers", "('colleague@example.org' in writers) and trashed = false"], + ["visibility = 'anyoneWithLink'", "(visibility = 'anyoneWithLink') and trashed = false"], + ["visibility = 'anyone'", "((visibility = 'anyoneCanFind' or visibility = 'anyoneWithLink')) and trashed = false"], + ["visibility != 'domain'", "(not (visibility = 'domainCanFind' or visibility = 'domainWithLink')) and trashed = false"], + ["sharedWithMe = true", "(sharedWithMe = true) and trashed = false"], + ["starred = false", "(starred = false) and trashed = false"], + ["starred = TRUE", "(starred = true) and trashed = false"], + ["trashed = true", "trashed = true"], + ["title contains 'x' and trashed = true", "(name contains 'x' and trashed = true)"], + ["not trashed = false", "not trashed = false"], + [ + "title contains 'hello' and title contains 'goodbye'", + "((name contains 'hello' and name contains 'goodbye')) and trashed = false", + ], + [ + "modifiedTime > '2024-01-01T00:00:00Z' and (mimeType contains 'image/' or mimeType contains 'video/')", + "((modifiedTime > '2024-01-01T00:00:00Z' and (mimeType contains 'image/' or mimeType contains 'video/'))) and trashed = false", + ], + ["title = 'x' or title = 'y'", "((name = 'x' or name = 'y')) and trashed = false"], + ["owner = 'me' AND NOT starred = true", "(('me' in owners and not starred = true)) and trashed = false"], + ["title contains \"double\"", "(name contains 'double') and trashed = false"], + ])("translates %j", (query, expected) => { + expect(driveSearchQuery(query)).toBe(expected); + }); + + it.each([ + ["title contains 'O\\'Brien'", "(name contains 'O\\'Brien') and trashed = false"], + ["title contains 'back\\\\slash'", "(name contains 'back\\\\slash') and trashed = false"], + ["title contains 'x\\' or trashed = true or name contains \\'y'", "(name contains 'x\\' or trashed = true or name contains \\'y') and trashed = false"], + ["title contains \"it's\"", "(name contains 'it\\'s') and trashed = false"], + ["title contains \"a\\\\' or 'b\"", "(name contains 'a\\\\\\' or \\'b') and trashed = false"], + ["title contains 'x) or (trashed = true'", "(name contains 'x) or (trashed = true') and trashed = false"], + ])("keeps quotes, backslashes and operators inside a value: %j", (query, expected) => { + expect(driveSearchQuery(query)).toBe(expected); + }); + + it("escapes values so the result always parses back to the same value", () => { + for (const value of ["'", "\\", "\\'", "'\\", "a' or 'b", "x\\' or trashed = true or name contains \\'", "''''", "\\\\\\"]) { + const tokens = tokenize(quote(value)); + expect(tokens).toEqual([{ kind: "string", value }]); + } + }); + + it.each([ + ["title contains 'x", /not closed/], + ["title contains 'x\\", /not closed|backslash/], + ["title", /expected an operator/], + ["title contains", /expected a quoted value/], + ["title contains x", /expected a quoted value/], + ["title > 'x'", /does not support the > operator/], + ["fullText = 'x'", /does not support the = operator/], + ["modifiedTime > 'yesterday'", /RFC 3339/], + ["starred = 'true'", /true or false/], + ["title = true", /quoted value/], + ["creator = 'me'", /creator term is not supported/], + ["sharedFrom = 'a@example.test'", /sharedFrom term is not supported/], + ["sharedTo = 'a@example.test'", /sharedTo term is not supported/], + ["followUp = 'any'", /followUp term is not supported/], + ["'syncedComputer' in folderProperties", /folderProperties term is not supported/], + ["'me' in owners", /works only with readers and writers/], + ["visibility = 'external'", /not supported/], + ["name contains 'x'", /unknown term "name"/], + ["title contains 'x' and", /expected a search term/], + ["(title contains 'x'", /expected "\)"/], + ["title contains 'x')", /unexpected "\)"/], + ["title contains 'x' title contains 'y'", /unexpected "title"/], + ["title contains 'x'; drop", /unexpected character/], + ["'x' in", /expected a term after "in"/], + ["'x'", /expected "in"/], + ["and = 'x'", /expected a search term/], + [`${"(".repeat(40)}starred = true${")".repeat(40)}`, /too deeply nested/], + [`${"not ".repeat(40)}starred = true`, /too deeply nested/], + ["x".repeat(4001), /longer than 4000/], + ])("refuses %j", (query, message) => { + let error: unknown; + try { + driveSearchQuery(query); + } catch (caught) { + error = caught; + } + expect(error).toBeInstanceOf(GoogleToolError); + expect((error as GoogleToolError).kind).toBe("invalid_argument"); + expect((error as Error).message).toMatch(message); + }); +}); diff --git a/server/src/google-workspace-rest-tools/drive/query.ts b/server/src/google-workspace-rest-tools/drive/query.ts new file mode 100644 index 00000000000..87f0057abe0 --- /dev/null +++ b/server/src/google-workspace-rest-tools/drive/query.ts @@ -0,0 +1,280 @@ +import { GoogleToolError } from "../errors.js"; + +export const MAX_QUERY_LENGTH = 4000; +const MAX_DEPTH = 32; + +type Token = + | { kind: "string"; value: string } + | { kind: "word"; value: string } + | { kind: "op"; value: string } + | { kind: "paren"; value: "(" | ")" }; + +type Value = { kind: "string"; value: string } | { kind: "boolean"; value: boolean }; + +export type QueryNode = + | { kind: "and" | "or"; left: QueryNode; right: QueryNode } + | { kind: "not"; operand: QueryNode } + | { kind: "compare"; term: string; op: string; value: Value } + | { kind: "in"; term: string; value: string }; + +function invalid(detail: string): GoogleToolError { + return new GoogleToolError("invalid_argument", `Invalid search query: ${detail}`); +} + +export function tokenize(query: string): Token[] { + const tokens: Token[] = []; + let index = 0; + while (index < query.length) { + const char = query[index]!; + if (/\s/.test(char)) { + index += 1; + } else if (char === "(" || char === ")") { + tokens.push({ kind: "paren", value: char }); + index += 1; + } else if (char === "'" || char === "\"") { + let value = ""; + index += 1; + for (;;) { + if (index >= query.length) throw invalid("a quoted value is not closed."); + const next = query[index]!; + if (next === "\\") { + if (index + 1 >= query.length) throw invalid("a quoted value ends with a backslash."); + value += query[index + 1]; + index += 2; + } else if (next === char) { + index += 1; + break; + } else { + value += next; + index += 1; + } + } + tokens.push({ kind: "string", value }); + } else { + const op = /^(!=|<=|>=|=|<|>)/.exec(query.slice(index)); + if (op) { + tokens.push({ kind: "op", value: op[1]! }); + index += op[1]!.length; + continue; + } + const word = /^[A-Za-z][A-Za-z0-9_]*/.exec(query.slice(index)); + if (!word) throw invalid(`unexpected character ${JSON.stringify(char)}.`); + tokens.push({ kind: "word", value: word[0] }); + index += word[0].length; + } + } + return tokens; +} + +const KEYWORDS = new Set(["and", "or", "not", "in", "contains", "true", "false"]); + +class Parser { + private position = 0; + constructor(private readonly tokens: Token[]) {} + + parse(): QueryNode { + const node = this.or(0); + if (this.position < this.tokens.length) throw invalid(`unexpected ${this.describe(this.tokens[this.position])}.`); + return node; + } + + private peekKeyword(word: string): boolean { + const token = this.tokens[this.position]; + return token?.kind === "word" && token.value.toLowerCase() === word; + } + + private describe(token: Token | undefined): string { + return token ? JSON.stringify(token.value) : "end of query"; + } + + private or(depth: number): QueryNode { + let left = this.and(depth); + while (this.peekKeyword("or")) { + this.position += 1; + left = { kind: "or", left, right: this.and(depth) }; + } + return left; + } + + private and(depth: number): QueryNode { + let left = this.not(depth); + while (this.peekKeyword("and")) { + this.position += 1; + left = { kind: "and", left, right: this.not(depth) }; + } + return left; + } + + private not(depth: number): QueryNode { + if (depth > MAX_DEPTH) throw invalid("too deeply nested."); + if (this.peekKeyword("not")) { + this.position += 1; + return { kind: "not", operand: this.not(depth + 1) }; + } + return this.primary(depth); + } + + private primary(depth: number): QueryNode { + const token = this.tokens[this.position]; + if (token?.kind === "paren" && token.value === "(") { + this.position += 1; + const node = this.or(depth + 1); + const close = this.tokens[this.position]; + if (close?.kind !== "paren" || close.value !== ")") throw invalid(`expected ")" but found ${this.describe(close)}.`); + this.position += 1; + return node; + } + if (token?.kind === "string") { + this.position += 1; + if (!this.peekKeyword("in")) throw invalid(`expected "in" after ${this.describe(token)}.`); + this.position += 1; + const term = this.tokens[this.position]; + if (term?.kind !== "word" || KEYWORDS.has(term.value.toLowerCase())) throw invalid(`expected a term after "in" but found ${this.describe(term)}.`); + this.position += 1; + return { kind: "in", term: term.value, value: token.value }; + } + if (token?.kind === "word" && !KEYWORDS.has(token.value.toLowerCase())) { + this.position += 1; + const op = this.tokens[this.position]; + let operator: string; + if (op?.kind === "op") operator = op.value; + else if (op?.kind === "word" && op.value.toLowerCase() === "contains") operator = "contains"; + else throw invalid(`expected an operator after ${this.describe(token)} but found ${this.describe(op)}.`); + this.position += 1; + const value = this.tokens[this.position]; + this.position += 1; + if (value?.kind === "string") return { kind: "compare", term: token.value, op: operator, value: { kind: "string", value: value.value } }; + if (value?.kind === "word" && /^(true|false)$/i.test(value.value)) { + return { kind: "compare", term: token.value, op: operator, value: { kind: "boolean", value: value.value.toLowerCase() === "true" } }; + } + throw invalid(`expected a quoted value or true/false after ${JSON.stringify(`${token.value} ${operator}`)} but found ${this.describe(value)}.`); + } + throw invalid(`expected a search term but found ${this.describe(token)}.`); + } +} + +export function parseQuery(query: string): QueryNode | null { + if (query.length > MAX_QUERY_LENGTH) throw invalid(`longer than ${MAX_QUERY_LENGTH} characters.`); + const tokens = tokenize(query); + return tokens.length ? new Parser(tokens).parse() : null; +} + +export function quote(value: string): string { + return `'${value.replace(/\\/g, "\\\\").replace(/'/g, "\\'")}'`; +} + +const TEXT_OPS = ["contains", "=", "!="]; +const TIME_OPS = ["<=", "<", "=", "!=", ">", ">="]; +const EQUALITY = ["=", "!="]; +const RFC3339 = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d{1,9})?(Z|[+-]\d{2}:\d{2})$/; +const NATIVE_VISIBILITY = new Set(["anyoneCanFind", "anyoneWithLink", "domainCanFind", "domainWithLink", "limited"]); +const UNSUPPORTED: Readonly> = { + creator: "creator", + sharedFrom: "sharedFrom", + sharedTo: "sharedTo", + followUp: "followUp", + folderProperties: "folderProperties", +}; + +function requireOp(term: string, op: string, allowed: readonly string[]): void { + if (!allowed.includes(op)) throw invalid(`${term} does not support the ${op} operator (use ${allowed.join(", ")}).`); +} + +function stringValue(term: string, value: Value): string { + if (value.kind !== "string") throw invalid(`${term} takes a quoted value.`); + return value.value; +} + +function booleanValue(term: string, value: Value): boolean { + if (value.kind !== "boolean") throw invalid(`${term} takes true or false.`); + return value.value; +} + +function negate(op: string, clause: string): string { + return op === "!=" ? `not ${clause}` : clause; +} + +function compareToDrive(node: Extract): string { + const { term, op, value } = node; + if (Object.hasOwn(UNSUPPORTED, term)) throw invalid(`the ${UNSUPPORTED[term]} term is not supported by this implementation.`); + switch (term) { + case "title": + requireOp(term, op, TEXT_OPS); + return `name ${op} ${quote(stringValue(term, value))}`; + case "fullText": + requireOp(term, op, ["contains"]); + return `fullText contains ${quote(stringValue(term, value))}`; + case "mimeType": + requireOp(term, op, TEXT_OPS); + return `mimeType ${op} ${quote(stringValue(term, value))}`; + case "modifiedTime": + case "viewedByMeTime": + case "createdTime": { + requireOp(term, op, TIME_OPS); + const time = stringValue(term, value); + if (!RFC3339.test(time)) throw invalid(`${term} takes an RFC 3339 time such as '2026-01-01T00:00:00Z'.`); + return `${term} ${op} ${quote(time)}`; + } + case "parentId": + requireOp(term, op, EQUALITY); + return negate(op, `${quote(stringValue(term, value))} in parents`); + case "owner": + requireOp(term, op, EQUALITY); + return negate(op, `${quote(stringValue(term, value))} in owners`); + case "visibility": { + requireOp(term, op, EQUALITY); + const level = stringValue(term, value); + if (NATIVE_VISIBILITY.has(level)) return `visibility ${op} ${quote(level)}`; + if (level === "anyone" || level === "domain") { + return negate(op, `(visibility = ${quote(`${level}CanFind`)} or visibility = ${quote(`${level}WithLink`)})`); + } + throw invalid(`visibility ${quote(level)} is not supported by this implementation.`); + } + case "sharedWithMe": + case "starred": + case "trashed": + requireOp(term, op, EQUALITY); + return `${term} ${op} ${booleanValue(term, value)}`; + default: + throw invalid(`unknown term ${JSON.stringify(term)}.`); + } +} + +export function toDriveQuery(node: QueryNode): string { + switch (node.kind) { + case "and": + case "or": + return `(${toDriveQuery(node.left)} ${node.kind} ${toDriveQuery(node.right)})`; + case "not": + return `not ${toDriveQuery(node.operand)}`; + case "in": + if (node.term !== "readers" && node.term !== "writers") { + if (node.term === "folderProperties") throw invalid("the folderProperties term is not supported by this implementation."); + throw invalid(`"in" works only with readers and writers, not ${JSON.stringify(node.term)}.`); + } + return `${quote(node.value)} in ${node.term}`; + case "compare": + return compareToDrive(node); + } +} + +function mentionsTrashed(node: QueryNode): boolean { + switch (node.kind) { + case "and": + case "or": + return mentionsTrashed(node.left) || mentionsTrashed(node.right); + case "not": + return mentionsTrashed(node.operand); + case "in": + return false; + case "compare": + return node.term === "trashed"; + } +} + +export function driveSearchQuery(query: string | undefined): string { + const node = parseQuery(query ?? ""); + if (!node) return "trashed = false"; + const translated = toDriveQuery(node); + return mentionsTrashed(node) ? translated : `(${translated}) and trashed = false`; +} diff --git a/server/src/google-workspace-rest-tools/drive/read-file-content.test.ts b/server/src/google-workspace-rest-tools/drive/read-file-content.test.ts new file mode 100644 index 00000000000..b151cf62f0b --- /dev/null +++ b/server/src/google-workspace-rest-tools/drive/read-file-content.test.ts @@ -0,0 +1,132 @@ +import { describe, expect, it } from "vitest"; +import { fakeGoogle, json, type RecordedCall } from "../fixtures/fake-google.js"; +import { createGoogleHttp } from "../google-http.js"; +import { MAX_RESULT_BYTES, serializedResultBytes } from "../tool.js"; +import { MAX_CONTENT_BYTES, READ_LESS, type RestFile } from "./file.js"; +import { DOC, DRAWING, FOLDER, HUGE_PDF, JSON_FILE, PDF, SHEET, SLIDES, TEXT_FILE } from "./fixtures/drive-rest.js"; +import { decodeText, readFileContent, readPlan, SHEET_NOTE, toCommentThread } from "./read-file-content.js"; + +describe("read plan", () => { + it.each([ + [DOC, "/drive/v3/files/doc0001synthetic/export", "text/markdown"], + [SLIDES, "/drive/v3/files/slides0001synthetic/export", "text/plain"], + [SHEET, "/drive/v3/files/sheet0001synthetic/export", "text/csv"], + [TEXT_FILE, "/drive/v3/files/text0001synthetic", "text/plain"], + [JSON_FILE, "/drive/v3/files/json0001synthetic", "application/json"], + [{ id: "x1", mimeType: "application/ld+json", size: "3" }, "/drive/v3/files/x1", "application/ld+json"], + ] as const)("%#: reads %s from %s as %s", (file, path, contentType) => { + const plan = readPlan(file.id!, file); + expect(plan?.request.path).toBe(path); + expect(plan?.contentType).toBe(contentType); + }); + + it.each([PDF, FOLDER, DRAWING, { id: "i1", mimeType: "image/png" }, { id: "w1", mimeType: "application/vnd.openxmlformats-officedocument.wordprocessingml.document" }])( + "%#: has no text version of %s", + (file: RestFile) => { + expect(readPlan(file.id!, file)).toBeNull(); + }, + ); + + it("refuses a text file over the cap before downloading", () => { + expect(() => readPlan("big1", { ...HUGE_PDF, mimeType: "text/plain" })).toThrow(/more than the 250000 bytes/); + }); + + it("decodes UTF-8, drops a byte order mark, and rejects bytes that are not UTF-8", () => { + expect(decodeText(Buffer.from("café", "utf8"))).toBe("café"); + expect(decodeText(Buffer.from([0xff, 0xfe, 0x00]))).toBeNull(); + }); + + it.each([ + [{ id: "c1", content: "Why?", author: { displayName: "A" }, modifiedTime: "2026-11-01T00:00:00Z" }, { commentId: "c1", status: "OPEN", headPost: { postId: "c1", content: "Why?", authorName: "A", modifiedTime: "2026-11-01T00:00:00Z" }, replies: [] }], + [{ id: "c2", content: "Done", resolved: true, replies: [{ id: "r1", content: "ok" }, { id: "r2", content: "", deleted: true }] }, { commentId: "c2", status: "RESOLVED", headPost: { postId: "c2", content: "Done" }, replies: [{ postId: "r1", content: "ok" }] }], + ])("%#: maps a comment thread", (comment, expected) => { + expect(toCommentThread(comment)).toEqual(expected); + }); +}); + +function route(file: RestFile, content: BodyInit | null, comments: (call: RecordedCall) => Response = () => json({ comments: [] })) { + return fakeGoogle((call) => { + if (call.url.pathname.endsWith("/comments")) return comments(call); + if (call.url.pathname.endsWith("/export") || call.url.searchParams.get("alt") === "media") return new Response(content); + return json(file); + }); +} + +describe("read_file_content tool", () => { + it("returns a Google Doc as Markdown", async () => { + const { fetch, calls } = route(DOC, "# Plan\n\nShip it.\n"); + const result = await readFileContent.call({ fileId: DOC.id }, createGoogleHttp({ accessToken: "t", fetch })); + expect(calls[1]!.url.searchParams.get("mimeType")).toBe("text/markdown"); + expect(result.structuredContent).toEqual({ fileContent: "# Plan\n\nShip it.\n" }); + }); + + it("says that a spreadsheet shows only its first sheet", async () => { + const { fetch } = route(SHEET, "a,b\n1,2\n"); + const result = await readFileContent.call({ fileId: SHEET.id }, createGoogleHttp({ accessToken: "t", fetch })); + expect(result.structuredContent).toEqual({ fileContent: `${SHEET_NOTE}\na,b\n1,2\n` }); + }); + + it("marks files with no text version, without downloading them", async () => { + const { fetch, calls } = route(PDF, "%PDF"); + const result = await readFileContent.call({ fileId: PDF.id, includeComments: true }, createGoogleHttp({ accessToken: "t", fetch })); + expect(calls).toHaveLength(1); + expect(result.structuredContent).toEqual({ + fileContent: "", contentAnchoredComments: [], unanchoredComments: [], textFormattingNotSupported: true, commentsNotSupported: true, + }); + }); + + it("marks a text file that is not valid UTF-8 as having no text version", async () => { + const { fetch } = route(TEXT_FILE, new Uint8Array([0xc3, 0x28])); + const result = await readFileContent.call({ fileId: TEXT_FILE.id }, createGoogleHttp({ accessToken: "t", fetch })); + expect(result.structuredContent).toEqual({ fileContent: "", textFormattingNotSupported: true }); + }); + + it("lists every comment thread across pages when asked", async () => { + const { fetch, calls } = route(DOC, "text", ({ url }) => (url.searchParams.get("pageToken") + ? json({ comments: [{ id: "c2", content: "second" }, { id: "c3", content: "gone", deleted: true }] }) + : json({ comments: [{ id: "c1", content: "first", resolved: true }], nextPageToken: "n" }))); + const result = await readFileContent.call({ fileId: DOC.id, includeComments: true }, createGoogleHttp({ accessToken: "t", fetch })); + expect(calls.filter((call) => call.url.pathname.endsWith("/comments"))).toHaveLength(2); + expect(result.structuredContent).toEqual({ + fileContent: "text", + contentAnchoredComments: [], + unanchoredComments: [ + { commentId: "c1", status: "RESOLVED", headPost: { postId: "c1", content: "first" }, replies: [] }, + { commentId: "c2", status: "OPEN", headPost: { postId: "c2", content: "second" }, replies: [] }, + ], + }); + }); + + it("refuses rather than returning some of a very long comment list", async () => { + let page = 0; + const { fetch } = route(SLIDES, "text", () => json({ comments: [{ id: `c${page}` }], nextPageToken: `p${++page}` })); + const result = await readFileContent.call({ fileId: SLIDES.id, includeComments: true }, createGoogleHttp({ accessToken: "t", fetch })); + expect(result.isError).toBe(true); + expect((result.content[0] as { text: string }).text).toMatch(/more than 1000 comment threads/); + }); + + it("refuses content that grows past the cap while streaming", async () => { + const { fetch } = route(SLIDES, new Uint8Array(MAX_CONTENT_BYTES + 1)); + const result = await readFileContent.call({ fileId: SLIDES.id }, createGoogleHttp({ accessToken: "t", fetch })); + expect(result).toEqual({ isError: true, content: [{ type: "text", text: `This file's content is more than the 250000 bytes this tool returns, so nothing was returned. ${READ_LESS.read}` }] }); + }); + + it("bounds the final serialized result, including JSON escaping, with advice on reading less", async () => { + const { fetch } = route(SLIDES, "\u0001".repeat(30_000)); + const result = await readFileContent.call({ fileId: SLIDES.id }, createGoogleHttp({ accessToken: "t", fetch })); + expect(result.isError).toBe(true); + const text = (result.content[0] as { text: string }).text; + expect(text).toMatch(/^The result is \d+ bytes, more than the 250000 bytes this tool returns, so nothing was returned\. /); + expect(text.endsWith(READ_LESS.read)).toBe(true); + expect(Number(/\d+/.exec(text)![0])).toBeGreaterThan(2 * 6 * 30_000); + }); + + it("returns the largest text that fits and refuses one byte more", async () => { + const run = async (size: number) => readFileContent.call({ fileId: SLIDES.id }, createGoogleHttp({ accessToken: "t", fetch: route(SLIDES, "a".repeat(size)).fetch })); + let largest = 0; + for (let step = 1 << 17; step >= 1; step >>= 1) if (!(await run(largest + step)).isError) largest += step; + expect(serializedResultBytes(await run(largest))).toBeLessThanOrEqual(MAX_RESULT_BYTES); + expect(serializedResultBytes(await run(largest))).toBeGreaterThan(MAX_RESULT_BYTES - 4); + expect((await run(largest + 1)).isError).toBe(true); + }); +}); diff --git a/server/src/google-workspace-rest-tools/drive/read-file-content.ts b/server/src/google-workspace-rest-tools/drive/read-file-content.ts new file mode 100644 index 00000000000..1aedbd7e0a7 --- /dev/null +++ b/server/src/google-workspace-rest-tools/drive/read-file-content.ts @@ -0,0 +1,158 @@ +import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js"; +import { z } from "zod"; +import { GoogleToolError } from "../errors.js"; +import type { GoogleHttp, GoogleRequest } from "../google-http.js"; +import { compact, defineTool } from "../tool.js"; +import { assertWithinCap, exportRequest, fetchContent, mediaRequest, readContentMeta, type ContentPlan } from "./content.js"; +import { boundedResult, DRIVE_HOST, fileId, fileIdInput, filePath, GOOGLE_DOC, GOOGLE_SHEET, GOOGLE_SLIDES, READ_LESS, type RestFile } from "./file.js"; + +const args = z.object({ fileId, includeComments: z.boolean().optional() }); +export type ReadFileContentArgs = z.infer; + +export const SHEET_NOTE = "[Only the first sheet of this spreadsheet is shown, as CSV. Other sheets are not included.]"; +export const MAX_COMMENT_PAGES = 10; +const COMMENT_PAGE_SIZE = 100; +const COMMENTABLE = new Set([GOOGLE_DOC, GOOGLE_SHEET, GOOGLE_SLIDES]); +const TEXT_APPLICATION_TYPES = new Set([ + "application/json", "application/xml", "application/javascript", "application/x-yaml", "application/yaml", + "application/x-sh", "application/sql", "application/csv", "application/x-ndjson", +]); + +export interface ReadPlan extends ContentPlan { + prefix?: string; +} + +export function readPlan(id: string, file: RestFile): ReadPlan | null { + const mimeType = file.mimeType ?? ""; + if (mimeType === GOOGLE_DOC) return { request: exportRequest(id, "text/markdown"), contentType: "text/markdown" }; + if (mimeType === GOOGLE_SLIDES) return { request: exportRequest(id, "text/plain"), contentType: "text/plain" }; + if (mimeType === GOOGLE_SHEET) return { request: exportRequest(id, "text/csv"), contentType: "text/csv", prefix: SHEET_NOTE }; + if (mimeType.startsWith("text/") || TEXT_APPLICATION_TYPES.has(mimeType) || /\+(json|xml)$/.test(mimeType)) { + assertWithinCap(file, READ_LESS.read); + return { request: mediaRequest(id), contentType: mimeType }; + } + return null; +} + +export function decodeText(data: Buffer): string | null { + try { + return new TextDecoder("utf-8", { fatal: true }).decode(data).replace(/^/, ""); + } catch { + return null; + } +} + +export interface RestReply { id?: string; content?: string; author?: { displayName?: string }; modifiedTime?: string; deleted?: boolean } +export interface RestComment extends RestReply { resolved?: boolean; replies?: RestReply[] } +export interface RestCommentList { comments?: RestComment[]; nextPageToken?: string } + +export function commentsRequest(id: string, pageToken?: string): GoogleRequest { + return { + method: "GET", + host: DRIVE_HOST, + path: `${filePath(id)}/comments`, + query: { + pageSize: COMMENT_PAGE_SIZE, + pageToken, + includeDeleted: false, + fields: "nextPageToken,comments(id,content,author(displayName),modifiedTime,resolved,deleted,replies(id,content,author(displayName),modifiedTime,deleted))", + }, + }; +} + +function toPost(post: RestReply): Record { + return compact({ postId: post.id, content: post.content ?? "", authorName: post.author?.displayName, modifiedTime: post.modifiedTime }); +} + +export function toCommentThread(comment: RestComment): Record { + return { + commentId: comment.id ?? "", + status: comment.resolved ? "RESOLVED" : "OPEN", + headPost: toPost(comment), + replies: (comment.replies ?? []).filter((reply) => !reply.deleted).map(toPost), + }; +} + +export async function readComments(id: string, http: GoogleHttp): Promise { + const comments: RestComment[] = []; + let pageToken: string | undefined; + for (let page = 0; page < MAX_COMMENT_PAGES; page += 1) { + const list = await http.send(commentsRequest(id, pageToken)); + comments.push(...(list.comments ?? []).filter((comment) => !comment.deleted)); + pageToken = list.nextPageToken || undefined; + if (!pageToken) return comments; + } + throw new GoogleToolError( + "too_large", + `This file has more than ${MAX_COMMENT_PAGES * COMMENT_PAGE_SIZE} comment threads, more than this tool returns. Read it without includeComments.`, + ); +} + +export function readFileContentResult(file: RestFile, text: string | null, comments: RestComment[] | null, includeComments: boolean): CallToolResult { + const commentable = COMMENTABLE.has(file.mimeType ?? ""); + return boundedResult(compact({ + fileContent: text ?? "", + contentAnchoredComments: includeComments ? [] : undefined, + unanchoredComments: includeComments ? (comments ?? []).map(toCommentThread) : undefined, + textFormattingNotSupported: text === null ? true : undefined, + commentsNotSupported: includeComments && !commentable ? true : undefined, + }), READ_LESS.read); +} + +const postSchema = { + type: "object", + properties: { + postId: { type: "string", description: "ID of the post." }, + content: { type: "string", description: "Text of the post." }, + authorName: { type: "string", description: "Name of the post's author." }, + modifiedTime: { type: "string", description: "When the post was last modified (RFC 3339)." }, + }, +} as const; +const threadSchema = { + type: "object", + properties: { + commentId: { type: "string", description: "ID of the comment thread." }, + status: { type: "string", enum: ["STATUS_UNSPECIFIED", "OPEN", "RESOLVED"], description: "Whether the thread is open or resolved." }, + headPost: { ...postSchema, description: "The first post." }, + replies: { type: "array", items: postSchema, description: "Replies, oldest first." }, + }, +} as const; + +export const readFileContent = defineTool({ + definition: { + name: "read_file_content", + description: "Returns a text version of a Drive file. Google Docs come back as Markdown, Slides as plain text, and Sheets as CSV of the first sheet only (the text says so). Text files (text/*, JSON, XML and similar) are returned as stored. Other files, such as PDFs, Office files and images, are not converted: the result has textFormattingNotSupported true and empty fileContent; use download_file_content for their bytes. The whole result is at most 250,000 bytes (about 120 KB of plain text, since the result carries it twice); a larger file is refused with an error, never cut short. With includeComments, the comment threads of a Google Doc, Sheet or Slides file are listed in unanchoredComments; they are not placed in the text. Get fileId from search_files or list_recent_files first.", + inputSchema: { + type: "object", + properties: { + fileId: fileIdInput("ID of the file to read."), + includeComments: { type: "boolean", description: "Optional. Also return the file's comment threads (Google Docs, Sheets and Slides only). Default: false." }, + }, + required: ["fileId"], + }, + outputSchema: { + type: "object", + properties: { + fileContent: { type: "string", description: "The file's text. Empty when textFormattingNotSupported is true." }, + contentAnchoredComments: { type: "array", items: threadSchema, description: "Always empty in this implementation: comments are not placed in the text." }, + unanchoredComments: { type: "array", items: threadSchema, description: "Comment threads, when includeComments is true." }, + textFormattingNotSupported: { type: "boolean", description: "True when this file type has no text version here." }, + commentsNotSupported: { type: "boolean", description: "True when includeComments is set and this file type has no comments." }, + }, + required: ["fileContent"], + }, + annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false }, + }, + args, + async run(input, http) { + const file = await readContentMeta(input.fileId, http); + const plan = readPlan(input.fileId, file); + let text: string | null = null; + if (plan) { + const decoded = decodeText(await fetchContent(plan, http, READ_LESS.read)); + text = decoded === null ? null : plan.prefix ? `${plan.prefix}\n${decoded}` : decoded; + } + const comments = input.includeComments && COMMENTABLE.has(file.mimeType ?? "") ? await readComments(input.fileId, http) : null; + return readFileContentResult(file, text, comments, input.includeComments === true); + }, +}); diff --git a/server/src/google-workspace-rest-tools/drive/search-files.test.ts b/server/src/google-workspace-rest-tools/drive/search-files.test.ts new file mode 100644 index 00000000000..e4dea8d77af --- /dev/null +++ b/server/src/google-workspace-rest-tools/drive/search-files.test.ts @@ -0,0 +1,129 @@ +import { describe, expect, it } from "vitest"; +import { fakeGoogle, json } from "../fixtures/fake-google.js"; +import { createGoogleHttp } from "../google-http.js"; +import { DOC, FOLDER } from "./fixtures/drive-rest.js"; +import { searchFiles, searchFilesRequest, searchOrder } from "./search-files.js"; + +describe("search_files request", () => { + it("builds one files.list request with a safe query, trash excluded, and the default page size", () => { + expect(searchFilesRequest({ query: "title contains 'O\\'Brien'" })).toEqual({ + method: "GET", + host: "www.googleapis.com", + path: "/drive/v3/files", + query: expect.objectContaining({ + q: "(name contains 'O\\'Brien') and trashed = false", + orderBy: undefined, + pageSize: 10, + pageToken: undefined, + supportsAllDrives: true, + includeItemsFromAllDrives: true, + }), + }); + }); + + it.each([ + [undefined, 10], + [1, 1], + [100, 100], + [500, 100], + ])("pageSize %s becomes %i", (pageSize, expected) => { + expect(searchFilesRequest({ pageSize }).query?.pageSize).toBe(expected); + }); + + it.each([ + [undefined, undefined], + ["", undefined], + ["modifiedTime", "modifiedTime desc"], + ["modifiedTime desc", "modifiedTime desc"], + ["modifiedTime asc", "modifiedTime"], + ["viewedByMeTime", "viewedByMeTime desc"], + [" viewedByMeTime asc ", "viewedByMeTime"], + ])("orderBy %j becomes %j", (value, expected) => { + expect(searchOrder(value)).toBe(expected); + }); + + it.each(["name", "modifiedTime sideways", "createdTime desc", "modifiedTime desc, name"])("refuses orderBy %j", (value) => { + expect(() => searchOrder(value)).toThrow(/orderBy must be/); + }); + + it("asks for owner names, last modifier and sharing only with includeRichMetadata", () => { + expect(String(searchFilesRequest({}).query?.fields)).not.toContain("lastModifyingUser"); + expect(String(searchFilesRequest({}).query?.fields)).toMatch(/^nextPageToken,incompleteSearch,files\(/); + const rich = String(searchFilesRequest({ includeRichMetadata: true }).query?.fields); + expect(rich).toContain("lastModifyingUser(displayName,emailAddress)"); + expect(rich).toContain("permissions(type,allowFileDiscovery)"); + }); +}); + +describe("search_files tool", () => { + it("returns Google's MCP file shape and the next page token", async () => { + const { fetch, calls } = fakeGoogle(() => json({ files: [DOC, FOLDER], nextPageToken: "next-1" })); + const result = await searchFiles.call({ query: "fullText contains 'plan'" }, createGoogleHttp({ accessToken: "t", fetch })); + expect(calls).toHaveLength(1); + expect(calls[0]!.url.searchParams.get("q")).toBe("(fullText contains 'plan') and trashed = false"); + expect(result.structuredContent).toEqual({ + files: [ + { + id: "doc0001synthetic", + title: "Quarterly plan", + parentId: "folder0001synthetic", + mimeType: "application/vnd.google-apps.document", + description: "Synthetic test document", + viewUrl: "https://docs.example.test/document/d/doc0001synthetic/edit", + createdTime: "2026-10-01T09:00:00.000Z", + modifiedTime: "2026-11-02T10:30:00.000Z", + viewedByMeTime: "2026-11-03T08:00:00.000Z", + owner: "owner@example.test", + canAddChildren: false, + }, + { id: "folder0001synthetic", title: "Projects", mimeType: "application/vnd.google-apps.folder", canAddChildren: true }, + ], + nextPageToken: "next-1", + }); + }); + + it("adds rich metadata when asked", async () => { + const { fetch } = fakeGoogle(() => json({ files: [{ ...DOC, permissions: [{ type: "user" }, { type: "anyone", allowFileDiscovery: false }] }] })); + const result = await searchFiles.call({ includeRichMetadata: true }, createGoogleHttp({ accessToken: "t", fetch })); + expect((result.structuredContent as { files: unknown[] }).files[0]).toMatchObject({ + ownerName: "Owner Example", + lastModifyingUserName: "Editor Example", + lastModifyingUserEmail: "editor@example.test", + visibility: "anyoneWithLink", + }); + }); + + it("sends nothing for an invalid query or conflicting snippet options", async () => { + const { fetch, calls } = fakeGoogle(() => json({ files: [] })); + const http = createGoogleHttp({ accessToken: "t", fetch }); + const bad = await searchFiles.call({ query: "title contains 'x' or creator = 'me'" }, http); + expect(bad).toEqual({ isError: true, content: [{ type: "text", text: "Invalid search query: the creator term is not supported by this implementation." }] }); + expect((await searchFiles.call({ excludeContentSnippets: true, snippetVerbosity: "BRIEF" }, http)).isError).toBe(true); + expect((await searchFiles.call({ pageSize: 0 }, http)).isError).toBe(true); + expect(calls).toHaveLength(0); + }); + + it("refuses a page whose result is over 250,000 bytes and says how to ask for less", async () => { + const files = Array.from({ length: 100 }, (_, index) => ({ ...DOC, id: `doc${index}`, description: "d".repeat(2_000) })); + const { fetch } = fakeGoogle(() => json({ files })); + const result = await searchFiles.call({ pageSize: 100 }, createGoogleHttp({ accessToken: "t", fetch })); + expect(result.isError).toBe(true); + expect((result.content[0] as { text: string }).text).toMatch(/more than the 250000 bytes this tool returns, so nothing was returned\. Ask for fewer files with a smaller pageSize/); + }); + + it("returns an empty list when nothing matches", async () => { + const { fetch } = fakeGoogle(() => json({})); + const result = await searchFiles.call({ query: "starred = true" }, createGoogleHttp({ accessToken: "t", fetch })); + expect(result.structuredContent).toEqual({ files: [] }); + }); + + it.each([ + [{ files: [DOC], incompleteSearch: true }, true], + [{ files: [DOC], incompleteSearch: false }, undefined], + [{ files: [DOC] }, undefined], + ])("%#: says when Google's search was incomplete", async (answer, expected) => { + const { fetch } = fakeGoogle(() => json(answer)); + const result = await searchFiles.call({ query: "fullText contains 'plan'" }, createGoogleHttp({ accessToken: "t", fetch })); + expect((result.structuredContent as { incompleteSearch?: boolean }).incompleteSearch).toBe(expected); + }); +}); diff --git a/server/src/google-workspace-rest-tools/drive/search-files.ts b/server/src/google-workspace-rest-tools/drive/search-files.ts new file mode 100644 index 00000000000..f153712e565 --- /dev/null +++ b/server/src/google-workspace-rest-tools/drive/search-files.ts @@ -0,0 +1,96 @@ +import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js"; +import { z } from "zod"; +import { GoogleToolError } from "../errors.js"; +import type { GoogleRequest } from "../google-http.js"; +import { defineTool } from "../tool.js"; +import { + assertSnippetArgs, + boundedResult, + READ_LESS, + DRIVE_BASE, + DRIVE_HOST, + fileListSchema, + listFields, + listResult, + pageSize, + pageSizeArg, + pageTokenArg, + richMetadataInput, + snippetArgs, + snippetInputs, + type RestFileList, +} from "./file.js"; +import { driveSearchQuery, MAX_QUERY_LENGTH } from "./query.js"; + +const args = z.object({ + query: z.string().max(MAX_QUERY_LENGTH).optional(), + pageSize: pageSizeArg, + pageToken: pageTokenArg, + orderBy: z.string().max(64).optional(), + includeRichMetadata: z.boolean().optional(), + ...snippetArgs, +}); +export type SearchFilesArgs = z.infer; + +export function searchOrder(value: string | undefined): string | undefined { + const trimmed = value?.trim(); + if (!trimmed) return undefined; + const match = /^(modifiedTime|viewedByMeTime)(?:\s+(asc|desc))?$/.exec(trimmed); + if (!match) throw new GoogleToolError("invalid_argument", "orderBy must be modifiedTime or viewedByMeTime, optionally followed by asc or desc."); + return match[2] === "asc" ? match[1] : `${match[1]} desc`; +} + +export function searchFilesRequest(input: SearchFilesArgs): GoogleRequest { + return { + method: "GET", + host: DRIVE_HOST, + path: `${DRIVE_BASE}/files`, + query: { + q: driveSearchQuery(input.query), + orderBy: searchOrder(input.orderBy), + pageSize: pageSize(input.pageSize), + pageToken: input.pageToken, + fields: listFields(input.includeRichMetadata === true), + supportsAllDrives: true, + includeItemsFromAllDrives: true, + }, + }; +} + +export function searchFilesResult(list: RestFileList, rich: boolean): CallToolResult { + return boundedResult(listResult(list, rich), READ_LESS.list); +} + +const QUERY_HELP = [ + "Optional. Structured query: term operator value. Combine clauses with and, or, not and parentheses. Quote string values with single quotes; write a quote inside a value as \\' and a backslash as \\\\.", + "Terms: title (contains, =, !=; title contains is a prefix match: 'Hello' finds HelloWorld, 'World' does not); fullText (contains; title or body text); mimeType (contains, =, !=); modifiedTime, viewedByMeTime, createdTime (<, <=, =, !=, >, >=, with an RFC 3339 time such as '2026-01-01T00:00:00Z'); parentId (=, !=; 'root' is My Drive); owner (=, !=; 'me' is the user); 'someone@example.com' in readers, 'me' in writers; visibility (=, !=: 'anyoneCanFind', 'anyoneWithLink', 'anyone', 'domainCanFind', 'domainWithLink', 'domain', 'limited'); sharedWithMe, starred, trashed (=, != with true or false).", + "Trashed files are left out unless the query uses trashed. Not supported here: creator, sharedFrom, sharedTo, followUp, folderProperties, and visibility 'external'.", + "Use title contains rather than title = unless the user asks for an exact title; to find a word inside a title, also try fullText contains. Put file types in mimeType clauses, not in title or fullText (for example mimeType = 'application/vnd.google-apps.presentation' for slides).", + "Examples: title contains 'budget' and modifiedTime > '2026-01-01T00:00:00Z'; parentId = 'root'; owner = 'me' and starred = true. Empty: all files that are not trashed.", +].join(" "); + +export const searchFiles = defineTool({ + definition: { + name: "search_files", + description: "Searches the user's Drive files with a structured query and returns one page of matching files (metadata only, no content snippets). Default page size 10, at most 100; pass nextPageToken as pageToken for more. Results may repeat across pages. When incompleteSearch is true, Google did not search everywhere and matching files may be missing. To read a file, pass its id to read_file_content.", + inputSchema: { + type: "object", + properties: { + query: { type: "string", description: QUERY_HELP }, + pageSize: { type: "integer", description: "Optional. Files per page. Default 10, at most 100." }, + pageToken: { type: "string", description: "Optional. nextPageToken from the previous page." }, + orderBy: { type: "string", description: "Optional. modifiedTime or viewedByMeTime, optionally followed by asc or desc (default desc). Default: Drive's own order." }, + includeRichMetadata: richMetadataInput, + ...snippetInputs, + }, + }, + outputSchema: fileListSchema, + annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false }, + }, + args, + async run(input, http) { + assertSnippetArgs(input); + const rich = input.includeRichMetadata === true; + return searchFilesResult(await http.send(searchFilesRequest(input)), rich); + }, +}); diff --git a/server/src/google-workspace-rest-tools/errors.ts b/server/src/google-workspace-rest-tools/errors.ts index 181aee30508..a836220a1a1 100644 --- a/server/src/google-workspace-rest-tools/errors.ts +++ b/server/src/google-workspace-rest-tools/errors.ts @@ -34,7 +34,8 @@ export type GoogleToolErrorKind = | "network" | "invalid_response" | "unsupported" - | "incomplete"; + | "incomplete" + | "too_large"; export interface GoogleErrorDetail { status?: string; diff --git a/server/src/google-workspace-rest-tools/fixtures/fake-google.ts b/server/src/google-workspace-rest-tools/fixtures/fake-google.ts index c992720a3b4..62d804a6816 100644 --- a/server/src/google-workspace-rest-tools/fixtures/fake-google.ts +++ b/server/src/google-workspace-rest-tools/fixtures/fake-google.ts @@ -5,6 +5,7 @@ export interface RecordedCall { url: URL; headers: Record; body: unknown; + raw?: Buffer; } export type Route = (call: RecordedCall) => Response | Promise; @@ -21,6 +22,7 @@ export function fakeGoogle(route: Route): { fetch: GoogleFetch; calls: RecordedC url: new URL(url), headers: Object.fromEntries(new Headers(init.headers).entries()), body: typeof init.body === "string" ? JSON.parse(init.body) : undefined, + raw: init.body instanceof Uint8Array ? Buffer.from(init.body) : undefined, }; calls.push(call); return route(call); diff --git a/server/src/google-workspace-rest-tools/google-http.test.ts b/server/src/google-workspace-rest-tools/google-http.test.ts index ad562bb0860..e125b2ca832 100644 --- a/server/src/google-workspace-rest-tools/google-http.test.ts +++ b/server/src/google-workspace-rest-tools/google-http.test.ts @@ -1,7 +1,46 @@ import { describe, expect, it } from "vitest"; import { GoogleToolError, GoogleWorkspaceAuthError } from "./errors.js"; import { fakeGoogle, json } from "./fixtures/fake-google.js"; -import { createGoogleHttp, googleRequestUrl, isWrite, MAX_RESPONSE_BYTES, type GoogleRequest } from "./google-http.js"; +import { createGoogleHttp, GOOGLE_API_HOSTS, googleError, googleRequestUrl, isWrite, MAX_RESPONSE_BYTES, type GoogleApiHost, type GoogleRequest } from "./google-http.js"; + +const HOST_PATHS: ReadonlyArray = [ + ["allows", "/gmail/v1/users/me/messages/m1", "gmail.googleapis.com"], + ["allows", "/gmail/v1/users/me/profile", "gmail.googleapis.com"], + ["rejects", "/gmail/v1/users/other@example.test/messages", "gmail.googleapis.com"], + ["rejects", "/upload/gmail/v1/users/me/messages", "gmail.googleapis.com"], + ["rejects", "/gmail/v1/users/me/../../../oauth2/v1/tokeninfo", "gmail.googleapis.com"], + ["rejects", "/drive/v3/files/f1", "gmail.googleapis.com"], + ["allows", "/calendar/v3/calendars/primary/events/e1", "www.googleapis.com"], + ["allows", "/drive/v3/files/f1", "www.googleapis.com"], + ["allows", "/drive/v3/files/f1/export", "www.googleapis.com"], + ["allows", "/upload/drive/v3/files", "www.googleapis.com"], + ["rejects", "/drive/v2/files", "www.googleapis.com"], + ["rejects", "/gmail/v1/users/me/profile", "www.googleapis.com"], + ["rejects", "/calendar/v30/x", "www.googleapis.com"], + ["rejects", "/drive/v3", "www.googleapis.com"], + ["rejects", "/upload/drive/v2/files", "www.googleapis.com"], + ["rejects", "/upload/calendar/v3/x", "www.googleapis.com"], + ["rejects", "/calendar/v3/../../drive/v2/files", "www.googleapis.com"], + ["rejects", "/drive/v3/../../oauth2/v1/tokeninfo", "www.googleapis.com"], + ["rejects", "/drive/v3/%2e%2e/%2e%2e/oauth2/v1/tokeninfo", "www.googleapis.com"], + ["rejects", "/upload/drive/v3/../../../storage/v1/b", "www.googleapis.com"], + ["rejects", "/v4/spreadsheets/s1", "www.googleapis.com"], + ["allows", "/v4/spreadsheets/s1", "sheets.googleapis.com"], + ["allows", "/v4/spreadsheets/s1:batchUpdate", "sheets.googleapis.com"], + ["rejects", "/v4/spreadsheets", "sheets.googleapis.com"], + ["rejects", "/v4/other", "sheets.googleapis.com"], + ["rejects", "/v4/spreadsheets/../other", "sheets.googleapis.com"], + ["rejects", "/drive/v3/files/f1", "sheets.googleapis.com"], + ["allows", "/v1/documents/doc-1", "docs.googleapis.com"], + ["allows", "/v1/documents/doc-1:batchUpdate", "docs.googleapis.com"], + ["rejects", "/v1/documents", "docs.googleapis.com"], + ["rejects", "/v1/documents/../../drive/v3/files", "docs.googleapis.com"], + ["rejects", "/v1/documents/doc-1", "www.googleapis.com"], + ["allows", "/v1/presentations/deck-1", "slides.googleapis.com"], + ["allows", "/v1/presentations/deck-1:batchUpdate", "slides.googleapis.com"], + ["rejects", "/v1/presentations", "slides.googleapis.com"], + ["rejects", "/v1/documents/doc-1", "slides.googleapis.com"], +]; const GET: GoogleRequest = { method: "GET", host: "gmail.googleapis.com", path: "/gmail/v1/users/me/labels" }; const POST: GoogleRequest = { method: "POST", host: "gmail.googleapis.com", path: "/gmail/v1/users/me/drafts", body: { message: { raw: "eA" } } }; @@ -272,11 +311,112 @@ describe("writes beyond POST", () => { expect(await failure(client(() => json({ error: { code: 410 } }, 410)).http.send(DELETE))).toMatchObject({ kind: "not_found" }); }); - it("allows www.googleapis.com only under /calendar/v3/, after path normalization", () => { - expect(googleRequestUrl(PATCH)).toBe("https://www.googleapis.com/calendar/v3/calendars/primary/events/e1"); - expect(() => googleRequestUrl({ ...GET, host: "www.googleapis.com", path: "/drive/v3/files" })).toThrow(/not allowed/); - expect(() => googleRequestUrl({ ...GET, host: "www.googleapis.com", path: "/calendar/v3/../../drive/v3/files" })).toThrow(/not allowed/); - expect(() => googleRequestUrl({ ...GET, host: "www.googleapis.com", path: "/calendar/v30/x" })).toThrow(/not allowed/); + it.each(HOST_PATHS)("%s %s on %s", (expected, path, host) => { + const attempt = () => googleRequestUrl({ ...GET, host: host as GoogleApiHost, path }); + if (expected === "rejects") expect(attempt).toThrow(/not allowed/); + else expect(new URL(attempt()).host).toBe(host); + }); + + it("has an allowed and a rejected path for every allowed host", () => { + for (const host of GOOGLE_API_HOSTS) { + expect(HOST_PATHS.some(([expected, , rowHost]) => expected === "allows" && rowHost === host), `${host} allowed row`).toBe(true); + expect(HOST_PATHS.some(([expected, , rowHost]) => expected === "rejects" && rowHost === host), `${host} rejected row`).toBe(true); + } + }); + + it("keeps an encoded slash inside one path segment", () => { + expect(new URL(googleRequestUrl({ ...GET, host: "www.googleapis.com", path: "/drive/v3/files/..%2f..%2f" })).pathname.startsWith("/drive/v3/files/")).toBe(true); + }); +}); + +describe("download", () => { + const MEDIA: GoogleRequest = { method: "GET", host: "www.googleapis.com", path: "/drive/v3/files/f1", query: { alt: "media" } }; + const bytes = (size: number) => new Uint8Array(size).fill(7); + + it("returns the raw bytes and content type, and asks for any type", async () => { + const { http, calls } = client(() => new Response(bytes(3), { headers: { "content-type": "image/png" } })); + const answer = await http.download(MEDIA, 10); + expect([...answer.data]).toEqual([7, 7, 7]); + expect(answer.contentType).toBe("image/png"); + expect(calls[0]!.headers.accept).toBe("*/*"); + }); + + it("refuses content over the cap, declared or streamed, as too large", async () => { + const declared = await failure(client(() => new Response(bytes(11), { headers: { "content-length": "11" } })).http.download(MEDIA, 10)); + expect(declared).toMatchObject({ kind: "too_large" }); + expect((declared as Error).message).toMatch(/larger than 10 bytes/); + const streamed = await failure(client(() => new Response(new ReadableStream({ + start(controller) { + controller.enqueue(bytes(6)); + controller.enqueue(bytes(6)); + controller.close(); + }, + }))).http.download(MEDIA, 10)); + expect(streamed).toMatchObject({ kind: "too_large" }); + }); + + it("never asks for more than the response cap", async () => { + const { http } = client(() => new Response(null, { headers: { "content-length": String(MAX_RESPONSE_BYTES + 1) } })); + expect(await failure(http.download(MEDIA, MAX_RESPONSE_BYTES * 2))).toMatchObject({ kind: "too_large" }); + }); + + it("maps Google errors as send does, and retries a download once", async () => { + let count = 0; + const flaky = client(() => (count++ === 0 ? json({}, 503) : new Response(bytes(1)))); + await expect(flaky.http.download(MEDIA, 10)).resolves.toMatchObject({ contentType: null }); + expect(flaky.calls).toHaveLength(2); + expect(await failure(client(() => json({ error: { code: 404 } }, 404)).http.download(MEDIA, 10))).toMatchObject({ kind: "not_found" }); + }); + + it("refuses to download with a write method", async () => { + const { http, calls } = client(() => new Response(bytes(1))); + await expect(http.download({ ...MEDIA, method: "POST" }, 10)).rejects.toThrow(/must be a read/); + expect(calls).toHaveLength(0); + }); +}); + +describe("redirects", () => { + it("asks fetch not to follow redirects, and turns any redirect into a tool error", async () => { + let init: RequestInit | undefined; + const fetch = async (_url: string, given: RequestInit) => { + init = given; + return new Response(null, { status: 302, headers: { location: "https://elsewhere.example.test/file" } }); + }; + const http = createGoogleHttp({ accessToken: "t", fetch, retryDelayMs: 0 }); + const error = await failure(http.download({ method: "GET", host: "www.googleapis.com", path: "/drive/v3/files/f1", query: { alt: "media" } }, 10)); + expect(init?.redirect).toBe("manual"); + expect(error).toMatchObject({ kind: "invalid_response", message: "Google answered with a redirect, which is not followed." }); + const write = await failure(http.send(POST)); + expect((write as Error).message).toMatch(/redirect, which is not followed\. The change may or may not have been made/); + }); + + it("treats an opaque redirect (status 0) the same way", () => { + expect(googleError({ status: 0, headers: new Headers() }, "")).toMatchObject({ kind: "invalid_response" }); + }); +}); + +describe("uploads and Drive error reasons", () => { + it("sends an upload body with its own content type", async () => { + const { http, calls } = client(() => json({ id: "n1" })); + await http.send({ method: "POST", host: "www.googleapis.com", path: "/upload/drive/v3/files", upload: { contentType: "multipart/related; boundary=b", data: Buffer.from("abc") } }); + expect(calls[0]!.headers["content-type"]).toBe("multipart/related; boundary=b"); + expect(calls[0]!.raw?.toString()).toBe("abc"); + }); + + it("refuses a request with both a JSON body and an upload", async () => { + const { http, calls } = client(() => json({})); + await expect(http.send({ ...POST, upload: { contentType: "text/plain", data: Buffer.from("x") } })).rejects.toThrow(/either/); + expect(calls).toHaveLength(0); + }); + + it("maps Drive's export size limit to too_large and drive.file refusals to a clear message", () => { + const headers = new Headers(); + expect(googleError({ status: 403, headers }, JSON.stringify({ error: { code: 403, errors: [{ reason: "exportSizeLimitExceeded" }] } }))) + .toMatchObject({ kind: "too_large" }); + const denied = googleError({ status: 403, headers }, JSON.stringify({ error: { code: 403, message: "The user has not granted the app 123456 write access to the file f1.", errors: [{ reason: "appNotAuthorizedToFile" }] } })); + expect(denied).toMatchObject({ kind: "permission_denied" }); + expect((denied as Error).message).not.toContain("123456"); + expect((denied as Error).message).toMatch(/drive\.file/); }); it.each([ diff --git a/server/src/google-workspace-rest-tools/google-http.ts b/server/src/google-workspace-rest-tools/google-http.ts index 843c4a146de..fd715dc8c2d 100644 --- a/server/src/google-workspace-rest-tools/google-http.ts +++ b/server/src/google-workspace-rest-tools/google-http.ts @@ -2,11 +2,12 @@ import { GoogleToolError, GoogleWorkspaceAuthError } from "./errors.js"; export const GOOGLE_API_HOSTS = ["gmail.googleapis.com", "www.googleapis.com", "docs.googleapis.com", "slides.googleapis.com", "sheets.googleapis.com"] as const; export type GoogleApiHost = (typeof GOOGLE_API_HOSTS)[number]; -export const GOOGLE_API_PATH_PREFIXES: Partial> = { - "www.googleapis.com": "/calendar/v3/", - "docs.googleapis.com": "/v1/documents/", - "slides.googleapis.com": "/v1/presentations/", - "sheets.googleapis.com": "/v4/spreadsheets/", +export const GOOGLE_API_PATH_PREFIXES: Readonly> = { + "gmail.googleapis.com": ["/gmail/v1/users/me/"], + "www.googleapis.com": ["/calendar/v3/", "/drive/v3/", "/upload/drive/v3/"], + "docs.googleapis.com": ["/v1/documents/"], + "slides.googleapis.com": ["/v1/presentations/"], + "sheets.googleapis.com": ["/v4/spreadsheets/"], }; export type QueryValue = string | number | boolean | readonly string[] | undefined; @@ -19,6 +20,12 @@ export interface GoogleRequest { body?: unknown; readOnly?: boolean; ifMatch?: string; + upload?: { contentType: string; data: Uint8Array }; +} + +export interface GoogleBytes { + data: Buffer; + contentType: string | null; } export type GoogleFetch = (url: string, init: RequestInit) => Promise; @@ -33,12 +40,13 @@ export interface GoogleHttpOptions { export interface GoogleHttp { send(request: GoogleRequest): Promise; + download(request: GoogleRequest, maxBytes: number): Promise; } interface GoogleAnswer { status: number; headers: Headers; - text: string; + data: Buffer; } export const DEFAULT_TIMEOUT_MS = 20_000; @@ -52,8 +60,8 @@ export function googleRequestUrl(request: GoogleRequest): string { if (!GOOGLE_API_HOSTS.includes(request.host)) throw new Error(`Host is not allowed: ${request.host}`); if (!request.path.startsWith("/") || request.path.startsWith("//")) throw new Error("Request path must be absolute"); const url = new URL(`https://${request.host}${request.path}`); - const prefix = GOOGLE_API_PATH_PREFIXES[request.host]; - if (prefix && !url.pathname.startsWith(prefix)) throw new Error(`Path is not allowed on ${request.host}`); + const prefixes = GOOGLE_API_PATH_PREFIXES[request.host]; + if (!prefixes.some((prefix) => url.pathname.startsWith(prefix))) throw new Error(`Path is not allowed on ${request.host}`); for (const [key, value] of Object.entries(request.query ?? {})) { if (value === undefined) continue; if (Array.isArray(value)) for (const item of value) url.searchParams.append(key, item); @@ -76,24 +84,26 @@ export function createGoogleHttp(options: GoogleHttpOptions): GoogleHttp { const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS; const retryDelayMs = options.retryDelayMs ?? DEFAULT_RETRY_DELAY_MS; - async function attempt(request: GoogleRequest): Promise { + async function attempt(request: GoogleRequest, limit: Limit): Promise { const signal = AbortSignal.any([AbortSignal.timeout(timeoutMs), ...(options.signal ? [options.signal] : [])]); const headers: Record = { Authorization: `Bearer ${options.accessToken}`, - Accept: "application/json", + Accept: limit.accept, }; + if (request.body !== undefined && request.upload !== undefined) throw new Error("A request has either a JSON body or an upload"); if (request.body !== undefined) headers["Content-Type"] = "application/json"; + if (request.upload) headers["Content-Type"] = request.upload.contentType; if (request.ifMatch) headers["If-Match"] = request.ifMatch; const url = googleRequestUrl(request); try { const response = await doFetch(url, { method: request.method, headers, - body: request.body === undefined ? undefined : JSON.stringify(request.body), + body: request.upload ? Buffer.from(request.upload.data) : request.body === undefined ? undefined : JSON.stringify(request.body), signal, - redirect: "error", + redirect: "manual", }); - return { status: response.status, headers: response.headers, text: await readBounded(response) }; + return { status: response.status, headers: response.headers, data: await readBounded(response, limit) }; } catch (error) { if (error instanceof GoogleToolError) { throw new GoogleToolError(error.kind, withWriteWarning(request, error.message), error.httpStatus); @@ -104,44 +114,73 @@ export function createGoogleHttp(options: GoogleHttpOptions): GoogleHttp { } } - return { - async send(request: GoogleRequest): Promise { - let answer: GoogleAnswer; - for (let tries = 0; ; tries += 1) { - const mayRetry = !isWrite(request) && tries === 0; - try { - answer = await attempt(request); - } catch (error) { - if (mayRetry && error instanceof GoogleToolError && error.kind === "network") { - await delay(retryDelayMs, options.signal); - continue; - } - throw error; - } - if (mayRetry && RETRYABLE_READ_STATUSES.has(answer.status)) { + async function exchange(request: GoogleRequest, limit: Limit): Promise { + let answer: GoogleAnswer; + for (let tries = 0; ; tries += 1) { + const mayRetry = !isWrite(request) && tries === 0; + try { + answer = await attempt(request, limit); + } catch (error) { + if (mayRetry && error instanceof GoogleToolError && error.kind === "network") { await delay(retryDelayMs, options.signal); continue; } - break; + throw error; } - if (answer.status < 200 || answer.status >= 300) throw googleError(answer, answer.text, request); - if (answer.text.length === 0) return {} as T; + if (mayRetry && RETRYABLE_READ_STATUSES.has(answer.status)) { + await delay(retryDelayMs, options.signal); + continue; + } + break; + } + if (answer.status < 200 || answer.status >= 300) throw googleError(answer, answer.data.toString("utf8"), request); + return answer; + } + + return { + async send(request: GoogleRequest): Promise { + const answer = await exchange(request, { accept: "application/json", maxBytes: MAX_RESPONSE_BYTES, kind: "invalid_response" }); + const text = answer.data.toString("utf8"); + if (text.length === 0) return {} as T; try { - return JSON.parse(answer.text) as T; + return JSON.parse(text) as T; } catch { throw new GoogleToolError("invalid_response", withWriteWarning(request, "Google returned a response that is not JSON."), answer.status); } }, + async download(request: GoogleRequest, maxBytes: number): Promise { + if (isWrite(request)) throw new Error("A download must be a read"); + const answer = await exchange(request, { accept: "*/*", maxBytes: Math.min(maxBytes, MAX_RESPONSE_BYTES), kind: "too_large" }); + return { data: answer.data, contentType: answer.headers.get("content-type") }; + }, }; } -async function readBounded(response: Response): Promise { - const declared = Number(response.headers.get("content-length") ?? "0"); - if (declared > MAX_RESPONSE_BYTES) { - await response.body?.cancel().catch(() => undefined); - throw new GoogleToolError("invalid_response", "Google's response is too large.", response.status); +interface Limit { + accept: string; + maxBytes: number; + kind: "invalid_response" | "too_large"; +} + +function tooLarge(response: Response, limit: Limit): GoogleToolError { + if (limit.kind === "too_large" && response.status >= 200 && response.status < 300) { + return new GoogleToolError("too_large", `The content is larger than ${formatBytes(limit.maxBytes)}, the most this tool returns. Nothing was returned.`, response.status); } - if (!response.body) return ""; + return new GoogleToolError("invalid_response", "Google's response is too large.", response.status); +} + +export function formatBytes(bytes: number): string { + return bytes % (1024 * 1024) === 0 ? `${bytes / (1024 * 1024)} MB` : `${bytes} bytes`; +} + +async function readBounded(response: Response, limit: Limit): Promise { + const maxBytes = response.status >= 200 && response.status < 300 ? limit.maxBytes : MAX_RESPONSE_BYTES; + const declared = Number(response.headers.get("content-length") ?? "0"); + if (declared > maxBytes) { + await response.body?.cancel().catch(() => undefined); + throw tooLarge(response, limit); + } + if (!response.body) return Buffer.alloc(0); const reader = response.body.getReader(); const chunks: Uint8Array[] = []; let size = 0; @@ -149,13 +188,13 @@ async function readBounded(response: Response): Promise { const { done, value } = await reader.read(); if (done) break; size += value.byteLength; - if (size > MAX_RESPONSE_BYTES) { + if (size > maxBytes) { await reader.cancel().catch(() => undefined); - throw new GoogleToolError("invalid_response", "Google's response is too large.", response.status); + throw tooLarge(response, limit); } chunks.push(value); } - return Buffer.concat(chunks).toString("utf8"); + return Buffer.concat(chunks); } interface GoogleErrorBody { @@ -188,6 +227,10 @@ export function googleError( ].filter((reason): reason is string => typeof reason === "string")); const authenticate = response.headers.get("www-authenticate") ?? ""; + if (status === 0 || (status >= 300 && status < 400)) { + const redirect = "Google answered with a redirect, which is not followed."; + return new GoogleToolError("invalid_response", request ? withWriteWarning(request, redirect) : redirect, status); + } if (status === 401) return new GoogleWorkspaceAuthError("unauthenticated"); if (status === 403 && ( /\berror\s*=\s*"?insufficient_scope\b/i.test(authenticate) @@ -203,6 +246,12 @@ export function googleError( if (status === 429 || reasons.has("RATE_LIMIT_EXCEEDED") || reasons.has("rateLimitExceeded") || reasons.has("userRateLimitExceeded")) { return new GoogleToolError("rate_limited", "Google is rate limiting requests. Try again shortly.", status); } + if (status === 403 && reasons.has("exportSizeLimitExceeded")) { + return new GoogleToolError("too_large", "This file is larger than Google's 10 MB export limit. Nothing was returned.", status); + } + if (status === 403 && reasons.has("appNotAuthorizedToFile")) { + return new GoogleToolError("permission_denied", "This connection can change only files that this app created or that were opened with it (Google Drive drive.file access). Nothing was changed.", status); + } if (status === 403) return new GoogleToolError("permission_denied", message ?? "Google denied access to this item.", status, { status: error?.status, reasons: [...reasons] }); if (status === 404 || status === 410) return new GoogleToolError("not_found", "Google could not find that item.", status); if (status === 412) return new GoogleToolError("invalid_argument", "The item changed after it was read, so nothing was changed. Read it again and retry.", status); diff --git a/server/src/google-workspace-rest-tools/probe.test.ts b/server/src/google-workspace-rest-tools/probe.test.ts index f9d5ae9fe87..1a24884f5f2 100644 --- a/server/src/google-workspace-rest-tools/probe.test.ts +++ b/server/src/google-workspace-rest-tools/probe.test.ts @@ -57,6 +57,19 @@ describe("probeGoogleWorkspaceRestService", () => { expect(fetch).not.toHaveBeenCalled(); }); + it("probes Drive with a one-field about.get, which drive.readonly and drive.file both allow", async () => { + for (const granted of [["drive.readonly"], ["drive.file"], ["drive.readonly", "drive.file"]]) { + const fetch = vi.fn(async () => Response.json({ kind: "drive#about" })); + await expect(probeGoogleWorkspaceRestService({ service: "drive", accessToken: "t", grantedScopes: granted.map(scope), fetch })) + .resolves.toEqual({ ok: true, probed: true }); + const [url, init] = fetch.mock.calls[0] as unknown as [string, RequestInit]; + expect(new URL(url).pathname).toBe("/drive/v3/about"); + expect(new URL(url).searchParams.get("fields")).toBe("kind"); + expect(init.method).toBe("GET"); + } + expect(googleWorkspaceRestProbeFor("drive", [scope("documents")])).toBeNull(); + }); + it.each(["docs", "slides"] as const)("lists %s without a network probe, since every read needs a file ID", async (service) => { const fetch = vi.fn(); for (const scopes of [["documents.readonly", "documents"], ["presentations.readonly", "presentations"]]) { diff --git a/server/src/google-workspace-rest-tools/probe.ts b/server/src/google-workspace-rest-tools/probe.ts index 50fd6458b33..2030db2ecb4 100644 --- a/server/src/google-workspace-rest-tools/probe.ts +++ b/server/src/google-workspace-rest-tools/probe.ts @@ -1,6 +1,7 @@ import { CALENDAR_BASE, CALENDAR_HOST } from "./calendar/event.js"; import { calendarProbeRequest } from "./calendar/list-calendars.js"; import { freeBusyRequest } from "./calendar/suggest-time.js"; +import { driveProbeRequest } from "./drive/index.js"; import { GoogleToolError, GoogleWorkspaceAuthError } from "./errors.js"; import { createGoogleHttp, type GoogleFetch, type GoogleRequest } from "./google-http.js"; import type { GoogleWorkspaceRestService } from "./tools.js"; @@ -37,6 +38,12 @@ export const GOOGLE_WORKSPACE_REST_PROBES: Readonly freeBusyRequest(["primary"], { start: now, end: now + PROBE_WINDOW_MS }, "UTC"), }, ], + drive: [ + { + anyOfScopes: [scope("drive.readonly"), scope("drive.file")], + request: () => driveProbeRequest(), + }, + ], docs: [], slides: [], sheets: [], diff --git a/server/src/google-workspace-rest-tools/tools.ts b/server/src/google-workspace-rest-tools/tools.ts index ad631e5a4fa..83eb3347200 100644 --- a/server/src/google-workspace-rest-tools/tools.ts +++ b/server/src/google-workspace-rest-tools/tools.ts @@ -3,18 +3,20 @@ import { McpError, ErrorCode } from "@modelcontextprotocol/sdk/types.js"; import { GoogleWorkspaceAuthError } from "./errors.js"; import { CALENDAR_TOOLS } from "./calendar/index.js"; import { DOCS_TOOLS } from "./docs/index.js"; +import { DRIVE_TOOLS } from "./drive/index.js"; import { GMAIL_TOOLS } from "./gmail/index.js"; import { SLIDES_TOOLS } from "./slides/index.js"; import { createGoogleHttp, type GoogleFetch } from "./google-http.js"; import { SHEETS_TOOLS } from "./sheets/index.js"; import type { RestTool } from "./tool.js"; -export const GOOGLE_WORKSPACE_REST_SERVICES = ["gmail", "calendar", "docs", "slides", "sheets"] as const; +export const GOOGLE_WORKSPACE_REST_SERVICES = ["gmail", "calendar", "drive", "docs", "slides", "sheets"] as const; export type GoogleWorkspaceRestService = (typeof GOOGLE_WORKSPACE_REST_SERVICES)[number]; const TOOLS: Record = { gmail: GMAIL_TOOLS, calendar: CALENDAR_TOOLS, + drive: DRIVE_TOOLS, docs: DOCS_TOOLS, slides: SLIDES_TOOLS, sheets: SHEETS_TOOLS, diff --git a/server/src/services/google-workspace-rest-dispatch.test.ts b/server/src/services/google-workspace-rest-dispatch.test.ts index 28b6c4154f9..dba6471c7cb 100644 --- a/server/src/services/google-workspace-rest-dispatch.test.ts +++ b/server/src/services/google-workspace-rest-dispatch.test.ts @@ -50,7 +50,7 @@ describe("callGoogleWorkspaceRest", () => { }); it("refuses a service the REST tools do not implement", async () => { - await expect(callGoogleWorkspaceRest({ service: "drive", toolName: "search_files", arguments: {}, credentialHeaders: {}, fetch: vi.fn() })) + await expect(callGoogleWorkspaceRest({ service: "chat", toolName: "send_message", arguments: {}, credentialHeaders: {}, fetch: vi.fn() })) .rejects.toThrow("no Paperclip REST tools"); }); });