@jaingxyz/personal-gmail-mcp 0.1.0

package/README.md

@@ -0,0 +1,142 @@
+# personal-gmail-mcp
+
+A [Model Context Protocol](https://modelcontextprotocol.io/) server that exposes a personal Gmail (consumer Google account) inbox **and calendar** to MCP clients like Claude Desktop. Talks to the Gmail and Google Calendar APIs over HTTPS, uses a local **loopback OAuth** flow, and stores tokens in the **OS keyring**.
+
+Sibling to [personal-outlook-mcp](https://github.com/jaingxyz/personal-outlook-mcp); same design (local stdio, keyring-backed tokens, you bring your own OAuth client), different provider. Tools are prefixed `gmail_*`.
+
+> **Status: functional.** Auth (loopback OAuth + keyring token cache), 12 mail tools, and 7 calendar tools are in place and verified against a live account. Not yet published to npm — install from source for now (see below).
+
+## Why keyring + bring-your-own-client
+
+Every Gmail MCP server we surveyed stores OAuth tokens as a **plaintext JSON file** in your home directory. This one stores them in the OS keyring (macOS Keychain / Windows Credential Manager / Linux Secret Service) via [`@napi-rs/keyring`](https://github.com/Brooooooklyn/keyring-node), and runs entirely locally — your mail never passes through anyone else's servers.
+
+## Google setup (required, ~5 minutes, free)
+
+You must create your own Google Cloud OAuth client.
+
+1. Go to https://console.cloud.google.com → create a project.
+2. **APIs & Services → Library** → enable both **Gmail API** and **Google Calendar API**.
+3. **APIs & Services → OAuth consent screen**:
+   - User type: **External**.
+   - Add your own Google account as a **test user**.
+   - **Publish the app ("In production").** You can leave it **unverified** for personal use (you'll click through an "unverified app" warning at sign-in).
+   - ⚠️ **This step matters:** an app left in **"Testing"** status issues refresh tokens that **expire after 7 days** — you'd have to re-auth every week. Publishing to production (even unverified) gives long-lived refresh tokens.
+4. **APIs & Services → Credentials → Create credentials → OAuth client ID** → application type **Desktop app**. Copy the **Client ID** and **Client secret**.
+5. `cp .env.example .env` and fill in `GOOGLE_CLIENT_ID` and `GOOGLE_CLIENT_SECRET`.
+
+The required scopes are requested at sign-in; you consent at the browser prompt:
+
+| Scope                                     | Used for                                                     |
+| ----------------------------------------- | ------------------------------------------------------------ |
+| `https://mail.google.com/`                | full mailbox read/modify/send                                |
+| `.../auth/calendar.events`                | event read/create/update/cancel/respond                      |
+| `.../auth/calendar.calendarlist.readonly` | enumerating your calendars (`gmail_calendar_list_calendars`) |
+| `.../auth/userinfo.email` + `openid`      | identifying the signed-in account                            |
+
+> Changing the scope list invalidates the cached token — re-run `npm run whoami` to re-consent.
+
+## First run (loopback auth)
+
+```bash
+npm install
+npm run build
+npm run whoami
+```
+
+`whoami` opens your browser to Google's consent page (the URL is also printed to **stderr** if the browser doesn't open). After you approve, a throwaway `127.0.0.1` listener captures the redirect, exchanges the code, and stores the token set in the OS keyring under service `personal-gmail-mcp`. It then prints your Gmail profile as JSON. Subsequent runs refresh silently.
+
+To sign out (forget the cached token):
+
+```bash
+node -e "import('./dist/auth.js').then(m => m.signOut())"
+```
+
+## MCP client integration
+
+Point your MCP client (Claude Desktop or similar) at the built server. Until
+this is published to npm, use the **from-source** form with an absolute path to
+`dist/index.js`:
+
+```json
+{
+  "mcpServers": {
+    "personal-gmail": {
+      "command": "node",
+      "args": ["/absolute/path/to/personal-gmail-mcp/dist/index.js"],
+      "env": {
+        "GOOGLE_CLIENT_ID": "<YOUR-CLIENT-ID>",
+        "GOOGLE_CLIENT_SECRET": "<YOUR-CLIENT-SECRET>"
+      }
+    }
+  }
+}
+```
+
+> If your `node` is managed by a version manager (nvm, mise, asdf), use the
+> **absolute path** to the node binary (e.g. `which node`) — MCP clients launch
+> with a minimal `PATH` and won't resolve a bare `node`.
+
+Once published to npm, the simpler `npx` form works:
+
+```json
+{
+  "command": "npx",
+  "args": ["-y", "@jaingxyz/personal-gmail-mcp"],
+  "env": { "GOOGLE_CLIENT_ID": "...", "GOOGLE_CLIENT_SECRET": "..." }
+}
+```
+
+Run `npm run whoami` from a terminal **once** to seed the keyring before
+launching the client — the browser/consent step can't be surfaced from inside
+the app (stderr is swallowed), so the MCP server only does silent refresh and
+will report `Re-authentication required` if the cache is empty or stale.
+
+## Tools
+
+All tools are prefixed `gmail_*` (mail) or `gmail_calendar_*` (calendar) so a
+multi-account setup can coexist.
+
+| Tool                               | Purpose                                                                                |
+| ---------------------------------- | -------------------------------------------------------------------------------------- |
+| `gmail_list_labels`                | List labels (system + custom) with unread/total counts.                                |
+| `gmail_list_recent`                | Newest-first messages in a label. Supports `unreadOnly`, cursor paging.                |
+| `gmail_search`                     | Search with Gmail query syntax (`from:`, `subject:`, `has:attachment`, `newer_than:`). |
+| `gmail_read`                       | Fetch one message with decoded body (text preferred, html fallback).                   |
+| `gmail_mark_read`                  | Mark read/unread (toggles the `UNREAD` label).                                         |
+| `gmail_modify_labels`              | Add/remove labels (remove `INBOX` to archive, add `STARRED`, etc.).                    |
+| `gmail_delete`                     | Trash (recoverable) by default; `hardDelete=true` is permanent.                        |
+| `gmail_untrash`                    | Restore a message from Trash.                                                          |
+| `gmail_send`                       | Send a new email immediately.                                                          |
+| `gmail_reply`                      | Reply in-thread by message id; `replyAll=true` for all recipients.                     |
+| `gmail_create_draft`               | Create a draft without sending; returns a draftId.                                     |
+| `gmail_send_draft`                 | Send a previously created draft.                                                       |
+| `gmail_calendar_list_calendars`    | List calendars with editability.                                                       |
+| `gmail_calendar_list_events`       | Events in a time range (recurring series expanded).                                    |
+| `gmail_calendar_read_event`        | Full event details incl. attendees and recurrence.                                     |
+| `gmail_calendar_create_event`      | Create an event; optional Google Meet link and invites.                                |
+| `gmail_calendar_update_event`      | Update subject/time/location/description/attendees.                                    |
+| `gmail_calendar_cancel_event`      | Delete an event; notifies attendees when you organize it.                              |
+| `gmail_calendar_respond_to_invite` | accept / tentativelyAccept / decline an invite.                                        |
+
+Calendar event times use `{ dateTime, timeZone }` where `dateTime` is local
+form (no offset) and `timeZone` is an IANA name. Output times default to
+`America/Los_Angeles`; override with `PERSONAL_GMAIL_TZ`.
+
+## How it differs from the Outlook server
+
+|                | Outlook (Graph)       | Gmail                                                            |
+| -------------- | --------------------- | ---------------------------------------------------------------- |
+| Auth flow      | MSAL device code      | Loopback / installed-app (Google forbids device code for Gmail)  |
+| Mail container | Folders               | **Labels** (`INBOX`, `SENT`, `DRAFT`, `TRASH`, custom)           |
+| Search         | Graph `$search` (KQL) | Gmail query syntax (`from: subject: has:attachment newer_than:`) |
+| Send           | JSON message          | base64url **RFC-2822 MIME**                                      |
+| Soft delete    | move to Deleted Items | `trash` / `untrash`                                              |
+| Calendar       | same Graph API        | **separate** Google Calendar API + scope                         |
+
+## License
+
+AGPL-3.0-or-later. See [LICENSE](./LICENSE).
+
+## Acknowledgements
+
+Built with assistance from [Claude](https://www.anthropic.com/claude) (Anthropic). Architecture and final review remain the human author's responsibility.

package/dist/auth.js

@@ -0,0 +1,200 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Copyright (C) 2026 jaingxyz
+import { createServer } from "node:http";
+import { randomBytes } from "node:crypto";
+import { execFile } from "node:child_process";
+import { AsyncEntry } from "@napi-rs/keyring";
+import { google } from "googleapis";
+import { config } from "./config.js";
+const keyringEntry = new AsyncEntry(config.keychainService, config.keychainAccount);
+// Persist the OAuth token set (access + refresh + expiry) in the OS keyring.
+// Same principle as the Outlook server: tokens never touch disk in plaintext.
+async function loadCredentials() {
+    const data = await keyringEntry.getPassword();
+    if (!data)
+        return null;
+    try {
+        return JSON.parse(data);
+    }
+    catch {
+        return null;
+    }
+}
+async function saveCredentials(creds) {
+    // Merge: a refresh response often omits refresh_token, so don't clobber it.
+    const existing = (await loadCredentials()) ?? {};
+    const merged = { ...existing, ...creds };
+    if (!merged.refresh_token && existing.refresh_token) {
+        merged.refresh_token = existing.refresh_token;
+    }
+    await keyringEntry.setPassword(JSON.stringify(merged));
+}
+export class ReauthRequiredError extends Error {
+    constructor(reason) {
+        super(`Re-authentication required: ${reason}. Run \`npm run whoami\` from a terminal to refresh the token cache, then retry.`);
+        this.name = "ReauthRequiredError";
+    }
+}
+function makeClient(redirectUri) {
+    return new google.auth.OAuth2(config.clientId, config.clientSecret, redirectUri);
+}
+/**
+ * Returns an authorized OAuth2 client. Silent path: load cached credentials;
+ * the googleapis client auto-refreshes using the refresh_token when the access
+ * token is expired, and we persist the refreshed token via the tokens event.
+ */
+export async function getAuthClient(opts = {}) {
+    const creds = await loadCredentials();
+    if (creds?.refresh_token) {
+        const client = makeClient();
+        client.setCredentials(creds);
+        client.on("tokens", (tokens) => {
+            void saveCredentials(tokens);
+        });
+        // Proactively ensure we have a live access token; this triggers a refresh
+        // if needed and throws if the refresh token is revoked/expired.
+        try {
+            await client.getAccessToken();
+            return client;
+        }
+        catch (err) {
+            if (!opts.interactive) {
+                throw new ReauthRequiredError(silentFailureReason(err));
+            }
+            // fall through to interactive
+        }
+    }
+    else if (!opts.interactive) {
+        throw new ReauthRequiredError("no cached refresh token");
+    }
+    return runLoopbackFlow();
+}
+/**
+ * Interactive loopback (installed-app) OAuth flow. Google does NOT support
+ * device-code for Gmail, so we spin up a throwaway localhost listener, open
+ * the consent page in the browser, and capture the redirected auth code.
+ */
+async function runLoopbackFlow() {
+    return new Promise((resolvePromise, reject) => {
+        const state = randomBytes(16).toString("hex");
+        const server = createServer((req, res) => {
+            try {
+                const url = new URL(req.url ?? "", `http://${config.redirectHost}`);
+                if (!url.pathname.startsWith("/oauth2callback")) {
+                    res.writeHead(404).end();
+                    return;
+                }
+                const returnedState = url.searchParams.get("state");
+                const code = url.searchParams.get("code");
+                const error = url.searchParams.get("error");
+                if (error) {
+                    finish(res, `Authorization failed: ${error}`);
+                    cleanup();
+                    reject(new Error(`OAuth error: ${error}`));
+                    return;
+                }
+                if (returnedState !== state) {
+                    finish(res, "State mismatch — aborting.");
+                    cleanup();
+                    reject(new Error("OAuth state mismatch (possible CSRF)"));
+                    return;
+                }
+                if (!code) {
+                    finish(res, "No authorization code received.");
+                    cleanup();
+                    reject(new Error("No authorization code in callback"));
+                    return;
+                }
+                const port = server.address().port;
+                const redirectUri = `http://${config.redirectHost}:${port}/oauth2callback`;
+                const client = makeClient(redirectUri);
+                client
+                    .getToken(code)
+                    .then(async ({ tokens }) => {
+                    if (!tokens.refresh_token) {
+                        // Without offline access we'd re-auth hourly. prompt=consent
+                        // below forces a refresh token to be issued.
+                        console.error("[auth] warning: no refresh_token returned; you may need to revoke the app's access and retry.");
+                    }
+                    client.setCredentials(tokens);
+                    client.on("tokens", (t) => void saveCredentials(t));
+                    await saveCredentials(tokens);
+                    finish(res, "Authentication complete. You can close this tab and return to the terminal.");
+                    cleanup();
+                    resolvePromise(client);
+                })
+                    .catch((err) => {
+                    finish(res, "Token exchange failed.");
+                    cleanup();
+                    reject(err);
+                });
+            }
+            catch (err) {
+                cleanup();
+                reject(err);
+            }
+        });
+        function cleanup() {
+            server.close();
+        }
+        function finish(res, message) {
+            res
+                .writeHead(200, { "Content-Type": "text/html" })
+                .end(`<!doctype html><meta charset="utf-8"><p>${message}</p>`);
+        }
+        // Bind to an ephemeral port on the loopback interface, then build the auth
+        // URL with the now-known port.
+        server.listen(0, config.redirectHost, () => {
+            const port = server.address().port;
+            const redirectUri = `http://${config.redirectHost}:${port}/oauth2callback`;
+            const client = makeClient(redirectUri);
+            const authUrl = client.generateAuthUrl({
+                access_type: "offline", // gets us a refresh_token
+                prompt: "consent", // force refresh_token issuance even on re-auth
+                scope: config.scopes,
+                state,
+            });
+            // CLI script context: print to stderr so the MCP stdout stream is never
+            // corrupted if this is ever reached from the server.
+            console.error("\nOpen this URL to authorize personal-gmail-mcp:\n");
+            console.error(authUrl + "\n");
+            openBrowser(authUrl);
+        });
+        server.on("error", reject);
+    });
+}
+function openBrowser(url) {
+    // Pass the URL as an argv element (no shell), so it can't be interpreted as
+    // a shell command. Best-effort; if it fails the user copies the URL from
+    // stderr. On Windows, `cmd /c start "" <url>` ("" = empty window title).
+    const platform = process.platform;
+    if (platform === "darwin") {
+        execFile("open", [url], () => { });
+    }
+    else if (platform === "win32") {
+        execFile("cmd", ["/c", "start", "", url], () => { });
+    }
+    else {
+        execFile("xdg-open", [url], () => { });
+    }
+}
+function silentFailureReason(err) {
+    if (err && typeof err === "object") {
+        const e = err;
+        if (e.message?.includes("invalid_grant")) {
+            return "refresh token expired or revoked (Google test-mode tokens expire after 7 days — publish the OAuth app)";
+        }
+        if (e.message)
+            return e.message.slice(0, 200);
+    }
+    return "silent token refresh failed";
+}
+export async function signOut() {
+    try {
+        await keyringEntry.deletePassword();
+    }
+    catch {
+        // Already signed out.
+    }
+}
+//# sourceMappingURL=auth.js.map

package/dist/auth.js.map

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

package/dist/config.js

@@ -0,0 +1,90 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Copyright (C) 2026 jaingxyz
+import { readFileSync, existsSync } from "node:fs";
+import { resolve, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+function loadDotEnv() {
+    const here = dirname(fileURLToPath(import.meta.url));
+    const candidates = [
+        resolve(here, "../../.env"),
+        resolve(process.cwd(), ".env"),
+    ];
+    for (const path of candidates) {
+        if (!existsSync(path))
+            continue;
+        const text = readFileSync(path, "utf8");
+        for (const rawLine of text.split(/\r?\n/)) {
+            const line = rawLine.trim();
+            if (!line || line.startsWith("#"))
+                continue;
+            const eq = line.indexOf("=");
+            if (eq === -1)
+                continue;
+            const key = line.slice(0, eq).trim();
+            let val = line.slice(eq + 1).trim();
+            if ((val.startsWith('"') && val.endsWith('"')) ||
+                (val.startsWith("'") && val.endsWith("'"))) {
+                val = val.slice(1, -1);
+            }
+            if (process.env[key] === undefined)
+                process.env[key] = val;
+        }
+        return;
+    }
+}
+loadDotEnv();
+function readVersion() {
+    const here = dirname(fileURLToPath(import.meta.url));
+    const candidates = [
+        resolve(here, "../package.json"),
+        resolve(here, "../../package.json"),
+    ];
+    for (const path of candidates) {
+        if (!existsSync(path))
+            continue;
+        try {
+            const pkg = JSON.parse(readFileSync(path, "utf8"));
+            if (pkg.version)
+                return pkg.version;
+        }
+        catch {
+            // Malformed package.json — try the next candidate.
+        }
+    }
+    return "0.0.0";
+}
+function required(name) {
+    const v = process.env[name];
+    if (!v) {
+        throw new Error(`Missing required env var ${name}. Copy .env.example to .env and fill it in (see README "Google setup").`);
+    }
+    return v;
+}
+export const config = {
+    version: readVersion(),
+    clientId: required("GOOGLE_CLIENT_ID"),
+    clientSecret: required("GOOGLE_CLIENT_SECRET"),
+    // Loopback redirect. Port 0 = OS picks a free port at auth time; the chosen
+    // port is appended before the redirect is registered with Google. A Desktop
+    // OAuth client accepts any http://127.0.0.1 / http://localhost port, so we
+    // don't have to pre-register a fixed one.
+    redirectHost: process.env.GOOGLE_REDIRECT_HOST || "127.0.0.1",
+    // Delegated scopes. mail.google.com gives full mailbox (read/modify/send);
+    // calendar.events covers event CRUD on a known calendar (incl. "primary");
+    // calendar.calendarlist.readonly is needed to ENUMERATE calendars
+    // (calendarList.list) — calendar.events alone returns 403 there.
+    // mail.google.com and the calendar scopes are "restricted" — the OAuth app
+    // must be published (not in Testing) for long-lived refresh tokens.
+    // NOTE: changing this list invalidates the cached token; re-run `whoami`.
+    scopes: [
+        "https://mail.google.com/",
+        "https://www.googleapis.com/auth/calendar.events",
+        "https://www.googleapis.com/auth/calendar.calendarlist.readonly",
+        "https://www.googleapis.com/auth/userinfo.email",
+        "openid",
+    ],
+    defaultTimeZone: process.env.PERSONAL_GMAIL_TZ || "America/Los_Angeles",
+    keychainService: "personal-gmail-mcp",
+    keychainAccount: "oauth-token",
+};
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

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

package/dist/google.js

@@ -0,0 +1,27 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Copyright (C) 2026 jaingxyz
+import { google } from "googleapis";
+import { getAuthClient } from "./auth.js";
+export async function gmailClient(opts) {
+    const auth = await getAuthClient(opts);
+    return google.gmail({ version: "v1", auth });
+}
+export async function calendarClient(opts) {
+    const auth = await getAuthClient(opts);
+    return google.calendar({ version: "v3", auth });
+}
+/**
+ * Smoke-test identity probe: returns the signed-in account's Gmail profile
+ * (email address, total messages/threads, history id).
+ */
+export async function getMe(opts) {
+    const gmail = await gmailClient(opts);
+    const res = await gmail.users.getProfile({ userId: "me" });
+    return {
+        emailAddress: res.data.emailAddress,
+        messagesTotal: res.data.messagesTotal,
+        threadsTotal: res.data.threadsTotal,
+        historyId: res.data.historyId,
+    };
+}
+//# sourceMappingURL=google.js.map

package/dist/google.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"google.js","sourceRoot":"","sources":["../src/google.ts"],"names":[],"mappings":"AAAA,6CAA6C;AAC7C,8BAA8B;AAC9B,OAAO,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AAEpC,OAAO,EAAE,aAAa,EAAyB,MAAM,WAAW,CAAC;AAEjE,MAAM,CAAC,KAAK,UAAU,WAAW,CAC/B,IAAuB;IAEvB,MAAM,IAAI,GAAG,MAAM,aAAa,CAAC,IAAI,CAAC,CAAC;IACvC,OAAO,MAAM,CAAC,KAAK,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;AAC/C,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,cAAc,CAClC,IAAuB;IAEvB,MAAM,IAAI,GAAG,MAAM,aAAa,CAAC,IAAI,CAAC,CAAC;IACvC,OAAO,MAAM,CAAC,QAAQ,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;AAClD,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,KAAK,CAAC,IAAuB;IAMjD,MAAM,KAAK,GAAG,MAAM,WAAW,CAAC,IAAI,CAAC,CAAC;IACtC,MAAM,GAAG,GAAG,MAAM,KAAK,CAAC,KAAK,CAAC,UAAU,CAAC,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC;IAC3D,OAAO;QACL,YAAY,EAAE,GAAG,CAAC,IAAI,CAAC,YAAY;QACnC,aAAa,EAAE,GAAG,CAAC,IAAI,CAAC,aAAa;QACrC,YAAY,EAAE,GAAG,CAAC,IAAI,CAAC,YAAY;QACnC,SAAS,EAAE,GAAG,CAAC,IAAI,CAAC,SAAS;KAC9B,CAAC;AACJ,CAAC"}

package/dist/index.js

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Copyright (C) 2026 jaingxyz
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { buildServer } from "./server.js";
+async function main() {
+    const server = buildServer();
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    // Server runs until the client closes stdin.
+}
+main().catch((err) => {
+    console.error("[personal-gmail-mcp] fatal:", err);
+    process.exit(1);
+});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA,6CAA6C;AAC7C,8BAA8B;AAC9B,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AACjF,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE1C,KAAK,UAAU,IAAI;IACjB,MAAM,MAAM,GAAG,WAAW,EAAE,CAAC;IAC7B,MAAM,SAAS,GAAG,IAAI,oBAAoB,EAAE,CAAC;IAC7C,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IAChC,6CAA6C;AAC/C,CAAC;AAED,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,GAAG,EAAE,EAAE;IACnB,OAAO,CAAC,KAAK,CAAC,6BAA6B,EAAE,GAAG,CAAC,CAAC;IAClD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}

package/dist/scripts/whoami.js

@@ -0,0 +1,16 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Copyright (C) 2026 jaingxyz
+import { getMe } from "../google.js";
+async function main() {
+    // Force the interactive loopback flow if the keyring is empty or the refresh
+    // token is stale. Subsequent runs (and the MCP server) reuse the cached token.
+    const me = await getMe({ interactive: true });
+    // Intentionally writes to stdout: this is a CLI script, not the MCP server.
+    // eslint-disable-next-line no-console
+    console.log(JSON.stringify(me, null, 2));
+}
+main().catch((err) => {
+    console.error(err);
+    process.exit(1);
+});
+//# sourceMappingURL=whoami.js.map

package/dist/scripts/whoami.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"whoami.js","sourceRoot":"","sources":["../../src/scripts/whoami.ts"],"names":[],"mappings":"AAAA,6CAA6C;AAC7C,8BAA8B;AAC9B,OAAO,EAAE,KAAK,EAAE,MAAM,cAAc,CAAC;AAErC,KAAK,UAAU,IAAI;IACjB,6EAA6E;IAC7E,+EAA+E;IAC/E,MAAM,EAAE,GAAG,MAAM,KAAK,CAAC,EAAE,WAAW,EAAE,IAAI,EAAE,CAAC,CAAC;IAC9C,4EAA4E;IAC5E,sCAAsC;IACtC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC;AAC3C,CAAC;AAED,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,GAAG,EAAE,EAAE;IACnB,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IACnB,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}