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

package/dist/tools/presentations.js

@@ -0,0 +1,87 @@
+import { z } from "zod";
+import { DESTRUCTIVE, fail, objectIdSchema, ok, presentationIdSchema, READ_ONLY, WRITE } from "./util.js";
+export function registerPresentationTools(server, client) {
+    server.registerTool("create_presentation", {
+        title: "Create a presentation",
+        annotations: WRITE,
+        description: "Creates a new Google Slides presentation and returns it (presentationId, revisionId, pageSize, the initial title slide with its object ids, layouts and masters). The API honors only the title at creation — add slides with add_slide, content with the text/shape/table/image tools. The new deck starts with one title slide and belongs to the authorized user's Drive. Note: this server cannot delete a presentation; removing the file is a Drive operation outside its scope.",
+        inputSchema: {
+            title: z.string().min(1).describe("The presentation title (also the Drive file name)."),
+        },
+    }, async ({ title }) => {
+        try {
+            return ok(await client.createPresentation(title));
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("get_presentation", {
+        title: "Get a presentation",
+        annotations: READ_ONLY,
+        description: "Returns the raw presentation JSON: slides[] with every page element (shapes, text runs, tables, images), layouts[], masters[], notesMaster, pageSize (EMU: 1 pt = 12700 EMU) and revisionId. WARNING: a full deck is often hundreds of kilobytes — prefer list_slides for an inventory, and pass fields (a Google fields mask, e.g. \"slides(objectId,pageElements(objectId,shape(text)))\") to trim this response when you need raw detail.",
+        inputSchema: {
+            presentation_id: presentationIdSchema(),
+            fields: z
+                .string()
+                .optional()
+                .describe('Optional Google fields mask to trim the response, e.g. "slides(objectId),pageSize".'),
+        },
+    }, async ({ presentation_id, fields }) => {
+        try {
+            return ok(await client.getPresentation(presentation_id, fields));
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("list_slides", {
+        title: "List slides (compact inventory)",
+        annotations: READ_ONLY,
+        description: "Compact inventory of the deck — the read to start from: presentationId, title, revisionId, pageSizePt, slideCount and per slide its 0-based index, objectId, layoutObjectId, speakerNotesObjectId and elements[] with each element's objectId, type (shape type / table RxC / image / video / line / group), placeholder role and visible text (truncated to 160 chars). All mutation tools address these object ids, so call this before editing; per-element geometry and full text need get_presentation or get_page.",
+        inputSchema: { presentation_id: presentationIdSchema() },
+    }, async ({ presentation_id }) => {
+        try {
+            return ok(await client.listSlides(presentation_id));
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("get_page", {
+        title: "Get one page",
+        annotations: READ_ONLY,
+        description: "Returns one page in full by its object id — works for slides, layouts, masters and notes pages alike. For a slide the response includes slideProperties.notesPage (the speaker-notes page) and every pageElement with its size, transform (EMU: 1 pt = 12700 EMU) and complete text. Use it when list_slides' summary is not enough for one page but the whole deck via get_presentation would be too much.",
+        inputSchema: {
+            presentation_id: presentationIdSchema(),
+            page_object_id: objectIdSchema("The page's object id — a slide/layout/master/notes-page id from list_slides or get_presentation."),
+        },
+    }, async ({ presentation_id, page_object_id }) => {
+        try {
+            return ok(await client.getPage(presentation_id, page_object_id));
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("batch_update", {
+        title: "Raw batchUpdate",
+        // Arbitrary requests include deleteObject — annotate for the worst case.
+        annotations: DESTRUCTIVE,
+        description: 'Sends raw Slides API batchUpdate requests for anything the typed tools don\'t cover: updateShapeProperties (fill, outline, shadow), updatePageProperties (slide background), updateParagraphStyle, createParagraphBullets, updateTableCellProperties, mergeTableCells, createVideo, createLine, groupObjects, updateSlideProperties and the rest of the request union. requests is the API\'s requests[] array verbatim, e.g. [{"updateShapeProperties":{"objectId":"...","shapeProperties":{...},"fields":"shapeFill"}}]. The batch is atomic: one invalid request rejects the whole batch and nothing is applied. Lengths/coordinates take {"magnitude":N,"unit":"PT"}; wire enums are UPPER_CASE.',
+        inputSchema: {
+            presentation_id: presentationIdSchema(),
+            requests: z
+                .array(z.record(z.any()))
+                .min(1)
+                .describe("The Slides API batchUpdate requests[] array, verbatim wire format."),
+        },
+    }, async ({ presentation_id, requests }) => {
+        try {
+            return ok(await client.batchUpdate(presentation_id, requests));
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+}

package/dist/tools/raw.js

@@ -0,0 +1,30 @@
+import { z } from "zod";
+import { DESTRUCTIVE, fail, ok } from "./util.js";
+export function registerRawTool(server, client) {
+    server.registerTool("raw_request", {
+        title: "Raw Google Slides API call",
+        // Full API surface incl. arbitrary batchUpdate — annotate for the worst
+        // case a call can do, not the average.
+        annotations: DESTRUCTIVE,
+        description: 'Escape hatch to call any Google Slides API v1 path directly, for requests even batch_update doesn\'t cover — e.g. GET "v1/presentations/<id>/pages/<pageId>" with a custom fields mask in the query string, or a POST with a body shaped differently from the typed tools. The Slides API only has GET and POST endpoints; the path is relative to https://slides.googleapis.com and may carry a query string. The Bearer token is added automatically; a path resolving to a foreign origin is rejected. Drive endpoints (comments, export) are NOT reachable here — use manage_comments / export_presentation.',
+        inputSchema: {
+            path: z
+                .string()
+                .min(1)
+                .describe('API path relative to https://slides.googleapis.com, e.g. "v1/presentations/<id>:batchUpdate".'),
+            method: z
+                .enum(["GET", "POST"])
+                .optional()
+                .describe("HTTP method (the Slides API uses only these two). Defaults to GET."),
+            body: z.record(z.any()).optional().describe("JSON request body (POST only)."),
+        },
+    }, async ({ path, method, body }) => {
+        try {
+            const m = (method ?? "GET");
+            return ok(await client.request(m, path, body));
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+}

package/dist/tools/slides.js

@@ -0,0 +1,117 @@
+import { z } from "zod";
+import { DESTRUCTIVE, fail, indexSchema, newObjectIdSchema, objectIdSchema, ok, presentationIdSchema, READ_ONLY, WRITE, } from "./util.js";
+export function registerSlideTools(server, client) {
+    server.registerTool("add_slide", {
+        title: "Add a slide",
+        annotations: WRITE,
+        description: "Adds a slide (batchUpdate createSlide) and returns the new slide's objectId in the reply. Pick the look with either predefined_layout (BLANK, TITLE, TITLE_AND_BODY, SECTION_HEADER, ...) or layout_object_id from list_layouts — not both; with neither the slide copies the layout of the current last slide. insertion_index is the 0-based position (omitted = append at the end). Placeholders inherited from the layout arrive empty — find their object ids via list_slides, then fill them with set_text.",
+        inputSchema: {
+            presentation_id: presentationIdSchema(),
+            insertion_index: indexSchema()
+                .optional()
+                .describe("0-based position for the new slide; omitted = append at the end."),
+            predefined_layout: z
+                .enum([
+                "BLANK",
+                "CAPTION_ONLY",
+                "TITLE",
+                "TITLE_AND_BODY",
+                "TITLE_AND_TWO_COLUMNS",
+                "TITLE_ONLY",
+                "SECTION_HEADER",
+                "SECTION_TITLE_AND_DESCRIPTION",
+                "ONE_COLUMN_TEXT",
+                "MAIN_POINT",
+                "BIG_NUMBER",
+            ])
+                .optional()
+                .describe("A predefined layout; the theme's actual layouts may support only a subset."),
+            layout_object_id: z
+                .string()
+                .min(1)
+                .optional()
+                .describe("A concrete layout's object id from list_layouts (alternative to predefined_layout)."),
+            object_id: newObjectIdSchema()
+                .optional()
+                .describe("Optional custom object id for the new slide (5-50 chars of [a-zA-Z0-9_-:])."),
+        },
+    }, async ({ presentation_id, insertion_index, predefined_layout, layout_object_id, object_id }) => {
+        try {
+            return ok(await client.addSlide({
+                presentationId: presentation_id,
+                insertionIndex: insertion_index,
+                predefinedLayout: predefined_layout,
+                layoutObjectId: layout_object_id,
+                objectId: object_id,
+            }));
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("duplicate_slide", {
+        title: "Duplicate a slide",
+        annotations: WRITE,
+        description: "Duplicates a slide (batchUpdate duplicateObject) — the copy, with all its elements and speaker notes, lands immediately after the original and its new objectId comes back in the reply. Works on any page element id too (the copy lands on the same slide, slightly offset). Move the copy with move_slides afterwards if needed.",
+        inputSchema: {
+            presentation_id: presentationIdSchema(),
+            slide_object_id: objectIdSchema("The object id of the slide (or page element) to duplicate."),
+        },
+    }, async ({ presentation_id, slide_object_id }) => {
+        try {
+            return ok(await client.duplicateSlide(presentation_id, slide_object_id));
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("move_slides", {
+        title: "Move slides",
+        annotations: WRITE,
+        description: "Moves one or more slides to a new position (batchUpdate updateSlidesPosition). slide_object_ids must appear in their current deck order with no duplicates; insertion_index is the 0-based position BEFORE the move is applied (moving a slide down: index counts with the slide still in its old place). Use list_slides to see the current order first.",
+        inputSchema: {
+            presentation_id: presentationIdSchema(),
+            slide_object_ids: z
+                .array(z.string().min(1))
+                .min(1)
+                .describe("The slides to move, listed in their current presentation order."),
+            insertion_index: indexSchema().describe("0-based target position, evaluated before the slides are removed from their old places."),
+        },
+    }, async ({ presentation_id, slide_object_ids, insertion_index }) => {
+        try {
+            return ok(await client.moveSlides(presentation_id, slide_object_ids, insertion_index));
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("delete_object", {
+        title: "Delete a slide or element",
+        annotations: DESTRUCTIVE,
+        description: "Deletes a slide or a page element (shape, image, table, video, line, group) by object id — batchUpdate deleteObject. Deleting a slide removes all its elements and speaker notes; deleting a group removes its children. There is no undo through the API (version history lives in the Slides UI). It cannot delete the whole presentation — that is a Drive file operation outside this server.",
+        inputSchema: {
+            presentation_id: presentationIdSchema(),
+            object_id: objectIdSchema("The object id of the slide or page element to delete (from list_slides)."),
+        },
+    }, async ({ presentation_id, object_id }) => {
+        try {
+            return ok(await client.deleteObject(presentation_id, object_id));
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("list_layouts", {
+        title: "List layouts and masters",
+        annotations: READ_ONLY,
+        description: "Lists the presentation's theme building blocks: layouts[] (objectId, name like TITLE_AND_BODY, displayName, masterObjectId), masters[] and the notesMasterObjectId. Layout object ids feed add_slide's layout_object_id; the Slides API cannot import a new theme or change the master set — themes are chosen in the UI, this tool only reads what the deck already has.",
+        inputSchema: { presentation_id: presentationIdSchema() },
+    }, async ({ presentation_id }) => {
+        try {
+            return ok(await client.listLayouts(presentation_id));
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+}

package/dist/tools/tables.js

@@ -0,0 +1,87 @@
+import { z } from "zod";
+import { DESTRUCTIVE, fail, indexSchema, newObjectIdSchema, objectIdSchema, ok, pointsSchema, presentationIdSchema, WRITE, } from "./util.js";
+export function registerTableTools(server, client) {
+    server.registerTool("create_table", {
+        title: "Create a table",
+        annotations: WRITE,
+        description: "Creates an empty rows x columns table on a slide (batchUpdate createTable) and returns its objectId in the reply. Fill cells with set_text / insert_text using row_index + column_index (0-based); restructure later with edit_table. Position/size are in points; omitted geometry lets the API pick a centered default. Cell styling (borders, background) goes through batch_update updateTableCellProperties.",
+        inputSchema: {
+            presentation_id: presentationIdSchema(),
+            page_object_id: objectIdSchema("The slide's object id to place the table on (from list_slides)."),
+            rows: z.number().int().min(1).max(20).describe("Row count (the API allows at most 20 rows at creation)."),
+            columns: z
+                .number()
+                .int()
+                .min(1)
+                .max(20)
+                .describe("Column count (the API allows at most 20 columns at creation)."),
+            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 table."),
+        },
+    }, async (args) => {
+        try {
+            return ok(await client.createTable({
+                presentationId: args.presentation_id,
+                pageObjectId: args.page_object_id,
+                rows: args.rows,
+                columns: args.columns,
+                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("edit_table", {
+        title: "Edit table structure",
+        // insert_* only adds, but delete_row/delete_column remove content — the
+        // whole tool carries the worst case's hints.
+        annotations: DESTRUCTIVE,
+        description: "Restructures an existing table in one call. action=insert_rows needs row_index (+optional below, default true, and count 1-20); insert_columns needs column_index (+optional right, default true, and count); delete_row needs row_index and delete_column needs column_index — deletion permanently discards the cells' content, and the remaining rows/columns shift so indexes change between successive edits (re-check with list_slides). Cell TEXT is written with set_text/insert_text (row_index + column_index), not here.",
+        inputSchema: {
+            presentation_id: presentationIdSchema(),
+            table_object_id: objectIdSchema('The table\'s object id (type "table" in list_slides).'),
+            action: z
+                .enum(["insert_rows", "insert_columns", "delete_row", "delete_column"])
+                .describe("The structural edit to apply."),
+            row_index: indexSchema()
+                .optional()
+                .describe("Reference row, 0-based (insert_rows / delete_row)."),
+            column_index: indexSchema()
+                .optional()
+                .describe("Reference column, 0-based (insert_columns / delete_column)."),
+            count: z.number().int().min(1).max(20).optional().describe("How many rows/columns to insert (default 1)."),
+            below: z
+                .boolean()
+                .optional()
+                .describe("insert_rows: insert below the reference row (default true; false = above)."),
+            right: z
+                .boolean()
+                .optional()
+                .describe("insert_columns: insert to the right of the reference column (default true; false = left)."),
+        },
+    }, async ({ presentation_id, table_object_id, action, row_index, column_index, count, below, right }) => {
+        try {
+            return ok(await client.editTable({
+                presentationId: presentation_id,
+                tableObjectId: table_object_id,
+                action,
+                rowIndex: row_index,
+                columnIndex: column_index,
+                count,
+                below,
+                right,
+            }));
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+}

package/dist/tools/text.js

@@ -0,0 +1,129 @@
+import { z } from "zod";
+import { fail, hexColorSchema, indexSchema, objectIdSchema, ok, presentationIdSchema, UPDATE, WRITE, } from "./util.js";
+export function registerTextTools(server, client) {
+    server.registerTool("insert_text", {
+        title: "Insert text",
+        annotations: WRITE,
+        description: "Inserts text into a shape or a table cell (batchUpdate insertText) at a 0-based character index (default 0 = the beginning). For a table cell pass row_index + column_index together. Text carries \\n for new paragraphs; the target must be a shape that can hold text or a table — images and lines cannot. To REPLACE what's already there use set_text instead; to fill an empty layout placeholder this works directly (find its object id via list_slides).",
+        inputSchema: {
+            presentation_id: presentationIdSchema(),
+            object_id: objectIdSchema("The shape or table object id (from list_slides)."),
+            text: z.string().min(1).describe("The text to insert; use \\n for paragraph breaks."),
+            insertion_index: indexSchema()
+                .optional()
+                .describe("0-based character index to insert at (default 0 — the start of the existing text)."),
+            row_index: indexSchema().optional().describe("Table cell row (0-based; requires column_index)."),
+            column_index: indexSchema().optional().describe("Table cell column (0-based; requires row_index)."),
+        },
+    }, async ({ presentation_id, object_id, text, insertion_index, row_index, column_index }) => {
+        try {
+            return ok(await client.insertText({
+                presentationId: presentation_id,
+                objectId: object_id,
+                text,
+                insertionIndex: insertion_index,
+                rowIndex: row_index,
+                columnIndex: column_index,
+            }));
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("set_text", {
+        title: "Set (replace) text",
+        annotations: UPDATE,
+        description: "Replaces the ENTIRE text of a shape or table cell: one atomic batch of deleteText(ALL) + insertText. If the target has no text yet the delete is skipped automatically, so it works on empty placeholders too. An empty text just clears the object. Replacing text drops per-character styling — restyle with update_text_style afterwards if needed. For a table cell pass row_index + column_index together.",
+        inputSchema: {
+            presentation_id: presentationIdSchema(),
+            object_id: objectIdSchema("The shape or table object id (from list_slides)."),
+            text: z.string().describe("The new full text; empty string clears the object. \\n starts a new paragraph."),
+            row_index: indexSchema().optional().describe("Table cell row (0-based; requires column_index)."),
+            column_index: indexSchema().optional().describe("Table cell column (0-based; requires row_index)."),
+        },
+    }, async ({ presentation_id, object_id, text, row_index, column_index }) => {
+        try {
+            return ok(await client.setText({
+                presentationId: presentation_id,
+                objectId: object_id,
+                text,
+                rowIndex: row_index,
+                columnIndex: column_index,
+            }));
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("replace_text", {
+        title: "Find & replace text",
+        annotations: UPDATE,
+        description: "Finds and replaces every occurrence of a string across the whole deck — shapes and table cells on slides, and their speaker notes (batchUpdate replaceAllText). Scope it with page_object_ids to touch only specific slides. Matching is literal (no regex), case-sensitive by default (match_case=false to ignore case). Returns occurrencesChanged in the reply — 0 means nothing matched, check the exact wording with list_slides. The classic template flow: duplicate a template deck, then replace {{placeholders}}.",
+        inputSchema: {
+            presentation_id: presentationIdSchema(),
+            find: z.string().min(1).describe("The literal text to find (no regex)."),
+            replace: z.string().describe("The replacement text (empty string deletes the matches)."),
+            match_case: z.boolean().optional().describe("Case-sensitive matching (default true)."),
+            page_object_ids: z
+                .array(z.string().min(1))
+                .optional()
+                .describe("Limit the replacement to these slides/pages (default: the whole presentation)."),
+        },
+    }, async ({ presentation_id, find, replace, match_case, page_object_ids }) => {
+        try {
+            return ok(await client.replaceText({
+                presentationId: presentation_id,
+                find,
+                replace,
+                matchCase: match_case,
+                pageObjectIds: page_object_ids,
+            }));
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("update_text_style", {
+        title: "Style text",
+        annotations: UPDATE,
+        description: "Styles the text of a shape or table cell (batchUpdate updateTextStyle): bold, italic, underline, strikethrough, font_family (e.g. \"Roboto\"), font_size_pt, foreground_color (#RRGGBB) and link_url. Only the provided fields change (the field mask is computed automatically); at least one is required. By default the whole text is styled; pass start_index + end_index (0-based character offsets, end exclusive) to style a range — get the offsets from get_page's textElements. For a table cell add row_index + column_index.",
+        inputSchema: {
+            presentation_id: presentationIdSchema(),
+            object_id: objectIdSchema("The shape or table object id whose text to style."),
+            bold: z.boolean().optional().describe("Bold on/off."),
+            italic: z.boolean().optional().describe("Italic on/off."),
+            underline: z.boolean().optional().describe("Underline on/off."),
+            strikethrough: z.boolean().optional().describe("Strikethrough on/off."),
+            font_family: z.string().min(1).optional().describe('Font family, e.g. "Roboto" or "Playfair Display".'),
+            font_size_pt: z.number().positive().optional().describe("Font size in points."),
+            foreground_color: hexColorSchema().optional().describe("Text color as #RRGGBB."),
+            link_url: z.string().url().optional().describe("Turns the styled range into a hyperlink."),
+            start_index: indexSchema().optional().describe("Range start, 0-based character offset (requires end_index)."),
+            end_index: indexSchema().optional().describe("Range end, exclusive (requires start_index)."),
+            row_index: indexSchema().optional().describe("Table cell row (0-based; requires column_index)."),
+            column_index: indexSchema().optional().describe("Table cell column (0-based; requires row_index)."),
+        },
+    }, async (args) => {
+        try {
+            return ok(await client.updateTextStyle({
+                presentationId: args.presentation_id,
+                objectId: args.object_id,
+                bold: args.bold,
+                italic: args.italic,
+                underline: args.underline,
+                strikethrough: args.strikethrough,
+                fontFamily: args.font_family,
+                fontSizePt: args.font_size_pt,
+                foregroundColor: args.foreground_color,
+                linkUrl: args.link_url,
+                startIndex: args.start_index,
+                endIndex: args.end_index,
+                rowIndex: args.row_index,
+                columnIndex: args.column_index,
+            }));
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+}

package/dist/tools/util.js

@@ -0,0 +1,73 @@
+import { z } from "zod";
+/**
+ * Schema factories, not shared consts: reusing one zod object across two fields
+ * makes zod-to-json-schema dedupe them into a `$ref`, which some tool-schema
+ * consumers (OpenAI Apps review) don't dereference and flag as `any`. A fresh
+ * object per field keeps each one inlined with its type + pattern.
+ */
+export const presentationIdSchema = () => z
+    .string()
+    .min(1)
+    .describe("The presentation id — the long id from the URL (docs.google.com/presentation/d/<presentationId>/edit) or from create_presentation output.");
+/** An existing object id (slide, page element, table, ...) as returned by get_presentation/list_slides. */
+export const objectIdSchema = (what) => z.string().min(1).describe(what);
+/**
+ * A caller-chosen id for a new object. The API's contract: 5-50 chars of
+ * [a-zA-Z0-9_-:], not starting with '-' or ':'.
+ */
+export const newObjectIdSchema = () => z
+    .string()
+    .regex(/^[A-Za-z0-9_][A-Za-z0-9_:-]{4,49}$/, "5-50 chars of [a-zA-Z0-9_-:], not starting with - or :");
+/** A 0-based index (slide position, table row/column, text insertion point). */
+export const indexSchema = () => z.number().int().min(0);
+/** A length/coordinate in points (PT). 1 pt = 12700 EMU; a default slide is 720x405 pt. */
+export const pointsSchema = () => z.number().finite();
+/** A hex RGB color like #FF8800 (the leading # is optional). */
+export const hexColorSchema = () => z.string().regex(/^#?[0-9a-fA-F]{6}$/, "Must be a hex RGB color like #FF8800");
+/** Wraps a value as a compact-JSON tool result (compact: the consumer is an LLM). */
+export function ok(data) {
+    const text = typeof data === "string" ? data : JSON.stringify(data);
+    return { content: [{ type: "text", text: text ?? "null" }] };
+}
+export function fail(err) {
+    let message = err instanceof Error ? err.message : String(err);
+    // Surface the underlying cause (e.g. the network error behind a timeout) — no
+    // secrets live in cause, and it makes failures far easier to diagnose.
+    if (err instanceof Error && err.cause instanceof Error)
+        message += ` (${err.cause.message})`;
+    return { content: [{ type: "text", text: `Error: ${message}` }], isError: true };
+}
+/**
+ * MCP tool annotations — hints the consuming client can use to gate or label a
+ * tool. All four hints are set explicitly on every tool: some clients (OpenAI
+ * Apps review) require readOnlyHint, destructiveHint and openWorldHint on each.
+ *
+ * The Slides API mixes reads and writes, so each tool picks one of four presets:
+ * READ_ONLY (pure reads), WRITE (creates new state; replaying duplicates it),
+ * UPDATE (overwrites existing fields; replaying the same update converges) and
+ * DESTRUCTIVE (removes existing state; replaying hits different targets).
+ */
+export const READ_ONLY = {
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: true,
+};
+export const WRITE = {
+    readOnlyHint: false,
+    destructiveHint: false,
+    idempotentHint: false,
+    openWorldHint: true,
+};
+export const UPDATE = {
+    readOnlyHint: false,
+    destructiveHint: true,
+    idempotentHint: true,
+    openWorldHint: true,
+};
+export const DESTRUCTIVE = {
+    readOnlyHint: false,
+    destructiveHint: true,
+    idempotentHint: false,
+    openWorldHint: true,
+};

package/dist/types.js

@@ -0,0 +1,47 @@
+/**
+ * The server talks to the Google Slides API v1 (https://slides.googleapis.com,
+ * REST over JSON). Comments, export and local-image upload need the Google
+ * Drive API v3 (https://www.googleapis.com) as an internal dependency — those
+ * endpoints are never exposed as generic Drive tools. Auth is Google OAuth
+ * 2.0: a Bearer access token, minted on demand from a refresh token via
+ * https://oauth2.googleapis.com/token (or a static short-lived access token,
+ * mostly for testing).
+ */
+/**
+ * Google APIs report failures as a non-2xx HTTP status with a JSON envelope
+ * ({ error: { code, message, status, details } }); the OAuth token endpoint
+ * uses { error, error_description }. The parsed body is kept alongside the
+ * status and a short readable message is derived.
+ */
+export class GoogleSlidesError extends Error {
+    status;
+    body;
+    constructor(status, body) {
+        super(`HTTP ${status}: ${formatErrorBody(body)}`);
+        this.name = "GoogleSlidesError";
+        this.status = status;
+        this.body = body;
+    }
+}
+/** Turns a parsed Google API error body into a short, readable message. */
+function formatErrorBody(body) {
+    if (body == null)
+        return "(no body)";
+    if (typeof body === "string")
+        return body.slice(0, 500);
+    if (typeof body !== "object")
+        return String(body);
+    const obj = body;
+    // OAuth token endpoint style: { error: "invalid_grant", error_description: "..." }
+    if (typeof obj.error === "string") {
+        const description = typeof obj.error_description === "string" ? `: ${obj.error_description}` : "";
+        return `${obj.error}${description}`.slice(0, 500);
+    }
+    // Google API envelope: { error: { code, message, status, details } }
+    const err = (typeof obj.error === "object" && obj.error !== null ? obj.error : obj);
+    if (typeof err.message === "string") {
+        const status = typeof err.status === "string" ? `[${err.status}] ` : "";
+        return `${status}${err.message}`.slice(0, 500);
+    }
+    return JSON.stringify(obj).slice(0, 500);
+}

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "@a1-x-tech/mcp-google-slides",
+  "version": "0.1.0",
+  "description": "MCP server for the Google Slides API — create and edit presentations, slides, text, shapes, tables and images, manage speaker notes, comments, thumbnails and export. For Claude, Cursor, Codex and other AI clients.",
+  "mcpName": "io.github.A1-x-Tech/mcp-google-slides",
+  "type": "module",
+  "bin": {
+    "mcp-google-slides": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "test"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "rm -rf dist && tsc",
+    "start": "node dist/index.js",
+    "dev": "tsx watch src/index.ts",
+    "typecheck": "tsc -p tsconfig.check.json",
+    "smoke": "node --import tsx src/smoke.ts",
+    "test": "npm run test:src && npm run test:dist",
+    "test:src": "node --import tsx --test $(find src -name '*.test.ts')",
+    "test:dist": "npm run build && node --test test/dist-smoke.test.js",
+    "prepare": "npm run build",
+    "prepublishOnly": "npm run typecheck && npm test"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "google",
+    "google-slides",
+    "slides",
+    "presentations",
+    "claude",
+    "cursor",
+    "codex"
+  ],
+  "license": "MIT",
+  "author": "gistrec <gistrec@gmail.com>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/A1-x-Tech/mcp-google-slides.git"
+  },
+  "homepage": "https://github.com/A1-x-Tech/mcp-google-slides#readme",
+  "bugs": {
+    "url": "https://github.com/A1-x-Tech/mcp-google-slides/issues"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "zod": "^3.25.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.9.3",
+    "tsx": "^4.22.4",
+    "typescript": "^5.7.0"
+  }
+}