fix(teams): remove create_webex_team; add bot-access guidance

claude · claude · commit d0db9d860db5 · 2026-05-24T21:00:25.000Z
Bots cannot create teams — POST /teams returns 401 for bot tokens regardless of scopes (verified live against the Webex API). This is a hard Webex platform restriction, not a configuration issue. Changes: - Remove create_webex_team (7 tools from 8; tools_count 35 → 34) - Update _map_exception_to_error: 404 now hints at bot membership requirement; 403 now mentions moderator role requirement - Add bot-access notes to all 7 remaining team tool docstrings - Add webex://help/teams resource explaining the full bot access model: what bots can/cannot do, how to get added to a team, 404 vs 403 semantics, and a typical workflow - Update CLAUDE.md: tool count, teams.py layout entry, explicit note on why create_webex_team is absent - Update tests: remove TestCreateWebexTeam; add TestBotAccessModel verifying create_webex_team is not exported and that 404/403 error messages mention membership/moderator requirements https://claude.ai/code/session_01NyYkRAictNQPcdWpepBbT3
diff --git a/CLAUDE.md b/CLAUDE.md
@@ -29,9 +29,13 @@ src/webex_bot_mcp/
                        Adaptive Card send/build tools
     memberships.py   — Membership CRUD (list, add, update, delete) + space aliases
     people.py        — get_webex_me, list_webex_people
+    teams.py         — Team tools (list, get, update, delete) + team membership tools
+                       Note: create_webex_team is intentionally absent — bots cannot
+                       create teams (Webex returns 401); only user/integration tokens can.
 
 tests/
   test_messages.py   — Unit tests (85 cases); mocks webexpythonsdk at sys.modules level
+  test_teams.py      — Unit tests (40 cases); same mock pattern
 
 .github/
   workflows/
@@ -44,11 +48,16 @@ tests/
 ## Key Conventions
 
 ### Tool count
-27 tools total: 5 room + 5 space-room aliases + 4 message + 2 space-message aliases +
+34 tools total: 5 room + 5 space-room aliases + 4 message + 2 space-message aliases +
 2 adaptive-card + 1 adaptive-card-space alias + 1 adaptive-card-builder +
-4 membership + 2 space-membership aliases + 2 people.
+4 membership + 2 space-membership aliases + 2 people +
+4 team + 3 team-membership.
 Update `tools_count` in the `server_version` resource (`src/webex_bot_mcp/main.py`) when adding tools.
 
+Note: `create_webex_team` is intentionally not implemented. Bots cannot create teams —
+the Webex platform returns 401 for `POST /teams` with bot tokens regardless of scopes.
+Only user tokens or OAuth integrations with `spark:teams_write` can create teams.
+
 ### Error handling — always use structured responses
 Every tool must return via `create_error_response` or `create_success_response` from
 `tools/common.py`. Never return a bare `{'success': False, 'error': str(e)}` dict.
diff --git a/src/webex_bot_mcp/main.py b/src/webex_bot_mcp/main.py
@@ -49,7 +49,7 @@
     # People functions
     get_webex_me, list_webex_people,
     # Team functions
-    list_webex_teams, create_webex_team, get_webex_team,
+    list_webex_teams, get_webex_team,
     update_webex_team, delete_webex_team,
     list_webex_team_memberships, add_webex_team_membership,
     delete_webex_team_membership,
@@ -126,7 +126,6 @@ async def dispatch(self, request, call_next):
 
 # Team management tools
 mcp.tool()(list_webex_teams)
-mcp.tool()(create_webex_team)
 mcp.tool()(get_webex_team)
 mcp.tool()(update_webex_team)
 mcp.tool()(delete_webex_team)
@@ -353,6 +352,89 @@ def webex_adaptive_cards_guide():
 """
 
 
+@mcp.resource("webex://help/teams")
+def webex_teams_guide():
+    """Bot access model and guidance for Webex Teams tools"""
+    return """# Webex Teams — Bot Access Guide
+
+## What is a Team in Webex?
+
+A team is a named group of people with a shared set of rooms. Teams are a higher-level
+construct than rooms: a team contains rooms, and all team members can see every room in
+the team. The team membership and team room membership are separate concepts.
+
+## Bot Access Model (Verified Against the Webex API)
+
+Bot tokens operate under stricter rules than user or integration tokens for the Teams API.
+Understanding these rules prevents confusing errors.
+
+### What bots CAN do
+
+| Tool | Requirement |
+|------|-------------|
+| `list_webex_teams` | Bot is a member of at least one team |
+| `get_webex_team` | Bot is a member of that team |
+| `list_webex_team_memberships` | Bot is a member of that team |
+| `update_webex_team` | Bot has the **moderator** role in that team |
+| `delete_webex_team` | Bot has the **moderator** role in that team |
+| `add_webex_team_membership` | Bot has the **moderator** role in that team |
+| `delete_webex_team_membership` | Bot has the **moderator** role in that team |
+
+### What bots CANNOT do
+
+| Operation | Reason |
+|-----------|--------|
+| **Create a team** | Hard platform restriction — `POST /teams` returns 401 for bot tokens regardless of scopes. This is not an error in the MCP; it is enforced by the Webex platform. |
+
+`create_webex_team` is intentionally not implemented in this MCP server. To create a
+team, use a personal access token or an OAuth integration with the `spark:teams_write`
+scope.
+
+## Getting the Bot Into a Team
+
+Before any team tool will work, a human user must add the bot to the team:
+
+1. **Via Webex UI**: Open the team in the Webex app → Members → Add member → paste the
+   bot's email address (visible in `get_webex_me`).
+2. **Via API with a user token**:
+   ```
+   POST https://webexapis.com/v1/team/memberships
+   { "teamId": "<id>", "personEmail": "<bot-email>", "isModerator": true }
+   ```
+   Set `isModerator: true` if you want the bot to be able to update the team or manage
+   members.
+
+## Understanding 404 vs 403 Errors
+
+- **404 "not found"** from a team tool usually means the bot is not a member of the team,
+  not that the team ID is wrong. Verify the bot has been added first.
+- **403 "forbidden"** from a write tool means the bot is a regular member but not a
+  moderator. Upgrade the bot's role in the team to moderator.
+
+## Typical Workflow
+
+```
+1. list_webex_teams()
+   → Empty? A human must add the bot to a team first (see above).
+
+2. list_webex_teams()
+   → Returns teams the bot belongs to. Pick a team_id.
+
+3. get_webex_team(team_id)
+   → Confirm team details.
+
+4. list_webex_team_memberships(team_id)
+   → See who is in the team. Check bot's isModerator value.
+
+5. add_webex_team_membership(team_id, person_email="...", is_moderator=False)
+   → Requires bot to be a moderator.
+
+6. delete_webex_team_membership(membership_id)
+   → Requires bot to be a moderator.
+```
+"""
+
+
 @mcp.resource("webex://config/current")
 def webex_current_config():
     """Current Webex bot configuration and status"""
@@ -1035,7 +1117,7 @@ def server_version():
             "streamable-http", "stdio",
             "error-handling", "versioning"
         ],
-        "tools_count": 35,
+        "tools_count": 34,
         "resources_count": 11,
         "prompts_count": 8,
         "breaking_changes": {
diff --git a/src/webex_bot_mcp/tools/__init__.py b/src/webex_bot_mcp/tools/__init__.py
@@ -27,7 +27,7 @@
 )
 
 from .teams import (
-    list_webex_teams, create_webex_team, get_webex_team,
+    list_webex_teams, get_webex_team,
     update_webex_team, delete_webex_team,
     list_webex_team_memberships, add_webex_team_membership,
     delete_webex_team_membership,
@@ -56,7 +56,7 @@
     # People functions
     'get_webex_me', 'list_webex_people',
     # Team functions
-    'list_webex_teams', 'create_webex_team', 'get_webex_team',
+    'list_webex_teams', 'get_webex_team',
     'update_webex_team', 'delete_webex_team',
     'list_webex_team_memberships', 'add_webex_team_membership',
     'delete_webex_team_membership',
diff --git a/src/webex_bot_mcp/tools/teams.py b/src/webex_bot_mcp/tools/teams.py
@@ -1,5 +1,16 @@
 """
 Webex Teams management tools.
+
+Bot-access model (verified against the Webex API):
+- Bots CANNOT create teams — POST /teams returns 401 for bot tokens regardless of scopes.
+  Team creation requires a human user token or an OAuth integration token.
+- Bots can only SEE teams they have been explicitly added to by a human user.
+  list_webex_teams returns an empty list until the bot is invited to at least one team.
+- Read operations (list, get, list memberships) work once the bot is a team member.
+- Write operations (update, delete team; add, delete members) require the bot to hold
+  the team moderator role within that team.
+- To add the bot to a team, a human user must do so via the Webex UI or a user/integration
+  token calling POST /team/memberships.
 """
 from typing import Optional, Dict, Any
 from .common import get_webex_api, create_error_response, create_success_response, WebexErrorCodes, WebexTokenMissingError
@@ -13,12 +24,18 @@ def _map_exception_to_error(e: Exception) -> Dict[str, Any]:
         return create_error_response(WebexErrorCodes.UNAUTHORIZED,
                                      "Invalid or expired bot token.")
     if 'not found' in error_str or '404' in error_str:
-        return create_error_response(WebexErrorCodes.NOT_FOUND,
-                                     "Team or membership not found.")
+        return create_error_response(
+            WebexErrorCodes.NOT_FOUND,
+            "Team or membership not found. Note: bots can only access teams they have "
+            "been added to — a human user must invite the bot to the team first."
+        )
     if 'forbidden' in error_str or '403' in error_str:
-        return create_error_response(WebexErrorCodes.FORBIDDEN,
-                                     "Bot lacks permission for this operation. "
-                                     "Ensure the bot has moderator privileges.")
+        return create_error_response(
+            WebexErrorCodes.FORBIDDEN,
+            "Bot lacks permission for this operation. Team write operations "
+            "(update, delete, add/remove members) require the bot to have the "
+            "moderator role within the team."
+        )
     if 'rate limit' in error_str or 'too many requests' in error_str:
         return create_error_response(WebexErrorCodes.RATE_LIMITED,
                                      "API rate limit exceeded. Please retry after delay.",
@@ -45,7 +62,7 @@ def _team_to_dict(t) -> Dict[str, Any]:
 
 
 def _team_membership_to_dict(m) -> Dict[str, Any]:
-    d: Dict[str, Any] = {
+    return {
         'id': m.id,
         'teamId': m.teamId,
         'personId': m.personId,
@@ -55,15 +72,18 @@ def _team_membership_to_dict(m) -> Dict[str, Any]:
         'isModerator': m.isModerator,
         'created': m.created,
     }
-    return d
 
 
 def list_webex_teams(
     display_name: Optional[str] = None,
     max_results: Optional[int] = None
 ) -> Dict[str, Any]:
     """
-    List Webex teams the authenticated bot belongs to.
+    List Webex teams the bot belongs to.
+
+    Bot access note: only teams the bot has been explicitly added to are returned.
+    If the list is empty, a human user must invite the bot to one or more teams first.
+    Teams cannot be created by a bot — use a user/integration token for that.
 
     Args:
         display_name: Filter teams by display name (optional)
@@ -88,38 +108,13 @@ def list_webex_teams(
         return _map_exception_to_error(e)
 
 
-def create_webex_team(
-    name: str,
-    description: Optional[str] = None
-) -> Dict[str, Any]:
-    """
-    Create a new Webex team.
-
-    Args:
-        name: Name of the team (required)
-        description: Description of the team (optional)
-
-    Returns:
-        Standardized response dictionary with success/error information
-    """
-    try:
-        params: Dict[str, Any] = {'name': name}
-        if description:
-            params['description'] = description
-
-        team = get_webex_api().teams.create(**params)
-        return create_success_response(
-            data={'team': _team_to_dict(team)},
-            metadata={'operation': 'create_team', 'parameters_used': params}
-        )
-    except Exception as e:
-        return _map_exception_to_error(e)
-
-
 def get_webex_team(team_id: str) -> Dict[str, Any]:
     """
     Get detailed information about a specific Webex team.
 
+    Bot access note: the bot must be a member of the team. If the team exists but the
+    bot has not been added to it, this will return a not-found error.
+
     Args:
         team_id: Team ID to get details for (required)
 
@@ -144,6 +139,9 @@ def update_webex_team(
     """
     Update an existing Webex team's name and/or description.
 
+    Bot access note: the bot must be a team moderator. If the bot is only a regular
+    member, this operation will fail with a forbidden error.
+
     Args:
         team_id: Team ID to update (required)
         name: New name for the team (optional)
@@ -182,6 +180,9 @@ def delete_webex_team(team_id: str) -> Dict[str, Any]:
     """
     Delete a Webex team.
 
+    Bot access note: the bot must be a team moderator. If the bot is only a regular
+    member, this operation will fail with a forbidden error.
+
     Args:
         team_id: Team ID to delete (required)
 
@@ -210,6 +211,9 @@ def list_webex_team_memberships(
     """
     List members of a Webex team.
 
+    Bot access note: the bot must be a member of the team. If the bot has not been
+    added to the team, this will return a not-found error.
+
     Args:
         team_id: Team ID to list members for (required)
         max_results: Maximum number of memberships to return (default 100, max 1000)
@@ -240,6 +244,9 @@ def add_webex_team_membership(
     """
     Add a person to a Webex team.
 
+    Bot access note: the bot must be a team moderator to add members. If the bot is
+    only a regular member, this operation will fail with a forbidden error.
+
     Args:
         team_id: Team ID to add person to (required)
         person_id: Person ID to add (use this OR person_email)
@@ -278,9 +285,12 @@ def delete_webex_team_membership(membership_id: str) -> Dict[str, Any]:
     """
     Remove a person from a Webex team by deleting their team membership.
 
+    Bot access note: the bot must be a team moderator to remove members. If the bot is
+    only a regular member, this operation will fail with a forbidden error.
+    Use list_webex_team_memberships to find the membership ID for a person.
+
     Args:
-        membership_id: Team membership ID to delete (required). Use
-                       list_webex_team_memberships to find the membership ID.
+        membership_id: Team membership ID to delete (required)
 
     Returns:
         Standardized response dictionary with success/error information
diff --git a/tests/test_teams.py b/tests/test_teams.py
