google-workspace-admin-mcp 0.1.0-beta.101 → 0.1.0-beta.97
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 +33 -61
- 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 +1 -2
- package/dist/server.js.map +1 -1
- package/docs/SETUP.md +5 -36
- package/docs/SMOKE-TESTING.md +3 -8
- package/docs/TOOLS.md +3 -4
- package/package.json +1 -1
- package/dist/version.d.ts +0 -7
- package/dist/version.d.ts.map +0 -1
- package/dist/version.js +0 -8
- package/dist/version.js.map +0 -1
package/README.md
CHANGED
|
@@ -3,9 +3,10 @@
|
|
|
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
|
-
>
|
|
6
|
+
> **Status: early development.** Surfaces land one branch at a time; the tool
|
|
7
|
+
> list for the checked-out revision is in [`docs/TOOLS.md`](docs/TOOLS.md) and
|
|
8
|
+
> setup is in [`docs/SETUP.md`](docs/SETUP.md). Track progress in the
|
|
9
|
+
> [issues](https://github.com/singlebarrellabs/google-workspace-admin-mcp/issues).
|
|
9
10
|
|
|
10
11
|
## Why
|
|
11
12
|
|
|
@@ -30,10 +31,9 @@ stated in a README:
|
|
|
30
31
|
- No domain-wide delegation.
|
|
31
32
|
- No impersonation: there is no `as` parameter anywhere, and no credential type
|
|
32
33
|
that could express one.
|
|
33
|
-
- No user-content APIs: Gmail, Drive, Docs, Sheets, Slides,
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
are admin data and are in scope.)
|
|
34
|
+
- No user-content APIs: Gmail, Drive, Docs, Sheets, Slides, Calendar, Chat, Meet,
|
|
35
|
+
Keep, Tasks, Forms, YouTube, Classroom, Sites and Apps Script are out of scope,
|
|
36
|
+
permanently.
|
|
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,15 +59,17 @@ without guessing.
|
|
|
59
59
|
|
|
60
60
|
## Authentication
|
|
61
61
|
|
|
62
|
-
One credential:
|
|
63
|
-
the
|
|
64
|
-
refresh token is stored with owner-only permissions.
|
|
62
|
+
One credential: an **admin user OAuth client** you create in your own Google
|
|
63
|
+
Cloud project, with the application type set to **Internal**. The administrator
|
|
64
|
+
signs in once; the refresh token is stored locally with owner-only permissions.
|
|
65
65
|
|
|
66
|
-
- No service account, no DWD grant, no
|
|
67
|
-
- Internal
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
66
|
+
- No service account, no DWD grant, no super-admin security settings to change.
|
|
67
|
+
- The Internal app type gives long-lived refresh tokens without verification.
|
|
68
|
+
A client left in **Testing** publishing status expires refresh tokens after
|
|
69
|
+
seven days — the setup docs call this out because it silently breaks an
|
|
70
|
+
unattended admin tool.
|
|
71
|
+
- Scopes are admin-only. Nothing in the requested scope list grants mailbox or
|
|
72
|
+
file content of another user.
|
|
71
73
|
|
|
72
74
|
## Safety model
|
|
73
75
|
|
|
@@ -84,65 +86,33 @@ refresh token is stored with owner-only permissions.
|
|
|
84
86
|
## Install
|
|
85
87
|
|
|
86
88
|
```bash
|
|
89
|
+
npm install -g google-workspace-admin-mcp
|
|
87
90
|
export GWS_CLIENT_ID=... # Desktop-app OAuth client, Internal consent screen
|
|
88
91
|
export GWS_CLIENT_SECRET=...
|
|
89
|
-
|
|
92
|
+
google-workspace-admin-mcp auth
|
|
90
93
|
```
|
|
91
94
|
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
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.
|
|
95
|
+
`npx google-workspace-admin-mcp` works the same way once the package is
|
|
96
|
+
published. The full walkthrough — enabling the six APIs, the consent screen, the
|
|
97
|
+
admin roles per surface, the seven-day refresh-token trap — is in
|
|
98
|
+
[`docs/SETUP.md`](docs/SETUP.md).
|
|
117
99
|
|
|
118
|
-
The
|
|
119
|
-
|
|
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.
|
|
100
|
+
The server starts read-only. Set `GWS_MODE=write` to register mutating tools, and
|
|
101
|
+
`GWS_PASSTHROUGH=on` for the allowlisted raw-call tools.
|
|
132
102
|
|
|
133
103
|
## Development
|
|
134
104
|
|
|
135
105
|
```bash
|
|
136
106
|
npm install
|
|
137
|
-
npm run check # typecheck
|
|
107
|
+
npm run check # typecheck + lint + generated docs + tests
|
|
138
108
|
```
|
|
139
109
|
|
|
140
110
|
`npm run docs:scopes` regenerates the scope list in `docs/SETUP.md` from
|
|
141
111
|
`ADMIN_SCOPES`; `npm run check` fails when the two disagree.
|
|
142
112
|
|
|
143
|
-
Specs live in `openspec/
|
|
144
|
-
|
|
145
|
-
|
|
113
|
+
Specs live in `openspec/changes/workspace-admin-mcp/`. Each capability spec is
|
|
114
|
+
linked from its tracking issue. OpenSpec is used for planning only; tests are the
|
|
115
|
+
enforcement mechanism.
|
|
146
116
|
|
|
147
117
|
No live Workspace tenant is needed to contribute. Verification tiers, tenant
|
|
148
118
|
access levels, the redaction rules for smoke output and the smoke commands are in
|
|
@@ -161,8 +131,10 @@ Publishing runs from GitHub Actions, never from a laptop:
|
|
|
161
131
|
`<version>-beta.<run_number>` to the `beta` dist-tag, so a branch is
|
|
162
132
|
installable before it merges. `v*-beta*` tags and manual runs do the same.
|
|
163
133
|
|
|
164
|
-
|
|
165
|
-
|
|
134
|
+
The name is claimed and the trusted publisher is configured for this
|
|
135
|
+
repository and `ci.yml`.
|
|
136
|
+
|
|
137
|
+
No `NPM_TOKEN` secret is used: npm validates the workflow's OIDC identity.
|
|
166
138
|
|
|
167
139
|
## License
|
|
168
140
|
|
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
|
+
const VERSION = "0.1.0";
|
|
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;AAE7D,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,7 +12,6 @@ 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";
|
|
16
15
|
export function buildServer(deps) {
|
|
17
16
|
const { config, token } = deps;
|
|
18
17
|
const audit = new AuditLog(config.auditPath);
|
|
@@ -29,7 +28,7 @@ export function buildServer(deps) {
|
|
|
29
28
|
...(deps.reports ? reportsTools(deps.reports) : []),
|
|
30
29
|
];
|
|
31
30
|
const registered = toolsForMode(specs, config.mode);
|
|
32
|
-
const server = new McpServer({ name: "google-workspace-admin-mcp", version:
|
|
31
|
+
const server = new McpServer({ name: "google-workspace-admin-mcp", version: "0.1.0" });
|
|
33
32
|
for (const spec of registered) {
|
|
34
33
|
server.registerTool(spec.name, { description: spec.description, inputSchema: spec.inputShape }, async (input) => {
|
|
35
34
|
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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"}
|
package/docs/SETUP.md
CHANGED
|
@@ -127,40 +127,9 @@ 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](#
|
|
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.
|
|
130
|
+
about the tenant, not a misconfiguration. See [Editions](#11-editions).
|
|
162
131
|
|
|
163
|
-
##
|
|
132
|
+
## 9. Grant the admin roles
|
|
164
133
|
|
|
165
134
|
The signed-in account needs the privilege for each surface you intend to use.
|
|
166
135
|
A super admin has all of them; anything less should be a custom role.
|
|
@@ -181,7 +150,7 @@ Vault is the one that surprises people: an admin without **View All Matters**
|
|
|
181
150
|
sees only the matters they created or that were shared with them. The tool says
|
|
182
151
|
so by name when a matter is not visible.
|
|
183
152
|
|
|
184
|
-
##
|
|
153
|
+
## 10. Choose a mode
|
|
185
154
|
|
|
186
155
|
The server starts **read-only**. In that mode every mutating tool is absent from
|
|
187
156
|
the tool list, not present and failing, so a model cannot talk itself into a
|
|
@@ -195,7 +164,7 @@ write.
|
|
|
195
164
|
|
|
196
165
|
Start read-only, use it for a while, and only then enable writes.
|
|
197
166
|
|
|
198
|
-
##
|
|
167
|
+
## 11. Editions
|
|
199
168
|
|
|
200
169
|
| Surface | Available on |
|
|
201
170
|
| --- | --- |
|
|
@@ -251,7 +220,7 @@ wrong. `npm run api:scopes` refreshes the snapshot after an API change.
|
|
|
251
220
|
| `auth_required` | Testing client, or revoked grant | Re-authorize, or use Internal |
|
|
252
221
|
| `redirect_uri_mismatch` | Client is a Web application | Create a Desktop app client |
|
|
253
222
|
| `invalid_client` | Secret is wrong or from another project | Copy both values again |
|
|
254
|
-
| 403 on a surface you enabled | API not enabled, or role missing | Check step 3 and step
|
|
223
|
+
| 403 on a surface you enabled | API not enabled, or role missing | Check step 3 and step 9 |
|
|
255
224
|
| `edition_unavailable` | Tenant lacks Vault or Cloud Search | Use another surface |
|
|
256
225
|
| Scripts see no token | Different `GWS_STATE_DIR` or user | Point both at the same path |
|
|
257
226
|
|
package/docs/SMOKE-TESTING.md
CHANGED
|
@@ -1,13 +1,8 @@
|
|
|
1
1
|
# Smoke testing and tenant access
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
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.
|
|
3
|
+
This project is built without access to a live Google Workspace tenant. This
|
|
4
|
+
document records how that works, what verification needs a human, and the rules
|
|
5
|
+
that keep tenant data out of the repository and out of shared output.
|
|
11
6
|
|
|
12
7
|
## Two verification tiers
|
|
13
8
|
|
package/docs/TOOLS.md
CHANGED
|
@@ -1,9 +1,8 @@
|
|
|
1
1
|
# Tools
|
|
2
2
|
|
|
3
|
-
One row per tool
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
anything new; the notes still need a human.
|
|
3
|
+
One row per tool. A tool without a row is a bug: `npm test` builds every tool
|
|
4
|
+
module and fails when a registered tool is not listed here. `npm run docs:tools`
|
|
5
|
+
appends a placeholder row for anything new; the notes still need a human.
|
|
7
6
|
|
|
8
7
|
| Tool | Surface | Mutating | Notes |
|
|
9
8
|
| --- | --- | --- | --- |
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "google-workspace-admin-mcp",
|
|
3
|
-
"version": "0.1.0-beta.
|
|
3
|
+
"version": "0.1.0-beta.97",
|
|
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",
|
package/dist/version.d.ts
DELETED
|
@@ -1,7 +0,0 @@
|
|
|
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
|
package/dist/version.d.ts.map
DELETED
|
@@ -1 +0,0 @@
|
|
|
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
DELETED
|
@@ -1,8 +0,0 @@
|
|
|
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
|
package/dist/version.js.map
DELETED
|
@@ -1 +0,0 @@
|
|
|
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"}
|