google-workspace-admin-mcp 0.1.1 → 0.1.3
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 +61 -33
- package/dist/main.js +1 -1
- package/dist/main.js.map +1 -1
- package/dist/server.d.ts.map +1 -1
- package/dist/server.js +2 -1
- package/dist/server.js.map +1 -1
- package/dist/version.d.ts +7 -0
- package/dist/version.d.ts.map +1 -0
- package/dist/version.js +8 -0
- package/dist/version.js.map +1 -0
- package/docs/SETUP.md +36 -5
- package/docs/SMOKE-TESTING.md +8 -3
- package/docs/TOOLS.md +4 -3
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -3,10 +3,9 @@
|
|
|
3
3
|
An MCP server for the **Google Workspace admin plane**: the APIs that manage a
|
|
4
4
|
tenant, not the ones that read a user's mail.
|
|
5
5
|
|
|
6
|
-
> **Status:
|
|
7
|
-
>
|
|
8
|
-
>
|
|
9
|
-
> [issues](https://github.com/singlebarrellabs/google-workspace-admin-mcp/issues).
|
|
6
|
+
> **Status: 0.1.1.** Eight admin surfaces, 107 tools, published to npm.
|
|
7
|
+
> [`docs/TOOLS.md`](docs/TOOLS.md) lists every tool; [`docs/SETUP.md`](docs/SETUP.md)
|
|
8
|
+
> takes you from a clean Cloud project to a working server.
|
|
10
9
|
|
|
11
10
|
## Why
|
|
12
11
|
|
|
@@ -31,9 +30,10 @@ stated in a README:
|
|
|
31
30
|
- No domain-wide delegation.
|
|
32
31
|
- No impersonation: there is no `as` parameter anywhere, and no credential type
|
|
33
32
|
that could express one.
|
|
34
|
-
- No user-content APIs: Gmail, Drive, Docs, Sheets, Slides, Calendar
|
|
35
|
-
Keep, Tasks, Forms, YouTube, Classroom, Sites and Apps Script are
|
|
36
|
-
permanently.
|
|
33
|
+
- No user-content APIs: Gmail, Drive, Docs, Sheets, Slides, the Calendar API,
|
|
34
|
+
Chat, Meet, Keep, Tasks, Forms, YouTube, Classroom, Sites and Apps Script are
|
|
35
|
+
out of scope, permanently. (Calendar *resources* — the rooms a company books —
|
|
36
|
+
are admin data and are in scope.)
|
|
37
37
|
|
|
38
38
|
The supported paths for the things people use impersonation for are the audited
|
|
39
39
|
ones: **Vault** for legal holds and eDiscovery, **Data Transfer** for offboarding,
|
|
@@ -59,17 +59,15 @@ without guessing.
|
|
|
59
59
|
|
|
60
60
|
## Authentication
|
|
61
61
|
|
|
62
|
-
One credential:
|
|
63
|
-
|
|
64
|
-
|
|
62
|
+
One credential: a **Desktop-app OAuth client** in your own Cloud project, with
|
|
63
|
+
the consent screen set to **Internal**. The administrator signs in once; the
|
|
64
|
+
refresh token is stored with owner-only permissions.
|
|
65
65
|
|
|
66
|
-
- No service account, no DWD grant, no
|
|
67
|
-
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
- Scopes are admin-only. Nothing in the requested scope list grants mailbox or
|
|
72
|
-
file content of another user.
|
|
66
|
+
- No service account, no DWD grant, no key file to rotate.
|
|
67
|
+
- Internal keeps refresh tokens long-lived. A client left in **Testing** expires
|
|
68
|
+
them after seven days; [`docs/SETUP.md`](docs/SETUP.md#the-seven-day-trap)
|
|
69
|
+
explains the fix.
|
|
70
|
+
- Scopes are admin-only. Nothing requested grants another user's mail or files.
|
|
73
71
|
|
|
74
72
|
## Safety model
|
|
75
73
|
|
|
@@ -86,33 +84,65 @@ signs in once; the refresh token is stored locally with owner-only permissions.
|
|
|
86
84
|
## Install
|
|
87
85
|
|
|
88
86
|
```bash
|
|
89
|
-
npm install -g google-workspace-admin-mcp
|
|
90
87
|
export GWS_CLIENT_ID=... # Desktop-app OAuth client, Internal consent screen
|
|
91
88
|
export GWS_CLIENT_SECRET=...
|
|
92
|
-
google-workspace-admin-mcp auth
|
|
89
|
+
npx google-workspace-admin-mcp@latest auth
|
|
93
90
|
```
|
|
94
91
|
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
92
|
+
Authorization prints a URL, waits for the loopback callback and stores the
|
|
93
|
+
refresh token. Then add the server to your client:
|
|
94
|
+
|
|
95
|
+
```json
|
|
96
|
+
{
|
|
97
|
+
"mcpServers": {
|
|
98
|
+
"gwa": {
|
|
99
|
+
"command": "npx",
|
|
100
|
+
"args": ["-y", "google-workspace-admin-mcp@latest"],
|
|
101
|
+
"env": {
|
|
102
|
+
"GWS_CLIENT_ID": "…",
|
|
103
|
+
"GWS_CLIENT_SECRET": "…"
|
|
104
|
+
}
|
|
105
|
+
}
|
|
106
|
+
}
|
|
107
|
+
}
|
|
108
|
+
```
|
|
109
|
+
|
|
110
|
+
That block is the shape Claude Desktop and Claude Code use; OpenCode puts the
|
|
111
|
+
same command under `mcp.servers` in its config. A client you launch from a shell
|
|
112
|
+
that already exports the two variables needs no `env` block at all.
|
|
113
|
+
|
|
114
|
+
The server starts **read-only**: mutating tools are absent, not merely refused.
|
|
115
|
+
Set `GWS_MODE=write` to register them, and `GWS_PASSTHROUGH=on` for the
|
|
116
|
+
allowlisted raw-call tools.
|
|
99
117
|
|
|
100
|
-
The
|
|
101
|
-
|
|
118
|
+
The full walkthrough — six APIs, consent screen, admin roles per surface,
|
|
119
|
+
editions, the seven-day trap — is in [`docs/SETUP.md`](docs/SETUP.md).
|
|
120
|
+
|
|
121
|
+
## What to ask it
|
|
122
|
+
|
|
123
|
+
- "Find jane@, list her recent logins, her OAuth grants and her devices." →
|
|
124
|
+
directory and audit tools, read-only.
|
|
125
|
+
- "Who changed group membership in the last week?" → flattened audit events.
|
|
126
|
+
- "Offboard jane@: revoke app grants, sign out sessions, list devices, then
|
|
127
|
+
suspend." → the destructive calls each ask for confirmation; run it in write
|
|
128
|
+
mode.
|
|
129
|
+
- "Which licence seats are unused?" → licence list plus user last-login data.
|
|
130
|
+
- "Can this tenant use Vault?" → `gws_auth_status` reports the edition it probed
|
|
131
|
+
and the source of that answer.
|
|
102
132
|
|
|
103
133
|
## Development
|
|
104
134
|
|
|
105
135
|
```bash
|
|
106
136
|
npm install
|
|
107
|
-
npm run check # typecheck
|
|
137
|
+
npm run check # typecheck, lint, scope check, tests
|
|
108
138
|
```
|
|
109
139
|
|
|
110
140
|
`npm run docs:scopes` regenerates the scope list in `docs/SETUP.md` from
|
|
111
141
|
`ADMIN_SCOPES`; `npm run check` fails when the two disagree.
|
|
112
142
|
|
|
113
|
-
Specs live in `openspec/
|
|
114
|
-
|
|
115
|
-
enforcement mechanism.
|
|
143
|
+
Specs live in `openspec/specs/`, one per capability; the archived change that
|
|
144
|
+
produced them is under `openspec/changes/archive/`. OpenSpec is used for
|
|
145
|
+
planning only; tests are the enforcement mechanism.
|
|
116
146
|
|
|
117
147
|
No live Workspace tenant is needed to contribute. Verification tiers, tenant
|
|
118
148
|
access levels, the redaction rules for smoke output and the smoke commands are in
|
|
@@ -131,10 +161,8 @@ Publishing runs from GitHub Actions, never from a laptop:
|
|
|
131
161
|
`<version>-beta.<run_number>` to the `beta` dist-tag, so a branch is
|
|
132
162
|
installable before it merges. `v*-beta*` tags and manual runs do the same.
|
|
133
163
|
|
|
134
|
-
|
|
135
|
-
repository and `ci.yml
|
|
136
|
-
|
|
137
|
-
No `NPM_TOKEN` secret is used: npm validates the workflow's OIDC identity.
|
|
164
|
+
No `NPM_TOKEN` secret is used: npm validates the workflow's OIDC identity
|
|
165
|
+
(trusted publisher bound to this repository and `ci.yml`).
|
|
138
166
|
|
|
139
167
|
## License
|
|
140
168
|
|
package/dist/main.js
CHANGED
|
@@ -20,7 +20,7 @@ import { RolesService } from "./services/roles.js";
|
|
|
20
20
|
import { TransferService } from "./services/transfer.js";
|
|
21
21
|
import { UserSecurityService } from "./services/user-security.js";
|
|
22
22
|
import { VaultService } from "./services/vault.js";
|
|
23
|
-
|
|
23
|
+
import { VERSION } from "./version.js";
|
|
24
24
|
async function main() {
|
|
25
25
|
const command = process.argv[2];
|
|
26
26
|
if (command === "--version" || command === "-v") {
|
package/dist/main.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"main.js","sourceRoot":"","sources":["../src/main.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AAEjF,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACjD,OAAO,EAAE,SAAS,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAC/D,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,EAAE,gBAAgB,EAAE,MAAM,2BAA2B,CAAC;AAC7D,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,EAAE,kBAAkB,EAAE,MAAM,4BAA4B,CAAC;AAChE,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAC3D,OAAO,EAAE,aAAa,EAAE,MAAM,gCAAgC,CAAC;AAC/D,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,EAAE,oBAAoB,EAAE,MAAM,8BAA8B,CAAC;AACpE,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAC3D,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AACzD,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAC3D,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACnD,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AACzD,OAAO,EAAE,mBAAmB,EAAE,MAAM,6BAA6B,CAAC;AAClE,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;
|
|
1
|
+
{"version":3,"file":"main.js","sourceRoot":"","sources":["../src/main.ts"],"names":[],"mappings":"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"}
|
package/dist/server.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAEpE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAClD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACtD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AACzD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAGhD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,4BAA4B,CAAC;AACrE,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,8BAA8B,CAAC;AACzE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAChE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAC5D,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAChE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAC9D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAExD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AAS9D,OAAO,EAAkB,SAAS,EAAE,MAAM,kBAAkB,CAAC;
|
|
1
|
+
{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAEpE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAClD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACtD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AACzD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAGhD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,4BAA4B,CAAC;AACrE,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,8BAA8B,CAAC;AACzE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAChE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAC5D,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAChE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAC9D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAExD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AAS9D,OAAO,EAAkB,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAG7D,MAAM,WAAW,UAAU;IACzB,MAAM,EAAE,SAAS,CAAC;IAClB,KAAK,CAAC,EAAE,WAAW,CAAC;IACpB,KAAK,CAAC,EAAE,YAAY,CAAC;IACrB,WAAW,CAAC,EAAE,kBAAkB,CAAC;IACjC,QAAQ,CAAC,EAAE,eAAe,CAAC;IAC3B,SAAS,CAAC,EAAE,gBAAgB,CAAC;IAC7B,aAAa,CAAC,EAAE,oBAAoB,CAAC;IACrC,SAAS,CAAC,EAAE,gBAAgB,CAAC;IAC7B,kFAAkF;IAClF,WAAW,CAAC,EAAE,WAAW,EAAE,CAAC;IAC5B,SAAS,CAAC,EAAE,iBAAiB,CAAC;IAC9B,OAAO,CAAC,EAAE,YAAY,CAAC;IACvB,OAAO,CAAC,EAAE,cAAc,CAAC;CAC1B;AAED,wBAAgB,WAAW,CAAC,IAAI,EAAE,UAAU,GAAG;IAAE,MAAM,EAAE,SAAS,CAAC;IAAC,KAAK,EAAE,MAAM,EAAE,CAAA;CAAE,CAmEpF;AAED,OAAO,EAAE,SAAS,EAAE,CAAC"}
|
package/dist/server.js
CHANGED
|
@@ -12,6 +12,7 @@ import { systemTools } from "./tools/system.js";
|
|
|
12
12
|
import { transferTools } from "./tools/transfer.js";
|
|
13
13
|
import { vaultTools } from "./tools/vault.js";
|
|
14
14
|
import { mapGoogleError, ToolError } from "./util/errors.js";
|
|
15
|
+
import { VERSION } from "./version.js";
|
|
15
16
|
export function buildServer(deps) {
|
|
16
17
|
const { config, token } = deps;
|
|
17
18
|
const audit = new AuditLog(config.auditPath);
|
|
@@ -28,7 +29,7 @@ export function buildServer(deps) {
|
|
|
28
29
|
...(deps.reports ? reportsTools(deps.reports) : []),
|
|
29
30
|
];
|
|
30
31
|
const registered = toolsForMode(specs, config.mode);
|
|
31
|
-
const server = new McpServer({ name: "google-workspace-admin-mcp", version:
|
|
32
|
+
const server = new McpServer({ name: "google-workspace-admin-mcp", version: VERSION });
|
|
32
33
|
for (const spec of registered) {
|
|
33
34
|
server.registerTool(spec.name, { description: spec.description, inputSchema: spec.inputShape }, async (input) => {
|
|
34
35
|
const started = Date.now();
|
package/dist/server.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"server.js","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACpE,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAKxB,OAAO,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAC7C,OAAO,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAQlE,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAE3D,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AACtD,OAAO,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAC/D,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AACtD,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AACrD,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,EAAE,cAAc,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;
|
|
1
|
+
{"version":3,"file":"server.js","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"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"}
|
|
@@ -0,0 +1,7 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The published version, read from the package manifest at run time. A copied
|
|
3
|
+
* literal here goes stale on every release, and `--version` then disagrees with
|
|
4
|
+
* what npm installed.
|
|
5
|
+
*/
|
|
6
|
+
export declare const VERSION: string;
|
|
7
|
+
//# sourceMappingURL=version.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"version.d.ts","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAEA;;;;GAIG;AACH,eAAO,MAAM,OAAO,QAIX,CAAC"}
|
package/dist/version.js
ADDED
|
@@ -0,0 +1,8 @@
|
|
|
1
|
+
import { readFileSync } from "node:fs";
|
|
2
|
+
/**
|
|
3
|
+
* The published version, read from the package manifest at run time. A copied
|
|
4
|
+
* literal here goes stale on every release, and `--version` then disagrees with
|
|
5
|
+
* what npm installed.
|
|
6
|
+
*/
|
|
7
|
+
export const VERSION = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version;
|
|
8
|
+
//# sourceMappingURL=version.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"version.js","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAEvC;;;;GAIG;AACH,MAAM,CAAC,MAAM,OAAO,GAClB,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,IAAI,GAAG,CAAC,iBAAiB,EAAE,OAAO,IAAI,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,CAG7E,CAAC,OAAO,CAAC"}
|
package/docs/SETUP.md
CHANGED
|
@@ -127,9 +127,40 @@ administrator, granted scopes, token expiry, mode, and which surfaces the tenant
|
|
|
127
127
|
can use.
|
|
128
128
|
|
|
129
129
|
If status says a surface is unavailable for edition reasons, that is a fact
|
|
130
|
-
about the tenant, not a misconfiguration. See [Editions](#
|
|
130
|
+
about the tenant, not a misconfiguration. See [Editions](#12-editions).
|
|
131
|
+
|
|
132
|
+
## 9. Connect a client
|
|
133
|
+
|
|
134
|
+
The server speaks MCP over stdio. Point your client at `npx` and pass the two
|
|
135
|
+
client variables; the token is read from the state directory, so `auth` only has
|
|
136
|
+
to run once.
|
|
137
|
+
|
|
138
|
+
```json
|
|
139
|
+
{
|
|
140
|
+
"mcpServers": {
|
|
141
|
+
"gwa": {
|
|
142
|
+
"command": "npx",
|
|
143
|
+
"args": ["-y", "google-workspace-admin-mcp@latest"],
|
|
144
|
+
"env": {
|
|
145
|
+
"GWS_CLIENT_ID": "…",
|
|
146
|
+
"GWS_CLIENT_SECRET": "…",
|
|
147
|
+
"GWS_MODE": "readonly"
|
|
148
|
+
}
|
|
149
|
+
}
|
|
150
|
+
}
|
|
151
|
+
}
|
|
152
|
+
```
|
|
153
|
+
|
|
154
|
+
- Claude Desktop and Claude Code read `mcpServers` from their own config file.
|
|
155
|
+
- OpenCode reads the same command shape under `mcp.servers` (`"type": "local"`,
|
|
156
|
+
`"command": [...]`); if the client is launched from a shell that already
|
|
157
|
+
exports the variables, the `env` block can be dropped.
|
|
158
|
+
- `GWS_MODE` is optional and defaults to `readonly`.
|
|
159
|
+
|
|
160
|
+
Ask the server for `gws_auth_status` first; it reports the signed-in
|
|
161
|
+
administrator, granted scopes, token expiry, mode and the edition it probed.
|
|
131
162
|
|
|
132
|
-
##
|
|
163
|
+
## 10. Grant the admin roles
|
|
133
164
|
|
|
134
165
|
The signed-in account needs the privilege for each surface you intend to use.
|
|
135
166
|
A super admin has all of them; anything less should be a custom role.
|
|
@@ -150,7 +181,7 @@ Vault is the one that surprises people: an admin without **View All Matters**
|
|
|
150
181
|
sees only the matters they created or that were shared with them. The tool says
|
|
151
182
|
so by name when a matter is not visible.
|
|
152
183
|
|
|
153
|
-
##
|
|
184
|
+
## 11. Choose a mode
|
|
154
185
|
|
|
155
186
|
The server starts **read-only**. In that mode every mutating tool is absent from
|
|
156
187
|
the tool list, not present and failing, so a model cannot talk itself into a
|
|
@@ -164,7 +195,7 @@ write.
|
|
|
164
195
|
|
|
165
196
|
Start read-only, use it for a while, and only then enable writes.
|
|
166
197
|
|
|
167
|
-
##
|
|
198
|
+
## 12. Editions
|
|
168
199
|
|
|
169
200
|
| Surface | Available on |
|
|
170
201
|
| --- | --- |
|
|
@@ -220,7 +251,7 @@ wrong. `npm run api:scopes` refreshes the snapshot after an API change.
|
|
|
220
251
|
| `auth_required` | Testing client, or revoked grant | Re-authorize, or use Internal |
|
|
221
252
|
| `redirect_uri_mismatch` | Client is a Web application | Create a Desktop app client |
|
|
222
253
|
| `invalid_client` | Secret is wrong or from another project | Copy both values again |
|
|
223
|
-
| 403 on a surface you enabled | API not enabled, or role missing | Check step 3 and step
|
|
254
|
+
| 403 on a surface you enabled | API not enabled, or role missing | Check step 3 and step 10 |
|
|
224
255
|
| `edition_unavailable` | Tenant lacks Vault or Cloud Search | Use another surface |
|
|
225
256
|
| Scripts see no token | Different `GWS_STATE_DIR` or user | Point both at the same path |
|
|
226
257
|
|
package/docs/SMOKE-TESTING.md
CHANGED
|
@@ -1,8 +1,13 @@
|
|
|
1
1
|
# Smoke testing and tenant access
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
that keep tenant data out of the repository and out of shared output.
|
|
3
|
+
The server is verified two ways: fixtures in CI, and read-only smoke runs
|
|
4
|
+
against a tenant the operator controls. This document covers the second, and the
|
|
5
|
+
rules that keep tenant data out of the repository and out of shared output.
|
|
6
|
+
|
|
7
|
+
The current tenant is a proof-of-concept workspace: directory, reports, transfer,
|
|
8
|
+
licensing, groups settings and calendar resources have run live. Vault and Cloud
|
|
9
|
+
Search report `unavailable` there because the tenant has neither, so those two
|
|
10
|
+
surfaces are still fixture-only.
|
|
6
11
|
|
|
7
12
|
## Two verification tiers
|
|
8
13
|
|
package/docs/TOOLS.md
CHANGED
|
@@ -1,8 +1,9 @@
|
|
|
1
1
|
# Tools
|
|
2
2
|
|
|
3
|
-
One row per tool
|
|
4
|
-
|
|
5
|
-
|
|
3
|
+
One row per tool — 107 of them, across eight admin surfaces. A tool without a
|
|
4
|
+
row is a bug: `npm test` builds every tool module and fails when a registered
|
|
5
|
+
tool is not listed here. `npm run docs:tools` appends a placeholder row for
|
|
6
|
+
anything new; the notes still need a human.
|
|
6
7
|
|
|
7
8
|
| Tool | Surface | Mutating | Notes |
|
|
8
9
|
| --- | --- | --- | --- |
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "google-workspace-admin-mcp",
|
|
3
|
-
"version": "0.1.
|
|
3
|
+
"version": "0.1.3",
|
|
4
4
|
"description": "MCP server for the Google Workspace admin plane: Directory, Reports, Vault, Cloud Search, Data Transfer, Licensing. Admin OAuth only - no impersonation, no service accounts.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"main": "dist/main.js",
|