mcp-google-tagmanager 1.0.0 → 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.ru.md ADDED
@@ -0,0 +1,328 @@
1
+ # <img src="./assets/a1-logo.svg" alt="A1" width="40"> Google Tag Manager MCP
2
+
3
+ [English](./README.md) | **Русский**
4
+
5
+ [![npm](https://img.shields.io/npm/v/mcp-google-tagmanager)](https://www.npmjs.com/package/mcp-google-tagmanager)
6
+ [![CI](https://github.com/A1-x-Tech/mcp-google-tagmanager/actions/workflows/ci.yml/badge.svg)](https://github.com/A1-x-Tech/mcp-google-tagmanager/actions/workflows/ci.yml)
7
+ [![Glama](https://glama.ai/mcp/servers/A1-x-Tech/mcp-google-tagmanager/badges/score.svg)](https://glama.ai/mcp/servers/A1-x-Tech/mcp-google-tagmanager)
8
+ [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
9
+
10
+ **A1 Google Tag Manager MCP** позволяет AI-приложению проверять и настраивать контейнеры Google Tag Manager на естественном языке. Можно увидеть, что срабатывает на странице, подготовить теги, триггеры и переменные в черновом рабочем пространстве, а затем осознанно собрать и опубликовать версию.
11
+
12
+ Сервер подключается к Google Tag Manager API v2 через ваш аккаунт Google. В отличие от догадки AI о настройке GTM, он работает с выбранными вами настоящими контейнером, рабочим пространством и версией.
13
+
14
+ - **25 инструментов.** 10 операций только читают данные GTM; 4 создают черновики или меняют встроенные переменные; 5 могут изменить, удалить, собрать или опубликовать конфигурацию.
15
+ - **Подключение из диалога.** Скажите «подключи Google Tag Manager»: сервер проведёт через создание OAuth-клиента, поймает редирект Google на `127.0.0.1` с PKCE и сам сохранит токены — без конфигов и перезапуска.
16
+ - **Сначала черновик.** Теги, триггеры и переменные создаются в рабочем пространстве. Публикация — отдельная явно разрушительная операция.
17
+ - **С учётом квоты.** GTM разрешает 0,25 запроса в секунду на проект; сервер делает паузу не менее 4,2 секунды между запросами, а не перегружает API.
18
+ - **Ваш доступ Google.** Сервер использует ваши OAuth-данные и запрашивает только scope GTM, нужные для чтения, редактирования, версий и публикации.
19
+
20
+ Начните с запроса, который только читает данные:
21
+
22
+ > Какие теги в моих контейнерах срабатывают по триггеру просмотра страницы?
23
+
24
+ [Подключить сервер](#быстрый-старт) · [Посмотреть сценарии](#что-можно-поручить) · [Открыть техническую документацию](#техническая-документация)
25
+
26
+ ---
27
+
28
+ ## Увидеть работу за минуту
29
+
30
+ > **Вы:** Покажи мои контейнеры GTM и теги, которые срабатывают при просмотре страницы.
31
+ >
32
+ > **Ассистент:** Показывает контейнеры, их рабочие пространства, подходящие триггеры и привязанные теги. Ничего не меняется.
33
+ >
34
+ > **Вы:** В Default Workspace контейнера `GTM-ABC123` подготовь GA4 configuration tag для measurement ID `G-XXXXXXX` на всех страницах.
35
+ >
36
+ > **Ассистент:** Показывает рабочее пространство, предлагаемые настройки тега и триггера, затем запрашивает подтверждение перед созданием черновика.
37
+ >
38
+ > **Вы:** Подтверждаю черновик.
39
+ >
40
+ > **Ассистент:** Создаёт тег в рабочем пространстве. Контейнер не публикуется: сборка и публикация версии остаются отдельным шагом.
41
+
42
+ ## Содержание
43
+
44
+ - [Быстрый старт](#быстрый-старт)
45
+ - [Что можно поручить](#что-можно-поручить)
46
+ - [Как связаны изменения GTM](#как-связаны-изменения-gtm)
47
+ - [Что может измениться](#что-может-измениться)
48
+ - [Как получить доступ](#как-получить-доступ)
49
+ - [Конфигурация](#конфигурация)
50
+ - [Данные и телеметрия](#данные-и-телеметрия)
51
+ - [Ограничения и работа в фоне](#ограничения-и-работа-в-фоне)
52
+ - [Техническая документация](#техническая-документация)
53
+ - [Поддержка](#поддержка)
54
+
55
+ ## Быстрый старт
56
+
57
+ Нужны Node.js 20+ и Google-аккаунт. Учётные данные при установке не нужны: сервер подключается прямо в диалоге.
58
+
59
+ 1. Добавьте сервер в AI-приложение.
60
+ 2. Скажите «подключи Google Tag Manager» — ассистент проведёт [создание OAuth-клиента и выдачу доступа](#как-получить-доступ), не трогая конфиги.
61
+ 3. Начните с запроса, который только читает данные.
62
+
63
+ <details open>
64
+ <summary><strong>Codex</strong></summary>
65
+
66
+ <br>
67
+
68
+ **В приложении:**
69
+
70
+ 1. Откройте **Settings → MCP servers**.
71
+ 2. Нажмите **Add server**.
72
+ 3. Выберите **STDIO**, затем укажите `npx -y mcp-google-tagmanager@latest` и три переменные окружения ниже.
73
+
74
+ | Переменная | Значение |
75
+ |---|---|
76
+ | `GOOGLE_TAGMANAGER_CLIENT_ID` | Ваш Google OAuth client ID |
77
+ | `GOOGLE_TAGMANAGER_CLIENT_SECRET` | Ваш Google OAuth client secret |
78
+ | `GOOGLE_TAGMANAGER_REFRESH_TOKEN` | Ваш Google OAuth refresh token |
79
+
80
+ 4. Нажмите **Save**, затем **Restart**.
81
+
82
+ **В командной строке:**
83
+
84
+ ```bash
85
+ codex mcp add google-tagmanager \
86
+ -- npx -y mcp-google-tagmanager@latest
87
+ ```
88
+
89
+ ```bash
90
+ codex mcp list
91
+ ```
92
+
93
+ [Документация Codex MCP](https://learn.chatgpt.com/docs/extend/mcp?surface=cli)
94
+
95
+ </details>
96
+
97
+ <details>
98
+ <summary><strong>Claude Code</strong></summary>
99
+
100
+ <br>
101
+
102
+ ```bash
103
+ claude mcp add \
104
+ --transport stdio \
105
+ --scope user \
106
+ google-tagmanager \
107
+ -- npx -y mcp-google-tagmanager@latest
108
+ ```
109
+
110
+ ```bash
111
+ claude mcp list
112
+ ```
113
+
114
+ [Документация Claude Code MCP](https://code.claude.com/docs/en/mcp)
115
+
116
+ </details>
117
+
118
+ <details>
119
+ <summary><strong>Claude Desktop</strong></summary>
120
+
121
+ <br>
122
+
123
+ Актуальный официальный путь — **Settings → Extensions**. Для пользовательского desktop extension откройте **Advanced settings → Extension Developer → Install Extension…**, выберите файл `.mcpb` и следуйте подсказкам.
124
+
125
+ Этот репозиторий сейчас публикует npm-пакет со stdio и пока не содержит `.mcpb`. Поэтому используйте приведённый ниже JSON stdio-конфиг как fallback только в сборках Claude Desktop, где ещё поддерживается локальная конфигурация:
126
+
127
+ ```json
128
+ {
129
+ "mcpServers": {
130
+ "google-tagmanager": {
131
+ "command": "npx",
132
+ "args": ["-y", "mcp-google-tagmanager@latest"]
133
+ }
134
+ }
135
+ }
136
+ ```
137
+
138
+ В таких сборках сохраните его в `~/Library/Application Support/Claude/claude_desktop_config.json` на macOS или `%APPDATA%\Claude\claude_desktop_config.json` на Windows.
139
+
140
+ [Документация Claude Desktop MCP](https://support.claude.com/en/articles/10949351-getting-started-with-local-mcp-servers-on-claude-desktop)
141
+
142
+ </details>
143
+
144
+ <details>
145
+ <summary><strong>Cursor</strong></summary>
146
+
147
+ <br>
148
+
149
+ Добавьте сервер уровня пользователя в `~/.cursor/mcp.json` на macOS/Linux или в `%USERPROFILE%\.cursor\mcp.json` на Windows:
150
+
151
+ ```json
152
+ {
153
+ "mcpServers": {
154
+ "google-tagmanager": {
155
+ "type": "stdio",
156
+ "command": "npx",
157
+ "args": ["-y", "mcp-google-tagmanager@latest"]
158
+ }
159
+ }
160
+ }
161
+ ```
162
+
163
+ [Документация Cursor MCP](https://cursor.com/docs/mcp)
164
+
165
+ </details>
166
+
167
+ <details>
168
+ <summary><strong>VS Code</strong></summary>
169
+
170
+ <br>
171
+
172
+ Запустите **MCP: Open User Configuration** из Command Palette и добавьте:
173
+
174
+ ```json
175
+ {
176
+ "servers": {
177
+ "google-tagmanager": {
178
+ "type": "stdio",
179
+ "command": "npx",
180
+ "args": ["-y", "mcp-google-tagmanager@latest"]
181
+ }
182
+ }
183
+ }
184
+ ```
185
+
186
+ Проверьте сервер командой **MCP: List Servers**.
187
+
188
+ [Документация VS Code MCP](https://code.visualstudio.com/docs/agent-customization/mcp-servers)
189
+
190
+ </details>
191
+
192
+ ## Что можно поручить
193
+
194
+ ### Понять текущую настройку
195
+
196
+ - Покажи доступные мне аккаунты и контейнеры GTM.
197
+ - Какие теги срабатывают при просмотре страницы в этом рабочем пространстве?
198
+ - Покажи настройки триггера и переменных для этого тега.
199
+ - Какие встроенные переменные включены?
200
+
201
+ ### Подготовить изменение аналитики в черновике
202
+
203
+ - Создай рабочее пространство для изменения отслеживания checkout.
204
+ - Подготовь GA4-тег и триггер для нужного события.
205
+ - Включи переменные клика, необходимые для этого триггера.
206
+ - Обнови этот тег, сначала показав мне полную конфигурацию для замены.
207
+
208
+ ### Осознанно выпустить версию
209
+
210
+ - Собери из этого рабочего пространства версию с названием `April release`.
211
+ - Покажи ошибки компилятора, если они есть.
212
+ - Опубликуй версию `42` после моего подтверждения версии и её изменений.
213
+
214
+ ## Как связаны изменения GTM
215
+
216
+ В GTM есть понятный путь выпуска:
217
+
218
+ 1. В **аккаунте** находятся один или несколько **контейнеров**.
219
+ 2. У контейнера есть **рабочие пространства** для черновых изменений.
220
+ 3. Теги, триггеры и переменные принадлежат рабочему пространству.
221
+ 4. Сборка рабочего пространства создаёт **версию контейнера** и удаляет исходное рабочее пространство. GTM создаёт замену.
222
+ 5. Публикация делает выбранную версию контейнера рабочей.
223
+
224
+ Сервер умеет проверить каждый шаг. Он не приравнивает черновик к выпуску: создание версии и публикация — разные операции.
225
+
226
+ ## Что может измениться
227
+
228
+ | Операция | Что происходит | Граница подтверждения |
229
+ |---|---|---|
230
+ | Просмотр аккаунтов, контейнеров, пространств, тегов, триггеров, переменных и версий | Читает конфигурацию GTM | Ничего не меняет |
231
+ | Создание контейнера или рабочего пространства | Добавляет объект GTM | Меняет GTM |
232
+ | Создание тега, триггера или переменной | Добавляет черновой объект в пространство | Меняет черновое пространство |
233
+ | Включение или выключение встроенных переменных | Меняет конфигурацию пространства | Меняет черновое пространство |
234
+ | Обновление тега, триггера или переменной | Полностью заменяет ресурс, защищённый fingerprint | Потенциально разрушительно |
235
+ | Удаление тега, триггера или переменной | Удаляет выбранный объект | Разрушительно |
236
+ | Сборка рабочего пространства | Создаёт версию и удаляет исходное пространство | Разрушительно |
237
+ | Публикация версии | Делает выбранную версию рабочей | Разрушительно |
238
+ | Технический запрос API | Может вызвать метод API без отдельного инструмента | Потенциально разрушительно |
239
+
240
+ То, как AI-приложение запрашивает подтверждение, определяет само приложение. Сервер помечает операции как read-only, write и destructive, чтобы оно могло отличить проверку от реального изменения.
241
+
242
+ ## Как получить доступ
243
+
244
+ Google Tag Manager требует OAuth 2.0: одного API-ключа недостаточно. Путей два, и первый не требует править конфигурационные файлы.
245
+
246
+ ### Подключение из диалога (рекомендуемый путь)
247
+
248
+ Скажите «подключи Google Tag Manager», и ассистент пройдёт флоу вместе с вами:
249
+
250
+ 1. `setup_instructions` выдаёт чек-лист: создать или выбрать проект Google Cloud, включить **Tag Manager API**, настроить consent screen и создать OAuth-клиент типа **Desktop app**.
251
+ 2. Скачайте JSON этого клиента («Download JSON») и передайте ассистенту **путь** к файлу — `set_client` сохранит его с правами только для владельца. Секрет через переписку не проходит.
252
+ 3. `start_login` возвращает ссылку на согласие Google. Откройте её **на этой же машине** и подтвердите доступ: код возвращается на одноразовый слушатель `127.0.0.1` (PKCE), а не в чат.
253
+ 4. `finish_login` меняет код на токены и кладёт их в `~/.config/mcp-google-tagmanager/credentials.json` (права 0600) и проверяет их реальным вызовом Tag Manager API — так невключённый API ловится сразу.
254
+
255
+ Токены перечитываются на каждый вызов, поэтому подключение действует немедленно — перезапускать AI-приложение не нужно. `auth_status` показывает состояние, `logout` отзывает токен и удаляет его.
256
+
257
+ ### Переменные окружения (CI и автоматические установки)
258
+
259
+ 1. Создайте или выберите проект Google Cloud и включите [Tag Manager API](https://console.cloud.google.com/apis/library/tagmanager.googleapis.com). Проект без включённого API не получает квоту.
260
+ 2. Настройте OAuth consent screen и создайте OAuth-клиент. Для локальной работы подходит тип **Desktop app**.
261
+ 3. Авторизуйте свой Google-аккаунт и получите refresh token. Это можно сделать через [OAuth 2.0 Playground](https://developers.google.com/oauthplayground), если включить **Use your own OAuth credentials**.
262
+ 4. Запросите все scope вместе:
263
+
264
+ ```text
265
+ https://www.googleapis.com/auth/tagmanager.readonly
266
+ https://www.googleapis.com/auth/tagmanager.edit.containers
267
+ https://www.googleapis.com/auth/tagmanager.edit.containerversions
268
+ https://www.googleapis.com/auth/tagmanager.publish
269
+ ```
270
+
271
+ Scope разделены: для чтения, редактирования, сборки версии и публикации требуется соответствующее разрешение. Храните client secret и refresh token как пароли.
272
+
273
+ ## Конфигурация
274
+
275
+ Все переменные необязательные — без единой из них сервер подключается [из диалога](#подключение-из-диалога-рекомендуемый-путь).
276
+
277
+ | Переменная | Обязательна | Описание |
278
+ |---|---|---|
279
+ | `GOOGLE_TAGMANAGER_CLIENT_ID` | Нет* | OAuth client ID. |
280
+ | `GOOGLE_TAGMANAGER_CLIENT_SECRET` | Нет* | OAuth client secret. |
281
+ | `GOOGLE_TAGMANAGER_REFRESH_TOKEN` | Нет* | OAuth refresh token. |
282
+ | `GOOGLE_TAGMANAGER_ACCESS_TOKEN` | Нет* | Короткоживущая альтернатива OAuth-тройке. |
283
+ | `GOOGLE_TAGMANAGER_OAUTH_PORT` | Нет | Фиксированный порт loopback-слушателя для входа из диалога; нужен при пробросе портов по SSH. |
284
+ | `GOOGLE_TAGMANAGER_API_BASE` | Нет | Переопределяет базовый URL Tag Manager API. |
285
+ | `GOOGLE_TAGMANAGER_TIMEOUT_MS` | Нет | Тайм-аут запроса; по умолчанию `60000` мс. |
286
+ | `GOOGLE_TAGMANAGER_MAX_RETRIES` | Нет | Максимум повторов при временных ошибках; по умолчанию `3`. |
287
+ | `GOOGLE_TAGMANAGER_MIN_INTERVAL_MS` | Нет | Минимальная пауза между запросами; по умолчанию `4200` мс. |
288
+
289
+ \* Передайте либо OAuth-тройку, либо access token. Access token истекает примерно через час и автоматически не обновляется.
290
+
291
+ ## Данные и телеметрия
292
+
293
+ Сервер работает локально и отправляет запросы GTM API и OAuth refresh requests в Google. Анонимная телеметрия содержит случайный ID установки, версию пакета, версии AI-клиента, Node.js и операционной системы, а также имена инструментов. OAuth-токены, данные GTM, аргументы инструментов и промпты не отправляются.
294
+
295
+ Отключить телеметрию для MCP-серверов A1 можно так:
296
+
297
+ ```bash
298
+ ASKADS_TELEMETRY=0
299
+ ```
300
+
301
+ ## Ограничения и работа в фоне
302
+
303
+ - **GTM ограничивает частоту.** API разрешает 0,25 запроса в секунду на проект, поэтому сервер выполняет запросы с интервалом не менее 4,2 секунды. Широкая проверка может занять время.
304
+ - **Временные лимиты обрабатываются осторожно.** Ответы `429` и quota `403` от Google обрабатываются с экспоненциальной задержкой и `Retry-After`. Чтение повторяется после сетевых и `5xx` ошибок; запись после неопределённой ошибки не повторяется.
305
+ - **Постоянного наблюдения нет.** Сервер работает только во время вызова из AI-приложения. Если приложение поддерживает задания по расписанию, оно может периодически проверять контейнер или его рабочую версию.
306
+ - **Рабочее пространство исчезает при сборке.** Перед `create_version` сохраните нужные данные и проверьте путь к созданному GTM пространству-замене.
307
+
308
+ ## Техническая документация
309
+
310
+ - [Каталог MCP-возможностей](./docs/capabilities/index.md) — страницы по пользовательским задачам для каждого инструмента.
311
+ - [Все инструменты и параметры](./docs/TOOLS.md)
312
+ - [Документация по разработке](./docs/DEVELOPMENT.md)
313
+ - [Документация по публикации](./docs/PUBLISHING.md)
314
+ - [Справочник Google Tag Manager API v2](https://developers.google.com/tag-platform/tag-manager/api/reference/rest)
315
+
316
+ ## Поддержка
317
+
318
+ Нашли ошибку или не хватает сценария? [Создайте issue](https://github.com/A1-x-Tech/mcp-google-tagmanager/issues) или напишите в [Telegram](https://t.me/a1_mcp).
319
+
320
+ <br>
321
+
322
+ <p align="center">
323
+ <img src="https://github.com/ztemerbekov/a1-yandex-kit-skills/raw/main/assets/images/mona-hifive-yandex-kit-warm.gif" alt="Две Моны дают пять" width="256">
324
+ </p>
325
+
326
+ <p align="center">
327
+ Вы дочитали до конца!
328
+ </p>
package/dist/auth.js CHANGED
@@ -1,3 +1,4 @@
1
+ import { CredentialsError } from "./config.js";
1
2
  import { TagManagerError } from "./types.js";
2
3
  /** Google OAuth 2.0 token endpoint. */
3
4
  const TOKEN_URL = "https://oauth2.googleapis.com/token";
@@ -8,30 +9,31 @@ const TOKEN_URL = "https://oauth2.googleapis.com/token";
8
9
  const EXPIRY_MARGIN_MS = 60_000;
9
10
  /** Fallback lifetime when the token response has no usable expires_in. */
10
11
  const DEFAULT_LIFETIME_S = 3600;
11
- /**
12
- * Supplies OAuth access tokens for API requests.
13
- *
14
- * With GOOGLE_TAGMANAGER_ACCESS_TOKEN set, that token is returned as-is (quick
15
- * sessions; Google access tokens expire in ~1 hour and are not auto-refreshed).
16
- * Otherwise the client-id/secret/refresh-token trio is exchanged at
17
- * https://oauth2.googleapis.com/token (form-urlencoded, grant_type=refresh_token)
18
- * and the resulting access token is cached until 60 s before expiry. Concurrent
19
- * callers share one in-flight exchange; a failed exchange is not cached.
20
- *
21
- * Token-endpoint calls do not count against the GTM API quota, so they bypass
22
- * the client's rate limiter.
23
- */
24
12
  export class TokenProvider {
25
13
  config;
14
+ fallback;
26
15
  cachedToken;
27
16
  cachedUntil = 0;
28
17
  pending;
29
- constructor(config) {
18
+ constructor(config,
19
+ /**
20
+ * Consulted only when the environment carries no credentials — env wins, so
21
+ * existing refresh-trio and access-token installs behave exactly as before.
22
+ * It re-reads the stored login per call, which is what lets a finish_login
23
+ * taken mid-session work without a restart.
24
+ */
25
+ fallback) {
30
26
  this.config = config;
27
+ this.fallback = fallback;
31
28
  }
32
29
  async getAccessToken() {
33
30
  if (this.config.accessToken)
34
31
  return this.config.accessToken;
32
+ if (!this.config.clientId && !this.config.clientSecret && !this.config.refreshToken) {
33
+ if (this.fallback)
34
+ return this.fallback.getAccessToken();
35
+ throw new CredentialsError();
36
+ }
35
37
  if (this.cachedToken && Date.now() < this.cachedUntil)
36
38
  return this.cachedToken;
37
39
  if (!this.pending) {
@@ -44,7 +46,8 @@ export class TokenProvider {
44
46
  async refresh() {
45
47
  const { clientId, clientSecret, refreshToken } = this.config;
46
48
  if (!clientId || !clientSecret || !refreshToken) {
47
- // loadConfig guarantees the trio when accessToken is absent; this guards direct construction.
49
+ // loadConfig yields either a full trio or no credentials at all (caught
50
+ // above as CredentialsError); this guards a direct partial construction.
48
51
  throw new Error("OAuth refresh requires GOOGLE_TAGMANAGER_CLIENT_ID, GOOGLE_TAGMANAGER_CLIENT_SECRET and GOOGLE_TAGMANAGER_REFRESH_TOKEN.");
49
52
  }
50
53
  const body = new URLSearchParams({
package/dist/client.js CHANGED
@@ -1,5 +1,6 @@
1
1
  import { TokenProvider } from "./auth.js";
2
2
  import { isQuotaError, TagManagerError } from "./types.js";
3
+ import { DEFAULT_BASE } from "./config.js";
3
4
  const ENTITY_COLLECTION = {
4
5
  tag: "tags",
5
6
  trigger: "triggers",
@@ -240,3 +241,29 @@ function compact(obj) {
240
241
  function delay(ms) {
241
242
  return new Promise((resolve) => setTimeout(resolve, ms));
242
243
  }
244
+ /**
245
+ * One cheap Tag Manager read, used to verify a fresh in-chat login against the
246
+ * API the server actually talks to. Standalone (not a client method) because it
247
+ * runs with a token the client does not hold yet — the login is still being
248
+ * finished, and it must bypass the client's rate limiter. Throws
249
+ * TagManagerError exactly like the client does, so the caller can recognize a
250
+ * disabled-API 403 and give the actionable advice.
251
+ */
252
+ export async function probeApi(accessToken) {
253
+ const base = (process.env.GOOGLE_TAGMANAGER_API_BASE || DEFAULT_BASE).replace(/\/+$/, "");
254
+ const res = await fetch(`${base}/tagmanager/v2/accounts`, {
255
+ headers: { Authorization: `Bearer ${accessToken}` },
256
+ signal: AbortSignal.timeout(10_000),
257
+ });
258
+ const text = await res.text();
259
+ if (res.ok)
260
+ return;
261
+ let data;
262
+ try {
263
+ data = JSON.parse(text);
264
+ }
265
+ catch {
266
+ data = text;
267
+ }
268
+ throw new TagManagerError(res.status, data);
269
+ }
package/dist/config.js CHANGED
@@ -1,5 +1,5 @@
1
1
  /** Default Google Tag Manager API host. */
2
- const DEFAULT_BASE = "https://tagmanager.googleapis.com";
2
+ export const DEFAULT_BASE = "https://tagmanager.googleapis.com";
3
3
  /**
4
4
  * GTM enforces 0.25 QPS per project (25 requests / 100 s sliding window), so
5
5
  * requests are spaced at least this far apart by default: 100_000 ms / 25 = 4_000,
@@ -7,9 +7,10 @@ const DEFAULT_BASE = "https://tagmanager.googleapis.com";
7
7
  */
8
8
  const DEFAULT_MIN_INTERVAL_MS = 4_200;
9
9
  /**
10
- * A missing or malformed environment variable. Thrown instead of exiting on the
11
- * spot so index.ts owns the process exit; `reason` is a machine-readable code
12
- * (never a variable's value).
10
+ * A malformed environment variable combination. Thrown instead of exiting on
11
+ * the spot so index.ts can catch it, report the drop-off and start degraded
12
+ * instead of dying; `reason` is a machine-readable code (never a variable's
13
+ * value).
13
14
  */
14
15
  export class ConfigError extends Error {
15
16
  reason;
@@ -19,12 +20,42 @@ export class ConfigError extends Error {
19
20
  this.reason = reason;
20
21
  }
21
22
  }
22
- function die(message, reason) {
23
- throw new ConfigError(message, reason);
23
+ /**
24
+ * What a tool call without credentials reads. The first sentence is the
25
+ * historical startup error, verbatim (it already names both auth modes) — the
26
+ * rest exists because credentials come only from the environment, so the fix
27
+ * is an operator action plus a restart, never a retry.
28
+ */
29
+ export const MISSING_CREDENTIALS_MESSAGE = "GOOGLE_TAGMANAGER_CLIENT_ID is required (OAuth client id; or set GOOGLE_TAGMANAGER_ACCESS_TOKEN directly). " +
30
+ "This is not a network failure and retrying will not help: the operator must set these " +
31
+ "environment variables in the MCP client's server config and restart the server — they are " +
32
+ "read only at startup.";
33
+ /**
34
+ * Raised when a tool call needs credentials and none were configured. The
35
+ * message is the whole point of the class: it is the only text the calling
36
+ * model reads about the missing setup, so it names the fix (which variables,
37
+ * and that a restart is needed) instead of the failure.
38
+ */
39
+ export class CredentialsError extends Error {
40
+ constructor(message = MISSING_CREDENTIALS_MESSAGE) {
41
+ super(message);
42
+ this.name = "CredentialsError";
43
+ }
44
+ }
45
+ /** True when the config carries usable credentials (a direct access token or the full refresh trio). */
46
+ export function hasCredentials(config) {
47
+ return Boolean(config.accessToken || (config.clientId && config.clientSecret && config.refreshToken));
24
48
  }
25
49
  /**
26
- * Builds the client config from environment variables, throwing ConfigError if
27
- * a required one is missing.
50
+ * Builds the client config from environment variables.
51
+ *
52
+ * Missing credentials are NOT an error here: the server starts anyway and the
53
+ * token provider raises {@link CredentialsError} on the first tool call, so an
54
+ * unconfigured install completes the MCP handshake and carries the fix into
55
+ * the session instead of dying before it with nothing to read. A malformed
56
+ * setup — some credential variable set but no workable combination — still
57
+ * throws, keeping the historical per-variable messages and reason codes,
58
+ * because guessing what the user meant is worse.
28
59
  *
29
60
  * Two auth modes:
30
61
  * GOOGLE_TAGMANAGER_ACCESS_TOKEN ready-made OAuth access token (quick sessions;
@@ -39,19 +70,24 @@ function die(message, reason) {
39
70
  * GOOGLE_TAGMANAGER_MIN_INTERVAL_MS min spacing between API requests (default 4200)
40
71
  */
41
72
  export function loadConfig() {
42
- const accessToken = process.env.GOOGLE_TAGMANAGER_ACCESS_TOKEN;
43
- const clientId = process.env.GOOGLE_TAGMANAGER_CLIENT_ID;
44
- const clientSecret = process.env.GOOGLE_TAGMANAGER_CLIENT_SECRET;
45
- const refreshToken = process.env.GOOGLE_TAGMANAGER_REFRESH_TOKEN;
46
- if (!accessToken) {
73
+ // An empty string counts as "not set" — a blank value in an MCP config is
74
+ // the same operator mistake as a missing one.
75
+ const accessToken = process.env.GOOGLE_TAGMANAGER_ACCESS_TOKEN || undefined;
76
+ const clientId = process.env.GOOGLE_TAGMANAGER_CLIENT_ID || undefined;
77
+ const clientSecret = process.env.GOOGLE_TAGMANAGER_CLIENT_SECRET || undefined;
78
+ const refreshToken = process.env.GOOGLE_TAGMANAGER_REFRESH_TOKEN || undefined;
79
+ // None of the four set → not an error (degraded start). Some set but no
80
+ // workable combination → the historical checks in their historical order.
81
+ const anyProvided = Boolean(accessToken || clientId || clientSecret || refreshToken);
82
+ if (anyProvided && !accessToken) {
47
83
  if (!clientId) {
48
- die("GOOGLE_TAGMANAGER_CLIENT_ID is required (OAuth client id; or set GOOGLE_TAGMANAGER_ACCESS_TOKEN directly).", "missing_client_id");
84
+ throw new ConfigError("GOOGLE_TAGMANAGER_CLIENT_ID is required (OAuth client id; or set GOOGLE_TAGMANAGER_ACCESS_TOKEN directly).", "missing_client_id");
49
85
  }
50
86
  if (!clientSecret) {
51
- die("GOOGLE_TAGMANAGER_CLIENT_SECRET is required (OAuth client secret).", "missing_client_secret");
87
+ throw new ConfigError("GOOGLE_TAGMANAGER_CLIENT_SECRET is required (OAuth client secret).", "missing_client_secret");
52
88
  }
53
89
  if (!refreshToken) {
54
- die("GOOGLE_TAGMANAGER_REFRESH_TOKEN is required (OAuth refresh token).", "missing_refresh_token");
90
+ throw new ConfigError("GOOGLE_TAGMANAGER_REFRESH_TOKEN is required (OAuth refresh token).", "missing_refresh_token");
55
91
  }
56
92
  }
57
93
  const timeoutMs = Number(process.env.GOOGLE_TAGMANAGER_TIMEOUT_MS);