Address code review: error handling, range rename, public API, token docs

- Wrap all 5 sheets tool functions in try/except for httpx.HTTPStatusError
  with user-friendly messages for 403/404/429 and generic Google API errors
- Rename `range` parameter to `cell_range` in GoogleSheetsClient methods
  to avoid shadowing the Python builtin (model field stays `range` for API)
- Use public `remove_tool()` API instead of `_tools.pop()` for stdio mode
  sheets tool removal in server.py
- Document single-tenant assumption on Google token key in sheets_client.py

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: RafaelPo

everyrow-mcp/src/everyrow_mcp/server.py

@@ -124,7 +124,7 @@ def main():
             "sheets_create",
             "sheets_info",
         ):
-            mcp._tool_manager._tools.pop(name, None)
+            mcp._tool_manager.remove_tool(name)
 
     mcp.run(transport=transport.value)
 

everyrow-mcp/src/everyrow_mcp/sheets_client.py

@@ -41,7 +41,8 @@ async def get_google_token() -> str:
 
     redis = get_redis_client()
 
-    # Try to get the stored token
+    # NOTE: single-tenant — "current" key is shared. If multi-tenancy is
+    # needed, key by session/user ID instead.
     token_key = build_key("google_token", "current")
     token_data = await redis.get(token_key)
     if token_data:
@@ -147,14 +148,14 @@ async def __aexit__(self, *args: Any) -> None:
         await self.close()
 
     async def read_range(
-        self, spreadsheet_id: str, range: str = "Sheet1"
+        self, spreadsheet_id: str, cell_range: str = "Sheet1"
     ) -> list[list[str]]:
         """Read values from a spreadsheet range.
 
         Returns a 2D list of strings (rows x columns).
         """
         resp = await self._client.get(
-            f"{SHEETS_API_BASE}/{spreadsheet_id}/values/{range}",
+            f"{SHEETS_API_BASE}/{spreadsheet_id}/values/{cell_range}",
             params={"valueRenderOption": "FORMATTED_VALUE"},
         )
         resp.raise_for_status()
@@ -164,12 +165,12 @@ async def read_range(
     async def write_range(
         self,
         spreadsheet_id: str,
-        range: str,
+        cell_range: str,
         values: list[list[str]],
     ) -> dict[str, Any]:
         """Write values to a spreadsheet range (overwrite)."""
         resp = await self._client.put(
-            f"{SHEETS_API_BASE}/{spreadsheet_id}/values/{range}",
+            f"{SHEETS_API_BASE}/{spreadsheet_id}/values/{cell_range}",
             params={"valueInputOption": "USER_ENTERED"},
             json={"values": values},
         )
@@ -179,12 +180,12 @@ async def write_range(
     async def append_range(
         self,
         spreadsheet_id: str,
-        range: str,
+        cell_range: str,
         values: list[list[str]],
     ) -> dict[str, Any]:
         """Append values after existing data in a range."""
         resp = await self._client.post(
-            f"{SHEETS_API_BASE}/{spreadsheet_id}/values/{range}:append",
+            f"{SHEETS_API_BASE}/{spreadsheet_id}/values/{cell_range}:append",
             params={
                 "valueInputOption": "USER_ENTERED",
                 "insertDataOption": "INSERT_ROWS",

everyrow-mcp/src/everyrow_mcp/sheets_tools.py

@@ -9,6 +9,7 @@
 import json
 import logging
 
+import httpx
 from mcp.types import TextContent, ToolAnnotations
 
 from everyrow_mcp.app import mcp
@@ -29,6 +30,20 @@
 logger = logging.getLogger(__name__)
 
 
+def _error_message(e: Exception) -> str:
+    """Format a user-friendly error message from a Google API exception."""
+    if isinstance(e, httpx.HTTPStatusError):
+        status = e.response.status_code
+        if status == 403:
+            return "Permission denied. Check that the spreadsheet is shared with you."
+        if status == 404:
+            return "Spreadsheet not found. Check the spreadsheet ID or URL."
+        if status == 429:
+            return "Rate limited by Google API. Please try again in a moment."
+        return f"Google API error (HTTP {status}): {e.response.text}"
+    return f"Error: {e!r}"
+
+
 @mcp.tool(
     name="sheets_list",
     annotations=ToolAnnotations(
@@ -41,11 +56,14 @@
 )
 async def sheets_list(params: SheetsListInput) -> list[TextContent]:
     """List the user's Google Sheets, optionally filtered by name."""
-    token = await get_google_token()
-    async with GoogleSheetsClient(token) as client:
-        files = await client.list_spreadsheets(
-            query=params.query, max_results=params.max_results
-        )
+    try:
+        token = await get_google_token()
+        async with GoogleSheetsClient(token) as client:
+            files = await client.list_spreadsheets(
+                query=params.query, max_results=params.max_results
+            )
+    except Exception as e:
+        return [TextContent(type="text", text=_error_message(e))]
 
     if not files:
         msg = "No spreadsheets found"
@@ -83,9 +101,14 @@ async def sheets_read(params: SheetsReadInput) -> list[TextContent]:
       everyrow_agent(input_json=data, task="Research each company")
       sheets_write(spreadsheet_id="...", data=enriched_results)
     """
-    token = await get_google_token()
-    async with GoogleSheetsClient(token) as client:
-        values = await client.read_range(params.spreadsheet_id, params.range)
+    try:
+        token = await get_google_token()
+        async with GoogleSheetsClient(token) as client:
+            values = await client.read_range(
+                params.spreadsheet_id, cell_range=params.range
+            )
+    except Exception as e:
+        return [TextContent(type="text", text=_error_message(e))]
 
     records = values_to_records(values)
 
@@ -127,36 +150,41 @@ async def sheets_write(params: SheetsWriteInput) -> list[TextContent]:
 
     Use append=True to add rows after existing data instead of overwriting.
     """
-    token = await get_google_token()
-    values = records_to_values(params.data)
-
-    async with GoogleSheetsClient(token) as client:
-        if params.append:
-            result = await client.append_range(
-                params.spreadsheet_id, params.range, values
-            )
-            updated_range = result.get("updates", {}).get("updatedRange", params.range)
-            updated_rows = result.get("updates", {}).get(
-                "updatedRows", len(params.data)
-            )
-            return [
-                TextContent(
-                    type="text",
-                    text=f"Appended {updated_rows} rows to {updated_range}.",
+    try:
+        token = await get_google_token()
+        values = records_to_values(params.data)
+
+        async with GoogleSheetsClient(token) as client:
+            if params.append:
+                result = await client.append_range(
+                    params.spreadsheet_id, cell_range=params.range, values=values
                 )
-            ]
-        else:
-            result = await client.write_range(
-                params.spreadsheet_id, params.range, values
-            )
-            updated_range = result.get("updatedRange", params.range)
-            updated_rows = result.get("updatedRows", len(params.data) + 1)
-            return [
-                TextContent(
-                    type="text",
-                    text=f"Wrote {updated_rows} rows (including header) to {updated_range}.",
+                updated_range = result.get("updates", {}).get(
+                    "updatedRange", params.range
+                )
+                updated_rows = result.get("updates", {}).get(
+                    "updatedRows", len(params.data)
                 )
-            ]
+                return [
+                    TextContent(
+                        type="text",
+                        text=f"Appended {updated_rows} rows to {updated_range}.",
+                    )
+                ]
+            else:
+                result = await client.write_range(
+                    params.spreadsheet_id, cell_range=params.range, values=values
+                )
+                updated_range = result.get("updatedRange", params.range)
+                updated_rows = result.get("updatedRows", len(params.data) + 1)
+                return [
+                    TextContent(
+                        type="text",
+                        text=f"Wrote {updated_rows} rows (including header) to {updated_range}.",
+                    )
+                ]
+    except Exception as e:
+        return [TextContent(type="text", text=_error_message(e))]
 
 
 @mcp.tool(
@@ -174,20 +202,23 @@ async def sheets_create(params: SheetsCreateInput) -> list[TextContent]:
 
     Returns the spreadsheet ID and URL.
     """
-    token = await get_google_token()
-
-    async with GoogleSheetsClient(token) as client:
-        metadata = await client.create_spreadsheet(params.title)
-        spreadsheet_id = metadata["spreadsheetId"]
-        url = metadata.get(
-            "spreadsheetUrl",
-            f"https://docs.google.com/spreadsheets/d/{spreadsheet_id}",
-        )
+    try:
+        token = await get_google_token()
+
+        async with GoogleSheetsClient(token) as client:
+            metadata = await client.create_spreadsheet(params.title)
+            spreadsheet_id = metadata["spreadsheetId"]
+            url = metadata.get(
+                "spreadsheetUrl",
+                f"https://docs.google.com/spreadsheets/d/{spreadsheet_id}",
+            )
 
-        # Optionally populate with initial data
-        if params.data:
-            values = records_to_values(params.data)
-            await client.write_range(spreadsheet_id, "Sheet1", values)
+            # Optionally populate with initial data
+            if params.data:
+                values = records_to_values(params.data)
+                await client.write_range(spreadsheet_id, "Sheet1", values)
+    except Exception as e:
+        return [TextContent(type="text", text=_error_message(e))]
 
     result = {
         "spreadsheet_id": spreadsheet_id,
@@ -217,10 +248,13 @@ async def sheets_create(params: SheetsCreateInput) -> list[TextContent]:
 )
 async def sheets_info(params: SheetsInfoInput) -> list[TextContent]:
     """Get metadata about a Google Sheet: title, sheet names, and dimensions."""
-    token = await get_google_token()
+    try:
+        token = await get_google_token()
 
-    async with GoogleSheetsClient(token) as client:
-        metadata = await client.get_spreadsheet_metadata(params.spreadsheet_id)
+        async with GoogleSheetsClient(token) as client:
+            metadata = await client.get_spreadsheet_metadata(params.spreadsheet_id)
+    except Exception as e:
+        return [TextContent(type="text", text=_error_message(e))]
 
     title = metadata.get("properties", {}).get("title", "Unknown")
     sheets = []