mcp-google-multi 6.0.0-alpha.76 → 6.0.0-alpha.78

package/README.md

@@ -55,6 +55,20 @@ New to all this? It's written for someone who just installed Claude Code and has
 
 **Go deeper:** [Configuration reference](./docs/configuration.md) · [What's covered](./COVERAGE.md) · [Features tour](./docs/features.md) · [Remote / HTTP setup](./docs/http-setup.md) · [Secrets in a vault](./docs/secrets.md) · [Local usage metrics](./docs/usage-metrics.md) · [Migrating to v6](./MIGRATION-v6.md) · [Security policy](./SECURITY.md) · [Roadmap](https://github.com/bakissation/mcp-google-multi/milestones)
 
+## Agent skill
+
+The repo and the npm package both ship an [Agent Skill](https://code.claude.com/docs/en/skills) at `skills/google-workspace/`: a hand-written `SKILL.md` covering account selection, the discover step, incremental Gmail sweeps, keeping results small, write profiles, and the escape hatch, plus a `reference/` folder with a generated argument table per service. Loading it gets an agent calling this server's tools correctly without guessing argument names.
+
+To install it for Claude Code, copy or symlink the `skills/google-workspace` folder into `~/.claude/skills/` (every project) or a project's own `.claude/skills/` (that project only):
+
+```bash
+# from a cloned copy of this repo
+ln -s "$(pwd)/skills/google-workspace" ~/.claude/skills/google-workspace
+
+# from the installed npm package
+ln -s "$(npm root -g)/mcp-google-multi/skills/google-workspace" ~/.claude/skills/google-workspace
+```
+
 ## Maintainer, sponsor & license
 
 Built and maintained by **Abdelbaki Berkati** — [berkati.xyz](https://berkati.xyz) · [@bakissation](https://github.com/bakissation). [Read the case study →](https://berkati.xyz/case-studies/mcp-google-multi/)

package/dist/fs-atomic.js

@@ -10,6 +10,9 @@ const RENAME_RETRY_MS = 20;
 const LOCK_LEASE_MS = 60_000;
 // Breaking a lock takes microseconds, so an older breaker file was left by a crash.
 const BREAKER_STALE_MS = 2_000;
+// The no-hard-link fallback writes the lock in two syscalls (create, then the
+// pid); a reader can catch it empty in between. See docs/internals.md.
+const LOCK_WRITE_GRACE_MS = 2_000;
 const PROCESS_START_MS = performance.timeOrigin;
 const OWNER_NAME = /^(\d+)\.(\d+|host)\.(\d+)\.([0-9a-f]{8}|0)\.[0-9a-f]{12}\.owner$/;
 function startOf(pid) {
@@ -63,11 +66,19 @@ function sameFile(a, b) {
 function isEnoent(error) {
     return error.code === 'ENOENT';
 }
+function bindingRecord(id) {
+    return `${id.dev}:${id.ino}:${id.mtimeNs}`;
+}
+function matchesBinding(content, id) {
+    const m = /^(\d+):(\d+):(\d+)$/.exec(content);
+    return m !== null && BigInt(m[1]) === id.dev && BigInt(m[2]) === id.ino && BigInt(m[3]) === id.mtimeNs;
+}
 // Undefined when the lock changed hands while it was being read.
 function readHolder(lock) {
     const before = fs.lstatSync(lock, { bigint: true });
     const body = before.isFile() ? fs.readFileSync(lock, 'utf8') : '';
     let owner;
+    let ownerPending = false;
     if (before.isFile()) {
         const dir = path.dirname(lock);
         const prefix = `${path.basename(lock)}.`;
@@ -79,10 +90,12 @@ function readHolder(lock) {
                 continue;
             const ownerPath = path.join(dir, name);
             try {
-                if (sameFile(fs.lstatSync(ownerPath, { bigint: true }), before)) {
+                const ownerStat = fs.lstatSync(ownerPath, { bigint: true });
+                if (sameFile(ownerStat, before) || matchesBinding(fs.readFileSync(ownerPath, 'utf8'), before)) {
                     owner = { path: ownerPath, ns: m[2], start: m[3], boot: m[4] };
                     break;
                 }
+                ownerPending = true;
             }
             catch (error) {
                 if (!isEnoent(error))
@@ -93,7 +106,7 @@ function readHolder(lock) {
     const after = fs.lstatSync(lock, { bigint: true });
     if (!sameFile(before, after))
         return undefined;
-    return { body, ino: after.ino, dev: after.dev, mtimeNs: after.mtimeNs, mtimeMs: Number(after.mtimeNs) / 1e6, owner };
+    return { body, ino: after.ino, dev: after.dev, mtimeNs: after.mtimeNs, mtimeMs: Number(after.mtimeNs) / 1e6, owner, ownerPending };
 }
 // The owner file's random name tells two holders apart even when the second
 // lock reuses the first one's freed inode.
@@ -115,10 +128,21 @@ function probeDead(pid) {
         return false;
     }
 }
+// Symmetric: a clock step back must not make a write-in-progress lock look
+// permanently fresh (see docs/internals.md).
+function withinWriteGrace(now, mtimeMs) {
+    return Math.abs(now - mtimeMs) < LOCK_WRITE_GRACE_MS;
+}
 function holderDead(holder, now) {
+    if (holder.body === '' && withinWriteGrace(now, holder.mtimeMs))
+        return false;
     const pid = Number(holder.body);
     if (!(Number.isSafeInteger(pid) && pid > 0))
         return true;
+    // A same-pid owner file exists but is not yet bound (the fallback lock's two
+    // writes race a reader); give it the same grace as an empty lock.
+    if (!holder.owner && holder.ownerPending && withinWriteGrace(now, holder.mtimeMs))
+        return false;
     const leaseOver = now - holder.mtimeMs >= LOCK_LEASE_MS;
     const owner = holder.owner;
     // No owner file: an older writer, whose namespace is unknown.
@@ -196,6 +220,53 @@ function releaseBreaker(breaker, token) {
             throw error;
     }
 }
+// No hard links here (Android/Termux denies link() in private storage, some
+// filesystems lack it entirely): the lock is created directly with O_EXCL,
+// carrying the bare pid a linked owner file would carry, and the owner file
+// is bound to it by a recorded identity instead of a hard link. See docs/internals.md.
+function takeFallbackLock(lock, ownerFile) {
+    const fd = fs.openSync(lock, 'wx', 0o600);
+    let acquired;
+    try {
+        fs.writeSync(fd, String(process.pid));
+        const stat = fs.fstatSync(fd, { bigint: true });
+        acquired = { dev: stat.dev, ino: stat.ino, mtimeNs: stat.mtimeNs };
+    }
+    catch (error) {
+        // The lock is left empty; remove it only if it is still the one we just
+        // created, then rethrow so the caller never retries a write failure.
+        const stat = fs.fstatSync(fd, { bigint: true });
+        fs.closeSync(fd);
+        try {
+            if (sameFile(fs.lstatSync(lock, { bigint: true }), stat))
+                fs.rmSync(lock, { force: true });
+        }
+        catch (cleanupError) {
+            if (!isEnoent(cleanupError))
+                throw cleanupError;
+        }
+        throw error;
+    }
+    fs.closeSync(fd);
+    try {
+        fs.writeFileSync(ownerFile, bindingRecord(acquired));
+    }
+    catch (error) {
+        // The lock already exists holding our live pid; without this cleanup
+        // every other writer sees an ownerless holder and waits out the full lease.
+        try {
+            const current = fs.lstatSync(lock, { bigint: true });
+            if (sameFile(current, acquired) && current.mtimeNs === acquired.mtimeNs)
+                fs.rmSync(lock, { force: true });
+        }
+        catch (cleanupError) {
+            if (!isEnoent(cleanupError))
+                throw cleanupError;
+        }
+        throw error;
+    }
+    return acquired;
+}
 // Hardlink-based advisory lock; the lock body is the bare pid, as older
 // readers expect. See docs/internals.md.
 export function withFileLock(absPath, fn, label = `lock: ${absPath}`) {
@@ -206,17 +277,31 @@ export function withFileLock(absPath, fn, label = `lock: ${absPath}`) {
     fs.writeFileSync(ownerFile, String(process.pid), { mode: 0o600, flag: 'wx' });
     const deadline = Date.now() + LOCK_TIMEOUT_MS;
     let linked = false;
+    let acquired;
     try {
         while (true) {
             try {
                 fs.linkSync(ownerFile, lock);
                 linked = true;
+                acquired = fs.lstatSync(lock, { bigint: true });
                 break;
             }
             catch (error) {
                 const err = error;
-                if (err.code !== 'EEXIST')
+                if (err.code === 'EACCES' || err.code === 'EPERM') {
+                    try {
+                        acquired = takeFallbackLock(lock, ownerFile);
+                        linked = true;
+                        break;
+                    }
+                    catch (fbError) {
+                        if (fbError.code !== 'EEXIST')
+                            throw fbError;
+                    }
+                }
+                else if (err.code !== 'EEXIST') {
                     throw error;
+                }
                 try {
                     const holder = readHolder(lock);
                     if (holder && holderDead(holder, Date.now()) && breakLock(lock, holder))
@@ -238,23 +323,24 @@ export function withFileLock(absPath, fn, label = `lock: ${absPath}`) {
         if (!linked)
             fs.rmSync(ownerFile, { force: true });
     }
-    let bound = false;
     try {
-        // Some network and FUSE filesystems give each name of one file its own
-        // inode number; there the owner file cannot vouch for the lock.
-        bound = sameFile(fs.lstatSync(ownerFile, { bigint: true }), fs.lstatSync(lock, { bigint: true }));
         return fn();
     }
     finally {
-        releaseLock(lock, ownerFile, bound);
+        releaseLock(lock, ownerFile, acquired);
     }
 }
 // A holder whose lock was broken (its owner file removed with it) must not
-// remove its successor's lock.
-function releaseLock(lock, ownerFile, bound) {
+// remove its successor's lock: only drop the lock if it is still the exact
+// file this call created, and our own owner file is still there to vouch for it.
+function releaseLock(lock, ownerFile, acquired) {
     try {
-        if (!bound || sameFile(fs.lstatSync(ownerFile, { bigint: true }), fs.lstatSync(lock, { bigint: true })))
-            fs.rmSync(lock, { force: true });
+        if (acquired) {
+            const current = fs.lstatSync(lock, { bigint: true });
+            if (sameFile(current, acquired) && current.mtimeNs === acquired.mtimeNs && fs.existsSync(ownerFile)) {
+                fs.rmSync(lock, { force: true });
+            }
+        }
     }
     catch (error) {
         if (!isEnoent(error))

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcp-google-multi",
-  "version": "6.0.0-alpha.76",
+  "version": "6.0.0-alpha.78",
   "mcpName": "io.github.bakissation/mcp-google-multi",
   "description": "Local MCP server for Google Workspace (Gmail, Drive, Calendar, Sheets, Docs, Contacts, Tasks, Meet, Search Console, +Forms/Chat/Admin) across multiple accounts — OAuth-only, encrypted token storage, deny-by-default writes.",
   "type": "module",
@@ -36,7 +36,8 @@
     "./package.json": "./package.json"
   },
   "files": [
-    "dist"
+    "dist",
+    "skills"
   ],
   "engines": {
     "node": ">=22"
@@ -85,6 +86,7 @@
     "gen:discovery": "tsx scripts/fetch-discovery.ts",
     "gen:tools": "tsx scripts/gen-tools.ts",
     "gen:coverage": "tsx scripts/gen-coverage.ts",
+    "gen:skill": "tsx scripts/gen-skill.ts",
     "eval:contract": "npx --yes promptfoo@0.123.1 eval -c eval/contract/promptfooconfig.yaml --no-progress-bar",
     "measure:lazy": "node scripts/measure-tools.mjs",
     "pack:mcpb": "mcpb pack . mcp-google-multi.mcpb",

package/skills/google-workspace/SKILL.md

@@ -0,0 +1,162 @@
+---
+name: google-workspace
+description: Use this skill when working with the mcp-google-multi MCP server to call Gmail, Drive, Calendar, Sheets, Docs, Contacts, Tasks, Meet, Chat, Slides, Forms, Search Console, Admin, or any other Google Workspace tool it exposes. Load it before the first discover or tool call in a session that touches this server, and whenever an account selector, a write-profile refusal, or an unfamiliar argument name needs resolving.
+---
+
+# Google Workspace MCP server
+
+This server exposes Google Workspace as MCP tools: a small set of curated,
+hand-written tools per service, a long tail of generated tools (one per
+Google API Discovery method), and an escape hatch for anything else. Reading
+this skill before the first call avoids the two most common failures: guessing
+an account when none was configured as default, and guessing an argument name
+instead of using the one the tool actually declares.
+
+## 1. Pick the account
+
+Every operational tool takes an `account` argument naming one of the
+configured aliases (an alias is a short local name, not the email address
+itself). Before calling anything:
+
+1. Call `account_list` first. It returns each alias, its email, admin flag,
+   token status, and which alias (if any) is the configured default.
+2. If a default account is set, omit `account` on a single-account call;
+   the server injects the default. Passing an alias is always safe too.
+3. If no default is set and more than one account is configured, you must
+   pass `account` explicitly. A call that omits it then fails with
+   `E_NO_DEFAULT_ACCOUNT` and a hint listing every `alias=email` pair so you
+   can match the one the user means by email, name, or context, rather than
+   guessing.
+4. Read tools accept `"*"` for the `account` argument to fan out across every
+   configured account (bounded concurrency), or a comma-separated subset such
+   as `"work,personal"`. Fan-out is read-only by design: write tools, and the
+   handful of read tools that save a file to local disk (`drive_download`,
+   `drive_export`, `gmail_download_attachment`), take exactly one account.
+   A fan-out call returns `{ results: [{ account, ok, data|error }], partial }`
+   so one account failing never hides the others.
+
+## 2. Discover before calling
+
+Tools are hidden from the model's context until revealed, but every tool is
+always callable by exact name (discovery is a listing optimization, not a
+security boundary).
+
+1. Call `{service}_discover` (e.g. `gmail_discover`, `drive_discover`) for the
+   service you need. It returns that service's catalog: each tool's name, a
+   one-line summary, its arguments, and its read/create/update/delete class.
+   An optional `query` argument filters the catalog by keyword.
+2. Call the tool **by its exact name** from that catalog. Do not guess a name
+   by analogy with another service.
+3. `discover_all` reveals every curated tool across all services at once,
+   useful before a session doing substantial cross-service work, and
+   `discover_reset` collapses back to the configured default afterward to
+   reclaim context.
+4. A client that loads tool schemas on demand (rather than accepting
+   everything a server advertises) may need its own tool-search or
+   tool-load step before a newly revealed tool is actually callable. If a
+   call to a tool you just discovered fails as unknown on such a client,
+   look for that client's own load-tool mechanism before retrying the
+   Google call itself.
+
+## 3. Incremental Gmail sweeps
+
+For a recurring "what's new in this mailbox" check, do not re-run the same
+broad `gmail_search` on a timer. Two cheaper patterns:
+
+- **`gmail_list_history(startHistoryId, historyTypes)`** with a
+  `startHistoryId` you stored from a previous `gmail_get_profile` or
+  `gmail_list_history` response. It returns exactly the mailbox changes since that
+  point (messages added/deleted, labels added/removed), optionally filtered
+  by `historyTypes`. Store the newest history ID you observe and pass it
+  next time.
+- **`gmail_search(since, until)`** when you have no stored history ID (e.g.
+  the first sweep, or after a gap long enough that Gmail's history window
+  has expired). Both accept an ISO 8601 date or a date-time with an explicit
+  `Z` or UTC offset, never a bare local time.
+
+## 4. Keep results small
+
+Large responses cost context and, for list endpoints, risk a page that looks
+complete but isn't. Prefer the per-call controls over reading everything and
+discarding most of it:
+
+- On a generated tool or the `google_api_call(queryParams)` escape hatch,
+  pass Google's own `fields` partial-response query param to restrict a
+  response to the properties you actually need. Curated tools already pick a
+  response shape for you, so they don't expose `fields` themselves.
+- Leave `full` unset (it defaults to the trimmed shape) on fat readers such as
+  `gmail_read(full)` and `gmail_read_thread(full)`; pass `full: true` only
+  when you actually need the untruncated body. `calendar_list_events` and
+  `calendar_list_instances` always return a trimmed view with no `full`
+  argument to toggle; call `calendar_get_event` for one event's complete
+  data.
+- Cap the page on list and search tools (the argument name varies by tool:
+  `drive_search(maxResults)` and `contacts_search(pageSize)` are two
+  examples; check `{service}_discover` or the reference table for the exact
+  name), and follow `nextPageToken` rather than assuming a short list is the
+  whole answer. Where a list reports `truncated`, there is more to fetch.
+- On Gmail, pass `headers` on `gmail_read(headers)` or
+  `gmail_read_batch(headers)` to fetch only `id`, `threadId`, `labelIds`, and
+  the named header values, skipping full body decoding entirely when you
+  only need metadata like `Subject` or `From`.
+
+## 5. Write profiles
+
+Reads are never gated. Writes (create/update/delete) are deny-by-default and
+controlled by the deployment's `GOOGLE_PROFILE`:
+
+- **`read-only`** (the default): every write refused.
+- **`safe-writes`**: ordinary creates and updates on your own data are
+  allowed, and so is moving an item to or from Trash (`gmail_trash`,
+  `drive_trash`, and their untrash equivalents) since that is recoverable.
+  Permanent deletes (emptying Trash, a hard Gmail or Drive delete),
+  `drive_transfer` with `move: true`, and privileged writes (anything needing
+  an admin, Vault, reseller, or script scope, or registering a push channel)
+  stay refused under this profile.
+- **`full-writes`**: everything permitted by OAuth scope and the account's
+  grants, privileged writes included. An operator's allow and deny patterns
+  can widen or narrow any profile.
+
+A write a profile refuses comes back as `{ error: "write_disabled", message,
+hint, retriable: false }` rather than a silent no-op or a generic failure.
+The `hint` names the exact rule that refused it (a deny pattern, the
+privileged-write rule, or the active profile) and what would need to change;
+read it rather than retrying the same call. This applies identically to
+curated tools, generated tools, and the `google_api_call` escape hatch.
+
+## 6. Argument names are exact
+
+The server never rewrites an argument name: if you pass `pageSize` where a
+tool expects `maxResults`, the call fails rather than silently mapping one to
+the other. Always use the exact name shown by `{service}_discover` or the
+service's reference table in `reference/` next to this file. When in doubt,
+discover the tool again and read its declared arguments rather than guessing
+from memory or from another service's convention.
+
+Each `reference/<service>.md` file tables every **curated** tool for that
+service: its name, its read/create/update/delete class, a one-line summary,
+and every argument with its type, whether it's required, and its
+description. **Generated** tools (the long tail, one per Google API
+Discovery method) are not tabled individually: they take Google's own
+Discovery parameter names directly, and calling `{service}_discover` lists
+each one with its arguments at call time.
+
+## 7. Escape hatch for anything not covered
+
+If a service has no curated or generated tool for the operation you need
+(or discovery/`reference/` doesn't cover it):
+
+1. Call `google_api_search(query, api, maxResults)` with keywords (optionally
+   scoped to one `api` alias) to find the Discovery method id, e.g.
+   `drive.revisions.list`.
+2. Call `google_api_call(api, methodId, pathParams, queryParams, body)` with
+   that method id and whichever of path params, query params, or a JSON body
+   it needs.
+
+The escape hatch runs through the same write-control policy as named tools
+(the read/create/update/delete class is derived from the method's HTTP verb
+and name), returns JSON only (binary media is refused with a pointer to
+`drive_download` / `drive_export`), and a response over about 100k
+characters may be cut by the client, so narrow a large request. Prefer a named curated or
+generated tool when one exists: it is more token-lean and better typed than
+building the call by hand.

package/skills/google-workspace/reference/admin.md

@@ -0,0 +1,105 @@
+# admin
+
+<!-- GENERATED by scripts/gen-skill.ts, do not edit by hand. Regenerate: npm run gen:skill -->
+
+6 curated tools, plus 132 generated tools (Google Discovery parameter names; see `admin_discover`).
+
+## `admin_group_members_list`
+
+Class: read
+
+List members of a Workspace group
+
+| Argument | Type | Required | Description |
+|---|---|---|---|
+| `account` | string | optional | Google account alias (must be a Workspace admin); "*" = all accounts; omit for the default account |
+| `groupKey` | string | required | Group email or ID |
+| `roles` | string | optional | Comma-separated roles to include (OWNER, MANAGER, MEMBER) |
+| `includeDerivedMembership` | boolean | optional |  |
+| `maxResults` | number | optional |  |
+| `pageToken` | string | optional |  |
+
+## `admin_groups_list`
+
+Class: read
+
+List groups in the Workspace customer
+
+| Argument | Type | Required | Description |
+|---|---|---|---|
+| `account` | string | optional | Google account alias (must be a Workspace admin); "*" = all accounts; omit for the default account |
+| `customer` | string | optional |  |
+| `domain` | string | optional |  |
+| `userKey` | string | optional | Only return groups containing this user |
+| `query` | string | optional |  |
+| `maxResults` | number | optional |  |
+| `pageToken` | string | optional |  |
+
+## `admin_users_get`
+
+Class: read
+
+Get a single Workspace user by email or user ID
+
+| Argument | Type | Required | Description |
+|---|---|---|---|
+| `account` | string | optional | Google account alias (must be a Workspace admin); "*" = all accounts; omit for the default account |
+| `userKey` | string | required | User email or ID |
+| `projection` | enum | optional |  |
+
+## `admin_users_list`
+
+Class: read
+
+List users in the Workspace customer. Filter by domain or customer=my_customer.
+
+| Argument | Type | Required | Description |
+|---|---|---|---|
+| `account` | string | optional | Google account alias (must be a Workspace admin); "*" = all accounts; omit for the default account |
+| `customer` | string | optional |  |
+| `domain` | string | optional |  |
+| `query` | string | optional | Directory search query: space-separated clauses of field+operator+value, ANDed together. "=" is exact match, ":" is a contains/startsWith match. Searchable fields include email, name (matches the concatenated givenName+familyName), givenName, familyName, isAdmin, isDelegatedAdmin, orgName, orgTitle, orgDepartment, manager, directManager, addressCountry. Prefix/wildcard matching is a trailing "*" on a ":" clause, e.g. "email:admin*" for every address starting with "admin". Examples: 'name:John', 'isAdmin=true', 'orgTitle:Manager orgName=Engineering'. |
+| `maxResults` | number | optional |  |
+| `pageToken` | string | optional |  |
+| `orderBy` | enum | optional |  |
+| `showDeleted` | boolean | optional |  |
+| `projection` | enum | optional |  |
+
+## `admin_users_update`
+
+Class: update
+
+Update a Workspace user (PATCH semantics). Gated by write-control (a CUD tool).
+
+| Argument | Type | Required | Description |
+|---|---|---|---|
+| `account` | string | optional | Google account alias (must be a Workspace admin) |
+| `userKey` | string | required | User email or ID |
+| `givenName` | string | optional |  |
+| `familyName` | string | optional |  |
+| `suspended` | boolean | optional |  |
+| `password` | string | optional |  |
+| `changePasswordAtNextLogin` | boolean | optional |  |
+| `orgUnitPath` | string | optional |  |
+
+## `reports_activities_list`
+
+Class: read
+
+List Admin Activity audit log entries. Filter by application (login, drive, gmail, admin, token, etc.), user, date range, event. The single most useful admin endpoint for SMB visibility.
+
+| Argument | Type | Required | Description |
+|---|---|---|---|
+| `account` | string | optional | Google account alias (must be a Workspace admin); "*" = all accounts; omit for the default account |
+| `applicationName` | enum | required | Which application's activity to query |
+| `userKey` | string | optional | User profile ID, email, or "all" (default) |
+| `startTime` | string | optional | RFC 3339 lower bound |
+| `endTime` | string | optional | RFC 3339 upper bound |
+| `eventName` | string | optional | Specific event name to filter |
+| `actorIpAddress` | string | optional |  |
+| `filters` | string | optional | Comma-separated event-parameter filters with relational operators |
+| `orgUnitID` | string | optional |  |
+| `groupIdFilter` | string | optional |  |
+| `customerId` | string | optional |  |
+| `maxResults` | number | optional |  |
+| `pageToken` | string | optional |  |

package/skills/google-workspace/reference/analytics.md

@@ -0,0 +1,70 @@
+# analytics
+
+<!-- GENERATED by scripts/gen-skill.ts, do not edit by hand. Regenerate: npm run gen:skill -->
+
+4 curated tools, plus 62 generated tools (Google Discovery parameter names; see `analytics_discover`).
+
+## `analytics_account_summaries`
+
+Class: read
+
+List every Google Analytics (GA4) account and property this Google account can access, with their numeric property IDs. The starting point for any Analytics question ("what properties do I have?").
+
+| Argument | Type | Required | Description |
+|---|---|---|---|
+| `account` | string | optional | Google account alias; "*" = all accounts; omit for the default account |
+| `pageSize` | number | optional | Summaries per page (default 50, max 200) |
+| `pageToken` | string | optional | Token from a previous page |
+
+## `analytics_get_metadata`
+
+Class: read
+
+List every valid dimension and metric API name for a GA4 property, including its custom definitions. Call this before analytics_run_report when unsure which names exist. Property "0" returns the standard set without property access.
+
+| Argument | Type | Required | Description |
+|---|---|---|---|
+| `account` | string | optional | Google account alias; "*" = all accounts; omit for the default account |
+| `property` | string | required | GA4 property: numeric ID like "213025502" or "properties/213025502" — NOT a "G-..." measurement ID and not "UA-...". Find yours with analytics_account_summaries. |
+
+## `analytics_run_realtime_report`
+
+Class: read
+
+Run a GA4 realtime report: who is on the site right now (last 30 minutes). Realtime supports a restricted set of names, e.g. metrics activeUsers, screenPageViews, eventCount, keyEvents; dimensions country, city, deviceCategory, unifiedScreenName, eventName.
+
+| Argument | Type | Required | Description |
+|---|---|---|---|
+| `account` | string | optional | Google account alias; "*" = all accounts; omit for the default account |
+| `property` | string | required | GA4 property: numeric ID like "213025502" or "properties/213025502" — NOT a "G-..." measurement ID and not "UA-...". Find yours with analytics_account_summaries. |
+| `metrics` | array | required | Realtime metric API names, e.g. ["activeUsers"] |
+| `dimensions` | array | optional | Realtime dimension API names, e.g. ["country"] or ["unifiedScreenName"] |
+| `dimensionFilter` | object | optional | FilterExpression on dimensions — same shape as analytics_run_report |
+| `metricFilter` | object | optional | FilterExpression on metric values — same shape as analytics_run_report |
+| `minuteRanges` | array | optional | Up to 2 ranges of minutes-ago, e.g. [{"startMinutesAgo":29,"endMinutesAgo":0}] (default: last 30 minutes) |
+| `limit` | number | optional | Max rows to return |
+| `returnPropertyQuota` | boolean | optional | Include this property's remaining realtime quota tokens |
+
+## `analytics_run_report`
+
+Class: read
+
+Run a Google Analytics (GA4) report: metrics over a date range, optionally grouped by dimensions — the workhorse for questions like "how many users last week, by country". Dates accept YYYY-MM-DD or relative forms ("today", "yesterday", "28daysAgo"). Also accepts the native GA4 request shapes directly: a single dateRanges entry in place of startDate/endDate, and metrics/dimensions as {name} objects. Unsure which dimension/metric names are valid? Call analytics_get_metadata first.
+
+| Argument | Type | Required | Description |
+|---|---|---|---|
+| `account` | string | optional | Google account alias; "*" = all accounts; omit for the default account |
+| `property` | string | required | GA4 property: numeric ID like "213025502" or "properties/213025502" — NOT a "G-..." measurement ID and not "UA-...". Find yours with analytics_account_summaries. |
+| `startDate` | string | optional | Start date: YYYY-MM-DD or relative ("today", "yesterday", "NdaysAgo" e.g. "28daysAgo"). Required unless dateRanges is given. |
+| `endDate` | string | optional | End date: YYYY-MM-DD or relative ("today", "yesterday", "NdaysAgo"). Required unless dateRanges is given. |
+| `dateRanges` | array | optional | Native GA4 shape, as an alternative to startDate/endDate: exactly one {startDate, endDate} entry (this tool runs one range per call). |
+| `metrics` | array | required | Metric API names, e.g. ["activeUsers","sessions","screenPageViews"], or the native GA4 [{"name":"activeUsers"}] form. Max 10. Valid names (including custom ones) come from analytics_get_metadata. |
+| `dimensions` | array | optional | Dimension API names to group by, e.g. ["date"] or ["country","deviceCategory"], or the native GA4 {"name":...} form. Max 9. Omit for a single total row. |
+| `dimensionFilter` | object | optional | FilterExpression on dimensions (applies independently of metricFilter). Simple: {"filter":{"fieldName":"country","stringFilter":{"matchType":"EXACT","value":"France"}}}. AND of two: {"andGroup":{"expressions":[{"filter":{"fieldName":"country","stringFilter":{"matchType":"EXACT","value":"France"}}},{"filter":{"fieldName":"deviceCategory","stringFilter":{"matchType":"EXACT","value":"mobile"}}}]}}. matchType: EXACT \| BEGINS_WITH \| ENDS_WITH \| CONTAINS \| FULL_REGEXP (add "caseSensitive":true for case-sensitive). Also available: inListFilter, notExpression, orGroup. |
+| `metricFilter` | object | optional | FilterExpression on metric values, e.g. {"filter":{"fieldName":"sessions","numericFilter":{"operation":"GREATER_THAN","value":{"int64Value":"100"}}}}. operation: EQUAL \| LESS_THAN \| LESS_THAN_OR_EQUAL \| GREATER_THAN \| GREATER_THAN_OR_EQUAL; betweenFilter takes fromValue/toValue. |
+| `orderBys` | array | optional | Sort order, e.g. [{"metric":{"metricName":"sessions"},"desc":true}] or [{"dimension":{"dimensionName":"date"}}]. Default: unordered. |
+| `limit` | number | optional | Max rows to return (API default 10000). Keep small for readable output. |
+| `offset` | number | optional | Zero-based row offset for pagination |
+| `metricAggregations` | array | optional | Also return aggregate rows across all matching data (surfaced as totals/maximums/minimums) |
+| `keepEmptyRows` | boolean | optional | Include rows whose metrics are all zero (default false) |
+| `returnPropertyQuota` | boolean | optional | Include this property's remaining quota tokens in the response |

package/skills/google-workspace/reference/appsmarket.md

@@ -0,0 +1,5 @@
+# appsmarket
+
+<!-- GENERATED by scripts/gen-skill.ts, do not edit by hand. Regenerate: npm run gen:skill -->
+
+This service has no curated tools. All 2 `appsmarket` tools are generated from Google's API Discovery document: they take Google's own Discovery parameter names (not a hand-written schema), and `appsmarket_discover` lists each one with its arguments.