@a1-x-tech/mcp-google-slides 0.2.0 → 1.1.0

package/README.md

@@ -274,7 +274,7 @@ Every variable is optional — with none of them the server connects [from the c
 
 ## Data, limits and background work
 
-- **Requests go to Google Slides.** The local server refreshes Google OAuth tokens and calls the Slides API; comments, export and local-image upload ride the Drive API, scoped to the one presentation file. Its anonymous telemetry contains an installation ID, package version, AI client and platform versions, and tool names — never OAuth tokens, presentation content, tool arguments or prompts. Set `ASKADS_TELEMETRY=0` to opt out.
+- **Requests go to Google Slides.** The local server refreshes Google OAuth tokens and calls the Slides API; comments, export and local-image upload ride the Drive API, scoped to the one presentation file. Its anonymous telemetry contains an installation ID, package version, AI client and platform versions, and tool names — never OAuth tokens, presentation content, tool arguments or prompts. For each tool call it also sends the outcome and, on failure, an excerpt of the error text with e-mails, addresses, tokens, numbers of 4+ digits and quoted text replaced by `#`; a value from your request can appear in it if the error text contains it. Set `ASKADS_TELEMETRY=0` to opt out.
 - **Google applies rate limits.** On `429`, the server uses backoff; reads also retry after network and `5xx` errors, while writes are not replayed after an uncertain failure. Thumbnails count against a more expensive read quota.
 - **There is no background polling.** The server runs only when called. Nothing watches a deck between calls; if your AI app supports scheduled tasks, it can check a presentation periodically.
 

package/README.ru.md

@@ -274,7 +274,7 @@ Refresh token OAuth-приложения в режиме Testing может ис
 
 ## Данные, лимиты и работа в фоне
 
-- **Запросы идут в Google Slides.** Локальный сервер обновляет OAuth-токены Google и вызывает Slides API; комментарии, экспорт и загрузка локальных изображений проходят через Drive API строго для одного файла презентации. Анонимная телеметрия содержит ID установки, версию пакета, версии AI-клиента и платформы и имена инструментов — но не OAuth-токены, содержимое презентаций, аргументы или промпты. Чтобы отключить её, задайте `ASKADS_TELEMETRY=0`.
+- **Запросы идут в Google Slides.** Локальный сервер обновляет OAuth-токены Google и вызывает Slides API; комментарии, экспорт и загрузка локальных изображений проходят через Drive API строго для одного файла презентации. Анонимная телеметрия содержит ID установки, версию пакета, версии AI-клиента и платформы и имена инструментов — но не OAuth-токены, содержимое презентаций, аргументы или промпты. При вызове инструмента сервер также отправляет его исход, а при ошибке - фрагмент её текста: код и сообщение, в которых e-mail, адреса, токены, числа от 4 цифр и текст в кавычках заменены на «#». Если в тексте ошибки есть значение из запроса, оно тоже может попасть во фрагмент. Чтобы отключить её, задайте `ASKADS_TELEMETRY=0`.
 - **У Google есть лимиты частоты.** При `429` сервер использует задержку; чтение также повторяется после сетевых и `5xx` ошибок, а запись после неопределённой ошибки не повторяется. Миниатюры расходуют более дорогую квоту чтения.
 - **Постоянного опроса нет.** Сервер работает только при вызове. Между вызовами за презентацией никто не следит; если AI-приложение поддерживает задания по расписанию, оно может периодически её проверять.
 

package/dist/telemetry.js

@@ -2,7 +2,7 @@
  * Anonymous usage telemetry — fire-and-forget pings to usage.gistrec.cloud.
  *
  * Privacy contract (mirrored by the receiver): only an anonymous random
- * instance id, event/tool names, a fixed-vocabulary failure reason and
+ * instance id, event/tool names, a fixed-vocabulary failure reason or tool outcome and
  * environment versions ever leave the machine. The OAuth credentials,
  * presentation content, tool arguments, prompts and the names or values of
  * environment variables are never read, serialized or sent. Sends are capped
@@ -64,6 +64,10 @@ export class Telemetry {
     setClientInfo(info) {
         this.clientInfo = info;
     }
+    /** Whether pings go out at all (ASKADS_TELEMETRY opt-out). */
+    isEnabled() {
+        return this.enabled;
+    }
     /** Fire-and-forget: the server's own work never waits on a ping. */
     send(event, fields = {}) {
         void this.post(event, fields);
@@ -87,7 +91,8 @@ export class Telemetry {
             client_name: this.clientInfo?.name,
             client_version: this.clientInfo?.version,
             tool: fields.tool,
-            reason: fields.reason,
+            reason: wireReason(event, fields.reason),
+            error_detail: event === "tool_call" ? fields.error_detail : undefined,
             node_version: process.version,
             os: process.platform,
         });
@@ -104,17 +109,221 @@ export class Telemetry {
         }
     }
 }
+/** How a tool call ended; only these constants leave the machine. */
+export const TOOL_OUTCOMES = [
+    "ok",
+    "error_auth",
+    "error_permission",
+    "error_not_found",
+    "error_rate_limit",
+    "error_invalid_request",
+    "error_upstream",
+    "error_timeout",
+    "error_network",
+    "error_internal",
+    "error_other",
+];
+/** Drops a tool_call reason that is not in TOOL_OUTCOMES. */
+function wireReason(event, reason) {
+    if (event !== "tool_call" || reason === undefined)
+        return reason;
+    return TOOL_OUTCOMES.includes(reason) ? reason : undefined;
+}
+// First match wins. Direct answers "no access to this client" with auth code 53, so that
+// permission line goes before auth.
+const OUTCOME_PATTERNS = [
+    ["error_timeout", /timed?[ _-]?out|таймаут|ETIMEDOUT|AbortError|не был готов|not ready/i],
+    ["error_network", /ECONNRESET|ECONNREFUSED|ENOTFOUND|EAI_AGAIN|EPIPE|fetch failed|socket hang up/i],
+    ["error_rate_limit", /\b429\b|rate[ _-]?limit|too many requests|quota|квот|лимит|\[(?:56|152|506|9000)\]/i],
+    ["error_permission", /нет доступа к кабинету|не подключ[её]н к аккаунту/i],
+    [
+        "error_auth",
+        /\b401\b|unauthori[sz]ed|unauthenticated|invalid[ _-]?(?:token|grant|credentials)|token (?:expired|revoked)|login required|AuthRequired|авториз|не подключ|\[53\]/i,
+    ],
+    ["error_permission", /\b403\b|forbidden|access[ _-]?denied|permission|insufficient[ _-]?scope|нет доступа|\[(?:54|3228)\]/i],
+    ["error_not_found", /\b404\b|not[ _-]?found|не найден|не существует|\[8800\]/i],
+    ["error_upstream", /\b5\d\d\b|\b204\b|unavailable|недоступ|internal server error|bad gateway|\[(?:52|1000|1001|1002)\]/i],
+    ["error_invalid_request", /\b400\b|\b422\b|bad request|invalid|syntax|некоррект|неверн|недопустим|required|обязател|expected|must (?:be|contain|have)|\[(?:4000|4001|4003|5000|8000)\]/i],
+];
+// An API code at the head of the message wins over the text, which may quote field names
+// ("ForbiddenPlatform" in a [8000] list of allowed values). 53 is absent: the text tells a
+// dead token from no access to a client.
+const CODE_OUTCOMES = new Map([
+    ...["56", "152", "506", "9000"].map((c) => [c, "error_rate_limit"]),
+    ...["54", "3228"].map((c) => [c, "error_permission"]),
+    ["8800", "error_not_found"],
+    ...["52", "1000", "1001", "1002"].map((c) => [c, "error_upstream"]),
+    ...["4000", "4001", "4003", "5000", "8000"].map((c) => [c, "error_invalid_request"]),
+]);
+const LEADING_CODE = /^[^[\n]{0,60}\[(\d{1,5})\]/;
+// Inputs are cut before any regex runs: a long argument echoed in an error must not stall the call.
+const TEXT_MAX = 4000;
+function resultText(value) {
+    if (value instanceof Error)
+        return `${value.name} ${value.message}`.slice(0, TEXT_MAX);
+    const content = value?.content;
+    if (!Array.isArray(content))
+        return "";
+    return content
+        .map((part) => (part && typeof part === "object" && typeof part.text === "string" ? part.text : ""))
+        .join("\n")
+        .slice(0, TEXT_MAX);
+}
+/** `toolOutcome(result)` for a returned result, `toolOutcome(undefined, error)` for a thrown one. */
+export function toolOutcome(result, ...thrown) {
+    const didThrow = thrown.length > 0;
+    if (!didThrow && !result?.isError)
+        return "ok";
+    const text = resultText(didThrow ? thrown[0] : result);
+    const byCode = CODE_OUTCOMES.get(LEADING_CODE.exec(text)?.[1] ?? "");
+    if (byCode)
+        return byCode;
+    for (const [outcome, pattern] of OUTCOME_PATTERNS)
+        if (pattern.test(text))
+            return outcome;
+    return didThrow ? "error_internal" : "error_other";
+}
+/** Error excerpt: allowlisted fragments of the error text, masked (port of the Ask Ads gateway's). */
+export const DETAIL_MAX = 200;
+const PICK = /\bHTTP (?<http>\d{3})\b(?::\s*(?<htext>[^{[]{1,200}))?|^(?:Ошибка: )?\[(?<bcode>\d{1,5})\]\s*(?<btext>[^;(]{1,200})|\[(?<tag>[A-Za-z][A-Za-z_]{2,})\]\s*(?<ttext>[^;(]{0,200})|\berror_code["']?\s*[:=]\s*["']?(?<code>\d{1,5})\b|\b(?<key>error_string|error_detail|error_type|message)["']?\s*[:=]\s*["']?(?<value>[^"'}\]]{1,80})|\b(?<net>ECONNRESET|ECONNREFUSED|ETIMEDOUT|ENOTFOUND|EAI_AGAIN|timed out|fetch failed|socket hang up|connection closed)\b|(?<netru>превысил таймаут)/gi;
+const SCRUB = /(?<key>(?:login|password|secret|token|api[_-]?key|authorization)\s*[:=]\s*["']?|(?:bearer|basic)\s+)(?<val>[^,;]+)|[^\s,;]*(?:@|:\/\/|%3A|\p{L}\.\p{L})[^\s,;]*|(?<key2>\b(?:token|secret|password|api[_-]?key|access_token|refresh_token|client_secret)\s+)(?!(?:expired|invalid|is|was|for|has|not|missing|required|revoked|provided|type)\b)\S+|\b(?:y0_|AQAA|AQVN|t1\.|sk-|vk1\.|vk_|ghp_|ya29\.)\S+|\b(?=[\w-]*\d)(?=[\w-]*[A-Za-z])[\w-]{20,}\b|\+?\d(?:[\s().-]*\d){3,}/giu;
+const QUOTED = /(?<!\p{L})'[^'\n]+(?:'(?!\p{L})|$)|"[^"\n]+(?:"|$)|«[^»]+(?:»|$)/gu;
+function scrub(value, quoted = true) {
+    return (quoted ? value.replace(QUOTED, "#") : value)
+        .replace(SCRUB, (...args) => {
+        const groups = args[args.length - 1];
+        return (groups.key ?? groups.key2 ?? "") + "#";
+    })
+        .replace(/^[ ;:,.]+|[ ;:,.]+$/g, "");
+}
+export function errorDetail(text) {
+    const flat = text.slice(0, 2000).split(/\s+/).filter(Boolean).join(" ");
+    const parts = [];
+    PICK.lastIndex = 0;
+    for (let m = PICK.exec(flat); m; m = PICK.exec(flat)) {
+        const g = m.groups ?? {};
+        let token;
+        if (g.http)
+            token = `HTTP ${g.http} ${scrub(g.htext ?? "")}`;
+        else if (g.bcode)
+            token = `code=${g.bcode} ${scrub(g.btext ?? "")}`;
+        else if (g.tag) {
+            // Tags are upper-case only; the rest of PICK is case-insensitive.
+            if (!/^[A-Z][A-Z_]{2,}$/.test(g.tag)) {
+                PICK.lastIndex = m.index + 1;
+                continue;
+            }
+            token = `${g.tag} ${scrub(g.ttext ?? "")}`;
+        }
+        else if (g.code)
+            token = `code=${g.code}`;
+        else if (g.key)
+            token = `${g.key.toLowerCase()}=${scrub(g.value ?? "")}`;
+        else
+            token = (g.net ?? g.netru ?? "").toLowerCase();
+        token = token.trim();
+        if (!parts.includes(token))
+            parts.push(token);
+    }
+    return parts.join("; ").slice(0, DETAIL_MAX);
+}
+/** Set by fail(), never serialized: our own refusal ("local"), a bug in our code ("internal") or a failed fetch ("network"). */
+const FAILURE_ORIGIN = new WeakMap();
+const JS_ERRORS = new Set(["TypeError", "ReferenceError", "RangeError", "SyntaxError", "EvalError", "URIError"]);
+function jsBug(err) {
+    return err instanceof Error && JS_ERRORS.has(err.name) ? `${err.name}: ${err.message.split("\n")[0]}` : undefined;
+}
+/**
+ * Node's fetch rejects a network failure as TypeError("fetch failed") with the socket/DNS/TLS error
+ * in `cause`. Only cause.code leaves the machine: cause.message names hosts and addresses.
+ */
+function fetchFailure(err) {
+    if (!(err instanceof Error) || err.name !== "TypeError" || err.message !== "fetch failed")
+        return undefined;
+    const cause = err.cause;
+    if (!cause || typeof cause !== "object")
+        return undefined;
+    const raw = cause.code;
+    const code = typeof raw === "string" && /^[A-Z][A-Z0-9_]{2,40}$/.test(raw) ? raw : "";
+    return {
+        reason: /TIMEOUT|TIMEDOUT/.test(code) ? "error_timeout" : "error_network",
+        text: code ? `fetch failed; ${code.toLowerCase()}` : "fetch failed",
+    };
+}
+export function noteFailure(result, err) {
+    try {
+        if (result && typeof result === "object") {
+            const net = fetchFailure(err);
+            if (typeof err === "string")
+                FAILURE_ORIGIN.set(result, { origin: "local", text: err });
+            else if (net)
+                FAILURE_ORIGIN.set(result, { origin: "network", ...net });
+            else {
+                const bug = jsBug(err);
+                if (bug)
+                    FAILURE_ORIGIN.set(result, { origin: "internal", text: bug });
+            }
+        }
+    }
+    catch {
+        // never affects the result
+    }
+    return result;
+}
+/** A JS error quotes identifiers of our code, not user data, so its quotes are kept. */
+function maskedOwnText(prefix, text, quoted = true) {
+    return (prefix + scrub(text.slice(0, 2 * DETAIL_MAX).split(/\s+/).filter(Boolean).join(" "), quoted)).slice(0, DETAIL_MAX);
+}
+/** Best effort: classifying or sending must never change what the tool returns or throws. */
+function reportCall(telemetry, tool, value, thrown) {
+    if (!telemetry.isEnabled())
+        return;
+    try {
+        let reason = thrown ? toolOutcome(undefined, value) : toolOutcome(value);
+        let detail = "";
+        if (reason !== "ok") {
+            const noted = value && typeof value === "object" ? FAILURE_ORIGIN.get(value) : undefined;
+            const net = noted?.origin === "network" ? noted : thrown ? fetchFailure(value) : undefined;
+            const bug = noted?.origin === "internal" ? noted.text : thrown ? jsBug(value) : undefined;
+            if (net) {
+                reason = net.reason;
+                detail = net.text;
+            }
+            else if (bug) {
+                reason = "error_internal";
+                detail = maskedOwnText("internal: ", bug, false);
+            }
+            else if (noted?.origin === "local") {
+                reason = "error_invalid_request";
+                detail = maskedOwnText("local: ", noted.text);
+            }
+            else
+                detail = errorDetail(resultText(value));
+        }
+        telemetry.send("tool_call", { tool, reason, error_detail: detail || undefined });
+    }
+    catch {
+        // never affects the call
+    }
+}
 /**
- * Count every tool invocation by name. Wraps registerTool once, before the
- * domain modules register their tools, so no per-tool wiring is needed.
- * Only the tool *name* is recorded — arguments never reach telemetry.
+ * Counts every tool call by name and outcome. Wraps registerTool once, before the domain
+ * modules register their tools. Calls rejected by SDK input validation are not counted.
  */
 export function instrumentToolCalls(server, telemetry) {
     const original = server.registerTool.bind(server);
     // registerTool's generic signature does not survive a wrapper; the runtime
     // shape (name, config, callback) is stable per SDK contract.
-    server.registerTool = ((name, config, callback) => original(name, config, ((...args) => {
-        telemetry.send("tool_call", { tool: name });
-        return callback(...args);
+    server.registerTool = ((name, config, callback) => original(name, config, (async (...args) => {
+        let result;
+        try {
+            result = await callback(...args);
+        }
+        catch (e) {
+            reportCall(telemetry, name, e, true);
+            throw e;
+        }
+        reportCall(telemetry, name, result, false);
+        return result;
     })));
 }

package/dist/tools/util.js

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { noteFailure } from "../telemetry.js";
 /**
  * Schema factories, not shared consts: reusing one zod object across two fields
  * makes zod-to-json-schema dedupe them into a `$ref`, which some tool-schema
@@ -29,7 +30,11 @@ export function ok(data) {
     const text = typeof data === "string" ? data : JSON.stringify(data);
     return { content: [{ type: "text", text: text ?? "null" }] };
 }
+/** The failed result; also notes, off the wire, whether it is our own refusal or a JS bug (telemetry). */
 export function fail(err) {
+    return noteFailure(failText(err), err);
+}
+function failText(err) {
     let message = err instanceof Error ? err.message : String(err);
     // Surface the underlying cause (e.g. the network error behind a timeout) — no
     // secrets live in cause, and it makes failures far easier to diagnose.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@a1-x-tech/mcp-google-slides",
-  "version": "0.2.0",
+  "version": "1.1.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",