From f2986dcf2f6ab9bb8870ec9911a4a8141b767423 Mon Sep 17 00:00:00 2001
From: Taylor Wilsdon <tbarrettwilsdon@gmail.com>
Date: Sat, 28 Feb 2026 11:19:19 -0400
Subject: [PATCH] pr feedback & readme update

---
 README.md | 18 ++++++++++++++++++
 main.py   | 23 +++++++++++++++++++++--
 2 files changed, 39 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index 6c15034..2cde17a 100644
--- a/README.md
+++ b/README.md
@@ -560,6 +560,21 @@ Read-only mode provides secure, restricted access by:
 - Automatically filtering out tools that require write permissions at startup
 - Allowing read operations: list, get, search, and export across all services
 
+**🔐 Granular Permissions**
+```bash
+# Per-service permission levels
+uv run main.py --permissions gmail:organize drive:readonly
+
+# Combine permissions with tier filtering
+uv run main.py --permissions gmail:send drive:full --tool-tier core
+```
+Granular permissions mode provides service-by-service scope control:
+- Format: `service:level` (one entry per service)
+- Gmail levels: `readonly`, `organize`, `drafts`, `send`, `full` (cumulative)
+- Other services currently support: `readonly`, `full`
+- `--permissions` and `--read-only` are mutually exclusive
+- With `--tool-tier`, only tier-matched tools are enabled and only services with matching tier tools are imported
+
 **★ Tool Tiers**
 ```bash
 uv run main.py --tool-tier core      # ● Essential tools only
@@ -738,6 +753,9 @@ uv run main.py --tool-tier complete                        # Enable all availabl
 uv run main.py --tools gmail drive --tool-tier core        # Core tools for specific services
 uv run main.py --tools gmail --tool-tier extended          # Extended Gmail functionality only
 uv run main.py --tools docs sheets --tool-tier complete    # Full access to Docs and Sheets
+
+# Combine tier selection with granular permission levels
+uv run main.py --permissions gmail:organize drive:full --tool-tier core
 ```
 
 ## 📋 Credential Configuration
diff --git a/main.py b/main.py
index 07f3cd2..8dc28be 100644
--- a/main.py
+++ b/main.py
@@ -91,6 +91,23 @@ def configure_safe_logging():
             handler.setFormatter(safe_formatter)
 
 
+def resolve_permissions_mode_selection(
+    permission_services: list[str], tool_tier: str | None
+) -> tuple[list[str], set[str] | None]:
+    """
+    Resolve service imports and optional tool-name filtering for --permissions mode.
+
+    When a tier is specified, both:
+    - imported services are narrowed to services with tier-matched tools
+    - registered tools are narrowed to the resolved tool names
+    """
+    if tool_tier is None:
+        return permission_services, None
+
+    tier_tools, tier_services = resolve_tools_from_tier(tool_tier, permission_services)
+    return tier_services, set(tier_tools)
+
+
 def main():
     """
     Main entry point for the Google Workspace MCP server.
@@ -306,8 +323,10 @@ def main():
         if args.tool_tier is not None:
             # Combine with tier filtering within the permission-selected services
             try:
-                tier_tools, _ = resolve_tools_from_tier(args.tool_tier, tools_to_import)
-                set_enabled_tool_names(set(tier_tools))
+                tools_to_import, tier_tool_filter = resolve_permissions_mode_selection(
+                    tools_to_import, args.tool_tier
+                )
+                set_enabled_tool_names(tier_tool_filter)
             except Exception as e:
                 print(
                     f"Error loading tools for tier '{args.tool_tier}': {e}",