Open-source AI coworkers that each get a computer of their own: a browser, files and tools, with every action decided before it happens and recorded after. Bring any AG-UI agent.
import { cutAtCodeUnits } from "../channels/text";
import { MAX_RESULT_CHARS, type McpCallResult, type McpTool } from "./mcp";
/**
* Google Drive, reached over its ordinary REST API instead of its MCP server.
*
* WHY THIS EXISTS. Google publishes a hosted MCP server for Drive, `drivemcp.googleapis.com`, and
* pointing the catalogue at it was the original design: a vendor-maintained server needs no code
* here at all. It is gated behind the Google Workspace Developer Preview Program, and refuses an
* unenrolled project with `The caller does not have permission` — a statement about the project,
* not the credential, so every check available locally says the setup is correct. It is.
*
* The REST API underneath has been generally available since 2015. So this trades "no code" for "no
* dependency on a preview", which for a connector people rely on is the better side of the trade.
*
* WHAT MAKES IT SWAPPABLE. This module implements the interface {@link ./mcp} already had —
* `listTools` and `callTool`, same shapes — rather than inventing one for itself. MCP is therefore
* not the default with an exception carved out of it; both are implementations of the same contract,
* chosen per catalogue entry by {@link ./access} and looked up in {@link ./transport}. Going back to
* the MCP server when the preview opens is one field on one entry, with nothing else in the system
* aware it changed.
*
* The TOOL NAMES are deliberately the ones Google's MCP server advertises, character for character.
* A grant is stored as `google-drive/search_files`, so keeping the names identical means every grant
* an administrator has already made keeps working across the swap, in either direction. Diverging
* here would silently turn switching transports into re-granting every tool on every Bot.
*
* Read-only, and only the tools that can be implemented faithfully. Google's MCP server also
* advertises writes; the `drive.readonly` scope refuses them, and nothing here offers them.
*/
/** Long enough for a slow listing, short enough that a Bot's turn is not held open on it. */
const REQUEST_TIMEOUT_MS = 30_000;
/** How many files a listing returns before the model is reading a directory rather than an answer. */
const PAGE_SIZE = 25;
/**
* The fields asked for, rather than Drive's default.
*
* Drive returns a thin projection unless asked, and `webViewLink` is the one worth naming: a result
* carrying it lets a Bot cite a file as a link somebody can open, which is the difference between an
* answer and an assertion about an answer.
*/
const FILE_FIELDS =
"id,name,mimeType,modifiedTime,webViewLink,size,owners(emailAddress)";
/**
* Shared drives as well as My Drive.
*
* Drive leaves shared drive items out of every `files.get` and `files.list` that does not say it
* supports them. A company's documents often live in shared drives, so a file the person could open
* came back from `get_file_metadata` and `read_file_content` as a 404 "File not found", and never
* came back from a search at all. The listing also has to ask for those items. It keeps Drive's
* default `user` corpus, which Google recommends over `allDrives`.
*/
const SHARED_DRIVES = { supportsAllDrives: "true" } as const;
const SHARED_DRIVE_ITEMS = {
...SHARED_DRIVES,
includeItemsFromAllDrives: "true",
} as const;
/**
* Google's editor formats, and the plain-text export each one has.
*
* A Doc has no bytes to download — `alt=media` refuses it — so it has to be exported. Anything not
* in here is a real file and is fetched directly.
*
* A Map, because the type comes off a file somebody else uploaded and named. Asked of a plain
* object, `toString` is answered with `Object.prototype.toString`: truthy, so the file is taken for
* an editor format, the refusal below is skipped, and that function is sent to Google as the format
* to export to.
*/
const EXPORTABLE: ReadonlyMap<string, string> = new Map([
["application/vnd.google-apps.document", "text/plain"],
["application/vnd.google-apps.spreadsheet", "text/csv"],
["application/vnd.google-apps.presentation", "text/plain"],
]);
/**
* What this adapter offers, as the same shape a server would have answered `tools/list` with.
*
* Static, and that is the point of difference from MCP: there is no remote list to discover, so
* `refreshTools` records what this code can actually do. A tool listed here that the dispatcher
* below does not handle would be advertised to a model and then fail, so the two are kept adjacent.
*/
const TOOLS: readonly McpTool[] = Object.freeze([
{
name: "search_files",
description:
"Search the files in your Google Drive by name and full text. Returns matching files with their names, types, last modified times and links.",
inputSchema: {
type: "object",
properties: {
query: {
type: "string",
description: "What to look for, in file names and file contents.",
},
},
required: ["query"],
},
},
{
name: "list_recent_files",
description:
"List the files in your Google Drive that changed most recently, newest first.",
inputSchema: { type: "object", properties: {} },
},
{
name: "get_file_metadata",
description:
"Get the name, type, size, owner, last modified time and link for one file, by its id.",
inputSchema: {
type: "object",
properties: {
fileId: { type: "string", description: "The file's Drive id." },
},
required: ["fileId"],
},
},
{
name: "read_file_content",
description:
"Read the text of one file in your Google Drive, by its id. Google Docs, Sheets and Slides are exported as text.",
inputSchema: {
type: "object",
properties: {
fileId: { type: "string", description: "The file's Drive id." },
},
required: ["fileId"],
},
},
]);
type Connection = { url: string; token?: string };
/**
* No credential is needed to know what this adapter can do, because the answer is in this file.
*
* This is not a detail. Assuming otherwise made configuring Drive a four-stop journey: an
* administrator enabling the connector was refused at "refresh tools" until they had gone to their
* own settings page and connected a personal Google account, whose token was then handed to
* {@link listTools} — which ignores it — and thrown away. The gate was real and the work behind it
* was not.
*/
export const listNeedsCredential = false;
/** The same list for everybody, because this adapter's capability is this code rather than a server. */
export async function listTools(_connection: Connection): Promise<McpTool[]> {
return TOOLS.map((tool) => ({ ...tool }));
}
/**
* One request to Drive, with the caller's own token.
*
* `token` is never optional in practice here — Drive is `user-oauth`, so the store has already
* refused a call with nobody's credential before this module is reached — but it is typed optional
* by the shared connection shape, so a missing one is named rather than sent as `Bearer undefined`.
*/
async function request(
connection: Connection,
path: string,
query: Record<string, string>,
): Promise<{ ok: true; response: Response } | { ok: false; message: string }> {
if (!connection.token) {
return { ok: false, message: "No credential was available for this call." };
}
const url = new URL(`${connection.url.replace(/\/+$/, "")}${path}`);
for (const [key, value] of Object.entries(query)) {
url.searchParams.set(key, value);
}
let response: Response;
try {
response = await fetch(url, {
headers: { authorization: `Bearer ${connection.token}` },
signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
});
} catch (error) {
return {
ok: false,
message:
error instanceof Error && error.name === "TimeoutError"
? "Google Drive did not answer in time."
: `Google Drive could not be reached: ${error instanceof Error ? error.message : String(error)}`,
};
}
if (!response.ok) {
/*
* Google's own sentence, kept. For a 403 this is where it names the API that is not enabled and
* gives the console URL, which is the difference between a fix and a guess. Dropping it once
* already cost a diagnosis.
*/
const body = await response.text().catch(() => "");
let detail = "";
try {
const parsed = JSON.parse(body) as { error?: { message?: unknown } };
if (typeof parsed.error?.message === "string")
detail = parsed.error.message;
} catch {
// Not JSON. The status alone is still worth saying.
}
return {
ok: false,
message: detail
? `Google Drive refused this request (${response.status}): ${detail}`
: `Google Drive refused this request (${response.status}).`,
};
}
return { ok: true, response };
}
/**
* Whether this type's bytes can be read as text at all.
*
* An allow list, not a deny list. New binary formats appear constantly and each one added to a deny
* list is a format that reached a model as mojibake first; the textual families are few and stable.
* `application/*` is deliberately not included wholesale — it holds JSON and XML, and also PDFs,
* archives and every office format.
*/
function isTextual(mimeType: string | undefined): boolean {
if (!mimeType) return false;
const type = mimeType.split(";")[0].trim().toLowerCase();
if (type.startsWith("text/")) return true;
return [
"application/json",
"application/xml",
"application/xhtml+xml",
"application/javascript",
"application/x-ndjson",
"application/yaml",
"application/x-yaml",
"application/sql",
"application/toml",
].includes(type);
}
type DriveFile = {
id?: string;
name?: string;
mimeType?: string;
modifiedTime?: string;
webViewLink?: string;
size?: string;
owners?: { emailAddress?: string }[];
shortcutDetails?: { targetId?: string; targetMimeType?: string };
};
const SHORTCUT_MIME = "application/vnd.google-apps.shortcut";
/**
* One file as a line a model can quote.
*
* The id is included because every other tool here takes one, and a model that has just been shown a
* file it cannot then read is a dead end it will try to talk its way out of.
*/
function fileLine(file: DriveFile): string {
const name = file.name ?? "(untitled)";
/*
* A markdown link, not a bare URL beside a name.
*
* This is K1's acceptance criterion rather than decoration: "the answer carries a link that opens
* the actual file". Tool results are drawn through a markdown renderer, so a link is a link a
* reader can click, and one the model can carry into its own prose when it cites the file. A bare
* URL depends on the renderer choosing to autolink, and reads as noise when it does not.
*
* The brackets in the name are escaped because a `]` in a file name would otherwise close the link
* text early and leave the rest of the name and the URL as literal characters on screen.
*/
const parts = [
file.webViewLink
? `[${name.replace(/\[/g, "\\[").replace(/\]/g, "\\]")}](${file.webViewLink})`
: name,
];
if (file.mimeType) parts.push(file.mimeType);
if (file.modifiedTime) parts.push(`modified ${file.modifiedTime}`);
// Kept even though the link carries it: every other tool here takes an id, and a model that has
// to parse one out of a URL will sometimes get it wrong.
if (file.id) parts.push(`id: ${file.id}`);
return `- ${parts.join(" · ")}`;
}
/**
* Only files that are not in the trash.
*
* `files.list` returns trashed files unless the query says otherwise, so a document somebody had
* thrown away came back as a match, or as a recent file, with nothing in its line to say it was in
* the trash, and a model answers from what it is handed. A file read by its id is still read, trashed
* or not: that is a request for that file.
*/
const NOT_TRASHED = "trashed = false";
/**
* A Drive query string built from what somebody typed.
*
* The quote is escaped, not stripped. Drive's `q` syntax delimits with single quotes, so an
* apostrophe in a search term would otherwise end the clause and change the query's meaning —
* searching for `don't` would become a syntax error at best, and at worst a different search than
* the one asked for. Escaped, a term is only ever a term.
*
* Bracketed, so the {@link NOT_TRASHED} joined to it applies to both halves of the `or`.
*/
const driveQuery = (query: string) => {
const escaped = query.replace(/\\/g, "\\\\").replace(/'/g, "\\'");
return `(name contains '${escaped}' or fullText contains '${escaped}') and ${NOT_TRASHED}`;
};
/**
* Text as an MCP result, through the one function that decides what a model is told.
*
* Reused rather than reimplemented so the empty case and the size cap behave identically across both
* transports. The empty case is the one that matters: a search that matched nothing has to SAY so,
* because an empty string reads to a model as "the tool had nothing to say" and gets filled in from
* memory — which for a knowledge connector is the exact failure the lane exists to prevent.
*
* `cut` is true when reading stopped before the file ended (see {@link readOpening}), so the file's
* full length is not known and is not claimed.
*/
function asResult(text: string, cut = false): McpCallResult {
const joined = text.trim();
if (joined === "") {
return {
text: "The tool returned no content. Nothing was found, so there is nothing here to answer from.",
isError: false,
truncated: false,
};
}
if (joined.length <= MAX_RESULT_CHARS && !cut) {
return { text: joined, isError: false, truncated: false };
}
return {
text: `${cutAtCodeUnits(joined, MAX_RESULT_CHARS)}\n\n[truncated: ${cut ? "the file is longer than this" : `the tool returned ${joined.length} characters`}]`,
isError: false,
truncated: true,
};
}
/**
* As much of a file's text as a result can show, and whether there was more.
*
* `response.text()` held the whole download as one string before all but its opening was dropped,
* so a 200 MB log raised the process's memory by more than 600 MB to return 20,000 characters, on
* the same process that serves everybody else. Reading stops once there is more than a result can
* carry, and the rest of the body is cancelled rather than downloaded.
*
* Decoded the way `response.text()` decodes: UTF-8, with a byte order mark dropped and anything
* malformed replaced.
*/
async function readOpening(
response: Response,
): Promise<{ text: string; cut: boolean }> {
if (!response.body) return { text: "", cut: false };
const reader = response.body.getReader();
const decoder = new TextDecoder();
let text = "";
try {
for (;;) {
const { done, value } = await reader.read();
if (done) return { text: text + decoder.decode(), cut: false };
text += decoder.decode(value, { stream: true });
if (text.length > MAX_RESULT_CHARS) return { text, cut: true };
}
} finally {
await reader.cancel().catch(() => {});
}
}
const failure = (message: string): McpCallResult => ({
text: message,
isError: true,
truncated: false,
});
/**
* Call one tool.
*
* Whether the call was permitted is decided before this module, exactly as it is for MCP. This
* dispatches and formats, and nothing else — an unknown tool is refused here rather than guessed at,
* because a tool name that reaches this point and is not in {@link TOOLS} means the stored tool list
* and this code have diverged, which is a bug to surface rather than to absorb.
*/
export async function callTool(
connection: Connection,
toolName: string,
args: Record<string, unknown>,
): Promise<McpCallResult> {
const stringArg = (key: string): string | null => {
const value = args[key];
return typeof value === "string" && value.trim() !== "" ? value : null;
};
if (toolName === "search_files" || toolName === "list_recent_files") {
const query = stringArg("query");
if (toolName === "search_files" && !query) {
return failure("A search needs something to search for.");
}
const result = await request(connection, "/files", {
...SHARED_DRIVE_ITEMS,
pageSize: String(PAGE_SIZE),
fields: `files(${FILE_FIELDS})`,
// Drive's own ordering for "recent". Search leaves it to relevance.
...(query
? { q: driveQuery(query) }
: { q: NOT_TRASHED, orderBy: "modifiedTime desc" }),
});
if (!result.ok) return failure(result.message);
const body = (await result.response.json()) as { files?: DriveFile[] };
const files = body.files ?? [];
return asResult(files.map(fileLine).join("\n"));
}
if (toolName === "get_file_metadata") {
const fileId = stringArg("fileId");
if (!fileId) return failure("A file id is needed to look a file up.");
const result = await request(
connection,
`/files/${encodeURIComponent(fileId)}`,
{ ...SHARED_DRIVES, fields: FILE_FIELDS },
);
if (!result.ok) return failure(result.message);
const file = (await result.response.json()) as DriveFile;
const owner = file.owners?.[0]?.emailAddress;
return asResult(
[
fileLine(file),
file.size ? `size: ${file.size} bytes` : null,
owner ? `owner: ${owner}` : null,
]
.filter(Boolean)
.join("\n"),
);
}
if (toolName === "read_file_content") {
const fileId = stringArg("fileId");
if (!fileId) return failure("A file id is needed to read a file.");
/*
* The type is looked up first, because how a file is read depends on what it is. A Doc has no
* bytes and must be exported; anything else is downloaded. Asking Drive rather than guessing from
* the name means a mislabelled file still reads correctly.
*/
const metadata = await request(
connection,
`/files/${encodeURIComponent(fileId)}`,
{
...SHARED_DRIVES,
fields: "id,name,mimeType,shortcutDetails(targetId,targetMimeType)",
},
);
if (!metadata.ok) return failure(metadata.message);
let file = (await metadata.response.json()) as DriveFile;
let readId = fileId;
/*
* A shortcut is a pointer, not a document. Drive's search and recent lists return them as
* ordinary hits, and reading one by that id used to be refused as a binary
* `application/vnd.google-apps.shortcut` — so a file the person could open, that search had
* just named, could not be read. Follow the target once. A shortcut that names another
* shortcut is declined as that type, rather than walked; loops are not a document.
*/
if (file.mimeType === SHORTCUT_MIME) {
const targetId = file.shortcutDetails?.targetId?.trim();
if (!targetId) {
return failure(
`${file.name ?? fileId} is a shortcut that does not name a file.`,
);
}
const target = await request(
connection,
`/files/${encodeURIComponent(targetId)}`,
{ ...SHARED_DRIVES, fields: "id,name,mimeType" },
);
if (!target.ok) return failure(target.message);
file = (await target.response.json()) as DriveFile;
readId = targetId;
}
const exportAs = file.mimeType ? EXPORTABLE.get(file.mimeType) : undefined;
/*
* A file whose bytes are not text is declined by name, not decoded and hoped for.
*
* `response.text()` on a PDF, an image or a zip produces thousands of replacement characters and
* mojibake, and that goes straight into a model's context: it costs the tokens of the real
* document, tells the model nothing, and looks enough like content that the model will try to
* summarise it. Saying which type it is instead lets the model do the one useful thing available
* — name the file and its type, and stop — and keeps a link the person can open themselves.
*
* Only positively-known-textual types are read. Anything unrecognised is declined, for the same
* reason an unknown tool counts as a write: guessing permissively here is not recoverable, since
* nothing downstream can tell garbage from content.
*/
if (!exportAs && !isTextual(file.mimeType)) {
return failure(
`${file.name ?? fileId} is a ${file.mimeType ?? "binary"} file, which this connector cannot read as text. Its metadata and link are available, and somebody can open it themselves.`,
);
}
const content = exportAs
? await request(
connection,
`/files/${encodeURIComponent(readId)}/export`,
{ mimeType: exportAs },
)
: await request(connection, `/files/${encodeURIComponent(readId)}`, {
...SHARED_DRIVES,
alt: "media",
});
if (!content.ok) return failure(content.message);
const { text, cut } = await readOpening(content.response);
// Named, because a model handed only the body cannot cite what it read.
return asResult(`${file.name ?? fileId}\n\n${text}`, cut);
}
return failure(
`${toolName} is not a tool this connector implements. The stored tool list is out of date; refresh it on the Plugins page.`,
);
}