@a1-x-tech/mcp-google-sheets 1.1.2 → 1.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -56,7 +56,7 @@ Start with a read-only question:
56
56
  You need Node.js 20+ and a Google account. Credentials are not required at install time — the server connects from the conversation.
57
57
 
58
58
  1. Add the server to your AI app.
59
- 2. Say "connect Google Sheets": the assistant walks you through [creating the OAuth client and approving access](#getting-access) without editing config files.
59
+ 2. Say "connect Google Sheets": the assistant gives you a Google sign-in link — [no Google Cloud project or OAuth client to create](#getting-access).
60
60
  3. Ask the read-only question above.
61
61
 
62
62
  <details open>
@@ -64,7 +64,7 @@ You need Node.js 20+ and a Google account. Credentials are not required at insta
64
64
 
65
65
  <br>
66
66
 
67
- **In the app:** open **Settings → MCP servers**, select **Add server**, choose **STDIO**, enter the command `npx -y @a1-x-tech/mcp-google-sheets@latest` and environment variables `GOOGLE_SHEETS_CLIENT_ID`, `GOOGLE_SHEETS_CLIENT_SECRET`, `GOOGLE_SHEETS_REFRESH_TOKEN`, then select **Save** and **Restart**.
67
+ **In the app:** open **Settings → MCP servers**, select **Add server**, choose **STDIO**, enter the command `npx -y @a1-x-tech/mcp-google-sheets@latest`, then select **Save** and **Restart**.
68
68
 
69
69
  **From the command line:**
70
70
 
@@ -230,12 +230,20 @@ Google Sheets requires OAuth 2.0; an API key is not enough. There are two ways i
230
230
 
231
231
  ### Connect from the chat (recommended)
232
232
 
233
- Say "connect Google Sheets" and the assistant runs the flow with you:
233
+ Say "connect Google Sheets". The server ships with a built-in OAuth client, so there is no Google Cloud project or OAuth client to create:
234
+
235
+ 1. `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.
236
+ 2. `finish_login` exchanges the code and saves the tokens to `~/.config/mcp-google-sheets/credentials.json` (mode 0600).
237
+
238
+ Google may show a **"Google hasn't verified this app"** screen while the app's verification is in progress: choose **Advanced → Go to A1 MCP**. The built-in client only identifies the app to Google — the tokens are issued to and stored on your machine, and A1 never receives them.
239
+
240
+ #### Use your own OAuth client
241
+
242
+ The built-in client and its Google API quota are shared by everyone who uses it. Bring your own client to get a quota of your own, or when a Google Workspace admin blocks third-party apps:
234
243
 
235
244
  1. `setup_instructions` prints the checklist: create or select a Google Cloud project, enable **Google Sheets API**, configure the consent screen and create a **Desktop app** OAuth client.
236
- 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.
237
- 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.
238
- 4. `finish_login` exchanges the code and saves the tokens to `~/.config/mcp-google-sheets/credentials.json` (mode 0600).
245
+ 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. From then on it takes priority over the built-in client.
246
+ 3. Run `start_login` and `finish_login` again.
239
247
 
240
248
  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.
241
249
 
@@ -269,7 +277,7 @@ Every variable is optional — with none of them the server connects [from the c
269
277
  | `GOOGLE_SHEETS_TIMEOUT_MS` | No | Per-request timeout; default `60000` ms. |
270
278
  | `GOOGLE_SHEETS_MAX_RETRIES` | No | Temporary-error retries; default `3`. |
271
279
 
272
- \* Provide either the OAuth trio or an access token. Without credentials the server still starts and lists its tools; the first call names the variables to set.
280
+ \* Only for a setup without the in-chat login: provide either the OAuth trio or an access token.
273
281
 
274
282
  ## Data, limits and background work
275
283
 
package/README.ru.md CHANGED
@@ -12,7 +12,7 @@
12
12
  Сервер работает с Google Sheets API через ваш Google-аккаунт. Он разделяет чтение и запись, явно помечает разрушительные операции и честно показывает ограничения Sheets API, а не создаёт впечатление, что с таблицей можно сделать всё.
13
13
 
14
14
  - **26 инструментов.** Поиск и создание таблиц, чтение и запись диапазонов, управление листами, форматированием, проверкой данных, защищёнными диапазонами, условным форматированием, структурированными таблицами, диаграммами и доступом.
15
- - **Подключение из диалога.** Скажите «подключи Google Таблицы»: сервер проведёт через создание OAuth-клиента, поймает редирект Google на `127.0.0.1` с PKCE и сам сохранит токены — без конфигов и перезапуска.
15
+ - **Подключение из диалога.** Скажите «подключи Google Таблицы»: встроенный OAuth-клиент уже есть — сервер даст ссылку на согласие Google, поймает редирект Google на `127.0.0.1` с PKCE и сам сохранит токены — без конфигов и перезапуска.
16
16
  - **Осознанная запись.** Запись никогда не повторяется после неопределённой ошибки — повтор `append` продублировал бы строки, — а разрушительные инструменты помечены, чтобы AI-клиент мог сначала спросить.
17
17
  - **Только Sheets.** Drive — внутренняя зависимость лишь для поиска таблиц и управления доступом; отдельного Drive-инструмента нет, и `raw_request` до Drive не дотягивается.
18
18
  - **Минимальные scope Google.** `spreadsheets` покрывает каждый Sheets-инструмент; scope Drive нужен только для поиска таблиц и управления доступом.
@@ -56,7 +56,7 @@
56
56
  Нужны Node.js 20+ и Google-аккаунт. Учётные данные при установке не нужны: сервер подключается прямо в диалоге.
57
57
 
58
58
  1. Добавьте сервер в AI-приложение.
59
- 2. Скажите «подключи Google Таблицы» — ассистент проведёт [создание OAuth-клиента и выдачу доступа](#как-получить-доступ), не трогая конфиги.
59
+ 2. Скажите «подключи Google Таблицы» — ассистент даст ссылку на согласие Google и [подключит аккаунт](#как-получить-доступ) — без проекта Google Cloud и без правки конфигов.
60
60
  3. Отправьте запрос, который только читает данные.
61
61
 
62
62
  <details open>
@@ -64,7 +64,7 @@
64
64
 
65
65
  <br>
66
66
 
67
- **В приложении:** откройте **Settings → MCP servers**, нажмите **Add server**, выберите **STDIO**, укажите команду `npx -y @a1-x-tech/mcp-google-sheets@latest` и переменные окружения `GOOGLE_SHEETS_CLIENT_ID`, `GOOGLE_SHEETS_CLIENT_SECRET`, `GOOGLE_SHEETS_REFRESH_TOKEN`, затем нажмите **Save**, потом **Restart**.
67
+ **В приложении:** откройте **Settings → MCP servers**, нажмите **Add server**, выберите **STDIO**, укажите команду `npx -y @a1-x-tech/mcp-google-sheets@latest`, затем нажмите **Save**, потом **Restart**.
68
68
 
69
69
  **В командной строке:**
70
70
 
@@ -230,12 +230,20 @@ Google Sheets требует OAuth 2.0: одного API-ключа недост
230
230
 
231
231
  ### Подключение из диалога (рекомендуемый путь)
232
232
 
233
- Скажите «подключи Google Таблицы», и ассистент пройдёт флоу вместе с вами:
233
+ Скажите «подключи Google Таблицы». У сервера есть встроенный OAuth-клиент, поэтому создавать проект Google Cloud и OAuth-клиент не нужно:
234
+
235
+ 1. `start_login` возвращает ссылку на согласие Google. Откройте её **на этой же машине** и подтвердите доступ: код возвращается на одноразовый слушатель `127.0.0.1` (PKCE), а не в чат.
236
+ 2. `finish_login` меняет код на токены и кладёт их в `~/.config/mcp-google-sheets/credentials.json` (права 0600).
237
+
238
+ Пока приложение проходит проверку Google, на шаге согласия может появиться экран **«Google hasn't verified this app»**: выберите **Advanced → Go to A1 MCP**. Встроенный клиент только называет приложение для Google — токены выдаются вашей машине и хранятся на ней, A1 их не получает.
239
+
240
+ #### Свой OAuth-клиент
241
+
242
+ Встроенный клиент и его квоту Google API делят все, кто им пользуется. Свой клиент даёт собственную квоту и нужен, если администратор Google Workspace блокирует сторонние приложения:
234
243
 
235
244
  1. `setup_instructions` выдаёт чек-лист: создать или выбрать проект Google Cloud, включить **Google Sheets API**, настроить consent screen и создать OAuth-клиент типа **Desktop app**.
236
- 2. Скачайте JSON этого клиента («Download JSON») и передайте ассистенту **путь** к файлу — `set_client` сохранит его с правами только для владельца. Секрет через переписку не проходит.
237
- 3. `start_login` возвращает ссылку на согласие Google. Откройте её **на этой же машине** и подтвердите доступ: код возвращается на одноразовый слушатель `127.0.0.1` (PKCE), а не в чат.
238
- 4. `finish_login` меняет код на токены и кладёт их в `~/.config/mcp-google-sheets/credentials.json` (права 0600).
245
+ 2. Скачайте JSON этого клиента («Download JSON») и передайте ассистенту **путь** к файлу — `set_client` сохранит его с правами только для владельца. Секрет через переписку не проходит. С этого момента он имеет приоритет над встроенным.
246
+ 3. Снова выполните `start_login` и `finish_login`.
239
247
 
240
248
  Токены перечитываются на каждый вызов, поэтому подключение действует немедленно — перезапускать AI-приложение не нужно. `auth_status` показывает состояние, `logout` отзывает токен и удаляет его.
241
249
 
@@ -269,7 +277,7 @@ Refresh token OAuth-приложения в режиме Testing может ис
269
277
  | `GOOGLE_SHEETS_TIMEOUT_MS` | Нет | Тайм-аут одного запроса; по умолчанию `60000` мс. |
270
278
  | `GOOGLE_SHEETS_MAX_RETRIES` | Нет | Повторы временных ошибок; по умолчанию `3`. |
271
279
 
272
- \* Передайте OAuth-тройку или access token. Без учётных данных сервер всё равно запустится и покажет инструменты; первый вызов назовёт переменные, которые нужно задать.
280
+ \* Нужны только для установки без входа из диалога: передайте OAuth-тройку или access token.
273
281
 
274
282
  ## Данные, лимиты и работа в фоне
275
283
 
@@ -1,4 +1,4 @@
1
- import { registerGoogleAuth, TokenProvider, unconfiguredPrefix, } from "@a1-x-tech/mcp-google-auth";
1
+ import { A1_DEFAULT_CLIENT, registerGoogleAuth, TokenProvider, unconfiguredPrefix, } from "@a1-x-tech/mcp-google-auth";
2
2
  import { fail } from "./util.js";
3
3
  /**
4
4
  * The scopes an in-chat login requests (the per-task table lives in
@@ -18,6 +18,8 @@ export const AUTH_OPTIONS = {
18
18
  serverName: "sheets",
19
19
  envPrefix: "GOOGLE_SHEETS",
20
20
  scopes: LOGIN_SCOPES,
21
+ // Built-in A1 OAuth client: login without a Google Cloud project. Env and set_client still win.
22
+ defaultClient: A1_DEFAULT_CLIENT,
21
23
  // Login-tool failures go through the server's own renderer, so telemetry gets their origin.
22
24
  fail,
23
25
  };
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@a1-x-tech/mcp-google-sheets",
3
- "version": "1.1.2",
3
+ "version": "1.2.0",
4
4
  "description": "MCP server for the Google Sheets API — search spreadsheets, read and write ranges, manage sheets, formatting, validation, protected ranges, tables, charts and sharing. For Claude, Cursor, Codex and other AI clients.",
5
5
  "mcpName": "io.github.A1-x-Tech/mcp-google-sheets",
6
6
  "type": "module",
@@ -52,7 +52,7 @@
52
52
  "url": "https://github.com/A1-x-Tech/mcp-google-sheets/issues"
53
53
  },
54
54
  "dependencies": {
55
- "@a1-x-tech/mcp-google-auth": "^0.1.2",
55
+ "@a1-x-tech/mcp-google-auth": "^0.1.3",
56
56
  "@modelcontextprotocol/sdk": "^1.29.0",
57
57
  "zod": "^3.25.0"
58
58
  },