fix: address PR taylorwilsdon#589 audit findings

mickey-mikey · claude · mickey-mikey · commit 0798609f877c · 2026-03-19T18:24:26.000+11:00
SKILL.md:
- Fix "every tool requires user_google_email" (generate_trigger_code doesn't)
- Add start_google_auth to routing tables
- Add missing reference file links for Forms, Tasks, Contacts, Chat, Apps Script, Search
- Move import_to_google_doc to Drive section (per tool_tiers.yaml)
- Remove non-standard metadata frontmatter field
- Rewrite setup: skill guides credential config into ~/.claude/settings.local.json
- Add PYTHONIOENCODING=utf-8 for Windows
- Add Windows cmd.exe quoting note for CLI mode

plugin.json:
- Add author field

Reference files:
- apps-script.md: fix header re generate_trigger_code
- docs.md: add user_google_email to all 12 tables that were missing it
- sheets.md: add missing include_notes parameter to read_sheet_values
- contacts.md, forms.md, gmail.md, drive.md, tasks.md: fix page_token type to any

Co-Authored-By: Claude Opus 4.6 (1M context) &lt;noreply@anthropic.com&gt;
diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json
@@ -2,5 +2,8 @@
   "name": "google-workspace-mcp",
   "description": "Complete Google Workspace integration — connects Gmail, Drive, Calendar, Docs, Sheets, Slides, Forms, Tasks, Contacts, Chat, and Apps Script via MCP with workflow guidance.",
   "version": "1.14.3",
+  "author": {
+    "name": "taylorwilsdon"
+  },
   "skills": "./skills/"
 }
diff --git a/skills/google-workspace/SKILL.md b/skills/google-workspace/SKILL.md
@@ -9,8 +9,6 @@ description: >
   Also triggers for phrases like "check my email", "find a file", "schedule a meeting", "update the spreadsheet", "share a doc",
   "create a presentation", "add a task", "look up a contact", or any mention of Gmail, Google Drive, Google Docs, Google Sheets,
   Google Slides, Google Forms, Google Tasks, Google Contacts, Google Chat, or Apps Script.
-metadata:
-  author: taylorwilsdon
 ---
 
 # Google Workspace — Tool Router
@@ -32,42 +30,48 @@ If no MCP tools are available, execute via bash:
 uvx workspace-mcp --cli <tool_name> --args '{"user_google_email": "USER_EMAIL", ...}'
 ```
 
+On Windows cmd.exe, use double quotes and escape inner quotes: `--args "{\"user_google_email\": \"USER_EMAIL\"}"`. PowerShell and Git Bash support single quotes as shown above.
+
 Before calling a tool, read the relevant reference file for exact parameter names and types. Only use parameters documented there — do not invent parameters.
 
 ## First-Time Setup
 
+If a tool call fails with a credential error, walk the user through this setup.
+
 ### 1. Create OAuth credentials
-At [Google Cloud Console](https://console.cloud.google.com/apis/credentials):
+Direct the user to [Google Cloud Console](https://console.cloud.google.com/apis/credentials):
 - Create OAuth 2.0 Client ID (Desktop application type)
-- Enable the Google APIs you need (Gmail, Drive, Calendar, etc.)
+- Enable the Google APIs they need (Gmail, Drive, Calendar, etc.)
+- Copy the Client ID and Client Secret
 
-### 2. Configure credentials
-Credentials load in this priority order:
-1. Environment variables
-2. `.env` file in project root — **will not work with `uvx`** (uvx spawns a standalone process outside your repo). Either export env vars or point to the file directly.
-3. `client_secret.json` via `GOOGLE_CLIENT_SECRET_PATH`
-4. Default `client_secret.json` in project root
+### 2. Store credentials
+Ask the user for their Client ID and Client Secret, then write them to `~/.claude/settings.local.json` in the `env` block (this file is gitignored and never shared):
 
-### 3. MCP config (recommended)
-Pass credentials in the MCP `env` block:
 ```json
 {
-  "command": "uvx",
-  "args": ["workspace-mcp"],
   "env": {
-    "GOOGLE_OAUTH_CLIENT_ID": "your-client-id",
-    "GOOGLE_OAUTH_CLIENT_SECRET": "your-secret",
-    "OAUTHLIB_INSECURE_TRANSPORT": "1"
+    "GOOGLE_OAUTH_CLIENT_ID": "their-client-id",
+    "GOOGLE_OAUTH_CLIENT_SECRET": "their-secret",
+    "PYTHONIOENCODING": "utf-8"
   }
 }
 ```
-`OAUTHLIB_INSECURE_TRANSPORT=1` is required for local (non-HTTPS) development.
 
-### 4. Authenticate
+`PYTHONIOENCODING=utf-8` prevents encoding errors on Windows when tool output contains non-ASCII characters.
+
+Read the existing `~/.claude/settings.local.json` first — merge into the existing `env` object, do not overwrite other settings. These env vars are inherited by all MCP servers and CLI processes that Claude Code spawns.
+
+### 3. Authenticate
 - **MCP mode**: call `start_google_auth` to open the browser OAuth flow
 - **CLI mode**: run any tool — the first invocation opens the OAuth flow
 - Credentials are cached in `store_creds/` for future sessions
 
+### Credential loading priority (for reference)
+1. Environment variables (including those from `~/.claude/settings.json` `env` block)
+2. `.env` file in project root — **will not work with `uvx`** (uvx runs outside the repo directory)
+3. `client_secret.json` via `GOOGLE_CLIENT_SECRET_PATH` env var
+4. Default `client_secret.json` in project root
+
 ## Server Options
 
 These mirror the MCP server's own flags. See the [README](https://github.com/taylorwilsdon/google_workspace_mcp) for full details.
@@ -114,7 +118,7 @@ Other services: `readonly`, `full`.
 
 ## Universal Patterns
 
-- Every tool requires `user_google_email`.
+- Almost every tool requires `user_google_email` (exception: `generate_trigger_code`).
 - Paginated tools support `page_size` and `page_token`. Check for `next_page_token` when completeness matters.
 - Consolidated "manage" tools use an `action` parameter for create/update/delete.
 - Prefer batch tools when working with multiple items.
@@ -157,6 +161,7 @@ For parameters: [references/gmail.md](references/gmail.md)
 | Check permissions | `get_drive_file_permissions` |
 | Get shareable link | `get_drive_shareable_link` |
 | Check public access | `check_drive_file_public_access` |
+| Import file to Google Doc | `import_to_google_doc` |
 
 For parameters: [references/drive.md](references/drive.md)
 
@@ -186,7 +191,6 @@ For parameters: [references/calendar.md](references/calendar.md)
 | Batch update (multiple ops) | `batch_update_doc` |
 | Headers/footers | `update_doc_headers_footers` |
 | Manage tabs | `insert_doc_tab` / `update_doc_tab` / `delete_doc_tab` |
-| Import file to Doc | `import_to_google_doc` |
 | Export to PDF | `export_doc_to_pdf` |
 | List docs in folder | `list_docs_in_folder` |
 | Search docs | `search_docs` |
@@ -231,6 +235,8 @@ For parameters: [references/slides.md](references/slides.md)
 | Get one response | `get_form_response` |
 | Publish settings | `set_publish_settings` |
 
+For parameters: [references/forms.md](references/forms.md)
+
 ### Google Tasks
 | Task | Tool |
 |------|------|
@@ -241,6 +247,8 @@ For parameters: [references/slides.md](references/slides.md)
 | Get task | `get_task` |
 | Manage task (CRUD/move) | `manage_task` |
 
+For parameters: [references/tasks.md](references/tasks.md)
+
 ### Contacts
 | Task | Tool |
 |------|------|
@@ -253,6 +261,8 @@ For parameters: [references/slides.md](references/slides.md)
 | Manage contact group | `manage_contact_group` |
 | List all contacts | `list_contacts` |
 
+For parameters: [references/contacts.md](references/contacts.md)
+
 ### Google Chat
 | Task | Tool |
 |------|------|
@@ -263,6 +273,8 @@ For parameters: [references/slides.md](references/slides.md)
 | React to message | `create_reaction` |
 | Download attachment | `download_chat_attachment` |
 
+For parameters: [references/chat.md](references/chat.md)
+
 ### Apps Script
 | Task | Tool |
 |------|------|
@@ -279,12 +291,21 @@ For parameters: [references/slides.md](references/slides.md)
 | Execution metrics | `get_script_metrics` |
 | Process history | `list_script_processes` |
 
+For parameters: [references/apps-script.md](references/apps-script.md)
+
 ### Google Custom Search
 | Task | Tool |
 |------|------|
 | Web search | `search_custom` |
 | Get search engine info | `get_search_engine_info` |
 
+For parameters: [references/search.md](references/search.md)
+
+### Auth
+| Task | Tool |
+|------|------|
+| Start OAuth flow | `start_google_auth` |
+
 ## Common Workflows
 
 ### Reply to an email
diff --git a/skills/google-workspace/references/apps-script.md b/skills/google-workspace/references/apps-script.md
@@ -1,6 +1,6 @@
 # Apps Script Tools Reference
 
-MCP tools for Google Apps Script via the Google Workspace MCP server. All tools require `user_google_email` (string, required).
+MCP tools for Google Apps Script via the Google Workspace MCP server. All tools require `user_google_email` (string, required) except `generate_trigger_code`.
 
 ---
 
diff --git a/skills/google-workspace/references/contacts.md b/skills/google-workspace/references/contacts.md
@@ -22,7 +22,7 @@ List contacts for the authenticated user.
 |---|---|---|---|---|
 | user_google_email | string | yes | | |
 | page_size | integer | no | 100 | Max 1000 |
-| page_token | string | no | | For pagination |
+| page_token | any | no | | For pagination |
 | sort_order | string | no | | `LAST_MODIFIED_ASCENDING`, `LAST_MODIFIED_DESCENDING`, `FIRST_NAME_ASCENDING`, or `LAST_NAME_ASCENDING` |
 
 ### get_contact
@@ -71,7 +71,7 @@ List contact groups (labels).
 |---|---|---|---|---|
 | user_google_email | string | yes | | |
 | page_size | integer | no | 100 | Max 1000 |
-| page_token | string | no | | For pagination |
+| page_token | any | no | | For pagination |
 
 ### get_contact_group
 Get details of a specific contact group including its members.
diff --git a/skills/google-workspace/references/docs.md b/skills/google-workspace/references/docs.md
@@ -23,6 +23,7 @@ Retrieves plain text content of a Google Doc or a Drive file (.docx, etc.). Nati
 
 | Parameter | Type | Required | Default | Notes |
 |-----------|------|----------|---------|-------|
+| user_google_email | string | yes | | |
 | document_id | string | yes | | Doc ID or file ID |
 
 ### search_docs
@@ -31,6 +32,7 @@ Searches for Google Docs by name using Drive API (mimeType filter).
 
 | Parameter | Type | Required | Default | Notes |
 |-----------|------|----------|---------|-------|
+| user_google_email | string | yes | | |
 | query | string | yes | | Search query for doc names |
 | page_size | integer | no | 10 | Max results to return |
 
@@ -40,6 +42,7 @@ Lists Google Docs within a specific Drive folder.
 
 | Parameter | Type | Required | Default | Notes |
 |-----------|------|----------|---------|-------|
+| user_google_email | string | yes | | |
 | folder_id | string | no | root | Drive folder ID |
 | page_size | integer | no | 100 | Max items to return |
 
@@ -53,6 +56,7 @@ Creates a new Google Doc with optional initial content.
 
 | Parameter | Type | Required | Default | Notes |
 |-----------|------|----------|---------|-------|
+| user_google_email | string | yes | | |
 | title | string | yes | | Document title |
 | content | string | no | (empty) | Initial text content |
 
@@ -62,6 +66,7 @@ Imports a file (Markdown, DOCX, TXT, HTML, RTF, ODT) into Google Docs format wit
 
 | Parameter | Type | Required | Default | Notes |
 |-----------|------|----------|---------|-------|
+| user_google_email | string | yes | | |
 | file_name | string | yes | | Name for the new Google Doc |
 | content | string | no | | Text content for MD, TXT, HTML |
 | file_path | string | no | | Local file path for DOCX, ODT, etc. Supports `file://` URLs |
@@ -193,6 +198,7 @@ Export a Google Doc to PDF and save it to Drive.
 
 | Parameter | Type | Required | Default | Notes |
 |-----------|------|----------|---------|-------|
+| user_google_email | string | yes | | |
 | document_id | string | yes | | |
 | pdf_filename | string | no | (original name + "_PDF") | PDF file name |
 | folder_id | string | no | (root) | Destination folder ID |
@@ -207,6 +213,7 @@ Add a new tab to a document.
 
 | Parameter | Type | Required | Default | Notes |
 |-----------|------|----------|---------|-------|
+| user_google_email | string | yes | | |
 | document_id | string | yes | | |
 | title | string | yes | | Tab title |
 | index | integer | yes | | 0-based position among sibling tabs |
@@ -218,6 +225,7 @@ Rename an existing tab.
 
 | Parameter | Type | Required | Default | Notes |
 |-----------|------|----------|---------|-------|
+| user_google_email | string | yes | | |
 | document_id | string | yes | | |
 | tab_id | string | yes | | Get from `inspect_doc_structure` |
 | title | string | yes | | New tab title |
@@ -228,6 +236,7 @@ Delete a tab by ID.
 
 | Parameter | Type | Required | Default | Notes |
 |-----------|------|----------|---------|-------|
+| user_google_email | string | yes | | |
 | document_id | string | yes | | |
 | tab_id | string | yes | | Get from `inspect_doc_structure` |
 
@@ -241,6 +250,7 @@ List all comments on a document.
 
 | Parameter | Type | Required | Default | Notes |
 |-----------|------|----------|---------|-------|
+| user_google_email | string | yes | | |
 | document_id | string | yes | | |
 
 ### manage_document_comment
@@ -249,6 +259,7 @@ Create, reply to, or resolve a comment.
 
 | Parameter | Type | Required | Default | Notes |
 |-----------|------|----------|---------|-------|
+| user_google_email | string | yes | | |
 | document_id | string | yes | | |
 | action | string | yes | | `create`, `reply`, or `resolve` |
 | comment_content | string | no | | Required for `create` and `reply` |
@@ -281,6 +292,7 @@ Detailed view of a single table's layout: dimensions, cell positions, current co
 
 | Parameter | Type | Required | Default | Notes |
 |-----------|------|----------|---------|-------|
+| user_google_email | string | yes | | |
 | document_id | string | yes | | |
 | table_index | integer | no | 0 | 0-based table number (0 = first table) |
 
diff --git a/skills/google-workspace/references/drive.md b/skills/google-workspace/references/drive.md
@@ -14,7 +14,7 @@ Search for files and folders across My Drive and shared drives.
 |-----------|------|----------|---------|-------|
 | query | string | yes | | Google Drive search query (see operators below) |
 | page_size | integer | no | 10 | Max results to return |
-| page_token | string | no | | Token from previous response for pagination |
+| page_token | any | no | | Token from previous response for pagination |
 | drive_id | string | no | | Shared drive ID to scope search |
 | include_items_from_all_drives | boolean | no | true | Include shared drive items when no drive_id set |
 | corpora | string | no | | `user`, `domain`, `drive`, or `allDrives`. Defaults to `drive` when drive_id is set. Prefer `user` or `drive` over `allDrives` |
@@ -29,7 +29,7 @@ List files and folders in a specific folder.
 |-----------|------|----------|---------|-------|
 | folder_id | string | no | root | Folder ID. Use shared drive ID for its root |
 | page_size | integer | no | 100 | Max items to return |
-| page_token | string | no | | Pagination token |
+| page_token | any | no | | Pagination token |
 | drive_id | string | no | | Shared drive ID to scope listing |
 | include_items_from_all_drives | boolean | no | true | Include shared drive items when no drive_id set |
 | corpora | string | no | | `user`, `drive`, `allDrives` |
diff --git a/skills/google-workspace/references/forms.md b/skills/google-workspace/references/forms.md
@@ -22,7 +22,7 @@ List responses submitted to a form.
 | form_id | string | yes | | |
 | user_google_email | string | yes | | |
 | page_size | integer | no | 10 | Max responses per page |
-| page_token | string | no | | From previous response for pagination |
+| page_token | any | no | | From previous response for pagination |
 
 ### get_form_response
 Get a single response from a form.
diff --git a/skills/google-workspace/references/gmail.md b/skills/google-workspace/references/gmail.md
@@ -14,7 +14,7 @@ Search messages by query. Returns message IDs, thread IDs, and Gmail web links.
 | query | string | yes | | Gmail search query (see operators below) |
 | user_google_email | string | yes | | |
 | page_size | integer | no | 10 | Max results per page |
-| page_token | string | no | | From previous response's `next_page_token` |
+| page_token | any | no | | From previous response's `next_page_token` |
 
 ### get_gmail_message_content
 Get full content of a single message (subject, sender, recipients, date, Message-ID, body).
diff --git a/skills/google-workspace/references/sheets.md b/skills/google-workspace/references/sheets.md
@@ -38,6 +38,7 @@ Read values from a range in a spreadsheet.
 | spreadsheet_id | string | yes | | |
 | range_name | string | no | A1:Z1000 | A1 notation, e.g. `Sheet1!A1:D10` |
 | include_hyperlinks | boolean | no | false | Fetch hyperlink metadata (slower) |
+| include_notes | boolean | no | false | Fetch cell notes (slower) |
 
 ### modify_sheet_values
 
diff --git a/skills/google-workspace/references/tasks.md b/skills/google-workspace/references/tasks.md
@@ -13,7 +13,7 @@ List all task lists for the user.
 |---|---|---|---|---|
 | user_google_email | string | yes | | |
 | max_results | integer | no | 1000 | Max 1000 |
-| page_token | string | no | | For pagination |
+| page_token | any | no | | For pagination |
 
 ### get_task_list
 Get details of a specific task list.
@@ -45,7 +45,7 @@ List tasks in a specific task list.
 | task_list_id | string | yes | | |
 | user_google_email | string | yes | | |
 | max_results | integer | no | 20 | Max 10000 |
-| page_token | string | no | | For pagination |
+| page_token | any | no | | For pagination |
 | show_completed | boolean | no | true | Include completed tasks |
 | show_deleted | boolean | no | false | Include deleted tasks |
 | show_hidden | boolean | no | false | Include hidden tasks; must be true to see tasks completed in first-party clients |

Original file line number	Diff line number	Diff line change
`@@ -2,5 +2,8 @@`
`2`	`2`	`"name": "google-workspace-mcp",`
`3`	`3`	`"description": "Complete Google Workspace integration — connects Gmail, Drive, Calendar, Docs, Sheets, Slides, Forms, Tasks, Contacts, Chat, and Apps Script via MCP with workflow guidance.",`
`4`	`4`	`"version": "1.14.3",`
	`5`	`+ "author": {`
	`6`	`+ "name": "taylorwilsdon"`
	`7`	`+ },`
`5`	`8`	`"skills": "./skills/"`
`6`	`9`	`}`