@dguido/google-workspace-mcp 3.1.0 → 3.1.1

package/README.md

@@ -162,6 +162,7 @@ To enable additional services, add them to `GOOGLE_WORKSPACE_SERVICES`:
 
 - Omit `GOOGLE_WORKSPACE_SERVICES` entirely to enable all services
 - Unified tools (`create_file`, `update_file`, `get_file_content`) require `drive`, `docs`, `sheets`, and `slides`
+- When you limit services, only the OAuth scopes for those services are requested during authentication. If you change enabled services, re-authenticate to update granted scopes.
 
 See [Advanced Configuration](docs/ADVANCED.md) for named profiles, multi-account setup, and environment variables.
 
@@ -266,22 +267,6 @@ If you have a Google Workspace account:
 
 Use `get_status` to check token age. Tokens older than 6 days show a warning automatically.
 
-## Scope Filtering
-
-When you limit services via `GOOGLE_WORKSPACE_SERVICES`, only the OAuth scopes for those services are requested during authentication. This provides:
-
-- **Cleaner consent screen** - Users see only the permissions they need
-- **Principle of least privilege** - App only has access to enabled services
-
-For example, setting `GOOGLE_WORKSPACE_SERVICES=drive,calendar` will only request Drive and Calendar scopes, not Gmail or Contacts.
-
-**Note:** If you change enabled services, re-authenticate to update granted scopes:
-
-```bash
-rm ~/.config/google-workspace-mcp/tokens.json
-npx @dguido/google-workspace-mcp auth
-```
-
 ## Development
 
 ```bash
@@ -293,12 +278,6 @@ npm test         # Run tests
 
 See [Contributing Guide](CONTRIBUTING.md) for project structure and development workflow.
 
-## Links
-
-- [GitHub Repository](https://github.com/dguido/google-workspace-mcp)
-- [Issue Tracker](https://github.com/dguido/google-workspace-mcp/issues)
-- [Model Context Protocol](https://modelcontextprotocol.io)
-
 ## Origin
 
 This project is a substantial rewrite of [piotr-agier/google-drive-mcp](https://github.com/piotr-agier/google-drive-mcp), originally created by Piotr Agier.

package/dist/index.js

@@ -5253,16 +5253,50 @@ var gmailTools = [
   },
   {
     name: "search_emails",
-    description: "Search emails using Gmail query syntax (max 500 per request)",
+    description: "Search emails using structured parameters or Gmail query syntax (max 500 per request). At least one search parameter required.",
     inputSchema: {
       type: "object",
       properties: {
-        query: { type: "string", description: "Gmail search query" },
+        query: {
+          type: "string",
+          description: "Gmail search query. Operators: from: to: subject: has:attachment is:unread after:YYYY/MM/DD before:YYYY/MM/DD larger: smaller: label:. Gmail ignores special characters like $ and commas \u2014 use plain numbers (5149 not $5,149)."
+        },
+        from: {
+          type: "string",
+          description: "Sender email or name"
+        },
+        to: {
+          type: "string",
+          description: "Recipient email or name"
+        },
+        subject: {
+          type: "string",
+          description: "Subject line text"
+        },
+        after: {
+          type: "string",
+          description: "After date (YYYY/MM/DD)"
+        },
+        before: {
+          type: "string",
+          description: "Before date (YYYY/MM/DD)"
+        },
+        hasAttachment: {
+          type: "boolean",
+          description: "Filter for messages with attachments"
+        },
+        label: {
+          type: "string",
+          description: "Gmail label name"
+        },
         maxResults: {
           type: "number",
           description: "(optional, default: 50) Maximum results (max 500)"
         },
-        pageToken: { type: "string", description: "(optional) Pagination token" },
+        pageToken: {
+          type: "string",
+          description: "(optional) Pagination token"
+        },
         labelIds: {
           type: "array",
           items: { type: "string" },
@@ -5272,8 +5306,7 @@ var gmailTools = [
           type: "boolean",
           description: "(optional, default: false) Include spam and trash"
         }
-      },
-      required: ["query"]
+      }
     },
     outputSchema: {
       type: "object",
@@ -7138,12 +7171,24 @@ var ReadEmailSchema = z8.object({
   contentFormat: z8.enum(["full", "text", "headers"]).optional().default("full").describe("Content format: 'full' (text+HTML), 'text' (plain text only), 'headers' (no body)")
 });
 var SearchEmailsSchema = z8.object({
-  query: z8.string().min(1, "Search query required").describe("Gmail search query (e.g., 'from:sender@example.com', 'is:unread', 'subject:hello')"),
+  query: z8.string().max(500).optional().describe(
+    "Gmail search query. Operators: from: to: subject: has:attachment is:unread after:YYYY/MM/DD before:YYYY/MM/DD larger: smaller: label:. Gmail ignores special characters like $ and commas \u2014 use plain numbers (5149 not $5,149)."
+  ),
+  from: z8.string().max(254).optional().describe("Sender email or name"),
+  to: z8.string().max(254).optional().describe("Recipient email or name"),
+  subject: z8.string().max(500).optional().describe("Subject line text"),
+  after: z8.string().max(10).optional().describe("After date (YYYY/MM/DD)"),
+  before: z8.string().max(10).optional().describe("Before date (YYYY/MM/DD)"),
+  hasAttachment: z8.boolean().optional().describe("Filter for messages with attachments"),
+  label: z8.string().max(225).optional().describe("Gmail label name"),
   maxResults: z8.number().int().min(1).max(500).optional().default(50).describe("Maximum results"),
   pageToken: z8.string().optional().describe("Token for pagination"),
   labelIds: z8.array(z8.string()).optional().describe("Filter by label IDs"),
   includeSpamTrash: z8.boolean().optional().default(false).describe("Include spam and trash")
-});
+}).refine(
+  (d) => d.query || d.from || d.to || d.subject || d.after || d.before || d.hasAttachment || d.label,
+  { message: "At least one search parameter required" }
+);
 var DeleteEmailSchema = z8.object({
   messageId: z8.union([z8.string().min(1), z8.array(z8.string().min(1)).min(1).max(1e3)]).describe("Message ID or array of IDs (max 1000 for batch)")
 });
@@ -11891,10 +11936,45 @@ async function handleReadEmail(gmail, args) {
     truncated
   });
 }
+function buildSearchQuery(args) {
+  const parts = [];
+  if (args.from) parts.push(`from:${args.from}`);
+  if (args.to) parts.push(`to:${args.to}`);
+  if (args.subject) parts.push(`subject:${args.subject}`);
+  if (args.after) parts.push(`after:${args.after}`);
+  if (args.before) parts.push(`before:${args.before}`);
+  if (args.hasAttachment) parts.push("has:attachment");
+  if (args.label) parts.push(`label:${args.label}`);
+  if (args.query) parts.push(args.query);
+  return parts.join(" ");
+}
+function buildSearchHints(args) {
+  const hints = [];
+  if (args.query && /[$#,]/.test(args.query)) {
+    hints.push(
+      "Gmail ignores special characters like $, #, and commas \u2014 use plain numbers (e.g. 5149 not $5,149)"
+    );
+  }
+  const dateFormat = /^\d{4}\/\d{2}\/\d{2}$/;
+  if (args.after && !dateFormat.test(args.after)) {
+    hints.push(`Date format for 'after' should be YYYY/MM/DD (got: ${args.after})`);
+  }
+  if (args.before && !dateFormat.test(args.before)) {
+    hints.push(`Date format for 'before' should be YYYY/MM/DD (got: ${args.before})`);
+  }
+  if (args.query && /\d{4}[-/]\d{2}[-/]\d{2}/.test(args.query) && !/(?:after|before):/.test(args.query)) {
+    hints.push("Dates in query need operators: use after:YYYY/MM/DD or before:YYYY/MM/DD");
+  }
+  if (args.query && args.query.length > 200) {
+    hints.push("Try simplifying \u2014 shorter queries often match more");
+  }
+  return hints;
+}
 async function handleSearchEmails(gmail, args) {
   const validation = validateArgs(SearchEmailsSchema, args);
   if (!validation.success) return validation.response;
-  const { query, maxResults, pageToken, labelIds, includeSpamTrash } = validation.data;
+  const { maxResults, pageToken, labelIds, includeSpamTrash } = validation.data;
+  const query = buildSearchQuery(validation.data);
   const response = await gmail.users.messages.list({
     userId: "me",
     q: query,
@@ -11905,7 +11985,12 @@ async function handleSearchEmails(gmail, args) {
   });
   const messages = response.data.messages || [];
   if (messages.length === 0) {
-    return structuredResponse(`No emails found matching: ${query}`, { messages: [] });
+    const hints = buildSearchHints(validation.data);
+    const text = `No emails found matching: ${query}` + (hints.length ? `
+
+Hints:
+${hints.map((h) => `- ${h}`).join("\n")}` : "");
+    return structuredResponse(text, { messages: [] });
   }
   const messageDetails = await Promise.all(
     messages.slice(0, 50).map(async (msg) => {
@@ -13303,10 +13388,12 @@ async function ensureAuthenticated() {
     authenticationPromise = authenticate();
     try {
       authClient = await authenticationPromise;
+      const hasCredentials = !!authClient?.credentials;
+      const hasAccessToken = !!authClient?.credentials?.access_token;
       log("Authentication complete", {
         authClientType: authClient?.constructor?.name,
-        hasCredentials: !!authClient?.credentials,
-        hasAccessToken: !!authClient?.credentials?.access_token
+        hasCredentials,
+        hasAccessToken
       });
       ensureDriveService();
       const healthy = await verifyAuthHealth();