mcp-google-tasks 0.1.0 → 1.0.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
@@ -3,15 +3,16 @@
3
3
  **English** | [Русский](./README.ru.md)
4
4
 
5
5
  [![npm](https://img.shields.io/npm/v/mcp-google-tasks)](https://www.npmjs.com/package/mcp-google-tasks)
6
- [![CI](https://github.com/A1-x-Tech/mcp-google-tasks/actions/workflows/ci.yml/badge.svg)](https://github.com/A1-x-Tech/mcp-google-tasks/actions/workflows/ci.yml)
7
6
  [![Glama](https://glama.ai/mcp/servers/A1-x-Tech/mcp-google-tasks/badges/score.svg)](https://glama.ai/mcp/servers/A1-x-Tech/mcp-google-tasks)
7
+ [![CI](https://github.com/A1-x-Tech/mcp-google-tasks/actions/workflows/ci.yml/badge.svg)](https://github.com/A1-x-Tech/mcp-google-tasks/actions/workflows/ci.yml)
8
8
  [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
9
9
 
10
10
  **A1 Google Tasks MCP** lets an AI app manage Google Tasks in plain language. Plan a project as a task list, break work into subtasks with due dates and notes, mark things done and keep everything in order.
11
11
 
12
12
  It uses the Google Tasks API with your Google account. It separates reversible completion from permanent deletion and makes the limits of the Tasks API explicit instead of implying that every to-do feature is possible.
13
13
 
14
- - **15 tools.** List, create and update task lists and tasks, move tasks, manage completion, sweep finished work and reach the raw API when a dedicated tool is missing.
14
+ - **21 tools.** List, create and update task lists and tasks, move tasks, manage completion, sweep finished work and reach the raw API when a dedicated tool is missing.
15
+ - **Connects from the conversation.** Say "connect Google Tasks": 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.
15
16
  - **Completion is reversible, deletion is not.** `complete_task` has an undo (`reopen_task`); the delete tools are separate and marked destructive.
16
17
  - **Due dates are honest.** The API stores only the calendar date — the server never pretends to schedule a time of day; times belong in the notes.
17
18
  - **Minimal Google scope.** A single `tasks` scope, without Drive, Calendar or Gmail access.
@@ -52,10 +53,10 @@ Start with a read-only question:
52
53
 
53
54
  ## Quick start
54
55
 
55
- You need Node.js 20+, a Google account and OAuth credentials from a Google Cloud project with the Google Tasks API enabled.
56
+ You need Node.js 20+ and a Google account. Credentials are not required at install time — the server connects from the conversation.
56
57
 
57
- 1. [Prepare Google OAuth access](#getting-access).
58
- 2. Add the server to your AI app.
58
+ 1. Add the server to your AI app.
59
+ 2. Say "connect Google Tasks": the assistant walks you through [creating the OAuth client and approving access](#getting-access) without editing config files.
59
60
  3. Ask the read-only question above.
60
61
 
61
62
  <details open>
@@ -63,15 +64,12 @@ You need Node.js 20+, a Google account and OAuth credentials from a Google Cloud
63
64
 
64
65
  <br>
65
66
 
66
- **In the app:** open **Settings → Plugins → MCP servers**, select **Add server**, then add `npx -y mcp-google-tasks@latest` with `GOOGLE_TASKS_CLIENT_ID`, `GOOGLE_TASKS_CLIENT_SECRET` and `GOOGLE_TASKS_REFRESH_TOKEN`.
67
+ **In the app:** open **Settings → MCP servers**, select **Add server**, choose **STDIO**, enter the command `npx -y mcp-google-tasks@latest` and environment variables `GOOGLE_TASKS_CLIENT_ID`, `GOOGLE_TASKS_CLIENT_SECRET`, `GOOGLE_TASKS_REFRESH_TOKEN`, then select **Save** and **Restart**.
67
68
 
68
69
  **From the command line:**
69
70
 
70
71
  ```bash
71
72
  codex mcp add google-tasks \
72
- --env GOOGLE_TASKS_CLIENT_ID=your_client_id \
73
- --env GOOGLE_TASKS_CLIENT_SECRET=your_client_secret \
74
- --env GOOGLE_TASKS_REFRESH_TOKEN=your_refresh_token \
75
73
  -- npx -y mcp-google-tasks@latest
76
74
  ```
77
75
 
@@ -90,9 +88,6 @@ codex mcp list
90
88
 
91
89
  ```bash
92
90
  claude mcp add \
93
- --env GOOGLE_TASKS_CLIENT_ID=your_client_id \
94
- --env GOOGLE_TASKS_CLIENT_SECRET=your_client_secret \
95
- --env GOOGLE_TASKS_REFRESH_TOKEN=your_refresh_token \
96
91
  --transport stdio --scope user google-tasks \
97
92
  -- npx -y mcp-google-tasks@latest
98
93
  ```
@@ -110,25 +105,22 @@ claude mcp list
110
105
 
111
106
  <br>
112
107
 
113
- Open **Settings → Developer → Edit Config** and add:
108
+ 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.
109
+
110
+ 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:
114
111
 
115
112
  ```json
116
113
  {
117
114
  "mcpServers": {
118
115
  "google-tasks": {
119
116
  "command": "npx",
120
- "args": ["-y", "mcp-google-tasks@latest"],
121
- "env": {
122
- "GOOGLE_TASKS_CLIENT_ID": "your_client_id",
123
- "GOOGLE_TASKS_CLIENT_SECRET": "your_client_secret",
124
- "GOOGLE_TASKS_REFRESH_TOKEN": "your_refresh_token"
125
- }
117
+ "args": ["-y", "mcp-google-tasks@latest"]
126
118
  }
127
119
  }
128
120
  }
129
121
  ```
130
122
 
131
- 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.
123
+ 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.
132
124
 
133
125
  [Claude Desktop MCP documentation](https://support.claude.com/en/articles/10949351-getting-started-with-local-mcp-servers-on-claude-desktop)
134
126
 
@@ -147,12 +139,7 @@ Add this to `~/.cursor/mcp.json` on macOS/Linux or `%USERPROFILE%\.cursor\mcp.js
147
139
  "google-tasks": {
148
140
  "type": "stdio",
149
141
  "command": "npx",
150
- "args": ["-y", "mcp-google-tasks@latest"],
151
- "env": {
152
- "GOOGLE_TASKS_CLIENT_ID": "your_client_id",
153
- "GOOGLE_TASKS_CLIENT_SECRET": "your_client_secret",
154
- "GOOGLE_TASKS_REFRESH_TOKEN": "your_refresh_token"
155
- }
142
+ "args": ["-y", "mcp-google-tasks@latest"]
156
143
  }
157
144
  }
158
145
  }
@@ -175,19 +162,9 @@ Run **MCP: Open User Configuration** and add:
175
162
  "google-tasks": {
176
163
  "type": "stdio",
177
164
  "command": "npx",
178
- "args": ["-y", "mcp-google-tasks@latest"],
179
- "env": {
180
- "GOOGLE_TASKS_CLIENT_ID": "${input:tasks_client_id}",
181
- "GOOGLE_TASKS_CLIENT_SECRET": "${input:tasks_client_secret}",
182
- "GOOGLE_TASKS_REFRESH_TOKEN": "${input:tasks_refresh_token}"
183
- }
165
+ "args": ["-y", "mcp-google-tasks@latest"]
184
166
  }
185
- },
186
- "inputs": [
187
- { "type": "promptString", "id": "tasks_client_id", "description": "Google OAuth client ID" },
188
- { "type": "promptString", "id": "tasks_client_secret", "description": "Google OAuth client secret", "password": true },
189
- { "type": "promptString", "id": "tasks_refresh_token", "description": "Google OAuth refresh token", "password": true }
190
- ]
167
+ }
191
168
  }
192
169
  ```
193
170
 
@@ -243,7 +220,20 @@ The AI client controls confirmation prompts. The server marks reads, writes and
243
220
 
244
221
  ## Getting access
245
222
 
246
- Google Tasks requires OAuth 2.0; an API key is not enough.
223
+ Google Tasks requires OAuth 2.0; an API key is not enough. There are two ways in, and the first one needs no configuration files.
224
+
225
+ ### Connect from the chat (recommended)
226
+
227
+ Say "connect Google Tasks" and the assistant runs the flow with you:
228
+
229
+ 1. `setup_instructions` prints the checklist: create or select a Google Cloud project, enable **Google Tasks API**, configure the consent screen and create a **Desktop app** OAuth client.
230
+ 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.
231
+ 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.
232
+ 4. `finish_login` exchanges the code and saves the tokens to `~/.config/mcp-google-tasks/credentials.json` (mode 0600) and verifies them with a real Google Tasks API call — so an API that is still switched off is caught right there.
233
+
234
+ 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.
235
+
236
+ ### Environment variables (CI, unattended installs)
247
237
 
248
238
  1. Create or select a Google Cloud project and enable **Google Tasks API**.
249
239
  2. Configure the OAuth consent screen and create a **Desktop app** OAuth client.
@@ -258,12 +248,15 @@ Testing-mode OAuth refresh tokens can expire after seven days. Publish the OAuth
258
248
 
259
249
  ## Configuration
260
250
 
251
+ Every variable is optional — with none of them the server connects [from the chat](#connect-from-the-chat-recommended).
252
+
261
253
  | Variable | Required | Description |
262
254
  |---|---|---|
263
- | `GOOGLE_TASKS_CLIENT_ID` | Yes* | OAuth client ID. |
264
- | `GOOGLE_TASKS_CLIENT_SECRET` | Yes* | OAuth client secret. |
265
- | `GOOGLE_TASKS_REFRESH_TOKEN` | Yes* | OAuth refresh token. |
266
- | `GOOGLE_TASKS_ACCESS_TOKEN` | Yes* | Short-lived alternative to the OAuth trio. |
255
+ | `GOOGLE_TASKS_CLIENT_ID` | No* | OAuth client ID. |
256
+ | `GOOGLE_TASKS_CLIENT_SECRET` | No* | OAuth client secret. |
257
+ | `GOOGLE_TASKS_REFRESH_TOKEN` | No* | OAuth refresh token. |
258
+ | `GOOGLE_TASKS_ACCESS_TOKEN` | No* | Short-lived alternative to the OAuth trio. |
259
+ | `GOOGLE_TASKS_OAUTH_PORT` | No | Fixed loopback port for the in-chat login; useful over SSH port forwarding. |
267
260
  | `GOOGLE_TASKS_API_BASE` | No | Google Tasks API base URL override. |
268
261
  | `GOOGLE_TASKS_TIMEOUT_MS` | No | Per-request timeout; default `60000` ms. |
269
262
  | `GOOGLE_TASKS_MAX_RETRIES` | No | Temporary-error retries; default `3`. |
package/README.ru.md CHANGED
@@ -11,7 +11,8 @@
11
11
 
12
12
  Сервер работает с Google Tasks API через ваш Google-аккаунт. Он отделяет обратимое завершение от безвозвратного удаления и явно показывает ограничения Tasks API, а не создаёт впечатление, что планировщику доступно всё.
13
13
 
14
- - **15 инструментов.** Просмотр, создание и изменение списков и задач, перемещение задач, управление завершением, массовая очистка сделанного и прямой вызов API, когда отдельного инструмента нет.
14
+ - **21 инструментов.** Просмотр, создание и изменение списков и задач, перемещение задач, управление завершением, массовая очистка сделанного и прямой вызов API, когда отдельного инструмента нет.
15
+ - **Подключение из диалога.** Скажите «подключи Google Задачи»: сервер проведёт через создание OAuth-клиента, поймает редирект Google на `127.0.0.1` с PKCE и сам сохранит токены — без конфигов и перезапуска.
15
16
  - **Завершение обратимо, удаление — нет.** У `complete_task` есть отмена (`reopen_task`); инструменты удаления отделены и помечены как разрушительные.
16
17
  - **Честные сроки.** API хранит только календарную дату — сервер не изображает планирование по часам; время дня записывается в заметки.
17
18
  - **Минимальный scope Google.** Единственный scope `tasks` — без доступа к Drive, Calendar и Gmail.
@@ -52,10 +53,10 @@
52
53
 
53
54
  ## Быстрый старт
54
55
 
55
- Нужны Node.js 20+, Google-аккаунт и OAuth-данные из проекта Google Cloud с включённым Google Tasks API.
56
+ Нужны Node.js 20+ и Google-аккаунт. Учётные данные при установке не нужны: сервер подключается прямо в диалоге.
56
57
 
57
- 1. [Подготовьте Google OAuth-доступ](#как-получить-доступ).
58
- 2. Добавьте сервер в AI-приложение.
58
+ 1. Добавьте сервер в AI-приложение.
59
+ 2. Скажите «подключи Google Задачи» — ассистент проведёт [создание OAuth-клиента и выдачу доступа](#как-получить-доступ), не трогая конфиги.
59
60
  3. Отправьте запрос, который только читает данные.
60
61
 
61
62
  <details open>
@@ -63,15 +64,12 @@
63
64
 
64
65
  <br>
65
66
 
66
- **В приложении:** откройте **Settings → Plugins → MCP servers**, нажмите **Add server**, затем добавьте `npx -y mcp-google-tasks@latest` с `GOOGLE_TASKS_CLIENT_ID`, `GOOGLE_TASKS_CLIENT_SECRET` и `GOOGLE_TASKS_REFRESH_TOKEN`.
67
+ **В приложении:** откройте **Settings → MCP servers**, нажмите **Add server**, выберите **STDIO**, укажите команду `npx -y mcp-google-tasks@latest` и переменные окружения `GOOGLE_TASKS_CLIENT_ID`, `GOOGLE_TASKS_CLIENT_SECRET`, `GOOGLE_TASKS_REFRESH_TOKEN`, затем нажмите **Save**, потом **Restart**.
67
68
 
68
69
  **В командной строке:**
69
70
 
70
71
  ```bash
71
72
  codex mcp add google-tasks \
72
- --env GOOGLE_TASKS_CLIENT_ID=your_client_id \
73
- --env GOOGLE_TASKS_CLIENT_SECRET=your_client_secret \
74
- --env GOOGLE_TASKS_REFRESH_TOKEN=your_refresh_token \
75
73
  -- npx -y mcp-google-tasks@latest
76
74
  ```
77
75
 
@@ -90,9 +88,6 @@ codex mcp list
90
88
 
91
89
  ```bash
92
90
  claude mcp add \
93
- --env GOOGLE_TASKS_CLIENT_ID=your_client_id \
94
- --env GOOGLE_TASKS_CLIENT_SECRET=your_client_secret \
95
- --env GOOGLE_TASKS_REFRESH_TOKEN=your_refresh_token \
96
91
  --transport stdio --scope user google-tasks \
97
92
  -- npx -y mcp-google-tasks@latest
98
93
  ```
@@ -110,25 +105,22 @@ claude mcp list
110
105
 
111
106
  <br>
112
107
 
113
- Откройте **Settings → Developer → Edit Config** и добавьте:
108
+ Актуальный официальный путь — **Settings → Extensions**. Для пользовательского desktop extension откройте **Advanced settings → Extension Developer → Install Extension…**, выберите файл `.mcpb` и следуйте подсказкам.
109
+
110
+ Этот репозиторий сейчас публикует npm-пакет со stdio и пока не содержит `.mcpb`. Поэтому используйте приведённый ниже JSON stdio-конфиг как fallback только в сборках Claude Desktop, где ещё поддерживается локальная конфигурация:
114
111
 
115
112
  ```json
116
113
  {
117
114
  "mcpServers": {
118
115
  "google-tasks": {
119
116
  "command": "npx",
120
- "args": ["-y", "mcp-google-tasks@latest"],
121
- "env": {
122
- "GOOGLE_TASKS_CLIENT_ID": "your_client_id",
123
- "GOOGLE_TASKS_CLIENT_SECRET": "your_client_secret",
124
- "GOOGLE_TASKS_REFRESH_TOKEN": "your_refresh_token"
125
- }
117
+ "args": ["-y", "mcp-google-tasks@latest"]
126
118
  }
127
119
  }
128
120
  }
129
121
  ```
130
122
 
131
- Если **Edit Config** недоступна, отредактируйте `~/Library/Application Support/Claude/claude_desktop_config.json` на macOS или `%APPDATA%\Claude\claude_desktop_config.json` на Windows.
123
+ В таких сборках сохраните его в `~/Library/Application Support/Claude/claude_desktop_config.json` на macOS или `%APPDATA%\Claude\claude_desktop_config.json` на Windows.
132
124
 
133
125
  [Документация Claude Desktop MCP](https://support.claude.com/en/articles/10949351-getting-started-with-local-mcp-servers-on-claude-desktop)
134
126
 
@@ -147,12 +139,7 @@ claude mcp list
147
139
  "google-tasks": {
148
140
  "type": "stdio",
149
141
  "command": "npx",
150
- "args": ["-y", "mcp-google-tasks@latest"],
151
- "env": {
152
- "GOOGLE_TASKS_CLIENT_ID": "your_client_id",
153
- "GOOGLE_TASKS_CLIENT_SECRET": "your_client_secret",
154
- "GOOGLE_TASKS_REFRESH_TOKEN": "your_refresh_token"
155
- }
142
+ "args": ["-y", "mcp-google-tasks@latest"]
156
143
  }
157
144
  }
158
145
  }
@@ -175,19 +162,9 @@ claude mcp list
175
162
  "google-tasks": {
176
163
  "type": "stdio",
177
164
  "command": "npx",
178
- "args": ["-y", "mcp-google-tasks@latest"],
179
- "env": {
180
- "GOOGLE_TASKS_CLIENT_ID": "${input:tasks_client_id}",
181
- "GOOGLE_TASKS_CLIENT_SECRET": "${input:tasks_client_secret}",
182
- "GOOGLE_TASKS_REFRESH_TOKEN": "${input:tasks_refresh_token}"
183
- }
165
+ "args": ["-y", "mcp-google-tasks@latest"]
184
166
  }
185
- },
186
- "inputs": [
187
- { "type": "promptString", "id": "tasks_client_id", "description": "Google OAuth client ID" },
188
- { "type": "promptString", "id": "tasks_client_secret", "description": "Google OAuth client secret", "password": true },
189
- { "type": "promptString", "id": "tasks_refresh_token", "description": "Google OAuth refresh token", "password": true }
190
- ]
167
+ }
191
168
  }
192
169
  ```
193
170
 
@@ -243,7 +220,20 @@ claude mcp list
243
220
 
244
221
  ## Как получить доступ
245
222
 
246
- Google Tasks требует OAuth 2.0: одного API-ключа недостаточно.
223
+ Google Tasks требует OAuth 2.0: одного API-ключа недостаточно. Путей два, и первый не требует править конфигурационные файлы.
224
+
225
+ ### Подключение из диалога (рекомендуемый путь)
226
+
227
+ Скажите «подключи Google Задачи», и ассистент пройдёт флоу вместе с вами:
228
+
229
+ 1. `setup_instructions` выдаёт чек-лист: создать или выбрать проект Google Cloud, включить **Google Tasks API**, настроить consent screen и создать OAuth-клиент типа **Desktop app**.
230
+ 2. Скачайте JSON этого клиента («Download JSON») и передайте ассистенту **путь** к файлу — `set_client` сохранит его с правами только для владельца. Секрет через переписку не проходит.
231
+ 3. `start_login` возвращает ссылку на согласие Google. Откройте её **на этой же машине** и подтвердите доступ: код возвращается на одноразовый слушатель `127.0.0.1` (PKCE), а не в чат.
232
+ 4. `finish_login` меняет код на токены и кладёт их в `~/.config/mcp-google-tasks/credentials.json` (права 0600) и проверяет их реальным вызовом Google Tasks API — так невключённый API ловится сразу.
233
+
234
+ Токены перечитываются на каждый вызов, поэтому подключение действует немедленно — перезапускать AI-приложение не нужно. `auth_status` показывает состояние, `logout` отзывает токен и удаляет его.
235
+
236
+ ### Переменные окружения (CI и автоматические установки)
247
237
 
248
238
  1. Создайте или выберите проект Google Cloud и включите **Google Tasks API**.
249
239
  2. Настройте OAuth consent screen и создайте OAuth-клиент типа **Desktop app**.
@@ -258,12 +248,15 @@ Refresh token OAuth-приложения в режиме Testing может ис
258
248
 
259
249
  ## Конфигурация
260
250
 
251
+ Все переменные необязательные — без единой из них сервер подключается [из диалога](#подключение-из-диалога-рекомендуемый-путь).
252
+
261
253
  | Переменная | Обязательна | Описание |
262
254
  |---|---|---|
263
- | `GOOGLE_TASKS_CLIENT_ID` | Да* | OAuth client ID. |
264
- | `GOOGLE_TASKS_CLIENT_SECRET` | Да* | OAuth client secret. |
265
- | `GOOGLE_TASKS_REFRESH_TOKEN` | Да* | OAuth refresh token. |
266
- | `GOOGLE_TASKS_ACCESS_TOKEN` | Да* | Короткоживущая альтернатива OAuth-тройке. |
255
+ | `GOOGLE_TASKS_CLIENT_ID` | Нет* | OAuth client ID. |
256
+ | `GOOGLE_TASKS_CLIENT_SECRET` | Нет* | OAuth client secret. |
257
+ | `GOOGLE_TASKS_REFRESH_TOKEN` | Нет* | OAuth refresh token. |
258
+ | `GOOGLE_TASKS_ACCESS_TOKEN` | Нет* | Короткоживущая альтернатива OAuth-тройке. |
259
+ | `GOOGLE_TASKS_OAUTH_PORT` | Нет | Фиксированный порт loopback-слушателя для входа из диалога; нужен при пробросе портов по SSH. |
267
260
  | `GOOGLE_TASKS_API_BASE` | Нет | Переопределяет базовый URL Google Tasks API. |
268
261
  | `GOOGLE_TASKS_TIMEOUT_MS` | Нет | Тайм-аут одного запроса; по умолчанию `60000` мс. |
269
262
  | `GOOGLE_TASKS_MAX_RETRIES` | Нет | Повторы временных ошибок; по умолчанию `3`. |
package/dist/client.js CHANGED
@@ -1,5 +1,5 @@
1
1
  import { GoogleTasksError } from "./types.js";
2
- import { CredentialsError } from "./config.js";
2
+ import { CredentialsError, DEFAULT_BASE } from "./config.js";
3
3
  /** Google's OAuth2 token endpoint — refresh tokens are exchanged here. */
4
4
  const TOKEN_URL = "https://oauth2.googleapis.com/token";
5
5
  /** The task-lists collection lives under the authenticated user, not a path parameter. */
@@ -14,6 +14,7 @@ export function normalizeDueDate(due) {
14
14
  }
15
15
  export class GoogleTasksClient {
16
16
  config;
17
+ tokenProvider;
17
18
  base;
18
19
  timeoutMs;
19
20
  maxRetries;
@@ -22,8 +23,16 @@ export class GoogleTasksClient {
22
23
  cachedToken;
23
24
  /** In-flight refresh, deduping concurrent token requests. */
24
25
  refreshInFlight;
25
- constructor(config) {
26
+ constructor(config,
27
+ /**
28
+ * Fallback token source (the in-chat login of @a1-x-tech/mcp-google-auth).
29
+ * Consulted only when the env-derived config carries no credentials —
30
+ * env wins (component invariant 3), so existing refresh-triple and
31
+ * access-token installs behave exactly as before.
32
+ */
33
+ tokenProvider) {
26
34
  this.config = config;
35
+ this.tokenProvider = tokenProvider;
27
36
  this.base = config.apiBase.endsWith("/") ? config.apiBase : config.apiBase + "/";
28
37
  this.timeoutMs = config.timeoutMs ?? 60_000;
29
38
  this.maxRetries = config.maxRetries ?? 3;
@@ -32,6 +41,19 @@ export class GoogleTasksClient {
32
41
  canRefresh() {
33
42
  return Boolean(this.config.refreshToken && this.config.clientId && this.config.clientSecret);
34
43
  }
44
+ /**
45
+ * Whether a 401 is worth one re-mint + replay: either the env config can mint
46
+ * from its refresh triple, or the provider holds a refresh token (env or
47
+ * stored login). A static env access token can never be re-minted, so a 401
48
+ * there is final — replaying it would just burn a second request.
49
+ */
50
+ canReplayOn401() {
51
+ if (this.canRefresh())
52
+ return true;
53
+ if (this.config.accessToken)
54
+ return false;
55
+ return this.tokenProvider?.canRefresh() ?? false;
56
+ }
35
57
  /**
36
58
  * Returns a valid Bearer token. With the refresh triple configured, mints an
37
59
  * access token from the refresh token and caches it until shortly before it
@@ -43,9 +65,13 @@ export class GoogleTasksClient {
43
65
  */
44
66
  async accessToken(forceRefresh = false) {
45
67
  if (!this.canRefresh()) {
46
- if (!this.config.accessToken)
47
- throw new CredentialsError();
48
- return this.config.accessToken;
68
+ // Env wins over the provider (component invariant 3): a static
69
+ // GOOGLE_TASKS_ACCESS_TOKEN keeps behaving exactly as before.
70
+ if (this.config.accessToken)
71
+ return this.config.accessToken;
72
+ if (this.tokenProvider)
73
+ return this.tokenProvider.getAccessToken(forceRefresh);
74
+ throw new CredentialsError();
49
75
  }
50
76
  if (!forceRefresh && this.cachedToken && Date.now() < this.cachedToken.expiresAt) {
51
77
  return this.cachedToken.value;
@@ -173,7 +199,7 @@ export class GoogleTasksClient {
173
199
  }
174
200
  // An expired/revoked access token: re-mint once and replay. The request
175
201
  // never executed, so this is safe for writes too.
176
- if (res.status === 401 && this.canRefresh() && !refreshedOn401) {
202
+ if (res.status === 401 && this.canReplayOn401() && !refreshedOn401) {
177
203
  refreshedOn401 = true;
178
204
  await this.accessToken(true);
179
205
  continue;
@@ -331,3 +357,28 @@ function compact(obj) {
331
357
  function delay(ms) {
332
358
  return new Promise((resolve) => setTimeout(resolve, ms));
333
359
  }
360
+ /**
361
+ * One cheap Google Tasks read, used to verify a fresh in-chat login against the
362
+ * API the server actually talks to. Standalone (not a client method) because it
363
+ * runs with a token the client does not hold yet — the login is still being
364
+ * finished. Throws GoogleTasksError exactly like the client does, so the caller
365
+ * can recognize a disabled-API 403 and give the actionable advice.
366
+ */
367
+ export async function probeApi(accessToken) {
368
+ const base = (process.env.GOOGLE_TASKS_API_BASE || DEFAULT_BASE).replace(/\/+$/, "");
369
+ const res = await fetch(`${base}/tasks/v1/users/@me/lists?maxResults=1`, {
370
+ headers: { Authorization: `Bearer ${accessToken}` },
371
+ signal: AbortSignal.timeout(10_000),
372
+ });
373
+ const text = await res.text();
374
+ if (res.ok)
375
+ return;
376
+ let data;
377
+ try {
378
+ data = JSON.parse(text);
379
+ }
380
+ catch {
381
+ data = text;
382
+ }
383
+ throw new GoogleTasksError(res.status, data);
384
+ }
package/dist/index.js CHANGED
@@ -9,6 +9,7 @@ import { registerTaskListTools } from "./tools/tasklists.js";
9
9
  import { registerTaskTools } from "./tools/tasks.js";
10
10
  import { registerCompletionTools } from "./tools/completion.js";
11
11
  import { registerRawTool } from "./tools/raw.js";
12
+ import { authUnconfiguredPrefix, hasAuthToken, registerAuthTools } from "./tools/auth.js";
12
13
  /**
13
14
  * Prose handed to the calling model in the `initialize` result — the only place
14
15
  * it learns what the tool list cannot say: which Google product this API is,
@@ -36,11 +37,6 @@ const INSTRUCTIONS = "Google Tasks API v1 manages the user's Google Tasks lists
36
37
  * rather than with a failed call. There is no in-chat login here: credentials
37
38
  * come only from the environment, so the fix is an operator action + restart.
38
39
  */
39
- const UNCONFIGURED_PREFIX = "ATTENTION: Google Tasks is not connected yet — no credentials are configured, so every " +
40
- "tool call will fail. The operator must set GOOGLE_TASKS_CLIENT_ID + " +
41
- "GOOGLE_TASKS_CLIENT_SECRET + GOOGLE_TASKS_REFRESH_TOKEN (recommended), or " +
42
- "GOOGLE_TASKS_ACCESS_TOKEN with a short-lived access token, in the MCP client's " +
43
- "server config and restart this server — the variables are read only at startup. ";
44
40
  /** Reads the package version so the server reports its real version to MCP clients. */
45
41
  function readVersion() {
46
42
  try {
@@ -81,10 +77,9 @@ async function main() {
81
77
  // credentials can be reported; wired to the server before tools register.
82
78
  const telemetry = new Telemetry(readVersion());
83
79
  const { config, problem } = loadConfigOrDegraded(telemetry);
84
- const client = new GoogleTasksClient(config);
85
80
  // Decided once, at startup: credentials come only from the environment, so
86
81
  // "restart after setting the variables" is the accurate advice to give.
87
- const connected = hasCredentials(config);
82
+ const connected = hasCredentials(config) || hasAuthToken();
88
83
  const server = new McpServer({
89
84
  name: "mcp-google-tasks",
90
85
  version: readVersion(),
@@ -93,7 +88,7 @@ async function main() {
93
88
  {
94
89
  instructions: connected
95
90
  ? INSTRUCTIONS
96
- : UNCONFIGURED_PREFIX + (problem ? `Configuration problem: ${problem.message} ` : "") + INSTRUCTIONS,
91
+ : authUnconfiguredPrefix() + (problem ? `Configuration problem: ${problem.message} ` : "") + INSTRUCTIONS,
97
92
  });
98
93
  instrumentToolCalls(server, telemetry);
99
94
  server.server.oninitialized = () => {
@@ -105,6 +100,11 @@ async function main() {
105
100
  else
106
101
  telemetry.send("unconfigured_start", { reason: problem?.reason ?? "missing_credentials" });
107
102
  };
103
+ // The auth tools come first so their TokenProvider exists before the client:
104
+ // the client falls back to it whenever the environment carries no
105
+ // credentials (env always wins — component invariant 3).
106
+ const tokenProvider = registerAuthTools(server);
107
+ const client = new GoogleTasksClient(config, tokenProvider);
108
108
  registerTaskListTools(server, client);
109
109
  registerTaskTools(server, client);
110
110
  registerCompletionTools(server, client);
@@ -0,0 +1,113 @@
1
+ import { OAuthError, registerGoogleAuth, TokenProvider, unconfiguredPrefix, USERINFO_URL, } from "@a1-x-tech/mcp-google-auth";
2
+ import { probeApi } from "../client.js";
3
+ import { GoogleTasksError } from "../types.js";
4
+ /**
5
+ * The scopes an in-chat login requests (the per-task table lives in
6
+ * docs/TOOLS.md). The component always adds the identity scopes on top.
7
+ */
8
+ export const LOGIN_SCOPES = [
9
+ "https://www.googleapis.com/auth/tasks",
10
+ ];
11
+ /**
12
+ * True when a Google API error body says the API itself is switched off in the
13
+ * caller's Cloud project. Google reports this two ways at once and has been
14
+ * migrating between them: the legacy `error.errors[].reason` is
15
+ * `accessNotConfigured`, the newer `error.details[].reason` is
16
+ * `SERVICE_DISABLED`. Either spelling means the same fix, so both are matched.
17
+ */
18
+ function isApiDisabled(body) {
19
+ if (typeof body !== "object" || body === null)
20
+ return false;
21
+ const error = body.error;
22
+ if (typeof error !== "object" || error === null)
23
+ return false;
24
+ const reasons = new Set();
25
+ for (const key of ["errors", "details"]) {
26
+ const list = error[key];
27
+ if (Array.isArray(list)) {
28
+ for (const entry of list) {
29
+ if (typeof entry === "object" && entry !== null) {
30
+ reasons.add(entry.reason);
31
+ }
32
+ }
33
+ }
34
+ }
35
+ return reasons.has("accessNotConfigured") || reasons.has("SERVICE_DISABLED");
36
+ }
37
+ /**
38
+ * `verifyIdentity` for the component: one cheap Google Tasks read, plus the
39
+ * translation the component cannot do itself. An API that is not enabled in the
40
+ * user's Cloud project answers the first call with HTTP 403 — the most likely
41
+ * failure right after a login — as a bare error reading "PERMISSION_DENIED",
42
+ * which sends the user to check permissions they cannot fix. Re-thrown as
43
+ * `OAuthError("accessNotConfigured")` it becomes the real advice: enable the
44
+ * API in the SAME project as the OAuth client.
45
+ *
46
+ * Checking the product API (rather than the component's default OIDC userinfo)
47
+ * is the point: OIDC answers even when Google Tasks API is switched off, so a
48
+ * login would look successful and the first real tool call would fail instead.
49
+ */
50
+ async function verifyIdentity(accessToken) {
51
+ try {
52
+ await probeApi(accessToken);
53
+ }
54
+ catch (error) {
55
+ if (error instanceof GoogleTasksError && error.status === 403 && isApiDisabled(error.body)) {
56
+ throw new OAuthError("accessNotConfigured", "Google Tasks API", error.status);
57
+ }
58
+ throw error;
59
+ }
60
+ return { email: await accountEmail(accessToken) };
61
+ }
62
+ /**
63
+ * The account label shown after a login. Best-effort on purpose: the connection
64
+ * is already proven by the probe above, and failing the whole login over a
65
+ * cosmetic label would be wrong.
66
+ */
67
+ async function accountEmail(accessToken) {
68
+ try {
69
+ const res = await fetch(USERINFO_URL, {
70
+ headers: { Authorization: `Bearer ${accessToken}` },
71
+ signal: AbortSignal.timeout(10_000),
72
+ });
73
+ if (!res.ok)
74
+ return undefined;
75
+ const data = await res.json();
76
+ const email = data.email;
77
+ return typeof email === "string" ? email : undefined;
78
+ }
79
+ catch {
80
+ return undefined;
81
+ }
82
+ }
83
+ /**
84
+ * The single source of the auth wiring: serverName "tasks" puts the stored
85
+ * login in ~/.config/mcp-google-tasks/credentials.json (the component
86
+ * prefixes "mcp-google-"), envPrefix keeps the provider reading the exact
87
+ * GOOGLE_TASKS_* variables config.ts documents — which is what preserves the
88
+ * env-beats-stored priority for existing installs.
89
+ */
90
+ export const AUTH_OPTIONS = {
91
+ serverName: "tasks",
92
+ envPrefix: "GOOGLE_TASKS",
93
+ scopes: LOGIN_SCOPES,
94
+ verifyIdentity,
95
+ };
96
+ /**
97
+ * Registers the six onboarding tools (auth_status, setup_instructions,
98
+ * set_client, start_login, finish_login, logout) and returns the TokenProvider
99
+ * the client plugs in as its fallback token source — the same instance, so a
100
+ * login finished mid-session is visible to the very next API call without a
101
+ * restart.
102
+ */
103
+ export function registerAuthTools(server) {
104
+ return registerGoogleAuth(server, AUTH_OPTIONS);
105
+ }
106
+ /** True when any token exists — env variables or a stored in-chat login. */
107
+ export function hasAuthToken() {
108
+ return new TokenProvider(AUTH_OPTIONS).hasToken();
109
+ }
110
+ /** The "NOT CONNECTED" prefix for the initialize instructions (names both fixes). */
111
+ export function authUnconfiguredPrefix() {
112
+ return unconfiguredPrefix(AUTH_OPTIONS);
113
+ }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "mcp-google-tasks",
3
- "version": "0.1.0",
3
+ "version": "1.0.0",
4
4
  "description": "MCP server for the Google Tasks API — manage task lists, create and organize tasks with due dates, notes and subtasks, track completion and sync changes. For Claude, Cursor, Codex and other AI clients.",
5
5
  "mcpName": "io.github.A1-x-Tech/mcp-google-tasks",
6
6
  "type": "module",
@@ -49,6 +49,7 @@
49
49
  "url": "https://github.com/A1-x-Tech/mcp-google-tasks/issues"
50
50
  },
51
51
  "dependencies": {
52
+ "@a1-x-tech/mcp-google-auth": "^0.1.0",
52
53
  "@modelcontextprotocol/sdk": "^1.29.0",
53
54
  "zod": "^3.25.0"
54
55
  },
@@ -1,4 +1,7 @@
1
1
  import assert from "node:assert/strict";
2
+ import { mkdtempSync, rmSync } from "node:fs";
3
+ import { tmpdir } from "node:os";
4
+ import { join } from "node:path";
2
5
  import test from "node:test";
3
6
  import { fileURLToPath } from "node:url";
4
7
 
@@ -10,25 +13,50 @@ import { registerTaskListTools } from "../dist/tools/tasklists.js";
10
13
  import { registerTaskTools } from "../dist/tools/tasks.js";
11
14
  import { registerCompletionTools } from "../dist/tools/completion.js";
12
15
  import { registerRawTool } from "../dist/tools/raw.js";
16
+ import { registerAuthTools } from "../dist/tools/auth.js";
13
17
 
18
+ /**
19
+ * Sorted, because every assertion compares it against a sorted tool list. The
20
+ * six onboarding tools come from @a1-x-tech/mcp-google-auth, so this list is
21
+ * also the check that the component is wired into the published binary.
22
+ */
14
23
  const ALL_TOOLS = [
24
+ "auth_status",
15
25
  "clear_completed_tasks",
16
26
  "complete_task",
17
27
  "create_task",
18
28
  "create_tasklist",
19
29
  "delete_task",
20
30
  "delete_tasklist",
31
+ "finish_login",
21
32
  "get_task",
22
33
  "get_tasklist",
23
34
  "list_tasklists",
24
35
  "list_tasks",
36
+ "logout",
25
37
  "move_task",
26
38
  "raw_request",
27
39
  "reopen_task",
40
+ "set_client",
41
+ "setup_instructions",
42
+ "start_login",
28
43
  "update_task",
29
44
  "update_tasklist",
30
45
  ];
31
46
 
47
+ /**
48
+ * A throwaway $XDG_CONFIG_HOME for the spawned server. The auth component
49
+ * re-reads $XDG_CONFIG_HOME/mcp-google-tasks/credentials.json per call, so
50
+ * without this a real login on the developer's machine would make the
51
+ * "unconfigured" case pass for the wrong reason.
52
+ */
53
+ function isolatedConfigDir(t) {
54
+ const dir = mkdtempSync(join(tmpdir(), "mcp-tasks-dist-smoke-"));
55
+ t.after(() => rmSync(dir, { recursive: true, force: true }));
56
+ return dir;
57
+ }
58
+
59
+
32
60
  test("dist client rejects foreign-origin paths before sending the Bearer token", async () => {
33
61
  const original = globalThis.fetch;
34
62
  let called = false;
@@ -82,6 +110,7 @@ test("dist registers the expected tools", () => {
82
110
  };
83
111
  const client = {};
84
112
 
113
+ registerAuthTools(server, client);
85
114
  registerTaskListTools(server, client);
86
115
  registerTaskTools(server, client);
87
116
  registerCompletionTools(server, client);
@@ -90,13 +119,14 @@ test("dist registers the expected tools", () => {
90
119
  assert.deepEqual(names.sort(), ALL_TOOLS);
91
120
  });
92
121
 
93
- test("dist binary completes a real MCP handshake over stdio and lists every tool", async () => {
122
+ test("dist binary completes a real MCP handshake over stdio and lists every tool", async (t) => {
94
123
  const transport = new StdioClientTransport({
95
124
  command: process.execPath,
96
125
  args: [fileURLToPath(new URL("../dist/index.js", import.meta.url))],
97
126
  env: {
98
127
  ...process.env,
99
128
  GOOGLE_TASKS_ACCESS_TOKEN: "test-token",
129
+ XDG_CONFIG_HOME: isolatedConfigDir(t),
100
130
  ASKADS_TELEMETRY: "0", // keep the suite offline
101
131
  },
102
132
  stderr: "pipe",
@@ -138,13 +168,14 @@ test("dist binary completes a real MCP handshake over stdio and lists every tool
138
168
  * answer a tool call with the actionable error — offline: the CredentialsError
139
169
  * fires before any fetch, so this test never touches the network.
140
170
  */
141
- test("dist binary starts without credentials: handshake, tool list, actionable call error", async () => {
171
+ test("dist binary starts without credentials: handshake, tool list, actionable call error", async (t) => {
142
172
  const env = Object.fromEntries(
143
173
  Object.entries(process.env).filter(
144
174
  ([key, value]) => value !== undefined && !key.startsWith("GOOGLE_TASKS_"),
145
175
  ),
146
176
  );
147
177
  env.ASKADS_TELEMETRY = "0"; // keep the suite offline
178
+ env.XDG_CONFIG_HOME = isolatedConfigDir(t); // ignore any real login on this machine
148
179
  const transport = new StdioClientTransport({
149
180
  command: process.execPath,
150
181
  args: [fileURLToPath(new URL("../dist/index.js", import.meta.url))],
@@ -156,7 +187,8 @@ test("dist binary starts without credentials: handshake, tool list, actionable c
156
187
  try {
157
188
  // The model must read the fix before it picks a tool.
158
189
  const instructions = client.getInstructions() ?? "";
159
- assert.match(instructions, /not connected/);
190
+ assert.match(instructions, /NOT CONNECTED/);
191
+ assert.match(instructions, /start_login/);
160
192
  assert.match(instructions, /GOOGLE_TASKS_CLIENT_ID/);
161
193
  assert.match(instructions, /restart/);
162
194
 
@@ -167,7 +199,8 @@ test("dist binary starts without credentials: handshake, tool list, actionable c
167
199
  const result = await client.callTool({ name: "list_tasklists", arguments: {} });
168
200
  assert.equal(result.isError, true);
169
201
  const text = result.content.map((c) => c.text ?? "").join(" ");
170
- assert.match(text, /Google OAuth credentials are required: set GOOGLE_TASKS_CLIENT_ID/);
202
+ assert.match(text, /not connected/i);
203
+ assert.match(text, /start_login/);
171
204
  assert.match(text, /restart the server/);
172
205
  } finally {
173
206
  await client.close();