Google Workspace MCP Server

Instructions

Implementation Reference

• src/services.ts:248-256 (schema)

  Tool definition for calendar_events_delete specifying name, description, gws CLI command (['calendar', 'events', 'delete']), and required parameters (calendarId, eventId)

  {
    name: "calendar_events_delete",
    description: "Delete a calendar event.",
    command: ["calendar", "events", "delete"],
    params: [
      { name: "calendarId", description: "Calendar ID", type: "string", required: true },
      { name: "eventId", description: "Event ID to delete", type: "string", required: true },
    ],
  },

• src/executor.ts:181-210 (handler)

  The executeGws function is the main handler that executes any tool including calendar_events_delete. It builds CLI args, spawns the gws process, handles errors, and returns results.

  export async function executeGws(
    tool: ToolDef,
    args: Record<string, unknown>,
    gwsBinary: string,
  ): Promise<ExecResult> {
    const cliArgs = buildArgs(tool, args);
  
    console.error(`[gws-mcp] Executing: ${gwsBinary} ${cliArgs.join(" ")}`);
  
    try {
      const { stdout, stderr } = await spawnGwsRaw(gwsBinary, cliArgs);
  
      if (stderr) {
        console.error(`[gws-mcp] stderr: ${stderr}`);
      }
  
      return { success: true, output: stdout || "(empty response)" };
    } catch (err: unknown) {
      const error = err as { message?: string };
      let message = error.message || "Unknown error";
  
      // Enhance Drive 404 errors with actionable hints
      if (message.includes("404") && message.includes("not found") && tool.command[0] === "drive") {
        message += "\n\nHint: If this file is in a shared drive, ensure supportsAllDrives is set (this should be automatic). Check that the file ID is correct and the authenticated account has access.";
      }
  
      console.error(`[gws-mcp] Error: ${message}`);
      return { success: false, output: "", error: message };
    }
  }

• src/index.ts:155-178 (registration)

  Registration loop that iterates through all tool definitions and registers each with the MCP server using server.tool(), including the handler callback that invokes executeGws

  // Register each tool
  for (const tool of tools) {
    const schema = buildZodSchema(tool);
  
    server.tool(
      tool.name,
      tool.description,
      schema,
      async (args) => {
        const result = await executeGws(tool, args as Record<string, unknown>, gwsBinary);
  
        if (result.success) {
          return {
            content: [{ type: "text" as const, text: result.output || "(empty response)" }],
          };
        } else {
          return {
            content: [{ type: "text" as const, text: `Error: ${result.error}` }],
            isError: true,
          };
        }
      },
    );
  }

• src/executor.ts:76-129 (helper)

  The buildArgs function constructs CLI arguments from tool definition and user args, handling params, bodyParams, and file uploads with proper escaping for security

  function buildArgs(
    tool: ToolDef,
    args: Record<string, unknown>,
  ): string[] {
    const cliArgs = [...tool.command];
  
    // Collect --params (query/path parameters)
    // Start with defaults (e.g. supportsAllDrives), then overlay caller values
    const params: Record<string, unknown> = { ...(tool.defaultParams || {}) };
    for (const p of tool.params) {
      if (args[p.name] !== undefined) {
        params[p.name] = args[p.name];
      }
    }
    if (Object.keys(params).length > 0) {
      cliArgs.push("--params", escapeJsonArg(JSON.stringify(params)));
    }
  
    // Collect --json (request body)
    if (tool.bodyParams && tool.bodyParams.length > 0) {
      const body: Record<string, unknown> = {};
      for (const p of tool.bodyParams) {
        if (args[p.name] !== undefined) {
          let val = args[p.name];
          if (typeof val === "string") {
            try {
              const parsed = JSON.parse(val);
              if (typeof parsed === "object") {
                val = parsed;
              }
            } catch {
              // Keep as string
            }
          }
          body[p.name] = val;
        }
      }
      if (Object.keys(body).length > 0) {
        cliArgs.push("--json", escapeJsonArg(JSON.stringify(body)));
      }
    }
  
    // File upload — validate path before passing to CLI
    if (tool.supportsUpload && args.uploadPath) {
      const safePath = sanitizeUploadPath(String(args.uploadPath));
      if (process.platform === "win32") {
        cliArgs.push("--upload", escapeForCmd(safePath));
      } else {
        cliArgs.push("--upload", safePath);
      }
    }
  
    return cliArgs;
  }

• src/index.ts:100-131 (helper)

  The buildZodSchema function generates Zod validation schemas from tool parameter definitions, converting ParamDef types to Zod types with optional/required handling

  function buildZodSchema(tool: ToolDef): Record<string, z.ZodTypeAny> {
    const shape: Record<string, z.ZodTypeAny> = {};
  
    const allParams = [...tool.params, ...(tool.bodyParams || [])];
  
    for (const p of allParams) {
      let field: z.ZodTypeAny;
      switch (p.type) {
        case "number":
          field = z.number().describe(p.description);
          break;
        case "boolean":
          field = z.boolean().describe(p.description);
          break;
        default:
          field = z.string().describe(p.description);
      }
  
      if (!p.required) {
        field = field.optional();
      }
  
      shape[p.name] = field;
    }
  
    // Add optional uploadPath for tools that support file upload
    if (tool.supportsUpload) {
      shape.uploadPath = z.string().describe("Local file path to upload").optional();
    }
  
    return shape;
  }