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

package/README.md

@@ -3,15 +3,16 @@
 **English** | [Русский](./README.ru.md)
 
 [![npm](https://img.shields.io/npm/v/%40a1-x-tech%2Fmcp-google-slides)](https://www.npmjs.com/package/@a1-x-tech/mcp-google-slides)
-[![CI](https://github.com/A1-x-Tech/mcp-google-slides/actions/workflows/ci.yml/badge.svg)](https://github.com/A1-x-Tech/mcp-google-slides/actions/workflows/ci.yml)
 [![Glama](https://glama.ai/mcp/servers/A1-x-Tech/mcp-google-slides/badges/score.svg)](https://glama.ai/mcp/servers/A1-x-Tech/mcp-google-slides)
+[![CI](https://github.com/A1-x-Tech/mcp-google-slides/actions/workflows/ci.yml/badge.svg)](https://github.com/A1-x-Tech/mcp-google-slides/actions/workflows/ci.yml)
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
 
 **A1 Google Slides MCP** lets an AI app build and edit Google Slides presentations in plain language. Draft a deck, add and rearrange slides, write and style text, place shapes, images and tables, keep speaker notes, review comments and export the result as PDF or PPTX.
 
 It uses the Google Slides API with your Google account. Everything inside a deck is addressed by explicit object ids, and it makes the limits of the Slides API explicit instead of implying that every presentation task is possible.
 
-- **26 tools.** Inspect decks and pages, edit slides, text, shapes, images and tables, manage speaker notes and comments, render thumbnails and export files.
+- **32 tools.** Inspect decks and pages, edit slides, text, shapes, images and tables, manage speaker notes and comments, render thumbnails and export files.
+- **Connects from the conversation.** Say "connect Google Slides": the server walks you through the OAuth client, catches Google's redirect on `127.0.0.1` with PKCE and keeps the tokens itself — no config files, no restart.
 - **Edits are atomic.** Changes ride the API's `batchUpdate`: one invalid request voids the whole batch, so a deck is never left half-edited.
 - **Your Drive stays out of reach.** Comments, export and local-image upload use the Drive API strictly for the one presentation file — there are no tools to list, share, rename or delete Drive files.
 - **Minimal Google scopes.** It needs `presentations`; Drive scopes are required only for local images, comments and export.
@@ -52,10 +53,10 @@ Start with a read-only question:
 
 ## Quick start
 
-You need Node.js 20+, a Google account and OAuth credentials from a Google Cloud project with the Google Slides API enabled.
+You need Node.js 20+ and a Google account. Credentials are not required at install time — the server connects from the conversation.
 
-1. [Prepare Google OAuth access](#getting-access).
-2. Add the server to your AI app.
+1. Add the server to your AI app.
+2. Say "connect Google Slides": the assistant walks you through [creating the OAuth client and approving access](#getting-access) without editing config files.
 3. Ask the read-only question above.
 
 <details open>
@@ -63,15 +64,12 @@ You need Node.js 20+, a Google account and OAuth credentials from a Google Cloud
 
 <br>
 
-**In the app:** open **Settings → Plugins → MCP servers**, select **Add server**, then add `npx -y @a1-x-tech/mcp-google-slides@latest` with `GOOGLE_SLIDES_CLIENT_ID`, `GOOGLE_SLIDES_CLIENT_SECRET` and `GOOGLE_SLIDES_REFRESH_TOKEN`.
+**In the app:** open **Settings → MCP servers**, select **Add server**, choose **STDIO**, enter the command `npx -y @a1-x-tech/mcp-google-slides@latest` and environment variables `GOOGLE_SLIDES_CLIENT_ID`, `GOOGLE_SLIDES_CLIENT_SECRET`, `GOOGLE_SLIDES_REFRESH_TOKEN`, then select **Save** and **Restart**.
 
 **From the command line:**
 
 ```bash
 codex mcp add google-slides \
-  --env GOOGLE_SLIDES_CLIENT_ID=your_client_id \
-  --env GOOGLE_SLIDES_CLIENT_SECRET=your_client_secret \
-  --env GOOGLE_SLIDES_REFRESH_TOKEN=your_refresh_token \
   -- npx -y @a1-x-tech/mcp-google-slides@latest
 ```
 
@@ -90,9 +88,6 @@ codex mcp list
 
 ```bash
 claude mcp add \
-  --env GOOGLE_SLIDES_CLIENT_ID=your_client_id \
-  --env GOOGLE_SLIDES_CLIENT_SECRET=your_client_secret \
-  --env GOOGLE_SLIDES_REFRESH_TOKEN=your_refresh_token \
   --transport stdio --scope user google-slides \
   -- npx -y @a1-x-tech/mcp-google-slides@latest
 ```
@@ -110,25 +105,22 @@ claude mcp list
 
 <br>
 
-Open **Settings → Developer → Edit Config** and add:
+The current official path is **Settings → Extensions**. For a custom desktop extension, open **Advanced settings → Extension Developer → Install Extension…**, select a `.mcpb` file and follow the prompts.
+
+This repository currently publishes an npm stdio package and does not contain a `.mcpb` bundle. For Claude Desktop builds that still support local configuration, use the following JSON stdio configuration as a fallback:
 
 ```json
 {
   "mcpServers": {
     "google-slides": {
       "command": "npx",
-      "args": ["-y", "@a1-x-tech/mcp-google-slides@latest"],
-      "env": {
-        "GOOGLE_SLIDES_CLIENT_ID": "your_client_id",
-        "GOOGLE_SLIDES_CLIENT_SECRET": "your_client_secret",
-        "GOOGLE_SLIDES_REFRESH_TOKEN": "your_refresh_token"
-      }
+      "args": ["-y", "@a1-x-tech/mcp-google-slides@latest"]
     }
   }
 }
 ```
 
-If **Edit Config** is unavailable, edit `~/Library/Application Support/Claude/claude_desktop_config.json` on macOS or `%APPDATA%\Claude\claude_desktop_config.json` on Windows.
+In those builds, save it to `~/Library/Application Support/Claude/claude_desktop_config.json` on macOS or `%APPDATA%\Claude\claude_desktop_config.json` on Windows.
 
 [Claude Desktop MCP documentation](https://support.claude.com/en/articles/10949351-getting-started-with-local-mcp-servers-on-claude-desktop)
 
@@ -147,12 +139,7 @@ Add this to `~/.cursor/mcp.json` on macOS/Linux or `%USERPROFILE%\.cursor\mcp.js
     "google-slides": {
       "type": "stdio",
       "command": "npx",
-      "args": ["-y", "@a1-x-tech/mcp-google-slides@latest"],
-      "env": {
-        "GOOGLE_SLIDES_CLIENT_ID": "your_client_id",
-        "GOOGLE_SLIDES_CLIENT_SECRET": "your_client_secret",
-        "GOOGLE_SLIDES_REFRESH_TOKEN": "your_refresh_token"
-      }
+      "args": ["-y", "@a1-x-tech/mcp-google-slides@latest"]
     }
   }
 }
@@ -175,19 +162,9 @@ Run **MCP: Open User Configuration** and add:
     "google-slides": {
       "type": "stdio",
       "command": "npx",
-      "args": ["-y", "@a1-x-tech/mcp-google-slides@latest"],
-      "env": {
-        "GOOGLE_SLIDES_CLIENT_ID": "${input:slides_client_id}",
-        "GOOGLE_SLIDES_CLIENT_SECRET": "${input:slides_client_secret}",
-        "GOOGLE_SLIDES_REFRESH_TOKEN": "${input:slides_refresh_token}"
-      }
+      "args": ["-y", "@a1-x-tech/mcp-google-slides@latest"]
     }
-  },
-  "inputs": [
-    { "type": "promptString", "id": "slides_client_id", "description": "Google OAuth client ID" },
-    { "type": "promptString", "id": "slides_client_secret", "description": "Google OAuth client secret", "password": true },
-    { "type": "promptString", "id": "slides_refresh_token", "description": "Google OAuth refresh token", "password": true }
-  ]
+  }
 }
 ```
 
@@ -248,7 +225,20 @@ The AI client controls confirmation prompts. The server marks reads, writes and
 
 ## Getting access
 
-Google Slides requires OAuth 2.0; an API key is not enough.
+Google Slides requires OAuth 2.0; an API key is not enough. There are two ways in, and the first one needs no configuration files.
+
+### Connect from the chat (recommended)
+
+Say "connect Google Slides" and the assistant runs the flow with you:
+
+1. `setup_instructions` prints the checklist: create or select a Google Cloud project, enable **Google Slides API**, configure the consent screen and create a **Desktop app** OAuth client.
+2. Download that client's JSON ("Download JSON") and give the assistant its **path** — `set_client` stores it owner-only. The secret never goes through the conversation.
+3. `start_login` returns a Google consent link. Open it **on this machine** and approve; the code comes back to a one-shot listener on `127.0.0.1` (PKCE), never through the chat.
+4. `finish_login` exchanges the code and saves the tokens to `~/.config/mcp-google-slides/credentials.json` (mode 0600).
+
+The tokens are re-read on every call, so the connection works immediately — no restart of the AI app. `auth_status` shows what is connected, `logout` revokes and deletes it.
+
+### Environment variables (CI, unattended installs)
 
 1. Create or select a Google Cloud project and enable **Google Slides API**. Enable **Google Drive API** too if you want comments, export or local-image upload.
 2. Configure the OAuth consent screen and create a **Desktop app** OAuth client.
@@ -266,12 +256,15 @@ Testing-mode OAuth refresh tokens can expire after seven days. Publish the OAuth
 
 ## Configuration
 
+Every variable is optional — with none of them the server connects [from the chat](#connect-from-the-chat-recommended).
+
 | Variable | Required | Description |
 |---|---|---|
-| `GOOGLE_SLIDES_CLIENT_ID` | Yes* | OAuth client ID. |
-| `GOOGLE_SLIDES_CLIENT_SECRET` | Yes* | OAuth client secret. |
-| `GOOGLE_SLIDES_REFRESH_TOKEN` | Yes* | OAuth refresh token. |
-| `GOOGLE_SLIDES_ACCESS_TOKEN` | Yes* | Short-lived (~1 h) alternative to the OAuth trio. |
+| `GOOGLE_SLIDES_CLIENT_ID` | No* | OAuth client ID. |
+| `GOOGLE_SLIDES_CLIENT_SECRET` | No* | OAuth client secret. |
+| `GOOGLE_SLIDES_REFRESH_TOKEN` | No* | OAuth refresh token. |
+| `GOOGLE_SLIDES_ACCESS_TOKEN` | No* | Short-lived (~1 h) alternative to the OAuth trio. |
+| `GOOGLE_SLIDES_OAUTH_PORT` | No | Fixed loopback port for the in-chat login; useful over SSH port forwarding. |
 | `GOOGLE_SLIDES_API_BASE` | No | Google Slides API base URL override. |
 | `GOOGLE_SLIDES_DRIVE_API_BASE` | No | Google Drive API base URL override (internal dependency: comments, export, image upload). |
 | `GOOGLE_SLIDES_TIMEOUT_MS` | No | Per-request timeout; default `60000` ms. |

package/README.ru.md

@@ -11,7 +11,8 @@
 
 Сервер работает с Google Slides API через ваш Google-аккаунт. Всё внутри презентации адресуется явными object id, а ограничения Slides API сервер называет прямо, вместо того чтобы делать вид, будто с презентацией возможно всё.
 
-- **26 инструментов.** Проверка презентаций и страниц, редактирование слайдов, текста, фигур, изображений и таблиц, заметки докладчика и комментарии, миниатюры и экспорт файлов.
+- **32 инструментов.** Проверка презентаций и страниц, редактирование слайдов, текста, фигур, изображений и таблиц, заметки докладчика и комментарии, миниатюры и экспорт файлов.
+- **Подключение из диалога.** Скажите «подключи Google Презентации»: сервер проведёт через создание OAuth-клиента, поймает редирект Google на `127.0.0.1` с PKCE и сам сохранит токены — без конфигов и перезапуска.
 - **Правки атомарны.** Изменения идут через `batchUpdate` API: один неверный запрос отменяет весь пакет, поэтому презентация не остаётся отредактированной наполовину.
 - **Ваш Drive недосягаем.** Комментарии, экспорт и загрузка локальных изображений используют Drive API строго для одного файла презентации — инструментов, чтобы перечислять, расшаривать, переименовывать или удалять файлы Drive, нет.
 - **Минимальные scope Google.** Нужен `presentations`; scope Drive требуются только для локальных изображений, комментариев и экспорта.
@@ -52,10 +53,10 @@
 
 ## Быстрый старт
 
-Нужны Node.js 20+, Google-аккаунт и OAuth-данные из проекта Google Cloud с включённым Google Slides API.
+Нужны Node.js 20+ и Google-аккаунт. Учётные данные при установке не нужны: сервер подключается прямо в диалоге.
 
-1. [Подготовьте Google OAuth-доступ](#как-получить-доступ).
-2. Добавьте сервер в AI-приложение.
+1. Добавьте сервер в AI-приложение.
+2. Скажите «подключи Google Презентации» — ассистент проведёт [создание OAuth-клиента и выдачу доступа](#как-получить-доступ), не трогая конфиги.
 3. Отправьте запрос, который только читает данные.
 
 <details open>
@@ -63,15 +64,12 @@
 
 <br>
 
-**В приложении:** откройте **Settings → Plugins → MCP servers**, нажмите **Add server**, затем добавьте `npx -y @a1-x-tech/mcp-google-slides@latest` с `GOOGLE_SLIDES_CLIENT_ID`, `GOOGLE_SLIDES_CLIENT_SECRET` и `GOOGLE_SLIDES_REFRESH_TOKEN`.
+**В приложении:** откройте **Settings → MCP servers**, нажмите **Add server**, выберите **STDIO**, укажите команду `npx -y @a1-x-tech/mcp-google-slides@latest` и переменные окружения `GOOGLE_SLIDES_CLIENT_ID`, `GOOGLE_SLIDES_CLIENT_SECRET`, `GOOGLE_SLIDES_REFRESH_TOKEN`, затем нажмите **Save**, потом **Restart**.
 
 **В командной строке:**
 
 ```bash
 codex mcp add google-slides \
-  --env GOOGLE_SLIDES_CLIENT_ID=your_client_id \
-  --env GOOGLE_SLIDES_CLIENT_SECRET=your_client_secret \
-  --env GOOGLE_SLIDES_REFRESH_TOKEN=your_refresh_token \
   -- npx -y @a1-x-tech/mcp-google-slides@latest
 ```
 
@@ -90,9 +88,6 @@ codex mcp list
 
 ```bash
 claude mcp add \
-  --env GOOGLE_SLIDES_CLIENT_ID=your_client_id \
-  --env GOOGLE_SLIDES_CLIENT_SECRET=your_client_secret \
-  --env GOOGLE_SLIDES_REFRESH_TOKEN=your_refresh_token \
   --transport stdio --scope user google-slides \
   -- npx -y @a1-x-tech/mcp-google-slides@latest
 ```
@@ -110,25 +105,22 @@ claude mcp list
 
 <br>
 
-Откройте **Settings → Developer → Edit Config** и добавьте:
+Актуальный официальный путь — **Settings → Extensions**. Для пользовательского desktop extension откройте **Advanced settings → Extension Developer → Install Extension…**, выберите файл `.mcpb` и следуйте подсказкам.
+
+Этот репозиторий сейчас публикует npm-пакет со stdio и пока не содержит `.mcpb`. Поэтому используйте приведённый ниже JSON stdio-конфиг как fallback только в сборках Claude Desktop, где ещё поддерживается локальная конфигурация:
 
 ```json
 {
   "mcpServers": {
     "google-slides": {
       "command": "npx",
-      "args": ["-y", "@a1-x-tech/mcp-google-slides@latest"],
-      "env": {
-        "GOOGLE_SLIDES_CLIENT_ID": "your_client_id",
-        "GOOGLE_SLIDES_CLIENT_SECRET": "your_client_secret",
-        "GOOGLE_SLIDES_REFRESH_TOKEN": "your_refresh_token"
-      }
+      "args": ["-y", "@a1-x-tech/mcp-google-slides@latest"]
     }
   }
 }
 ```
 
-Если **Edit Config** недоступна, отредактируйте `~/Library/Application Support/Claude/claude_desktop_config.json` на macOS или `%APPDATA%\Claude\claude_desktop_config.json` на Windows.
+В таких сборках сохраните его в `~/Library/Application Support/Claude/claude_desktop_config.json` на macOS или `%APPDATA%\Claude\claude_desktop_config.json` на Windows.
 
 [Документация Claude Desktop MCP](https://support.claude.com/en/articles/10949351-getting-started-with-local-mcp-servers-on-claude-desktop)
 
@@ -147,12 +139,7 @@ claude mcp list
     "google-slides": {
       "type": "stdio",
       "command": "npx",
-      "args": ["-y", "@a1-x-tech/mcp-google-slides@latest"],
-      "env": {
-        "GOOGLE_SLIDES_CLIENT_ID": "your_client_id",
-        "GOOGLE_SLIDES_CLIENT_SECRET": "your_client_secret",
-        "GOOGLE_SLIDES_REFRESH_TOKEN": "your_refresh_token"
-      }
+      "args": ["-y", "@a1-x-tech/mcp-google-slides@latest"]
     }
   }
 }
@@ -175,19 +162,9 @@ claude mcp list
     "google-slides": {
       "type": "stdio",
       "command": "npx",
-      "args": ["-y", "@a1-x-tech/mcp-google-slides@latest"],
-      "env": {
-        "GOOGLE_SLIDES_CLIENT_ID": "${input:slides_client_id}",
-        "GOOGLE_SLIDES_CLIENT_SECRET": "${input:slides_client_secret}",
-        "GOOGLE_SLIDES_REFRESH_TOKEN": "${input:slides_refresh_token}"
-      }
+      "args": ["-y", "@a1-x-tech/mcp-google-slides@latest"]
     }
-  },
-  "inputs": [
-    { "type": "promptString", "id": "slides_client_id", "description": "Google OAuth client ID" },
-    { "type": "promptString", "id": "slides_client_secret", "description": "Google OAuth client secret", "password": true },
-    { "type": "promptString", "id": "slides_refresh_token", "description": "Google OAuth refresh token", "password": true }
-  ]
+  }
 }
 ```
 
@@ -248,7 +225,20 @@ Slides API не может удалить, переименовать или р
 
 ## Как получить доступ
 
-Google Slides требует OAuth 2.0: одного API-ключа недостаточно.
+Google Slides требует OAuth 2.0: одного API-ключа недостаточно. Путей два, и первый не требует править конфигурационные файлы.
+
+### Подключение из диалога (рекомендуемый путь)
+
+Скажите «подключи Google Презентации», и ассистент пройдёт флоу вместе с вами:
+
+1. `setup_instructions` выдаёт чек-лист: создать или выбрать проект Google Cloud, включить **Google Slides API**, настроить consent screen и создать OAuth-клиент типа **Desktop app**.
+2. Скачайте JSON этого клиента («Download JSON») и передайте ассистенту **путь** к файлу — `set_client` сохранит его с правами только для владельца. Секрет через переписку не проходит.
+3. `start_login` возвращает ссылку на согласие Google. Откройте её **на этой же машине** и подтвердите доступ: код возвращается на одноразовый слушатель `127.0.0.1` (PKCE), а не в чат.
+4. `finish_login` меняет код на токены и кладёт их в `~/.config/mcp-google-slides/credentials.json` (права 0600).
+
+Токены перечитываются на каждый вызов, поэтому подключение действует немедленно — перезапускать AI-приложение не нужно. `auth_status` показывает состояние, `logout` отзывает токен и удаляет его.
+
+### Переменные окружения (CI и автоматические установки)
 
 1. Создайте или выберите проект Google Cloud и включите **Google Slides API**. Также включите **Google Drive API**, если нужны комментарии, экспорт или загрузка локальных изображений.
 2. Настройте OAuth consent screen и создайте OAuth-клиент типа **Desktop app**.
@@ -266,12 +256,15 @@ Refresh token OAuth-приложения в режиме Testing может ис
 
 ## Конфигурация
 
+Все переменные необязательные — без единой из них сервер подключается [из диалога](#подключение-из-диалога-рекомендуемый-путь).
+
 | Переменная | Обязательна | Описание |
 |---|---|---|
-| `GOOGLE_SLIDES_CLIENT_ID` | Да* | OAuth client ID. |
-| `GOOGLE_SLIDES_CLIENT_SECRET` | Да* | OAuth client secret. |
-| `GOOGLE_SLIDES_REFRESH_TOKEN` | Да* | OAuth refresh token. |
-| `GOOGLE_SLIDES_ACCESS_TOKEN` | Да* | Короткоживущая (~1 ч) альтернатива OAuth-тройке. |
+| `GOOGLE_SLIDES_CLIENT_ID` | Нет* | OAuth client ID. |
+| `GOOGLE_SLIDES_CLIENT_SECRET` | Нет* | OAuth client secret. |
+| `GOOGLE_SLIDES_REFRESH_TOKEN` | Нет* | OAuth refresh token. |
+| `GOOGLE_SLIDES_ACCESS_TOKEN` | Нет* | Короткоживущая (~1 ч) альтернатива OAuth-тройке. |
+| `GOOGLE_SLIDES_OAUTH_PORT` | Нет | Фиксированный порт loopback-слушателя для входа из диалога; нужен при пробросе портов по SSH. |
 | `GOOGLE_SLIDES_API_BASE` | Нет | Переопределяет базовый URL Google Slides API. |
 | `GOOGLE_SLIDES_DRIVE_API_BASE` | Нет | Переопределяет базовый URL Google Drive API (внутренняя зависимость: комментарии, экспорт, загрузка изображений). |
 | `GOOGLE_SLIDES_TIMEOUT_MS` | Нет | Тайм-аут одного запроса; по умолчанию `60000` мс. |

package/dist/client.js

@@ -164,6 +164,7 @@ export function extractText(text) {
 }
 export class GoogleSlidesClient {
     config;
+    tokenProvider;
     base;
     driveBase;
     timeoutMs;
@@ -173,8 +174,16 @@ export class GoogleSlidesClient {
     cachedToken;
     /** In-flight refresh, deduping concurrent token requests. */
     refreshInFlight;
-    constructor(config) {
+    constructor(config, 
+    /**
+     * Fallback token source (the in-chat login of @a1-x-tech/mcp-google-auth).
+     * Consulted only when the env-derived config carries no credentials —
+     * env wins (component invariant 3), so existing refresh-triple and
+     * access-token installs behave exactly as before.
+     */
+    tokenProvider) {
         this.config = config;
+        this.tokenProvider = tokenProvider;
         this.base = config.apiBase.endsWith("/") ? config.apiBase : config.apiBase + "/";
         const drive = config.driveApiBase ?? "https://www.googleapis.com";
         this.driveBase = drive.endsWith("/") ? drive : drive + "/";
@@ -185,6 +194,19 @@ export class GoogleSlidesClient {
     canRefresh() {
         return Boolean(this.config.refreshToken && this.config.clientId && this.config.clientSecret);
     }
+    /**
+     * Whether a 401 is worth one re-mint + replay: either the env config can mint
+     * from its refresh triple, or the provider holds a refresh token (env or
+     * stored login). A static env access token can never be re-minted, so a 401
+     * there is final — replaying it would just burn a second request.
+     */
+    canReplayOn401() {
+        if (this.canRefresh())
+            return true;
+        if (this.config.accessToken)
+            return false;
+        return this.tokenProvider?.canRefresh() ?? false;
+    }
     /**
      * Returns a valid Bearer token. With the refresh triple configured, mints an
      * access token from the refresh token and caches it until shortly before it
@@ -196,9 +218,13 @@ export class GoogleSlidesClient {
      */
     async accessToken(forceRefresh = false) {
         if (!this.canRefresh()) {
-            if (!this.config.accessToken)
-                throw new CredentialsError();
-            return this.config.accessToken;
+            // Env wins over the provider (component invariant 3): a static
+            // GOOGLE_SLIDES_ACCESS_TOKEN keeps behaving exactly as before.
+            if (this.config.accessToken)
+                return this.config.accessToken;
+            if (this.tokenProvider)
+                return this.tokenProvider.getAccessToken(forceRefresh);
+            throw new CredentialsError();
         }
         if (!forceRefresh && this.cachedToken && Date.now() < this.cachedToken.expiresAt) {
             return this.cachedToken.value;
@@ -358,7 +384,7 @@ export class GoogleSlidesClient {
             // eat into the transient-retry budget (attempt-- cancels the loop's
             // attempt++), so a 429/5xx after the re-mint still gets maxRetries
             // tries; refreshedOn401 guarantees this runs at most once.
-            if (res.status === 401 && this.canRefresh() && !refreshedOn401) {
+            if (res.status === 401 && this.canReplayOn401() && !refreshedOn401) {
                 refreshedOn401 = true;
                 await this.accessToken(true);
                 attempt--;
@@ -395,7 +421,7 @@ export class GoogleSlidesClient {
         for (let attempt = 0;; attempt++) {
             const token = await this.accessToken(attempt > 0);
             const { res, bytes } = await this.fetchBytesWithTimeout(url, { method: "GET", headers: { Authorization: `Bearer ${token}` } }, label);
-            if (res.status === 401 && this.canRefresh() && attempt === 0)
+            if (res.status === 401 && this.canReplayOn401() && attempt === 0)
                 continue;
             if (!res.ok) {
                 let parsed;
@@ -917,7 +943,7 @@ export class GoogleSlidesClient {
                 },
                 body,
             }, "drive image upload");
-            if (res.status === 401 && this.canRefresh() && attempt === 0)
+            if (res.status === 401 && this.canReplayOn401() && attempt === 0)
                 continue;
             let parsed;
             try {

package/dist/index.js

@@ -14,6 +14,7 @@ import { registerNoteTools } from "./tools/notes.js";
 import { registerCommentTools } from "./tools/comments.js";
 import { registerExportTools } from "./tools/export.js";
 import { registerRawTool } from "./tools/raw.js";
+import { authUnconfiguredPrefix, hasAuthToken, registerAuthTools } from "./tools/auth.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,
@@ -40,11 +41,6 @@ const INSTRUCTIONS = "Google Slides API v1 builds and edits presentations — no
  * 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 {
@@ -88,10 +84,9 @@ async function main() {
     // 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 connected = hasCredentials(config) || hasAuthToken();
     const server = new McpServer({
         name: "mcp-google-slides",
         version: readVersion(),
@@ -100,7 +95,7 @@ async function main() {
     {
         instructions: connected
             ? INSTRUCTIONS
-            : UNCONFIGURED_PREFIX + (problem ? `Configuration problem: ${problem.message} ` : "") + INSTRUCTIONS,
+            : authUnconfiguredPrefix() + (problem ? `Configuration problem: ${problem.message} ` : "") + INSTRUCTIONS,
     });
     instrumentToolCalls(server, telemetry);
     server.server.oninitialized = () => {
@@ -112,6 +107,11 @@ async function main() {
         else
             telemetry.send("unconfigured_start", { reason: problem?.reason ?? "missing_credentials" });
     };
+    // The auth tools come first so their TokenProvider exists before the client:
+    // the client falls back to it whenever the environment carries no
+    // credentials (env always wins — component invariant 3).
+    const tokenProvider = registerAuthTools(server);
+    const client = new GoogleSlidesClient(config, tokenProvider);
     registerPresentationTools(server, client);
     registerSlideTools(server, client);
     registerTextTools(server, client);

package/dist/tools/auth.js

@@ -0,0 +1,39 @@
+import { registerGoogleAuth, TokenProvider, unconfiguredPrefix, } from "@a1-x-tech/mcp-google-auth";
+/**
+ * The scopes an in-chat login requests (the per-task table lives in
+ * docs/TOOLS.md). The component always adds the identity scopes on top. The full `drive` scope rides along because export and comments reach presentations this server did not create; `drive.file` would silently fail on decks the user opened elsewhere.
+ */
+export const LOGIN_SCOPES = [
+    "https://www.googleapis.com/auth/presentations",
+    "https://www.googleapis.com/auth/drive",
+];
+/**
+ * The single source of the auth wiring: serverName "slides" puts the stored
+ * login in ~/.config/mcp-google-slides/credentials.json (the component
+ * prefixes "mcp-google-"), envPrefix keeps the provider reading the exact
+ * GOOGLE_SLIDES_* variables config.ts documents — which is what preserves the
+ * env-beats-stored priority for existing installs.
+ */
+export const AUTH_OPTIONS = {
+    serverName: "slides",
+    envPrefix: "GOOGLE_SLIDES",
+    scopes: LOGIN_SCOPES,
+};
+/**
+ * Registers the six onboarding tools (auth_status, setup_instructions,
+ * set_client, start_login, finish_login, logout) and returns the TokenProvider
+ * the client plugs in as its fallback token source — the same instance, so a
+ * login finished mid-session is visible to the very next API call without a
+ * restart.
+ */
+export function registerAuthTools(server) {
+    return registerGoogleAuth(server, AUTH_OPTIONS);
+}
+/** True when any token exists — env variables or a stored in-chat login. */
+export function hasAuthToken() {
+    return new TokenProvider(AUTH_OPTIONS).hasToken();
+}
+/** The "NOT CONNECTED" prefix for the initialize instructions (names both fixes). */
+export function authUnconfiguredPrefix() {
+    return unconfiguredPrefix(AUTH_OPTIONS);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@a1-x-tech/mcp-google-slides",
-  "version": "0.1.0",
+  "version": "1.0.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",
@@ -51,6 +51,7 @@
     "url": "https://github.com/A1-x-Tech/mcp-google-slides/issues"
   },
   "dependencies": {
+    "@a1-x-tech/mcp-google-auth": "^0.1.0",
     "@modelcontextprotocol/sdk": "^1.29.0",
     "zod": "^3.25.0"
   },

package/test/dist-smoke.test.js

@@ -1,4 +1,7 @@
 import assert from "node:assert/strict";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
 import test from "node:test";
 import { fileURLToPath } from "node:url";
 
@@ -15,9 +18,16 @@ import { registerNoteTools } from "../dist/tools/notes.js";
 import { registerCommentTools } from "../dist/tools/comments.js";
 import { registerExportTools } from "../dist/tools/export.js";
 import { registerRawTool } from "../dist/tools/raw.js";
+import { registerAuthTools } from "../dist/tools/auth.js";
 
+/**
+ * Sorted, because every assertion compares it against a sorted tool list. The
+ * six onboarding tools come from @a1-x-tech/mcp-google-auth, so this list is
+ * also the check that the component is wired into the published binary.
+ */
 const ALL_TOOLS = [
   "add_slide",
+  "auth_status",
   "batch_update",
   "create_image",
   "create_presentation",
@@ -27,6 +37,7 @@ const ALL_TOOLS = [
   "duplicate_slide",
   "edit_table",
   "export_presentation",
+  "finish_login",
   "get_page",
   "get_presentation",
   "get_speaker_notes",
@@ -34,17 +45,34 @@ const ALL_TOOLS = [
   "insert_text",
   "list_layouts",
   "list_slides",
+  "logout",
   "manage_comments",
   "move_slides",
   "raw_request",
   "replace_image",
   "replace_text",
+  "set_client",
   "set_speaker_notes",
   "set_text",
+  "setup_instructions",
+  "start_login",
   "update_text_style",
   "update_transform",
 ];
 
+/**
+ * A throwaway $XDG_CONFIG_HOME for the spawned server. The auth component
+ * re-reads $XDG_CONFIG_HOME/mcp-google-slides/credentials.json per call, so
+ * without this a real login on the developer's machine would make the
+ * "unconfigured" case pass for the wrong reason.
+ */
+function isolatedConfigDir(t) {
+  const dir = mkdtempSync(join(tmpdir(), "mcp-slides-dist-smoke-"));
+  t.after(() => rmSync(dir, { recursive: true, force: true }));
+  return dir;
+}
+
+
 test("dist client rejects foreign-origin paths before sending the Bearer token", async () => {
   const original = globalThis.fetch;
   let called = false;
@@ -98,6 +126,7 @@ test("dist registers the expected tools", () => {
   };
   const client = {};
 
+  registerAuthTools(server, client);
   registerPresentationTools(server, client);
   registerSlideTools(server, client);
   registerTextTools(server, client);
@@ -111,13 +140,14 @@ test("dist registers the expected tools", () => {
   assert.deepEqual(names.sort(), ALL_TOOLS);
 });
 
-test("dist binary completes a real MCP handshake over stdio and lists every tool", async () => {
+test("dist binary completes a real MCP handshake over stdio and lists every tool", async (t) => {
   const transport = new StdioClientTransport({
     command: process.execPath,
     args: [fileURLToPath(new URL("../dist/index.js", import.meta.url))],
     env: {
       ...process.env,
       GOOGLE_SLIDES_ACCESS_TOKEN: "test-token",
+      XDG_CONFIG_HOME: isolatedConfigDir(t),
       ASKADS_TELEMETRY: "0", // keep the suite offline
     },
     stderr: "pipe",
@@ -152,13 +182,14 @@ test("dist binary completes a real MCP handshake over stdio and lists every tool
  * tool call with the actionable error — offline: the CredentialsError fires
  * before any fetch, so this test never touches the network.
  */
-test("dist binary starts without credentials: handshake, tool list, actionable call error", async () => {
+test("dist binary starts without credentials: handshake, tool list, actionable call error", async (t) => {
   const env = Object.fromEntries(
     Object.entries(process.env).filter(
       ([key, value]) => value !== undefined && !key.startsWith("GOOGLE_SLIDES_"),
     ),
   );
   env.ASKADS_TELEMETRY = "0"; // keep the suite offline
+  env.XDG_CONFIG_HOME = isolatedConfigDir(t); // ignore any real login on this machine
   const transport = new StdioClientTransport({
     command: process.execPath,
     args: [fileURLToPath(new URL("../dist/index.js", import.meta.url))],
@@ -170,7 +201,8 @@ test("dist binary starts without credentials: handshake, tool list, actionable c
   try {
     // The model must read the fix before it picks a tool.
     const instructions = client.getInstructions() ?? "";
-    assert.match(instructions, /not connected/);
+    assert.match(instructions, /NOT CONNECTED/);
+    assert.match(instructions, /start_login/);
     assert.match(instructions, /GOOGLE_SLIDES_CLIENT_ID/);
     assert.match(instructions, /restart/);
 
@@ -181,7 +213,8 @@ test("dist binary starts without credentials: handshake, tool list, actionable c
     const result = await client.callTool({ name: "list_slides", arguments: { presentation_id: "smoke-deck" } });
     assert.equal(result.isError, true);
     const text = result.content.map((c) => c.text ?? "").join(" ");
-    assert.match(text, /Google OAuth credentials are required: set GOOGLE_SLIDES_CLIENT_ID/);
+    assert.match(text, /not connected/i);
+    assert.match(text, /start_login/);
     assert.match(text, /restart the server/);
   } finally {
     await client.close();