using-googledrive-connector

name	using-googledrive-connector
description	Implements Google Drive file listing, reading, and management using generated clients and MCP tools. Use when doing ANYTHING that touches Google Drive, files, or documents in any way, load this skill.

Major Platform Resource: Google Drive

Setting Up a Google Drive Connector

Google Drive requires OAuth authentication before use.

When the user asks you to set up Google Drive or connect their files:

1. Call mcp__resource-setup__request-resource-setup with subtype: "googledrive" — this prompts the user to authenticate with Google
2. Once setup completes, the resource is ready to use

---

Common: Interacting with Resources

Security: Never connect directly to databases/APIs. Never use credentials in code. Always use generated clients or MCP tools.

Description field: Always include a short description (~5 words) when calling any resource MCP tool, explaining what the operation does (e.g. "List project documents", "Get file contents"). This is displayed to the user in the chat UI.

Two ways to interact with resources:

1. MCP tools (direct, no code needed): Tools follow the pattern mcp__resources__<resourcetype>_<toolname>. Use mcp__resources__list_resources to discover available resources and their IDs.
2. Generated TypeScript clients (for app code): Call mcp__resource-tools__add-resource-client with a resourceId to generate a typed client. Clients are created in /clients/ (Next.js) or /src/clients/ (Vite).

CRITICAL: Do NOT guess client method names or signatures. The TypeScript clients in @major-tech/resource-client have strongly typed inputs and outputs. ALWAYS read the actual client source code in the generated /clients/ directory (or the package itself) to verify available methods and their exact signatures before writing any client code.

Framework note: Next.js = resource clients must be used in server-side code only (Server Components, Server Actions, API Routes). Vite = call directly from frontend.

Error handling: Always check result.ok before accessing result.result.

Invocation keys must be static strings — use descriptive literals like "list-project-files", never dynamic values like `${folder}-files`.

---

MCP Tools

• mcp__resources__googledrive_list_files — Search and list files. Args: resourceId, query? (Drive search syntax), maxResults?, pageToken?
• mcp__resources__googledrive_get_file — Get file metadata by ID. Args: resourceId, fileId
• mcp__resources__googledrive_get_file_content — Export a Google Docs/Sheets/Slides file to a specified format. Args: resourceId, fileId, mimeType? (default: "text/plain"). For binary files, use googledrive_invoke with alt=media.
• mcp__resources__googledrive_list_shared_drives — List shared drives. Args: resourceId
• mcp__resources__googledrive_invoke — Make any HTTP request to the Google Drive API v3 (for operations not covered by other tools). Args: resourceId, method, path, query?, body?, timeoutMs?

TypeScript Client

import { googleDriveClient } from "./clients";

// invoke(method, path, invocationKey, options?)
// All paths are relative to https://www.googleapis.com/drive/v3/

// List recent files
const result = await googleDriveClient.invoke("GET", "files", "list-files", {
	query: { pageSize: "10", fields: "files(id,name,mimeType,modifiedTime)", orderBy: "modifiedTime desc" },
});
if (result.ok && result.result.status === 200 && result.result.body.kind === "json") {
	const files = result.result.body.value.files;
}

// Search for spreadsheets
const searchResult = await googleDriveClient.invoke("GET", "files", "search-spreadsheets", {
	query: { q: "mimeType='application/vnd.google-apps.spreadsheet'", fields: "files(id,name)" },
});

// Export a Google Doc as plain text
const exportResult = await googleDriveClient.invoke("GET", "files/FILE_ID/export", "export-doc", {
	query: { mimeType: "text/plain" },
});

Tips

• All paths are relative to https://www.googleapis.com/drive/v3/ — e.g. use files, not the full URL.
• Drive search syntax: name contains 'report', mimeType = 'application/vnd.google-apps.spreadsheet', modifiedTime > '2024-01-01', 'FOLDER_ID' in parents, trashed = false. Combine with and/or.
• Google Workspace MIME types: application/vnd.google-apps.document (Docs), application/vnd.google-apps.spreadsheet (Sheets), application/vnd.google-apps.presentation (Slides), application/vnd.google-apps.folder (Folder)
• Export MIME types (for get_file_content): text/plain, text/csv, application/pdf, application/vnd.openxmlformats-officedocument.wordprocessingml.document (.docx), application/vnd.openxmlformats-officedocument.spreadsheetml.sheet (.xlsx)
• Binary file download: Use googledrive_invoke with path files/{id}?alt=media to download non-Google files directly.
• Pagination: Check nextPageToken in the response and pass it as pageToken to get the next page.
• Fields parameter: Use fields query param to limit response size, e.g. fields=files(id,name,mimeType,modifiedTime,size).
• Response structure: { kind: "api", status: number, body: { kind: "json", value: {...} } }
• Scope presets: "readonly" (view files) or "readwrite" (view all files + manage app-created files). Write operations fail with 403 on readonly.

Docs: Google Drive API Reference