@a1-x-tech/mcp-google-slides 0.1.0

package/dist/config.js

@@ -0,0 +1,87 @@
+/** Default Google Slides API host. */
+export const DEFAULT_BASE = "https://slides.googleapis.com";
+/** Default Google Drive API host (internal dependency: comments, export, image upload). */
+export const DEFAULT_DRIVE_BASE = "https://www.googleapis.com";
+/**
+ * A malformed environment variable. Thrown instead of exiting on the spot so
+ * index.ts can catch it, report the drop-off and start degraded instead of
+ * dying; `reason` is the machine-readable code that ships with that ping
+ * (never a variable's value).
+ */
+export class ConfigError extends Error {
+    reason;
+    constructor(message, reason) {
+        super(message);
+        this.name = "ConfigError";
+        this.reason = reason;
+    }
+}
+/**
+ * What a tool call without credentials reads. The first sentence is the
+ * historical startup error, verbatim — the rest exists because credentials come
+ * only from the environment, so the fix is an operator action plus a restart,
+ * never a retry.
+ */
+export const MISSING_CREDENTIALS_MESSAGE = "Google OAuth credentials are required: set GOOGLE_SLIDES_CLIENT_ID + " +
+    "GOOGLE_SLIDES_CLIENT_SECRET + GOOGLE_SLIDES_REFRESH_TOKEN (recommended), or " +
+    "GOOGLE_SLIDES_ACCESS_TOKEN with a short-lived access token. " +
+    "This is not a network failure and retrying will not help: the operator must set these " +
+    "environment variables in the MCP client's server config and restart the server — they are " +
+    "read only at startup.";
+/**
+ * Raised when a tool call needs credentials and none were configured. The
+ * message is the whole point of the class: it is the only text the calling
+ * model reads about the missing setup, so it names the fix (which variables,
+ * and that a restart is needed) instead of the failure.
+ */
+export class CredentialsError extends Error {
+    constructor(message = MISSING_CREDENTIALS_MESSAGE) {
+        super(message);
+        this.name = "CredentialsError";
+    }
+}
+/** True when the config carries usable credentials (the full refresh triple or a static token). */
+export function hasCredentials(config) {
+    return Boolean(config.accessToken || (config.clientId && config.clientSecret && config.refreshToken));
+}
+/**
+ * Builds the client config from environment variables.
+ *
+ * Missing credentials are NOT an error here: the server starts anyway and the
+ * client raises {@link CredentialsError} on the first tool call, so an
+ * unconfigured install completes the MCP handshake and carries the fix into
+ * the session instead of dying before it with nothing to read. A malformed
+ * setup — the refresh triple set only partially — still throws, because
+ * guessing what the user meant is worse.
+ *
+ *   GOOGLE_SLIDES_CLIENT_ID       OAuth2 client id      (refresh flow, recommended)
+ *   GOOGLE_SLIDES_CLIENT_SECRET   OAuth2 client secret  (refresh flow)
+ *   GOOGLE_SLIDES_REFRESH_TOKEN   OAuth2 refresh token  (refresh flow)
+ *   GOOGLE_SLIDES_ACCESS_TOKEN    static access token (alternative; expires in ~1h)
+ *   GOOGLE_SLIDES_API_BASE        Slides API root override (default https://slides.googleapis.com)
+ *   GOOGLE_SLIDES_DRIVE_API_BASE  Drive API root override (default https://www.googleapis.com)
+ *   GOOGLE_SLIDES_TIMEOUT_MS      per-request timeout (default 60000)
+ *   GOOGLE_SLIDES_MAX_RETRIES     retries on transient errors (default 3)
+ */
+export function loadConfig() {
+    const clientId = process.env.GOOGLE_SLIDES_CLIENT_ID;
+    const clientSecret = process.env.GOOGLE_SLIDES_CLIENT_SECRET;
+    const refreshToken = process.env.GOOGLE_SLIDES_REFRESH_TOKEN;
+    const accessToken = process.env.GOOGLE_SLIDES_ACCESS_TOKEN;
+    const oauthProvided = [clientId, clientSecret, refreshToken].filter(Boolean).length;
+    if (oauthProvided > 0 && oauthProvided < 3) {
+        throw new ConfigError("GOOGLE_SLIDES_CLIENT_ID, GOOGLE_SLIDES_CLIENT_SECRET and GOOGLE_SLIDES_REFRESH_TOKEN must be set together (OAuth2 refresh flow).", "incomplete_oauth_config");
+    }
+    const timeoutMs = Number(process.env.GOOGLE_SLIDES_TIMEOUT_MS);
+    const maxRetries = Number(process.env.GOOGLE_SLIDES_MAX_RETRIES);
+    return {
+        clientId,
+        clientSecret,
+        refreshToken,
+        accessToken,
+        apiBase: process.env.GOOGLE_SLIDES_API_BASE || DEFAULT_BASE,
+        driveApiBase: process.env.GOOGLE_SLIDES_DRIVE_API_BASE || DEFAULT_DRIVE_BASE,
+        timeoutMs: Number.isFinite(timeoutMs) && timeoutMs > 0 ? timeoutMs : 60_000,
+        maxRetries: Number.isFinite(maxRetries) && maxRetries >= 0 ? maxRetries : 3,
+    };
+}

package/dist/index.js

@@ -0,0 +1,131 @@
+#!/usr/bin/env node
+import { readFileSync } from "node:fs";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { GoogleSlidesClient } from "./client.js";
+import { ConfigError, DEFAULT_BASE, DEFAULT_DRIVE_BASE, hasCredentials, loadConfig } from "./config.js";
+import { instrumentToolCalls, Telemetry } from "./telemetry.js";
+import { registerPresentationTools } from "./tools/presentations.js";
+import { registerSlideTools } from "./tools/slides.js";
+import { registerTextTools } from "./tools/text.js";
+import { registerElementTools } from "./tools/elements.js";
+import { registerTableTools } from "./tools/tables.js";
+import { registerNoteTools } from "./tools/notes.js";
+import { registerCommentTools } from "./tools/comments.js";
+import { registerExportTools } from "./tools/export.js";
+import { registerRawTool } from "./tools/raw.js";
+/**
+ * Prose handed to the calling model in the `initialize` result — the only place
+ * it learns what the tool list cannot say: which Google product this API is,
+ * what the API refuses to do, and the behaviours that make a naive loop
+ * expensive, lossy or duplicating.
+ */
+const INSTRUCTIONS = "Google Slides API v1 builds and edits presentations — not Docs, Sheets or Drive browsing: " +
+    "comments and export ride the Drive API internally for this one file; sharing, renaming, listing " +
+    "and deleting files are out of reach (create_presentation cannot be undone here). Everything is " +
+    "addressed by object ids — start with list_slides, not get_presentation (a full deck is hundreds " +
+    "of kilobytes). All writes are batchUpdate and atomic: one invalid request voids the whole batch, " +
+    "nothing is applied. Coordinates are points (a 16:9 slide is 720x405 pt); JSON responses use EMU " +
+    "(1 pt = 12700 EMU). update_transform mode=absolute replaces the entire transform — omitted scale " +
+    "resets to 1, not to the current value. create_image needs a URL Google's servers can fetch " +
+    "(public https, PNG/JPEG/GIF ≤50 MB, ≤25 MP); a local image_path is uploaded to Drive, inserted " +
+    "and the temp file deleted automatically. Thumbnails return a ~30-minute contentUrl; export is " +
+    "capped at 10 MB; both plus comments need a Drive scope on the token. Themes cannot be imported — " +
+    "add_slide only instantiates layouts the deck already has (list_layouts). replace_text returning " +
+    "occurrencesChanged:0 means the wording didn't match — re-check with list_slides. Writes are never " +
+    "retried after a 5xx or timeout: verify with list_slides before re-sending; delete_object is final.";
+/**
+ * Prepended to INSTRUCTIONS when no credentials are configured. The model reads
+ * this before it picks a tool, so an unconfigured session opens with the fix
+ * rather than with a failed call. There is no in-chat login here: credentials
+ * come only from the environment, so the fix is an operator action + restart.
+ */
+const UNCONFIGURED_PREFIX = "ATTENTION: Google Slides is not connected yet — no credentials are configured, so every " +
+    "tool call will fail. The operator must set GOOGLE_SLIDES_CLIENT_ID + " +
+    "GOOGLE_SLIDES_CLIENT_SECRET + GOOGLE_SLIDES_REFRESH_TOKEN (recommended), or " +
+    "GOOGLE_SLIDES_ACCESS_TOKEN with a short-lived access token, in the MCP client's " +
+    "server config and restart this server — the variables are read only at startup. ";
+/** Reads the package version so the server reports its real version to MCP clients. */
+function readVersion() {
+    try {
+        const pkg = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
+        return typeof pkg.version === "string" ? pkg.version : "0.0.0";
+    }
+    catch {
+        return "0.0.0";
+    }
+}
+/**
+ * Loads the config without dying on a bad value. A server that exits here never
+ * completes the MCP handshake, so the user sees a dead server and no reason.
+ * Instead the problem is carried into the session, where the model can read it
+ * and relay it: the config degrades to "no credentials" and every tool call
+ * fails with the actionable message.
+ */
+function loadConfigOrDegraded(telemetry) {
+    try {
+        return { config: loadConfig() };
+    }
+    catch (err) {
+        if (!(err instanceof ConfigError))
+            throw err;
+        console.error(`Error: ${err.message}`);
+        // Fire-and-forget now that the process survives: the historical
+        // `startup_failed` funnel stays comparable, but nothing blocks startup.
+        telemetry.send("startup_failed", { reason: err.reason });
+        return {
+            config: {
+                apiBase: process.env.GOOGLE_SLIDES_API_BASE || DEFAULT_BASE,
+                driveApiBase: process.env.GOOGLE_SLIDES_DRIVE_API_BASE || DEFAULT_DRIVE_BASE,
+            },
+            problem: err,
+        };
+    }
+}
+async function main() {
+    // Anonymous usage pings (ids/names/versions only, never data or arguments);
+    // opt out with ASKADS_TELEMETRY=0. Built before the config so missing
+    // credentials can be reported; wired to the server before tools register.
+    const telemetry = new Telemetry(readVersion());
+    const { config, problem } = loadConfigOrDegraded(telemetry);
+    const client = new GoogleSlidesClient(config);
+    // Decided once, at startup: credentials come only from the environment, so
+    // "restart after setting the variables" is the accurate advice to give.
+    const connected = hasCredentials(config);
+    const server = new McpServer({
+        name: "mcp-google-slides",
+        version: readVersion(),
+    }, 
+    // Surfaces in the initialize result, before the client sees a single tool.
+    {
+        instructions: connected
+            ? INSTRUCTIONS
+            : UNCONFIGURED_PREFIX + (problem ? `Configuration problem: ${problem.message} ` : "") + INSTRUCTIONS,
+    });
+    instrumentToolCalls(server, telemetry);
+    server.server.oninitialized = () => {
+        telemetry.setClientInfo(server.server.getClientVersion());
+        // Split on purpose: `server_start` keeps meaning "a usable install started",
+        // so the unconfigured case gets its own event instead of inflating that number.
+        if (connected)
+            telemetry.send("server_start");
+        else
+            telemetry.send("unconfigured_start", { reason: problem?.reason ?? "missing_credentials" });
+    };
+    registerPresentationTools(server, client);
+    registerSlideTools(server, client);
+    registerTextTools(server, client);
+    registerElementTools(server, client);
+    registerTableTools(server, client);
+    registerNoteTools(server, client);
+    registerCommentTools(server, client);
+    registerExportTools(server, client);
+    registerRawTool(server, client);
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error(`mcp-google-slides running on stdio${connected ? "" : " (no credentials — set the environment variables and restart)"}`);
+}
+main().catch((err) => {
+    console.error("Fatal error starting mcp-google-slides:", err);
+    process.exit(1);
+});

package/dist/telemetry.js

@@ -0,0 +1,120 @@
+/**
+ * Anonymous usage telemetry — fire-and-forget pings to usage.gistrec.cloud.
+ *
+ * Privacy contract (mirrored by the receiver): only an anonymous random
+ * instance id, event/tool names, a fixed-vocabulary failure reason and
+ * environment versions ever leave the machine. The OAuth credentials,
+ * presentation content, tool arguments, prompts and the names or values of
+ * environment variables are never read, serialized or sent. Sends are capped
+ * at 2 s and swallow every error — telemetry must never affect the server's
+ * operation. Opt out for every server of this line at once: ASKADS_TELEMETRY=0
+ * (also accepts false/off/no).
+ */
+import { randomUUID } from "node:crypto";
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+const ENDPOINT = "https://usage.gistrec.cloud/v1/events";
+const APP = "mcp-google-slides";
+const SEND_TIMEOUT_MS = 2000;
+export function telemetryEnabled(env = process.env) {
+    const value = (env.ASKADS_TELEMETRY ?? "").trim().toLowerCase();
+    return !["0", "false", "off", "no"].includes(value);
+}
+/**
+ * Stable anonymous installation id, persisted under the user's config dir.
+ * Any filesystem failure degrades to an ephemeral id: the ping still counts
+ * today's activity, just not installation uniqueness across restarts.
+ */
+function loadInstanceId() {
+    try {
+        const base = process.env.XDG_CONFIG_HOME || join(homedir(), ".config");
+        const dir = join(base, APP);
+        const file = join(dir, "instance-id");
+        try {
+            const existing = readFileSync(file, "utf8").trim();
+            if (/^[0-9a-f]{8}-[0-9a-f-]{27}$/.test(existing))
+                return existing;
+        }
+        catch {
+            // first run — fall through and mint one
+        }
+        const id = randomUUID();
+        mkdirSync(dir, { recursive: true });
+        writeFileSync(file, `${id}\n`);
+        return id;
+    }
+    catch {
+        return randomUUID();
+    }
+}
+export class Telemetry {
+    appVersion;
+    enabled;
+    fetchImpl;
+    instanceId;
+    clientInfo;
+    constructor(appVersion, enabled = telemetryEnabled(), fetchImpl = fetch) {
+        this.appVersion = appVersion;
+        this.enabled = enabled;
+        this.fetchImpl = fetchImpl;
+        this.instanceId = enabled ? loadInstanceId() : "";
+    }
+    /** The MCP initialize handshake tells us which agent host is on the other side. */
+    setClientInfo(info) {
+        this.clientInfo = info;
+    }
+    /** Fire-and-forget: the server's own work never waits on a ping. */
+    send(event, fields = {}) {
+        void this.post(event, fields);
+    }
+    /**
+     * The same ping, awaited. Only for a caller that exits right after — a
+     * fire-and-forget request would die in flight with the process. No startup
+     * path needs it anymore (a config problem degrades instead of exiting).
+     */
+    async sendBlocking(event, fields = {}) {
+        await this.post(event, fields);
+    }
+    async post(event, fields) {
+        if (!this.enabled)
+            return;
+        const body = JSON.stringify({
+            app: APP,
+            event,
+            instance_id: this.instanceId,
+            app_version: this.appVersion,
+            client_name: this.clientInfo?.name,
+            client_version: this.clientInfo?.version,
+            tool: fields.tool,
+            reason: fields.reason,
+            node_version: process.version,
+            os: process.platform,
+        });
+        try {
+            await this.fetchImpl(ENDPOINT, {
+                method: "POST",
+                headers: { "Content-Type": "application/json" },
+                body,
+                signal: AbortSignal.timeout(SEND_TIMEOUT_MS),
+            });
+        }
+        catch {
+            // network failure, timeout abort or a synchronous throw — all silent
+        }
+    }
+}
+/**
+ * Count every tool invocation by name. Wraps registerTool once, before the
+ * domain modules register their tools, so no per-tool wiring is needed.
+ * Only the tool *name* is recorded — arguments never reach telemetry.
+ */
+export function instrumentToolCalls(server, telemetry) {
+    const original = server.registerTool.bind(server);
+    // registerTool's generic signature does not survive a wrapper; the runtime
+    // shape (name, config, callback) is stable per SDK contract.
+    server.registerTool = ((name, config, callback) => original(name, config, ((...args) => {
+        telemetry.send("tool_call", { tool: name });
+        return callback(...args);
+    })));
+}

package/dist/tools/comments.js

@@ -0,0 +1,39 @@
+import { z } from "zod";
+import { DESTRUCTIVE, fail, ok, presentationIdSchema } from "./util.js";
+export function registerCommentTools(server, client) {
+    server.registerTool("manage_comments", {
+        title: "Manage comments",
+        // One tool covers list/get/create/reply/delete; delete removes state, so
+        // the whole tool carries the destructive, non-idempotent hints.
+        annotations: DESTRUCTIVE,
+        description: "Comment threads on the presentation file (served by the Drive API internally — scoped to this one file, no generic Drive access). action=list returns comments with replies and resolved status (pageSize/page_token to paginate, include_deleted for tombstones); get needs comment_id; create needs content and starts a new unanchored thread (the API cannot anchor a new comment to a specific slide or shape); reply needs comment_id + content and/or resolve=true (resolve closes the thread); delete needs comment_id and permanently removes the thread with all replies. Requires a Drive scope on the OAuth token (https://www.googleapis.com/auth/drive) — a presentations-only token gets a 403 here.",
+        inputSchema: {
+            presentation_id: presentationIdSchema(),
+            action: z
+                .enum(["list", "get", "create", "reply", "delete"])
+                .describe("What to do with the presentation's comments."),
+            comment_id: z.string().min(1).optional().describe("get/reply/delete: the comment id from list."),
+            content: z.string().min(1).optional().describe("create/reply: the comment text (plain text)."),
+            resolve: z.boolean().optional().describe("reply only: also mark the whole thread resolved."),
+            page_size: z.number().int().min(1).max(100).optional().describe("list: comments per page (1-100)."),
+            page_token: z.string().optional().describe("list: nextPageToken from the previous page."),
+            include_deleted: z.boolean().optional().describe("list: include deleted comments as tombstones."),
+        },
+    }, async ({ presentation_id, action, comment_id, content, resolve, page_size, page_token, include_deleted }) => {
+        try {
+            return ok(await client.manageComments({
+                presentationId: presentation_id,
+                action,
+                commentId: comment_id,
+                content,
+                resolve,
+                pageSize: page_size,
+                pageToken: page_token,
+                includeDeleted: include_deleted,
+            }));
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+}

package/dist/tools/elements.js

@@ -0,0 +1,164 @@
+import { z } from "zod";
+import { fail, newObjectIdSchema, objectIdSchema, ok, pointsSchema, presentationIdSchema, UPDATE, WRITE, } from "./util.js";
+export function registerElementTools(server, client) {
+    server.registerTool("create_shape", {
+        title: "Create a shape",
+        annotations: WRITE,
+        description: "Creates a shape on a slide (batchUpdate createShape), optionally with its initial text in the same atomic batch. Types: text_box, rectangle, round_rectangle, ellipse, diamond, triangle, right_arrow, left_arrow, up_arrow, down_arrow, star, heart, cloud, callout — the API's other ~130 ShapeTypes go through batch_update. Position/size are in points ((0,0) is top-left; a default 16:9 slide is 720x405 pt); omitted geometry defaults to 300x80 pt at (50,50). Returns the shape's objectId in the reply. Fill/outline/shadow are not parameters here — style via batch_update updateShapeProperties; text styling via update_text_style.",
+        inputSchema: {
+            presentation_id: presentationIdSchema(),
+            page_object_id: objectIdSchema("The slide's object id to place the shape on (from list_slides)."),
+            shape_type: z
+                .enum([
+                "text_box",
+                "rectangle",
+                "round_rectangle",
+                "ellipse",
+                "diamond",
+                "triangle",
+                "right_arrow",
+                "left_arrow",
+                "up_arrow",
+                "down_arrow",
+                "star",
+                "heart",
+                "cloud",
+                "callout",
+            ])
+                .describe("The shape type."),
+            text: z.string().optional().describe("Initial text, inserted in the same atomic batch."),
+            x_pt: pointsSchema().optional().describe("Left edge in points (requires y_pt; default 50)."),
+            y_pt: pointsSchema().optional().describe("Top edge in points (requires x_pt; default 50)."),
+            width_pt: pointsSchema().optional().describe("Width in points (requires height_pt; default 300)."),
+            height_pt: pointsSchema().optional().describe("Height in points (requires width_pt; default 80)."),
+            object_id: newObjectIdSchema()
+                .optional()
+                .describe("Optional custom object id (5-50 chars of [a-zA-Z0-9_-:]); auto-generated when omitted."),
+        },
+    }, async (args) => {
+        try {
+            return ok(await client.createShape({
+                presentationId: args.presentation_id,
+                pageObjectId: args.page_object_id,
+                shapeType: args.shape_type,
+                text: args.text,
+                xPt: args.x_pt,
+                yPt: args.y_pt,
+                widthPt: args.width_pt,
+                heightPt: args.height_pt,
+                objectId: args.object_id,
+            }));
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("create_image", {
+        title: "Insert an image",
+        annotations: WRITE,
+        description: "Inserts an image on a slide (batchUpdate createImage) from EITHER image_url — a public https URL Google's servers can fetch (validated: https-only, no private/local hosts, ≤2 kB; the image itself must be PNG/JPEG/GIF, ≤50 MB, ≤25 megapixels) — OR image_path, a local file that is checked by magic bytes, uploaded to Drive, shared by link for the fetch and DELETED from Drive right after (Slides stores its own copy, so the temp file is disposable; the result reports the cleanup). Omitted size keeps the image's native proportions fitted to the page; position/size are in points. Returns the image objectId in the reply.",
+        inputSchema: {
+            presentation_id: presentationIdSchema(),
+            page_object_id: objectIdSchema("The slide's object id to place the image on (from list_slides)."),
+            image_url: z
+                .string()
+                .url()
+                .optional()
+                .describe("Public https URL of a PNG/JPEG/GIF (exactly one of image_url / image_path)."),
+            image_path: z
+                .string()
+                .min(1)
+                .optional()
+                .describe("Absolute local path of a PNG/JPEG/GIF file (exactly one of image_url / image_path)."),
+            x_pt: pointsSchema().optional().describe("Left edge in points (requires y_pt)."),
+            y_pt: pointsSchema().optional().describe("Top edge in points (requires x_pt)."),
+            width_pt: pointsSchema().optional().describe("Width in points (requires height_pt)."),
+            height_pt: pointsSchema().optional().describe("Height in points (requires width_pt)."),
+            object_id: newObjectIdSchema().optional().describe("Optional custom object id for the new image."),
+        },
+    }, async (args) => {
+        try {
+            return ok(await client.createImage({
+                presentationId: args.presentation_id,
+                pageObjectId: args.page_object_id,
+                imageUrl: args.image_url,
+                imagePath: args.image_path,
+                xPt: args.x_pt,
+                yPt: args.y_pt,
+                widthPt: args.width_pt,
+                heightPt: args.height_pt,
+                objectId: args.object_id,
+            }));
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("replace_image", {
+        title: "Replace an image",
+        annotations: UPDATE,
+        description: "Swaps the bitmap of an existing image element while keeping its frame, position and effects (batchUpdate replaceImage). The new picture comes from image_url or image_path with exactly the same validation/upload/cleanup rules as create_image. replace_method: center_inside (default — scales to fit inside the frame, keeping aspect) or center_crop (fills the frame, cropping the overflow).",
+        inputSchema: {
+            presentation_id: presentationIdSchema(),
+            image_object_id: objectIdSchema("The existing image element's object id (type \"image\" in list_slides)."),
+            image_url: z
+                .string()
+                .url()
+                .optional()
+                .describe("Public https URL of the new PNG/JPEG/GIF (exactly one of image_url / image_path)."),
+            image_path: z
+                .string()
+                .min(1)
+                .optional()
+                .describe("Absolute local path of the new image (exactly one of image_url / image_path)."),
+            replace_method: z
+                .enum(["center_inside", "center_crop"])
+                .optional()
+                .describe("How the new image fills the old frame (default center_inside)."),
+        },
+    }, async ({ presentation_id, image_object_id, image_url, image_path, replace_method }) => {
+        try {
+            return ok(await client.replaceImage({
+                presentationId: presentation_id,
+                imageObjectId: image_object_id,
+                imageUrl: image_url,
+                imagePath: image_path,
+                replaceMethod: replace_method,
+            }));
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("update_transform", {
+        title: "Move / scale an element",
+        annotations: UPDATE,
+        description: "Moves and/or scales a page element (batchUpdate updatePageElementTransform). mode=absolute REPLACES the element's whole transform: translate_x_pt/translate_y_pt become the new top-left-ish origin and omitted scales default to 1 — NOT to the current values, so an absolute move of a scaled element also resets its scale unless you resend it. mode=relative multiplies onto the existing transform: translate shifts by the given points, scale 2 doubles the current size (scaling happens around the origin, which also shifts the element — for a simple move prefer relative translate only). Element geometry to reason from is in get_page.",
+        inputSchema: {
+            presentation_id: presentationIdSchema(),
+            object_id: objectIdSchema("The page element's object id (from list_slides)."),
+            mode: z
+                .enum(["absolute", "relative"])
+                .describe("absolute = replace the whole transform; relative = multiply onto the current one."),
+            translate_x_pt: pointsSchema().optional().describe("Horizontal translation in points (default 0)."),
+            translate_y_pt: pointsSchema().optional().describe("Vertical translation in points (default 0)."),
+            scale_x: z.number().finite().optional().describe("Horizontal scale factor (default 1)."),
+            scale_y: z.number().finite().optional().describe("Vertical scale factor (default 1)."),
+        },
+    }, async ({ presentation_id, object_id, mode, translate_x_pt, translate_y_pt, scale_x, scale_y }) => {
+        try {
+            return ok(await client.updateTransform({
+                presentationId: presentation_id,
+                objectId: object_id,
+                mode,
+                translateXPt: translate_x_pt,
+                translateYPt: translate_y_pt,
+                scaleX: scale_x,
+                scaleY: scale_y,
+            }));
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+}

package/dist/tools/export.js

@@ -0,0 +1,54 @@
+import { z } from "zod";
+import { fail, objectIdSchema, ok, presentationIdSchema, READ_ONLY } from "./util.js";
+export function registerExportTools(server, client) {
+    server.registerTool("get_thumbnail", {
+        title: "Get a slide thumbnail",
+        annotations: READ_ONLY,
+        description: "Renders one page (slide, layout or master) as a PNG. Without output_path it returns contentUrl + width/height — the URL is short-lived (~30 minutes) and served from googleusercontent.com. With output_path the PNG is downloaded and saved to that local file instead (the download is restricted to Google's image hosts). size: large (1600px, default), medium (800px) or small (200px). This is the way to SEE what a slide actually looks like — the JSON never shows rendering. Counts as an expensive read in the API quota.",
+        inputSchema: {
+            presentation_id: presentationIdSchema(),
+            page_object_id: objectIdSchema("The slide's object id to render (from list_slides)."),
+            size: z
+                .enum(["large", "medium", "small"])
+                .optional()
+                .describe("Thumbnail width: large=1600px (default), medium=800px, small=200px."),
+            output_path: z
+                .string()
+                .min(1)
+                .optional()
+                .describe("Local file path to save the PNG to; omitted = return the short-lived contentUrl."),
+        },
+    }, async ({ presentation_id, page_object_id, size, output_path }) => {
+        try {
+            return ok(await client.getThumbnail({
+                presentationId: presentation_id,
+                pageObjectId: page_object_id,
+                size,
+                outputPath: output_path,
+            }));
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("export_presentation", {
+        title: "Export the presentation",
+        annotations: READ_ONLY,
+        description: "Downloads the whole presentation as pdf, pptx, odp or txt (txt = all text incl. speaker notes) and saves it to output_path, overwriting an existing file. Served by the Drive export endpoint internally, which caps exports at 10 MB — a bigger deck fails with an export-size error (split it or use the Slides UI). Requires a Drive scope on the OAuth token (drive.readonly is enough; presentations-only gets a 403). Returns saved_to, bytes and mime_type; nothing in the presentation changes.",
+        inputSchema: {
+            presentation_id: presentationIdSchema(),
+            format: z.enum(["pdf", "pptx", "odp", "txt"]).describe("The export format."),
+            output_path: z
+                .string()
+                .min(1)
+                .describe("Local file path to write, e.g. /tmp/deck.pdf — existing files are overwritten."),
+        },
+    }, async ({ presentation_id, format, output_path }) => {
+        try {
+            return ok(await client.exportPresentation(presentation_id, format, output_path));
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+}

package/dist/tools/notes.js

@@ -0,0 +1,37 @@
+import { z } from "zod";
+import { fail, objectIdSchema, ok, presentationIdSchema, READ_ONLY, UPDATE } from "./util.js";
+export function registerNoteTools(server, client) {
+    server.registerTool("get_speaker_notes", {
+        title: "Get speaker notes",
+        annotations: READ_ONLY,
+        description: "Returns a slide's speaker notes as plain text, plus the speakerNotesObjectId (the text shape on the slide's hidden notes page). The lookup fetches the slide's notes page internally, so you only need the slide's object id from list_slides. An empty string means the slide has no notes yet. Notes text is also searched by replace_text.",
+        inputSchema: {
+            presentation_id: presentationIdSchema(),
+            slide_object_id: objectIdSchema("The slide's object id (from list_slides) — not the notes page id."),
+        },
+    }, async ({ presentation_id, slide_object_id }) => {
+        try {
+            return ok(await client.getSpeakerNotes(presentation_id, slide_object_id));
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("set_speaker_notes", {
+        title: "Set speaker notes",
+        annotations: UPDATE,
+        description: "Replaces a slide's speaker notes with the given text (empty string clears them). The tool resolves the slide's speakerNotesObjectId internally and rewrites that shape atomically — you pass the slide's object id, not the notes shape id. Notes are visible in the presenter view and exported by format txt; use \\n for paragraphs.",
+        inputSchema: {
+            presentation_id: presentationIdSchema(),
+            slide_object_id: objectIdSchema("The slide's object id (from list_slides) — not the notes page id."),
+            text: z.string().describe("The new speaker notes; empty string clears them. \\n starts a new paragraph."),
+        },
+    }, async ({ presentation_id, slide_object_id, text }) => {
+        try {
+            return ok(await client.setSpeakerNotes(presentation_id, slide_object_id, text));
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+}