Fix org-contacts UUID format and cross-platform skill improvements

codegen/generate_cli.py

@@ -222,11 +222,14 @@ def generate_command(ep, group_var, base_url_const, is_calling):
     original_name = ep.get('original_name', cmd_name)
     has_from = any(p['name'] == 'from' for p in query_params)
 
-    # Normalize orgId → orgid for CC commands so auto-populate in root.go works
-    # consistently (CC APIs use UUID format via the --orgid flag path).
+    # Normalize orgId → orgid so auto-populate in root.go resolves to UUID format.
+    # Applies to CC commands (is_calling=False) and to any endpoint under
+    # /contacts/organizations/ which explicitly requires UUID despite being in a
+    # non-CC collection (Postman note: "orgId used in path are the org UUIDs").
     # For path params, rename both the flag and the param key (path uses {orgid}).
     # For query params, only rename the flag; keep the original API key (orgId).
-    if not is_calling:
+    needs_uuid_orgid = not is_calling or '/contacts/organizations/' in path
+    if needs_uuid_orgid:
         path = path.replace('{orgId}', '{orgid}')
         for p in path_params:
             if p['name'] == 'orgId':

skill/SKILL.md

@@ -76,6 +76,20 @@ webex cc site list --orgid="Y2lzY29zcGFyazovL3Vz..."  # Base64 — auto-decoded
 
 If you need to override the org, use `--organization <orgId>` (global flag) which feeds into `--orgid` automatically. Both base64 and UUID formats are accepted.
 
+## OrgID Format Troubleshooting
+
+**General rule:** CC commands (`webex cc ...`) use UUID format; all other commands (`webex admin`, `webex calling`, etc.) use base64 format. The CLI normalizes automatically, but if an API call returns a 400 or 404 with an org-related error, the format passed may be wrong for that endpoint.
+
+**If you get an org ID error, try the other format:**
+```bash
+# Got a 400 on a CC command? Make sure the value decodes to a plain UUID:
+webex cc site list --orgid="4ebc486d-ff5f-4abc-9d44-1234567890ab"   # UUID
+# Got a 400 on an admin/calling command? Make sure it's base64:
+webex admin people list --organization="Y2lzY29zcGFyazovL3Vz..."    # Base64
+```
+
+You can inspect what the CLI resolved to by running `webex auth status` — the org ID shown there is the base64 form. Strip the trailing `=` padding issues or swap formats if calls are failing with 400/404 on org-scoped endpoints.
+
 ## CC Subcommand Names
 
 Most CC resources use a consistent `list` subcommand. A few exceptions remain:
@@ -94,21 +108,83 @@ All other CC resources (site, team, users, global-variables, business-hour, audi
 
 1. **Always redirect stderr separately** when capturing JSON output:
    ```bash
-   webex cc site list --orgid="$ORG" > /tmp/result.json 2>/tmp/error.log
+   # Mac/Linux/WSL — $TMPDIR is set on macOS; falls back to /tmp on Linux
+   webex cc site list --orgid="$ORG" > "${TMPDIR:-/tmp}/result.json" 2>"${TMPDIR:-/tmp}/error.log"
+   # Windows PowerShell
+   # webex cc site list --orgid="$ORG" > "$env:TEMP\result.json" 2> "$env:TEMP\error.log"
    ```
 
 2. **Use `--orgid=VALUE` syntax** (with `=`) for CC commands to avoid shell quoting issues. Do NOT use `--orgid "$VAR"` with a space — use `--orgid="$VAR"`.
 
 3. **Write output to temp files first**, then read/analyze. Do NOT pipe webex output directly into python or jq in a single shell command — complex pipes can cause issues with the binary output.
+   - Mac/Linux/WSL: use `"${TMPDIR:-/tmp}/filename.json"`
+   - Windows PowerShell: use `"$env:TEMP\filename.json"`
 
 4. **Check `--help` before guessing** subcommand names:
    ```bash
    webex <api> <resource> --help
    ```
 
-## Admin API Examples
+## Using as an MCP Server
+
+The CLI includes a built-in MCP server exposing four tools:
+
+| Tool | API methods | When to use |
+|---|---|---|
+| `webex_read` | GET | List, get, download, export — auto-approvable |
+| `webex_write` | POST / PUT / PATCH / DELETE | Create, update, delete — prompts for confirmation |
+| `webex_help` | — | Discover commands and flags |
+| `webex_usage` | — | View recent MCP command history |
+
+**Claude Code / stdio clients** — no server process needed:
+```bash
+claude mcp add webex -- webex mcp serve
+```
+
+**Claude Desktop / HTTP clients** — start the server first, then point the config at it:
+```bash
+# Start server (loopback only, port 47890)
+webex mcp serve --http
+```
+Add to your Claude Desktop config file, then restart Claude Desktop:
+
+| Platform | Config path |
+|---|---|
+| macOS | `~/Library/Application Support/Claude/claude_desktop_config.json` |
+| Linux | `~/.config/Claude/claude_desktop_config.json` |
+| Windows | `%APPDATA%\Claude\claude_desktop_config.json` |
+
+```json
+{
+  "mcpServers": {
+    "webex": { "url": "http://localhost:47890/mcp" }
+  }
+}
+```
+Use `--http-addr 127.0.0.1:<port>` to change the port.
+Only loopback addresses (127.x.x.x / ::1) are accepted — the server cannot bind to public interfaces.
+
+## Sub-Skills
+
+For detailed flags, body schemas, and usage examples, Read the sub-skill file before working in that area.
+
+Sub-skills are installed alongside this file. Resolve the base path for your platform:
+
+| Platform | Skills base path |
+|---|---|
+| macOS / Linux | `~/.claude/skills/webex-cli/` |
+| Windows | `%USERPROFILE%\.claude\skills\webex-cli\` |
+
+| Area | Sub-path |
+|---|---|
+| Admin | `admin/SKILL.md` |
+| Calling | `calling/SKILL.md` |
+| Contact Center | `cc/SKILL.md` |
+| Devices | `device/SKILL.md` |
+| Meetings | `meetings/SKILL.md` |
+| Messaging | `messaging/SKILL.md` |
 
-Admin commands manage people, organizations, licenses, roles, and other administrative resources:
+## Quick Reference
 
 ```bash
 # List people in the org
@@ -386,8 +462,8 @@ webex admin people list --output=table
 # Raw JSON (no formatting)
 webex admin people list --output=raw
 
-# Save to file for processing
-webex admin people list > /tmp/people.json
+# Save to file for processing (Mac/Linux/WSL)
+webex admin people list > "${TMPDIR:-/tmp}/people.json"
 ```
 
 ## Converged Recordings: Admin vs Non-Admin Endpoints