google-workspace-admin-mcp 0.1.0 → 0.1.2

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 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: 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).
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, Chat, Meet,
35
- Keep, Tasks, Forms, YouTube, Classroom, Sites and Apps Script are out of scope,
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: 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.
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 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.
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
- `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).
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.
117
+
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).
99
120
 
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.
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 + lint + generated docs + tests
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/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.
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,17 +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
- The first release needs two one-time steps:
135
-
136
- 1. Claim the name: `npm publish --access public` once from a checkout, signed in
137
- with an account that can publish `@singlebarrellabs` packages.
138
- 2. Configure the trusted publisher at
139
- `npmjs.com/package/google-workspace-admin-mcp/access` with repository
140
- `singlebarrellabs/google-workspace-admin-mcp` and workflow `ci.yml`.
141
-
142
- Until then, both publishing jobs are gated by the repository variable
143
- `NPM_PUBLISH_ENABLED`; set it to `true` after step 2 and delete the gate. No
144
- `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`).
145
166
 
146
167
  ## License
147
168
 
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](#11-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
- ## 9. Grant the admin roles
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
- ## 10. Choose a mode
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
- ## 11. Editions
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 9 |
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
 
@@ -1,8 +1,13 @@
1
1
  # Smoke testing and tenant access
2
2
 
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.
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. 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.
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.0",
3
+ "version": "0.1.2",
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",