@jaingxyz/personal-gmail-mcp 0.1.0

package/dist/server.js

@@ -0,0 +1,136 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Copyright (C) 2026 jaingxyz
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import { config } from "./config.js";
+import { getMe } from "./google.js";
+import { listLabels, listLabelsSchema, listRecent, listRecentSchema, read, readSchema, search, searchSchema, } from "./tools/read.js";
+import { deleteMessage, deleteSchema, markRead, markReadSchema, modifyLabels, modifyLabelsSchema, untrash, untrashSchema, } from "./tools/mutate.js";
+import { createDraft, createDraftSchema, reply, replySchema, send, sendSchema, sendDraft, sendDraftSchema, } from "./tools/send.js";
+import { cancelEvent, cancelEventSchema, createEvent, createEventSchema, listCalendars, listCalendarsSchema, listEvents, listEventsSchema, readEvent, readEventSchema, respondSchema, respondToInvite, updateEvent, updateEventSchema, } from "./tools/calendar.js";
+const PAGINATION_NOTE = "Returns up to `limit` (max 100) plus a `nextCursor`; pass it back as `cursor` to page through more.";
+export function buildServer() {
+    const server = new McpServer({
+        name: "personal-gmail-mcp",
+        version: config.version,
+    });
+    server.registerTool("gmail_whoami", {
+        title: "Signed-in Gmail account",
+        description: "Return the signed-in Google account's Gmail profile (email address, message/thread totals).",
+        inputSchema: z.object({}).shape,
+    }, async () => toolResult(await getMe()));
+    server.registerTool("gmail_list_labels", {
+        title: "List labels",
+        description: "List the mailbox's labels (system labels like INBOX/SENT/TRASH and custom labels) with id, name, type, and unread/total counts.",
+        inputSchema: listLabelsSchema.shape,
+    }, async (args) => toolResult(await listLabels(args)));
+    server.registerTool("gmail_list_recent", {
+        title: "Recent messages in a label",
+        description: `List the most recent messages carrying a label, newest first. Defaults to INBOX. Supports unreadOnly. ${PAGINATION_NOTE}`,
+        inputSchema: listRecentSchema.shape,
+    }, async (args) => toolResult(await listRecent(args)));
+    server.registerTool("gmail_search", {
+        title: "Search mail",
+        description: `Search messages with Gmail query syntax (from:, subject:, has:attachment, newer_than:7d, is:unread, etc.). ${PAGINATION_NOTE}`,
+        inputSchema: searchSchema.shape,
+    }, async (args) => toolResult(await search(args)));
+    server.registerTool("gmail_read", {
+        title: "Read message",
+        description: "Fetch a single message by id, including its decoded body (text preferred, html fallback) and threading headers.",
+        inputSchema: readSchema.shape,
+    }, async (args) => toolResult(await read(args)));
+    server.registerTool("gmail_mark_read", {
+        title: "Mark message read/unread",
+        description: "Mark a message read (remove UNREAD) or unread (add UNREAD). Pass isRead=false to mark unread.",
+        inputSchema: markReadSchema.shape,
+        annotations: { destructiveHint: false, idempotentHint: true },
+    }, async (args) => toolResult(await markRead(args)));
+    server.registerTool("gmail_modify_labels", {
+        title: "Add/remove labels",
+        description: "Add or remove labels on a message. Removing INBOX archives the message; adding STARRED stars it. Use gmail_list_labels for ids.",
+        inputSchema: modifyLabelsSchema.shape,
+        annotations: { destructiveHint: false },
+    }, async (args) => toolResult(await modifyLabels(args)));
+    server.registerTool("gmail_delete", {
+        title: "Delete message",
+        description: "Delete a message. By default moves to Trash (recoverable). Pass hardDelete=true to permanently delete — not recoverable.",
+        inputSchema: deleteSchema.shape,
+        annotations: { destructiveHint: true },
+    }, async (args) => toolResult(await deleteMessage(args)));
+    server.registerTool("gmail_untrash", {
+        title: "Restore from Trash",
+        description: "Restore a message from Trash back to the mailbox.",
+        inputSchema: untrashSchema.shape,
+        annotations: { destructiveHint: false },
+    }, async (args) => toolResult(await untrash(args)));
+    server.registerTool("gmail_send", {
+        title: "Send email",
+        description: "Send a new email immediately. Saved to Sent. Use gmail_create_draft to review before sending.",
+        inputSchema: sendSchema.shape,
+        annotations: { destructiveHint: true },
+    }, async (args) => toolResult(await send(args)));
+    server.registerTool("gmail_reply", {
+        title: "Reply to message",
+        description: "Reply to a message by id, keeping it in the same thread. Sends immediately. replyAll=true to include all original recipients.",
+        inputSchema: replySchema.shape,
+        annotations: { destructiveHint: true },
+    }, async (args) => toolResult(await reply(args)));
+    server.registerTool("gmail_create_draft", {
+        title: "Create draft",
+        description: "Create a draft without sending. Returns a draftId for gmail_send_draft.",
+        inputSchema: createDraftSchema.shape,
+    }, async (args) => toolResult(await createDraft(args)));
+    server.registerTool("gmail_send_draft", {
+        title: "Send draft",
+        description: "Send a previously created draft by id.",
+        inputSchema: sendDraftSchema.shape,
+        annotations: { destructiveHint: true },
+    }, async (args) => toolResult(await sendDraft(args)));
+    // ---------- Calendar ----------
+    server.registerTool("gmail_calendar_list_calendars", {
+        title: "List calendars",
+        description: "List the user's calendars (primary + subscribed) with id, name, default flag, and whether they're editable.",
+        inputSchema: listCalendarsSchema.shape,
+    }, async (args) => toolResult(await listCalendars(args)));
+    server.registerTool("gmail_calendar_list_events", {
+        title: "List events in range",
+        description: "List events in a time range. Recurring series are expanded into individual instances, ordered by start time. Defaults to the primary calendar.",
+        inputSchema: listEventsSchema.shape,
+    }, async (args) => toolResult(await listEvents(args)));
+    server.registerTool("gmail_calendar_read_event", {
+        title: "Read event",
+        description: "Read full details of a single event including description, attendees, and recurrence.",
+        inputSchema: readEventSchema.shape,
+    }, async (args) => toolResult(await readEvent(args)));
+    server.registerTool("gmail_calendar_create_event", {
+        title: "Create event",
+        description: "Create an event. Times use {dateTime, timeZone} where dateTime is local-form (no offset) and timeZone is an IANA name. If attendees are provided, invites are sent. isOnlineMeeting attaches a Google Meet link.",
+        inputSchema: createEventSchema.shape,
+        annotations: { destructiveHint: true },
+    }, async (args) => toolResult(await createEvent(args)));
+    server.registerTool("gmail_calendar_update_event", {
+        title: "Update event",
+        description: "Update an event's subject, time, location, description, or attendees. Works on single instances of a recurring series (each instance has its own id).",
+        inputSchema: updateEventSchema.shape,
+        annotations: { destructiveHint: true },
+    }, async (args) => toolResult(await updateEvent(args)));
+    server.registerTool("gmail_calendar_cancel_event", {
+        title: "Cancel/delete event",
+        description: "Delete an event. If you organize it and sendUpdates=all (default), attendees receive a cancellation. Use sendUpdates=none for solo events.",
+        inputSchema: cancelEventSchema.shape,
+        annotations: { destructiveHint: true },
+    }, async (args) => toolResult(await cancelEvent(args)));
+    server.registerTool("gmail_calendar_respond_to_invite", {
+        title: "Respond to invite",
+        description: "Respond to a meeting invite as accept, tentativelyAccept, or decline. Optionally include a comment and choose whether to notify the organizer.",
+        inputSchema: respondSchema.shape,
+        annotations: { destructiveHint: true },
+    }, async (args) => toolResult(await respondToInvite(args)));
+    return server;
+}
+function toolResult(payload) {
+    return {
+        content: [{ type: "text", text: JSON.stringify(payload, null, 2) }],
+    };
+}
+//# sourceMappingURL=server.js.map

package/dist/server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.js","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA,6CAA6C;AAC7C,8BAA8B;AAC9B,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACpE,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,OAAO,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AACpC,OAAO,EACL,UAAU,EACV,gBAAgB,EAChB,UAAU,EACV,gBAAgB,EAChB,IAAI,EACJ,UAAU,EACV,MAAM,EACN,YAAY,GACb,MAAM,iBAAiB,CAAC;AACzB,OAAO,EACL,aAAa,EACb,YAAY,EACZ,QAAQ,EACR,cAAc,EACd,YAAY,EACZ,kBAAkB,EAClB,OAAO,EACP,aAAa,GACd,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACL,WAAW,EACX,iBAAiB,EACjB,KAAK,EACL,WAAW,EACX,IAAI,EACJ,UAAU,EACV,SAAS,EACT,eAAe,GAChB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EACL,WAAW,EACX,iBAAiB,EACjB,WAAW,EACX,iBAAiB,EACjB,aAAa,EACb,mBAAmB,EACnB,UAAU,EACV,gBAAgB,EAChB,SAAS,EACT,eAAe,EACf,aAAa,EACb,eAAe,EACf,WAAW,EACX,iBAAiB,GAClB,MAAM,qBAAqB,CAAC;AAE7B,MAAM,eAAe,GACnB,qGAAqG,CAAC;AAExG,MAAM,UAAU,WAAW;IACzB,MAAM,MAAM,GAAG,IAAI,SAAS,CAAC;QAC3B,IAAI,EAAE,oBAAoB;QAC1B,OAAO,EAAE,MAAM,CAAC,OAAO;KACxB,CAAC,CAAC;IAEH,MAAM,CAAC,YAAY,CACjB,cAAc,EACd;QACE,KAAK,EAAE,yBAAyB;QAChC,WAAW,EACT,6FAA6F;QAC/F,WAAW,EAAE,CAAC,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,KAAK;KAChC,EACD,KAAK,IAAI,EAAE,CAAC,UAAU,CAAC,MAAM,KAAK,EAAE,CAAC,CACtC,CAAC;IAEF,MAAM,CAAC,YAAY,CACjB,mBAAmB,EACnB;QACE,KAAK,EAAE,aAAa;QACpB,WAAW,EACT,iIAAiI;QACnI,WAAW,EAAE,gBAAgB,CAAC,KAAK;KACpC,EACD,KAAK,EAAE,IAAI,EAAE,EAAE,CAAC,UAAU,CAAC,MAAM,UAAU,CAAC,IAAI,CAAC,CAAC,CACnD,CAAC;IAEF,MAAM,CAAC,YAAY,CACjB,mBAAmB,EACnB;QACE,KAAK,EAAE,4BAA4B;QACnC,WAAW,EAAE,yGAAyG,eAAe,EAAE;QACvI,WAAW,EAAE,gBAAgB,CAAC,KAAK;KACpC,EACD,KAAK,EAAE,IAAI,EAAE,EAAE,CAAC,UAAU,CAAC,MAAM,UAAU,CAAC,IAAI,CAAC,CAAC,CACnD,CAAC;IAEF,MAAM,CAAC,YAAY,CACjB,cAAc,EACd;QACE,KAAK,EAAE,aAAa;QACpB,WAAW,EAAE,8GAA8G,eAAe,EAAE;QAC5I,WAAW,EAAE,YAAY,CAAC,KAAK;KAChC,EACD,KAAK,EAAE,IAAI,EAAE,EAAE,CAAC,UAAU,CAAC,MAAM,MAAM,CAAC,IAAI,CAAC,CAAC,CAC/C,CAAC;IAEF,MAAM,CAAC,YAAY,CACjB,YAAY,EACZ;QACE,KAAK,EAAE,cAAc;QACrB,WAAW,EACT,iHAAiH;QACnH,WAAW,EAAE,UAAU,CAAC,KAAK;KAC9B,EACD,KAAK,EAAE,IAAI,EAAE,EAAE,CAAC,UAAU,CAAC,MAAM,IAAI,CAAC,IAAI,CAAC,CAAC,CAC7C,CAAC;IAEF,MAAM,CAAC,YAAY,CACjB,iBAAiB,EACjB;QACE,KAAK,EAAE,0BAA0B;QACjC,WAAW,EACT,+FAA+F;QACjG,WAAW,EAAE,cAAc,CAAC,KAAK;QACjC,WAAW,EAAE,EAAE,eAAe,EAAE,KAAK,EAAE,cAAc,EAAE,IAAI,EAAE;KAC9D,EACD,KAAK,EAAE,IAAI,EAAE,EAAE,CAAC,UAAU,CAAC,MAAM,QAAQ,CAAC,IAAI,CAAC,CAAC,CACjD,CAAC;IAEF,MAAM,CAAC,YAAY,CACjB,qBAAqB,EACrB;QACE,KAAK,EAAE,mBAAmB;QAC1B,WAAW,EACT,iIAAiI;QACnI,WAAW,EAAE,kBAAkB,CAAC,KAAK;QACrC,WAAW,EAAE,EAAE,eAAe,EAAE,KAAK,EAAE;KACxC,EACD,KAAK,EAAE,IAAI,EAAE,EAAE,CAAC,UAAU,CAAC,MAAM,YAAY,CAAC,IAAI,CAAC,CAAC,CACrD,CAAC;IAEF,MAAM,CAAC,YAAY,CACjB,cAAc,EACd;QACE,KAAK,EAAE,gBAAgB;QACvB,WAAW,EACT,0HAA0H;QAC5H,WAAW,EAAE,YAAY,CAAC,KAAK;QAC/B,WAAW,EAAE,EAAE,eAAe,EAAE,IAAI,EAAE;KACvC,EACD,KAAK,EAAE,IAAI,EAAE,EAAE,CAAC,UAAU,CAAC,MAAM,aAAa,CAAC,IAAI,CAAC,CAAC,CACtD,CAAC;IAEF,MAAM,CAAC,YAAY,CACjB,eAAe,EACf;QACE,KAAK,EAAE,oBAAoB;QAC3B,WAAW,EAAE,mDAAmD;QAChE,WAAW,EAAE,aAAa,CAAC,KAAK;QAChC,WAAW,EAAE,EAAE,eAAe,EAAE,KAAK,EAAE;KACxC,EACD,KAAK,EAAE,IAAI,EAAE,EAAE,CAAC,UAAU,CAAC,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC,CAChD,CAAC;IAEF,MAAM,CAAC,YAAY,CACjB,YAAY,EACZ;QACE,KAAK,EAAE,YAAY;QACnB,WAAW,EACT,+FAA+F;QACjG,WAAW,EAAE,UAAU,CAAC,KAAK;QAC7B,WAAW,EAAE,EAAE,eAAe,EAAE,IAAI,EAAE;KACvC,EACD,KAAK,EAAE,IAAI,EAAE,EAAE,CAAC,UAAU,CAAC,MAAM,IAAI,CAAC,IAAI,CAAC,CAAC,CAC7C,CAAC;IAEF,MAAM,CAAC,YAAY,CACjB,aAAa,EACb;QACE,KAAK,EAAE,kBAAkB;QACzB,WAAW,EACT,+HAA+H;QACjI,WAAW,EAAE,WAAW,CAAC,KAAK;QAC9B,WAAW,EAAE,EAAE,eAAe,EAAE,IAAI,EAAE;KACvC,EACD,KAAK,EAAE,IAAI,EAAE,EAAE,CAAC,UAAU,CAAC,MAAM,KAAK,CAAC,IAAI,CAAC,CAAC,CAC9C,CAAC;IAEF,MAAM,CAAC,YAAY,CACjB,oBAAoB,EACpB;QACE,KAAK,EAAE,cAAc;QACrB,WAAW,EACT,yEAAyE;QAC3E,WAAW,EAAE,iBAAiB,CAAC,KAAK;KACrC,EACD,KAAK,EAAE,IAAI,EAAE,EAAE,CAAC,UAAU,CAAC,MAAM,WAAW,CAAC,IAAI,CAAC,CAAC,CACpD,CAAC;IAEF,MAAM,CAAC,YAAY,CACjB,kBAAkB,EAClB;QACE,KAAK,EAAE,YAAY;QACnB,WAAW,EAAE,wCAAwC;QACrD,WAAW,EAAE,eAAe,CAAC,KAAK;QAClC,WAAW,EAAE,EAAE,eAAe,EAAE,IAAI,EAAE;KACvC,EACD,KAAK,EAAE,IAAI,EAAE,EAAE,CAAC,UAAU,CAAC,MAAM,SAAS,CAAC,IAAI,CAAC,CAAC,CAClD,CAAC;IAEF,iCAAiC;IAEjC,MAAM,CAAC,YAAY,CACjB,+BAA+B,EAC/B;QACE,KAAK,EAAE,gBAAgB;QACvB,WAAW,EACT,6GAA6G;QAC/G,WAAW,EAAE,mBAAmB,CAAC,KAAK;KACvC,EACD,KAAK,EAAE,IAAI,EAAE,EAAE,CAAC,UAAU,CAAC,MAAM,aAAa,CAAC,IAAI,CAAC,CAAC,CACtD,CAAC;IAEF,MAAM,CAAC,YAAY,CACjB,4BAA4B,EAC5B;QACE,KAAK,EAAE,sBAAsB;QAC7B,WAAW,EACT,gJAAgJ;QAClJ,WAAW,EAAE,gBAAgB,CAAC,KAAK;KACpC,EACD,KAAK,EAAE,IAAI,EAAE,EAAE,CAAC,UAAU,CAAC,MAAM,UAAU,CAAC,IAAI,CAAC,CAAC,CACnD,CAAC;IAEF,MAAM,CAAC,YAAY,CACjB,2BAA2B,EAC3B;QACE,KAAK,EAAE,YAAY;QACnB,WAAW,EACT,uFAAuF;QACzF,WAAW,EAAE,eAAe,CAAC,KAAK;KACnC,EACD,KAAK,EAAE,IAAI,EAAE,EAAE,CAAC,UAAU,CAAC,MAAM,SAAS,CAAC,IAAI,CAAC,CAAC,CAClD,CAAC;IAEF,MAAM,CAAC,YAAY,CACjB,6BAA6B,EAC7B;QACE,KAAK,EAAE,cAAc;QACrB,WAAW,EACT,kNAAkN;QACpN,WAAW,EAAE,iBAAiB,CAAC,KAAK;QACpC,WAAW,EAAE,EAAE,eAAe,EAAE,IAAI,EAAE;KACvC,EACD,KAAK,EAAE,IAAI,EAAE,EAAE,CAAC,UAAU,CAAC,MAAM,WAAW,CAAC,IAAI,CAAC,CAAC,CACpD,CAAC;IAEF,MAAM,CAAC,YAAY,CACjB,6BAA6B,EAC7B;QACE,KAAK,EAAE,cAAc;QACrB,WAAW,EACT,uJAAuJ;QACzJ,WAAW,EAAE,iBAAiB,CAAC,KAAK;QACpC,WAAW,EAAE,EAAE,eAAe,EAAE,IAAI,EAAE;KACvC,EACD,KAAK,EAAE,IAAI,EAAE,EAAE,CAAC,UAAU,CAAC,MAAM,WAAW,CAAC,IAAI,CAAC,CAAC,CACpD,CAAC;IAEF,MAAM,CAAC,YAAY,CACjB,6BAA6B,EAC7B;QACE,KAAK,EAAE,qBAAqB;QAC5B,WAAW,EACT,4IAA4I;QAC9I,WAAW,EAAE,iBAAiB,CAAC,KAAK;QACpC,WAAW,EAAE,EAAE,eAAe,EAAE,IAAI,EAAE;KACvC,EACD,KAAK,EAAE,IAAI,EAAE,EAAE,CAAC,UAAU,CAAC,MAAM,WAAW,CAAC,IAAI,CAAC,CAAC,CACpD,CAAC;IAEF,MAAM,CAAC,YAAY,CACjB,kCAAkC,EAClC;QACE,KAAK,EAAE,mBAAmB;QAC1B,WAAW,EACT,gJAAgJ;QAClJ,WAAW,EAAE,aAAa,CAAC,KAAK;QAChC,WAAW,EAAE,EAAE,eAAe,EAAE,IAAI,EAAE;KACvC,EACD,KAAK,EAAE,IAAI,EAAE,EAAE,CAAC,UAAU,CAAC,MAAM,eAAe,CAAC,IAAI,CAAC,CAAC,CACxD,CAAC;IAEF,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,SAAS,UAAU,CAAC,OAAgB;IAGlC,OAAO;QACL,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,CAAC;KACpE,CAAC;AACJ,CAAC"}

package/dist/tools/calendar.js

@@ -0,0 +1,296 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Copyright (C) 2026 jaingxyz
+import { z } from "zod";
+import { calendarClient } from "../google.js";
+import { config } from "../config.js";
+// Google Calendar event times: { dateTime, timeZone } where dateTime is
+// RFC-3339 local form (no offset) when timeZone is supplied, OR { date } for
+// all-day. We mirror the Outlook tool's input shape; a separate timeZone field
+// keeps callers from having to bake offsets into the string.
+const dateTimeWithTz = z.object({
+    dateTime: z
+        .string()
+        .min(1)
+        .describe("Local date-time, no offset, e.g. '2026-05-20T15:00:00'. The timeZone field controls interpretation."),
+    timeZone: z
+        .string()
+        .min(1)
+        .describe("IANA timezone, e.g. 'America/Los_Angeles' or 'UTC'."),
+});
+const attendeeSchema = z.object({
+    email: z.string().email(),
+    name: z.string().optional(),
+    optional: z
+        .boolean()
+        .default(false)
+        .describe("If true, the attendee is marked optional."),
+});
+function toGoogleAttendees(attendees) {
+    return attendees.map((a) => ({
+        email: a.email,
+        displayName: a.name,
+        optional: a.optional,
+    }));
+}
+function formatPerson(p) {
+    if (!p)
+        return null;
+    if (p.displayName && p.email)
+        return `${p.displayName} <${p.email}>`;
+    return p.email ?? p.displayName ?? null;
+}
+export function summarizeEvent(e) {
+    const attendees = e.attendees ?? [];
+    const self = attendees.find((a) => a.self);
+    return {
+        id: e.id,
+        subject: e.summary ?? null,
+        start: e.start, // { dateTime, timeZone } or { date }
+        end: e.end,
+        isAllDay: !!e.start?.date,
+        location: e.location ?? null,
+        organizer: formatPerson(e.organizer),
+        attendees: attendees.map((a) => ({
+            email: formatPerson(a),
+            optional: a.optional ?? false,
+            responseStatus: a.responseStatus, // needsAction|declined|tentative|accepted
+        })),
+        status: e.status, // confirmed | tentative | cancelled
+        myResponse: self?.responseStatus ?? null,
+        // Google: recurringEventId present => this is an instance of a series.
+        recurringEventId: e.recurringEventId ?? null,
+        htmlLink: e.htmlLink,
+        preview: (e.description ?? "").slice(0, 200) || null,
+    };
+}
+// ---------- list_calendars ----------
+export const listCalendarsSchema = z.object({});
+export async function listCalendars(_input) {
+    const cal = await calendarClient();
+    const res = await cal.calendarList.list();
+    return {
+        calendars: (res.data.items ?? []).map((c) => ({
+            id: c.id,
+            name: c.summary,
+            isDefault: !!c.primary,
+            // owner/writer/reader/freeBusyReader — editable if owner or writer.
+            canEdit: c.accessRole === "owner" || c.accessRole === "writer",
+            accessRole: c.accessRole,
+        })),
+    };
+}
+// ---------- list_events ----------
+export const listEventsSchema = z.object({
+    start: z
+        .string()
+        .min(1)
+        .describe("Inclusive window start, RFC-3339, e.g. '2026-05-20T00:00:00Z' or with offset."),
+    end: z
+        .string()
+        .min(1)
+        .describe("Exclusive window end. Same format as start."),
+    calendarId: z
+        .string()
+        .default("primary")
+        .describe("Calendar id. Defaults to the primary calendar."),
+    limit: z.number().int().min(1).max(200).default(50),
+});
+export async function listEvents(input) {
+    const cal = await calendarClient();
+    // singleEvents + orderBy=startTime expands recurring series into individual
+    // instances ordered by time (the "what's on my calendar" question).
+    const res = await cal.events.list({
+        calendarId: input.calendarId,
+        timeMin: input.start,
+        timeMax: input.end,
+        singleEvents: true,
+        orderBy: "startTime",
+        maxResults: input.limit,
+        timeZone: config.defaultTimeZone,
+    });
+    return {
+        timeZone: config.defaultTimeZone,
+        events: (res.data.items ?? []).map(summarizeEvent),
+        nextCursor: res.data.nextPageToken ?? null,
+    };
+}
+// ---------- read_event ----------
+export const readEventSchema = z.object({
+    eventId: z.string().min(1),
+    calendarId: z.string().default("primary"),
+});
+export async function readEvent(input) {
+    const cal = await calendarClient();
+    const res = await cal.events.get({
+        calendarId: input.calendarId,
+        eventId: input.eventId,
+        timeZone: config.defaultTimeZone,
+    });
+    const e = res.data;
+    return {
+        ...summarizeEvent(e),
+        body: { contentType: "text", content: e.description ?? "" },
+        recurrence: e.recurrence ?? null,
+    };
+}
+// ---------- create_event ----------
+export const createEventSchema = z.object({
+    subject: z.string().min(1),
+    start: dateTimeWithTz,
+    end: dateTimeWithTz,
+    attendees: z.array(attendeeSchema).default([]),
+    location: z.string().optional(),
+    body: z.string().optional(),
+    isOnlineMeeting: z
+        .boolean()
+        .default(false)
+        .describe("If true, attaches a Google Meet conference link."),
+    calendarId: z.string().default("primary"),
+    sendUpdates: z
+        .enum(["all", "externalOnly", "none"])
+        .default("all")
+        .describe("Whether to send invites/notifications to attendees."),
+});
+export async function createEvent(input) {
+    const cal = await calendarClient();
+    const requestBody = {
+        summary: input.subject,
+        start: input.start,
+        end: input.end,
+        attendees: toGoogleAttendees(input.attendees),
+    };
+    if (input.location)
+        requestBody.location = input.location;
+    if (input.body)
+        requestBody.description = input.body;
+    if (input.isOnlineMeeting) {
+        requestBody.conferenceData = {
+            createRequest: {
+                // requestId must be unique per create; derive from subject + start.
+                requestId: `meet-${Buffer.from(input.subject + input.start.dateTime)
+                    .toString("base64url")
+                    .slice(0, 32)}`,
+                conferenceSolutionKey: { type: "hangoutsMeet" },
+            },
+        };
+    }
+    const res = await cal.events.insert({
+        calendarId: input.calendarId,
+        requestBody,
+        sendUpdates: input.sendUpdates,
+        conferenceDataVersion: input.isOnlineMeeting ? 1 : 0,
+    });
+    return summarizeEvent(res.data);
+}
+// ---------- update_event ----------
+export const updateEventSchema = z.object({
+    eventId: z.string().min(1),
+    calendarId: z.string().default("primary"),
+    subject: z.string().optional(),
+    start: dateTimeWithTz.optional(),
+    end: dateTimeWithTz.optional(),
+    attendees: z.array(attendeeSchema).optional(),
+    location: z.string().optional(),
+    body: z.string().optional(),
+    sendUpdates: z.enum(["all", "externalOnly", "none"]).default("all"),
+});
+export async function updateEvent(input) {
+    const cal = await calendarClient();
+    const patch = {};
+    if (input.subject !== undefined)
+        patch.summary = input.subject;
+    if (input.start !== undefined)
+        patch.start = input.start;
+    if (input.end !== undefined)
+        patch.end = input.end;
+    if (input.attendees !== undefined) {
+        patch.attendees = toGoogleAttendees(input.attendees);
+    }
+    if (input.location !== undefined)
+        patch.location = input.location;
+    if (input.body !== undefined)
+        patch.description = input.body;
+    const changed = Object.keys(patch);
+    if (changed.length === 0) {
+        return { ok: true, eventId: input.eventId, changed: [] };
+    }
+    // events.patch does a partial update. Unlike Graph, Google handles single
+    // recurring instances fine (an instance has its own id), so we don't refuse.
+    const res = await cal.events.patch({
+        calendarId: input.calendarId,
+        eventId: input.eventId,
+        requestBody: patch,
+        sendUpdates: input.sendUpdates,
+    });
+    return {
+        ok: true,
+        eventId: input.eventId,
+        changed,
+        event: summarizeEvent(res.data),
+    };
+}
+// ---------- cancel_event ----------
+export const cancelEventSchema = z.object({
+    eventId: z.string().min(1),
+    calendarId: z.string().default("primary"),
+    sendUpdates: z
+        .enum(["all", "externalOnly", "none"])
+        .default("all")
+        .describe("Whether to notify attendees of the cancellation. Use 'all' for meetings; 'none' for solo events."),
+});
+export async function cancelEvent(input) {
+    const cal = await calendarClient();
+    // Google has no separate cancel vs delete: deleting an event you organize
+    // sends cancellations to attendees when sendUpdates=all.
+    await cal.events.delete({
+        calendarId: input.calendarId,
+        eventId: input.eventId,
+        sendUpdates: input.sendUpdates,
+    });
+    return { ok: true, eventId: input.eventId, sendUpdates: input.sendUpdates };
+}
+// ---------- respond_to_invite ----------
+const RESPONSE_MAP = {
+    accept: "accepted",
+    tentativelyAccept: "tentative",
+    decline: "declined",
+};
+export const respondSchema = z.object({
+    eventId: z.string().min(1),
+    calendarId: z.string().default("primary"),
+    response: z.enum(["accept", "tentativelyAccept", "decline"]),
+    comment: z.string().optional(),
+    sendResponse: z
+        .boolean()
+        .default(true)
+        .describe("Whether to notify the organizer of your response."),
+});
+export async function respondToInvite(input) {
+    const cal = await calendarClient();
+    // Google has no /accept endpoint: you patch your own attendee entry's
+    // responseStatus. Fetch the event, find the self attendee, update it.
+    const current = await cal.events.get({
+        calendarId: input.calendarId,
+        eventId: input.eventId,
+    });
+    const attendees = current.data.attendees ?? [];
+    const self = attendees.find((a) => a.self);
+    if (!self) {
+        throw new Error(`You are not an attendee of event ${input.eventId}, so there is nothing to respond to.`);
+    }
+    self.responseStatus = RESPONSE_MAP[input.response];
+    if (input.comment)
+        self.comment = input.comment;
+    await cal.events.patch({
+        calendarId: input.calendarId,
+        eventId: input.eventId,
+        requestBody: { attendees },
+        sendUpdates: input.sendResponse ? "all" : "none",
+    });
+    return {
+        ok: true,
+        eventId: input.eventId,
+        response: RESPONSE_MAP[input.response],
+    };
+}
+//# sourceMappingURL=calendar.js.map

package/dist/tools/calendar.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"calendar.js","sourceRoot":"","sources":["../../src/tools/calendar.ts"],"names":[],"mappings":"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"}

package/dist/tools/helpers.js

@@ -0,0 +1,125 @@
+/** Case-insensitive lookup of a header value from a Gmail message payload. */
+export function header(msg, name) {
+    const headers = msg.payload?.headers ?? [];
+    const lower = name.toLowerCase();
+    return (headers.find((h) => (h.name ?? "").toLowerCase() === lower)?.value ??
+        undefined);
+}
+/**
+ * Flatten a message into a compact summary for list/search results. Pulls the
+ * common headers and the snippet; does not walk the body (use readMessage for
+ * that).
+ */
+export function summarizeMessage(msg) {
+    return {
+        id: msg.id,
+        threadId: msg.threadId,
+        from: header(msg, "From") ?? null,
+        to: header(msg, "To") ?? null,
+        subject: header(msg, "Subject") ?? null,
+        date: header(msg, "Date") ?? null,
+        snippet: msg.snippet ?? null,
+        labelIds: msg.labelIds ?? [],
+        unread: (msg.labelIds ?? []).includes("UNREAD"),
+        hasAttachments: hasAttachments(msg),
+    };
+}
+/** True if any part of the message carries a filename (i.e. an attachment). */
+export function hasAttachments(msg) {
+    const walk = (part) => {
+        if (!part)
+            return false;
+        if (part.filename && part.filename.length > 0)
+            return true;
+        return (part.parts ?? []).some(walk);
+    };
+    return walk(msg.payload);
+}
+/**
+ * Extract the best-effort body text from a message payload. Prefers text/plain;
+ * falls back to text/html (caller may strip). Walks multipart trees.
+ */
+export function extractBody(msg) {
+    const decode = (data) => data ? Buffer.from(data, "base64url").toString("utf8") : "";
+    let plain;
+    let html;
+    const walk = (part) => {
+        if (!part)
+            return;
+        const mime = part.mimeType ?? "";
+        if (mime === "text/plain" && plain === undefined) {
+            plain = decode(part.body?.data);
+        }
+        else if (mime === "text/html" && html === undefined) {
+            html = decode(part.body?.data);
+        }
+        for (const child of part.parts ?? [])
+            walk(child);
+    };
+    walk(msg.payload);
+    if (plain !== undefined && plain.length > 0) {
+        return { contentType: "text", content: plain };
+    }
+    if (html !== undefined && html.length > 0) {
+        return { contentType: "html", content: html };
+    }
+    // Single-part message: body sits directly on the payload.
+    return { contentType: "text", content: decode(msg.payload?.body?.data) };
+}
+/**
+ * Build an RFC-2822 message and return it base64url-encoded for
+ * users.messages.send / drafts.create. Gmail wants the raw MIME, not JSON.
+ * `threadHeaders` lets replies set In-Reply-To / References.
+ */
+export function buildRawMessage(opts) {
+    const lines = [];
+    lines.push(`To: ${opts.to.join(", ")}`);
+    if (opts.cc?.length)
+        lines.push(`Cc: ${opts.cc.join(", ")}`);
+    if (opts.bcc?.length)
+        lines.push(`Bcc: ${opts.bcc.join(", ")}`);
+    // Encode the subject as RFC-2047 if it has non-ASCII chars.
+    lines.push(`Subject: ${encodeHeaderValue(opts.subject ?? "")}`);
+    lines.push("MIME-Version: 1.0");
+    // inReplyTo/references are derived from a FETCHED message's headers, not
+    // from email-validated input, so strip CR/LF to prevent header injection
+    // (a crafted Message-ID could otherwise smuggle "\r\nBcc: ...").
+    if (opts.inReplyTo)
+        lines.push(`In-Reply-To: ${stripCrlf(opts.inReplyTo)}`);
+    if (opts.references)
+        lines.push(`References: ${stripCrlf(opts.references)}`);
+    const contentType = opts.bodyFormat === "html" ? "text/html" : "text/plain";
+    lines.push(`Content-Type: ${contentType}; charset="UTF-8"`);
+    lines.push("Content-Transfer-Encoding: base64");
+    lines.push("");
+    // Body as base64 so arbitrary UTF-8 survives the 7-bit transport.
+    lines.push(Buffer.from(opts.body, "utf8").toString("base64"));
+    return Buffer.from(lines.join("\r\n"), "utf8").toString("base64url");
+}
+/** Remove CR/LF so a value can't inject extra MIME headers. */
+export function stripCrlf(value) {
+    return value.replace(/[\r\n]+/g, " ");
+}
+/**
+ * RFC-2047 encode a header value. CR/LF are stripped first so they can't
+ * smuggle additional headers (the plain-ASCII branch would otherwise pass
+ * them straight through, since the test below treats them as ASCII).
+ */
+export function encodeHeaderValue(value) {
+    const safe = stripCrlf(value);
+    // eslint-disable-next-line no-control-regex
+    if (/^[\x00-\x7f]*$/.test(safe))
+        return safe;
+    return `=?UTF-8?B?${Buffer.from(safe, "utf8").toString("base64")}?=`;
+}
+/** Truncate text to a max length, appending a marker when cut. */
+export function truncate(text, max) {
+    if (max === 0 || text.length <= max)
+        return { text, truncated: false };
+    let cut = text.slice(0, max);
+    const lastCode = cut.charCodeAt(cut.length - 1);
+    if (lastCode >= 0xd800 && lastCode <= 0xdbff)
+        cut = cut.slice(0, -1);
+    return { text: cut + "\n…[truncated]", truncated: true };
+}
+//# sourceMappingURL=helpers.js.map

package/dist/tools/helpers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"helpers.js","sourceRoot":"","sources":["../../src/tools/helpers.ts"],"names":[],"mappings":"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"}