@n24q02m/workspace 0.6.0 → 0.7.0-beta.1

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.
Files changed (152) hide show
  1. package/NOTICE +9 -2
  2. package/README.md +101 -10
  3. package/bin/cli.mjs +78 -51
  4. package/build/src/auth/workspace-auth.test.js +3 -3
  5. package/build/src/auth/workspace-auth.test.js.map +1 -1
  6. package/build/src/cli/tools.d.ts +64 -0
  7. package/build/src/cli/tools.d.ts.map +1 -0
  8. package/build/src/cli/tools.integration.test.d.ts +2 -0
  9. package/build/src/cli/tools.integration.test.d.ts.map +1 -0
  10. package/build/src/cli/tools.integration.test.js +46 -0
  11. package/build/src/cli/tools.integration.test.js.map +1 -0
  12. package/build/src/cli/tools.js +411 -0
  13. package/build/src/cli/tools.js.map +1 -0
  14. package/build/src/cli/tools.test.d.ts +2 -0
  15. package/build/src/cli/tools.test.d.ts.map +1 -0
  16. package/build/src/cli/tools.test.js +365 -0
  17. package/build/src/cli/tools.test.js.map +1 -0
  18. package/build/src/constants.d.ts +2 -1
  19. package/build/src/constants.d.ts.map +1 -1
  20. package/build/src/constants.js +8 -5
  21. package/build/src/constants.js.map +1 -1
  22. package/build/src/data-dir-migration.d.ts +72 -0
  23. package/build/src/data-dir-migration.d.ts.map +1 -0
  24. package/build/src/data-dir-migration.js +181 -0
  25. package/build/src/data-dir-migration.js.map +1 -0
  26. package/build/src/data-dir-migration.test.d.ts +2 -0
  27. package/build/src/data-dir-migration.test.d.ts.map +1 -0
  28. package/build/src/data-dir-migration.test.js +148 -0
  29. package/build/src/data-dir-migration.test.js.map +1 -0
  30. package/build/src/data-dir.d.ts +59 -0
  31. package/build/src/data-dir.d.ts.map +1 -0
  32. package/build/src/data-dir.js +94 -0
  33. package/build/src/data-dir.js.map +1 -0
  34. package/build/src/data-dir.test.d.ts +2 -0
  35. package/build/src/data-dir.test.d.ts.map +1 -0
  36. package/build/src/data-dir.test.js +73 -0
  37. package/build/src/data-dir.test.js.map +1 -0
  38. package/build/src/docs/calendar.md +27 -0
  39. package/build/src/docs/chat.md +34 -0
  40. package/build/src/docs/config.md +17 -0
  41. package/build/src/docs/docs.md +1 -1
  42. package/build/src/docs/drive.md +29 -0
  43. package/build/src/docs/forms.md +19 -0
  44. package/build/src/docs/gmail.md +37 -0
  45. package/build/src/docs/overview.md +24 -0
  46. package/build/src/docs/people.md +23 -0
  47. package/build/src/docs/sheets.md +27 -0
  48. package/build/src/docs/slides.md +31 -0
  49. package/build/src/docs/tasks.md +18 -0
  50. package/build/src/main.d.ts +2 -0
  51. package/build/src/main.d.ts.map +1 -1
  52. package/build/src/main.js +25 -5
  53. package/build/src/main.js.map +1 -1
  54. package/build/src/main.test.js +42 -1
  55. package/build/src/main.test.js.map +1 -1
  56. package/build/src/tools/config.d.ts +10 -1
  57. package/build/src/tools/config.d.ts.map +1 -1
  58. package/build/src/tools/config.js +20 -1
  59. package/build/src/tools/config.js.map +1 -1
  60. package/build/src/tools/dispatch.d.ts +25 -0
  61. package/build/src/tools/dispatch.d.ts.map +1 -0
  62. package/build/src/tools/dispatch.js +119 -0
  63. package/build/src/tools/dispatch.js.map +1 -0
  64. package/build/src/tools/domains/bounds-e2e.test.d.ts +2 -0
  65. package/build/src/tools/domains/bounds-e2e.test.d.ts.map +1 -0
  66. package/build/src/tools/domains/bounds-e2e.test.js +166 -0
  67. package/build/src/tools/domains/bounds-e2e.test.js.map +1 -0
  68. package/build/src/tools/domains/bounds.d.ts +53 -0
  69. package/build/src/tools/domains/bounds.d.ts.map +1 -0
  70. package/build/src/tools/domains/bounds.js +72 -0
  71. package/build/src/tools/domains/bounds.js.map +1 -0
  72. package/build/src/tools/domains/calendar.d.ts.map +1 -1
  73. package/build/src/tools/domains/calendar.js +5 -1
  74. package/build/src/tools/domains/calendar.js.map +1 -1
  75. package/build/src/tools/domains/chat.d.ts.map +1 -1
  76. package/build/src/tools/domains/chat.js +3 -1
  77. package/build/src/tools/domains/chat.js.map +1 -1
  78. package/build/src/tools/domains/docs.d.ts.map +1 -1
  79. package/build/src/tools/domains/docs.js +2 -1
  80. package/build/src/tools/domains/docs.js.map +1 -1
  81. package/build/src/tools/domains/drive.d.ts.map +1 -1
  82. package/build/src/tools/domains/drive.js +5 -1
  83. package/build/src/tools/domains/drive.js.map +1 -1
  84. package/build/src/tools/domains/factory-bounds.test.d.ts +2 -0
  85. package/build/src/tools/domains/factory-bounds.test.d.ts.map +1 -0
  86. package/build/src/tools/domains/factory-bounds.test.js +169 -0
  87. package/build/src/tools/domains/factory-bounds.test.js.map +1 -0
  88. package/build/src/tools/domains/factory.d.ts +15 -0
  89. package/build/src/tools/domains/factory.d.ts.map +1 -1
  90. package/build/src/tools/domains/factory.js +18 -1
  91. package/build/src/tools/domains/factory.js.map +1 -1
  92. package/build/src/tools/domains/forms.d.ts.map +1 -1
  93. package/build/src/tools/domains/forms.js +5 -1
  94. package/build/src/tools/domains/forms.js.map +1 -1
  95. package/build/src/tools/domains/gmail.d.ts.map +1 -1
  96. package/build/src/tools/domains/gmail.js +5 -1
  97. package/build/src/tools/domains/gmail.js.map +1 -1
  98. package/build/src/tools/domains/index.d.ts.map +1 -1
  99. package/build/src/tools/domains/index.js +94 -12
  100. package/build/src/tools/domains/index.js.map +1 -1
  101. package/build/src/tools/domains/people.d.ts.map +1 -1
  102. package/build/src/tools/domains/people.js +2 -1
  103. package/build/src/tools/domains/people.js.map +1 -1
  104. package/build/src/tools/domains/slides.d.ts.map +1 -1
  105. package/build/src/tools/domains/slides.js +2 -1
  106. package/build/src/tools/domains/slides.js.map +1 -1
  107. package/build/src/tools/domains/tasks.d.ts.map +1 -1
  108. package/build/src/tools/domains/tasks.js +3 -1
  109. package/build/src/tools/domains/tasks.js.map +1 -1
  110. package/build/src/tools/helpers/bounds.d.ts +72 -0
  111. package/build/src/tools/helpers/bounds.d.ts.map +1 -0
  112. package/build/src/tools/helpers/bounds.js +234 -0
  113. package/build/src/tools/helpers/bounds.js.map +1 -0
  114. package/build/src/tools/helpers/bounds.test.d.ts +2 -0
  115. package/build/src/tools/helpers/bounds.test.d.ts.map +1 -0
  116. package/build/src/tools/helpers/bounds.test.js +239 -0
  117. package/build/src/tools/helpers/bounds.test.js.map +1 -0
  118. package/build/src/tools/registry.d.ts +28 -0
  119. package/build/src/tools/registry.d.ts.map +1 -1
  120. package/build/src/tools/registry.js +15 -120
  121. package/build/src/tools/registry.js.map +1 -1
  122. package/build/src/tools/registry.test.js +7 -1
  123. package/build/src/tools/registry.test.js.map +1 -1
  124. package/build/src/vendored/services/CalendarService.d.ts +2 -0
  125. package/build/src/vendored/services/CalendarService.d.ts.map +1 -1
  126. package/build/src/vendored/services/CalendarService.js +13 -2
  127. package/build/src/vendored/services/CalendarService.js.map +1 -1
  128. package/build/src/vendored/services/ChatService.d.ts +4 -1
  129. package/build/src/vendored/services/ChatService.d.ts.map +1 -1
  130. package/build/src/vendored/services/ChatService.js +11 -3
  131. package/build/src/vendored/services/ChatService.js.map +1 -1
  132. package/build/src/vendored/services/DocsService.d.ts.map +1 -1
  133. package/build/src/vendored/services/DocsService.js +6 -1
  134. package/build/src/vendored/services/DocsService.js.map +1 -1
  135. package/build/src/vendored/services/DocsService.test.js +2 -2
  136. package/build/src/vendored/services/DocsService.test.js.map +1 -1
  137. package/build/src/vendored/services/DriveService.d.ts +3 -1
  138. package/build/src/vendored/services/DriveService.d.ts.map +1 -1
  139. package/build/src/vendored/services/DriveService.js +10 -3
  140. package/build/src/vendored/services/DriveService.js.map +1 -1
  141. package/build/src/vendored/services/SheetsService.d.ts +6 -2
  142. package/build/src/vendored/services/SheetsService.d.ts.map +1 -1
  143. package/build/src/vendored/services/SheetsService.js +67 -6
  144. package/build/src/vendored/services/SheetsService.js.map +1 -1
  145. package/build/src/vendored/services/SheetsService.test.js +67 -0
  146. package/build/src/vendored/services/SheetsService.test.js.map +1 -1
  147. package/build/src/vendored/utils/textBounds.d.ts +40 -0
  148. package/build/src/vendored/utils/textBounds.d.ts.map +1 -0
  149. package/build/src/vendored/utils/textBounds.js +115 -0
  150. package/build/src/vendored/utils/textBounds.js.map +1 -0
  151. package/build/tsconfig.tsbuildinfo +1 -1
  152. package/package.json +1 -1
package/NOTICE CHANGED
@@ -15,8 +15,13 @@ is unparseable or names a file that is not on disk -- an empty list would otherw
15
15
  These no longer match gemini-cli-extensions/workspace byte-for-byte. `sync-upstream.mjs` reports them
16
16
  as CONFLICT and leaves them alone; whoever syncs merges them by hand:
17
17
 
18
- - src/vendored/services/DriveService.ts — SECURITY: Prevent path traversal in relative localPath
19
- - src/vendored/services/CalendarService.ts — PERFORMANCE: Using Date.parse() instead of new Date().getTime() skips object allocation and reduces GC pressure
18
+ - src/vendored/services/DocsService.ts — BOUNDS: `getText` caps the returned text
19
+ (20,000 characters by default, 1–100,000 via `limit`, 2,000 via `preview`) and ends a cut body with the
20
+ shared truncation marker that names its true size.
21
+ - src/vendored/services/DriveService.ts — SECURITY: Prevent path traversal in relative localPath; BOUNDS:
22
+ `getComments` takes `pageSize`/`pageToken` and returns `nextPageToken` instead of a bare array that
23
+ dropped the cursor.
24
+ - src/vendored/services/CalendarService.ts — PERFORMANCE: Using Date.parse() instead of new Date().getTime() skips object allocation and reduces GC pressure; BOUNDS: `listEvents` takes `maxResults`/`pageToken` and returns `{events, nextPageToken}` instead of a bare array that dropped the cursor.
20
25
  - src/vendored/utils/MimeHelper.ts — the multipart boundary suffix could be empty
21
26
  (`.substring(7)` on a short `Math.random().toString(36)`, e.g. 0.5 -> "0.i"), so two messages
22
27
  built in the same millisecond collided on their boundary. Now a randomUUID-derived suffix.
@@ -28,6 +33,8 @@ as CONFLICT and leaves them alone; whoever syncs merges them by hand:
28
33
  (`.substring(7)` on a short `Math.random().toString(36)`, e.g. 0.5 -> "0.i"), so two messages
29
34
  built in the same millisecond collided on their boundary. Now a randomUUID-derived suffix.
30
35
  - src/vendored/utils/validation.ts — optimization: Date.parse vs new Date().getTime()
36
+ - src/vendored/services/ChatService.ts — BOUNDS: `listSpaces` takes `pageSize`/`pageToken` and returns
37
+ `{spaces, nextPageToken}` instead of a bare array that dropped the cursor.
31
38
 
32
39
  ## Files that replace an upstream file (ours, never synced)
33
40
 
package/README.md CHANGED
@@ -7,7 +7,7 @@
7
7
  > **ARCHIVED 2026-09-13** — This repository is no longer maintained. Use the official Google Workspace APIs instead of this MCP server. Existing installations keep working but receive no updates or support.
8
8
 
9
9
  <p align="center">
10
- <a href="https://mcp.n24q02m.com/get-started/modes-overview/"><img alt="Mode: stdio · http remote oauth" src="https://img.shields.io/badge/mode-stdio_%C2%B7_http--remote--oauth-5C6BC0"></a>
10
+ <img alt="Mode: stdio · http remote oauth" src="https://img.shields.io/badge/mode-stdio_%C2%B7_http--remote--oauth-5C6BC0">
11
11
  <a href="https://github.com/n24q02m/workspace/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/n24q02m/workspace/actions/workflows/ci.yml/badge.svg"></a>
12
12
  <a href="https://github.com/n24q02m/workspace/actions/workflows/cd.yml"><img alt="CD" src="https://github.com/n24q02m/workspace/actions/workflows/cd.yml/badge.svg"></a>
13
13
  <a href="https://codecov.io/gh/n24q02m/workspace"><img alt="codecov" src="https://codecov.io/gh/n24q02m/workspace/graph/badge.svg"></a>
@@ -17,7 +17,7 @@
17
17
  </p>
18
18
 
19
19
  <p align="center">
20
- <a href="https://mcp.n24q02m.com">Docs</a> ·
20
+ <a href="https://docs.n24q02m.com/servers/workspace/">Docs</a> ·
21
21
  <a href="#install">Install</a> ·
22
22
  <a href="#quick-start">Quick start</a> ·
23
23
  <a href="https://github.com/n24q02m/workspace/discussions">Community</a>
@@ -57,6 +57,7 @@
57
57
  - [Install](#install)
58
58
  - [Remote (HTTP mode)](#remote-http-mode)
59
59
  - [Tools](#tools)
60
+ - [CLI](#cli)
60
61
  - [Quick start](#quick-start)
61
62
  - [Multi-account](#multi-account)
62
63
  - [Documentation](#documentation)
@@ -100,8 +101,9 @@ not on a public URL. Enable the Workspace APIs you plan to call on the same
100
101
  project, and add yourself as a test user while the consent screen is unpublished.
101
102
 
102
103
  The first run opens the Google consent screen in your browser; the refresh token
103
- is stored encrypted on your machine under `~/.better-workspace/` (a legacy
104
- `~/.better-workspace-mcp/` is read as a fallback), so later runs start without asking again.
104
+ is stored encrypted on your machine under `~/.workspace/` (a store an earlier
105
+ release wrote under `~/.better-workspace/` is copied forward on the next start, and the
106
+ older `~/.better-workspace-mcp/` is read as a fallback), so later runs start without asking again.
105
107
 
106
108
  The same server can also serve several people over HTTP -- see
107
109
  [Remote (HTTP mode)](#remote-http-mode).
@@ -160,10 +162,11 @@ and renames it on the way into the container.
160
162
  | `GOOGLE_OAUTH_CLIENT_SECRET` | yes | Web client secret. Same. |
161
163
  | `CREDENTIAL_SECRET` | yes | Derives the encryption key of each user's credential store. The server refuses to start without it, rather than fail in the middle of a user's consent. |
162
164
  | `WORKSPACE_USERS_FILE` | yes in HTTP | Users file that maps each bearer token to a user namespace (hull `multi` auth). Unset uses hull's default location. |
165
+ | `WORKSPACE_DATA_DIR` | no | Base directory for the credential store (`<dir>/.workspace/`, one encrypted blob per user). Unset uses the home directory. A relative value is resolved under the home directory and must stay inside it, so use an absolute path for a mounted volume. |
163
166
  | `PORT` | no | Listen port. `0` (the default) asks the OS for a free one. |
164
167
  | `HOST` | no | Bind address. Defaults to loopback, so a container needs `0.0.0.0`. |
165
168
 
166
- Credentials are stored on local disk under `~/.better-workspace/`, which is the data volume in the container. A legacy `~/.better-workspace-mcp/` is read as a fallback.
169
+ Credentials are stored on local disk under `~/.workspace/`, which is the data volume in the container. A store from an earlier release (`~/.better-workspace/`) is copied forward on startup, and the older `~/.better-workspace-mcp/` is read as a fallback.
167
170
 
168
171
  `docker-compose.http.yml` in this repo is these variables written out as a
169
172
  runnable overlay.
@@ -185,13 +188,88 @@ One composite tool per Workspace domain, plus `config` and `help`:
185
188
  | `people` | Profile lookups -- `getMe`, `getUserProfile`, `getUserRelations` |
186
189
  | `forms` | Forms -- `create`, `get`, `batchUpdate`, `listResponses`, `getResponse` |
187
190
  | `time` | Local date/time/timezone helpers (no Google account needed) |
188
- | `config` | Credential state and account management |
191
+ | `config` | Credential state and account management (CLI: `config-tool`) |
189
192
  | `help` | Full documentation for any tool |
190
193
 
191
194
  Questions are added to a form with `forms(action="batchUpdate")`, not at `create`;
192
195
  responses are read-only, because the Forms API cannot write one. Listing or
193
196
  deleting forms goes through `drive`.
194
197
 
198
+ ### Response size
199
+
200
+ A Google read can return megabytes from one call, so every action whose payload
201
+ can grow is bounded by default:
202
+
203
+ - 20,000 characters per response. Raise it with `max_chars` (1--100,000), or pass
204
+ `full: true` for the complete payload. The same envelope `docs` exposes as
205
+ `limit`/`preview` and `sheets` as `max_chars`/`full`.
206
+ - Listings that page keep their page size (default 20, clamped to 1--100) and
207
+ always return their `nextPageToken`; listings with no cursor (`getImages`,
208
+ `findFolder`, `findSpaceByName`, `listCalendars`, `getUserRelations`, free/busy
209
+ slots, labels) also cap how many items one response carries (50--100).
210
+ - Truncation is never silent. A cut payload carries
211
+ `_truncation: {truncated, total_characters, returned_characters, omitted_items?, note}`
212
+ whose `note` reads
213
+ `[Content truncated: showing <kept> of <total> characters (<omitted> omitted). ...]`.
214
+ A JSON payload stays parseable, and a pagination cursor is never cut.
215
+
216
+ ```sh
217
+ workspace gmail get --messageId <id> --max_chars 60000 --json # a longer body
218
+ workspace slides getText --presentationId <id> --full --json # the whole deck
219
+ ```
220
+
221
+ ## CLI
222
+
223
+ Every tool is also a shell subcommand, so the same operations work without an MCP
224
+ client. `workspace <tool> <action>` turns those parameters into the tool's input
225
+ object and calls the same handler the server registers -- one dispatch, two front
226
+ doors, so credential gating and validation behave identically.
227
+
228
+ ```sh
229
+ workspace <tool> <action> [--param <value>]... [--json]
230
+ ```
231
+
232
+ `--json` prints one envelope on stdout -- `{"tool", "action", "result"}`, where
233
+ `result` is the tool's own payload (parsed when the tool emits JSON, the raw text
234
+ otherwise). Without it you get the tool's text as-is. A tool failure prints to
235
+ stderr and exits 1; argv the CLI cannot parse exits 2. `workspace --help` lists the
236
+ tool subcommands and the operator commands (`auth`, `config`, `status`, `logout`,
237
+ `doctor`, `token`) separately, and `workspace <tool> --help` prints that tool's
238
+ actions and options.
239
+
240
+ One tool name is already taken. `config` is the operator command that reads the
241
+ credential store hull manages (`workspace config status`); the MCP `config` tool
242
+ is a different surface -- credential lifecycle plus the Google accounts the
243
+ server acts as. It keeps a console path under the alias `config-tool`, so neither
244
+ command can silently stand in for the other:
245
+
246
+ ```sh
247
+ workspace config-tool status --json
248
+ workspace config-tool account_list
249
+ ```
250
+
251
+ | Group | Example |
252
+ | --- | --- |
253
+ | `docs` | `workspace docs getText --documentId <document-id> --limit 2000` |
254
+ | `drive` | `workspace drive search --query "name contains 'Q3 report'" --pageSize 5` |
255
+ | `calendar` | `workspace calendar listCalendars --json` |
256
+ | `chat` | `workspace chat listSpaces --json` |
257
+ | `gmail` | `workspace gmail search --query "is:unread" --maxResults 5 --json` |
258
+ | `sheets` | `workspace sheets getRange --spreadsheetId <spreadsheet-id> --range "Sheet1!A1:C10"` |
259
+ | `slides` | `workspace slides getMetadata --presentationId <presentation-id>` |
260
+ | `tasks` | `workspace tasks listTasks --taskListId <task-list-id> --maxResults 20` |
261
+ | `people` | `workspace people getMe --json` |
262
+ | `forms` | `workspace forms listResponses --formId <form-id> --pageSize 10` |
263
+ | `time` | `workspace time getCurrentTime --json` |
264
+ | `config-tool` | `workspace config-tool status --json` (the MCP `config` tool) |
265
+ | `help` | `workspace help gmail` |
266
+
267
+ Values are coerced from the tool's own schema: `--maxResults 5` is a number,
268
+ `--includeSpamTrash` (also `--includeSpamTrash true`, or `--no-includeSpamTrash`)
269
+ is a boolean, and `--labelIds INBOX,IMPORTANT` (or a JSON array) is a list. Every
270
+ domain accepts `--account <email>` to choose the Google account, exactly like the
271
+ tool's `account` parameter.
272
+
195
273
  ## Quick start
196
274
 
197
275
  Check that the credentials landed, with the `config` tool. Before the first
@@ -202,6 +280,9 @@ is acting as:
202
280
  { "action": "status" }
203
281
  ```
204
282
 
283
+ From a shell the same call is `workspace config-tool status --json`, and it works
284
+ before consent -- it reads the store, it does not need Google.
285
+
205
286
  Then call a domain tool. On `docs`, `create` returns the new document's ID, which
206
287
  `getText` reads back:
207
288
 
@@ -241,6 +322,18 @@ Accounts are managed through the `config` tool:
241
322
  | `config(action="account_remove", account="<email>")` | Forget one account. |
242
323
  | `config(action="account_set_default", account="<email>")` | Make one account the primary. |
243
324
 
325
+ From a shell, the same four calls:
326
+
327
+ ```sh
328
+ workspace config-tool account_add
329
+ workspace config-tool account_list
330
+ workspace config-tool account_remove --account <email>
331
+ workspace config-tool account_set_default --account <email>
332
+ ```
333
+
334
+ `config-tool`, not `config`: the plain name is the operator command that reads the
335
+ credential store.
336
+
244
337
  The first account authorized becomes the primary. Removing the primary promotes
245
338
  one of the remaining accounts; removing the last one puts the server back to
246
339
  awaiting setup. Naming an account that is not configured is an error that names
@@ -303,11 +396,9 @@ replaced in place, so nothing else changes.
303
396
 
304
397
  ## Documentation
305
398
 
306
- Full docs at **[mcp.n24q02m.com/servers/better-workspace-mcp/](https://mcp.n24q02m.com/servers/better-workspace-mcp/)**:
399
+ Full docs at **[docs.n24q02m.com/servers/workspace/](https://docs.n24q02m.com/servers/workspace/)**:
307
400
 
308
- - [Setup](https://mcp.n24q02m.com/servers/better-workspace-mcp/setup/) -- plugin install, Docker stdio, and Docker HTTP methods
309
- - [Modes overview](https://mcp.n24q02m.com/get-started/modes-overview/) -- stdio (default) and HTTP (multi-user, bearer tokens)
310
- - [Multi-user setup](https://mcp.n24q02m.com/get-started/multi-user/) -- the per-namespace credential model behind [Remote (HTTP mode)](#remote-http-mode)
401
+ - [Setup](https://docs.n24q02m.com/servers/workspace/setup/) -- plugin install, Docker stdio, and Docker HTTP methods
311
402
 
312
403
  Every tool also documents itself at runtime: call `help` for the full reference on
313
404
  any of them, including the exact parameters each action takes.