Merge pull request #2 from mycollablab/dev

Add MCP server: read/write tools, HTTP transport, DXT extension, skill bundle, Claude Desktop docs

Author: edumansky

.gitignore

@@ -3,6 +3,8 @@ webex
 webex-cli
 *.exe
 dist/
+webex-mcp.dxt
+webex.skill
 
 # Codegen intermediates
 codegen/api_outline.json
@@ -24,3 +26,4 @@ Thumbs.db
 *.swp
 *.swo
 /docs/wxcc-search
+.webex-cli/

CLAUDE_DESKTOP.md

@@ -0,0 +1,146 @@
+# Webex MCP — Claude Desktop Setup
+
+This guide covers installing and using the Webex MCP server with **Claude Desktop** specifically. For Claude Code (CLI), see the [main README](README.md).
+
+## Requirements
+
+- **Claude Desktop** — latest version
+- **Webex CLI** — installed and authenticated on each user's machine
+  ```bash
+  # Install
+  curl -fsSL https://raw.githubusercontent.com/Cloverhound/webex-cli/main/install.sh | sh
+
+  # Authenticate (opens browser for OAuth)
+  webex login
+  ```
+- **Platform** — macOS, Windows, or Linux
+
+The MCP server runs **locally** using stdio transport — no network port is opened and no shared server is required. Each user's own Webex credentials are used automatically.
+
+---
+
+## Installation
+
+### Option 1 — Admin Portal (Team Distribution)
+
+Admins can distribute the extension to the entire team without each user needing to install it manually.
+
+1. Build the extension package:
+   ```bash
+   git clone https://github.com/Cloverhound/webex-cli.git
+   cd webex-cli
+   make extension   # produces webex-mcp.dxt
+   ```
+2. Upload `webex-mcp.dxt` to the [Claude admin portal](https://console.anthropic.com) under **Extensions**
+3. Enable it for your team or org
+4. Each team member must still install the Webex CLI and run `webex login` on their own machine
+
+### Option 2 — Individual Install (Double-click)
+
+Download or build `webex-mcp.dxt` and double-click it in Finder (macOS) or Explorer (Windows). Claude Desktop installs the extension automatically.
+
+### Option 3 — HTTP Transport (Manual Config)
+
+If you prefer HTTP transport instead of the DXT extension:
+
+1. Start the MCP server:
+   ```bash
+   webex mcp serve --http          # binds to 127.0.0.1:47890
+   webex mcp serve --http --http-addr 127.0.0.1:9000   # custom port
+   ```
+2. Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS):
+   ```json
+   {
+     "mcpServers": {
+       "webex": { "url": "http://localhost:47890/mcp" }
+     }
+   }
+   ```
+3. Restart Claude Desktop
+4. Stop the server when done: `webex mcp stop`
+
+The HTTP server only binds to loopback (`127.x.x.x`) and cannot be exposed on public interfaces.
+
+---
+
+## Tools
+
+The extension exposes four tools:
+
+| Tool | Maps to | Auto-approvable | Description |
+|---|---|---|---|
+| `webex_read` | GET | Yes | List, get, download, export, search — read-only operations |
+| `webex_write` | POST / PUT / PATCH / DELETE | No | Create, update, delete — always prompts for confirmation |
+| `webex_help` | — | Yes | Get help text and flag listings for any command |
+| `webex_usage` | — | Yes | View recent MCP command history with timing and status |
+
+`webex_read`, `webex_help`, and `webex_usage` are safe to auto-approve. `webex_write` is intentionally kept separate so write operations always require explicit user confirmation.
+
+---
+
+## Adding the Skill for Better Results
+
+The DXT extension provides Claude Desktop with the **tools** to execute Webex commands, but not the **knowledge** of how to use them optimally. Without the skill, Claude will use `webex_help` to discover commands on demand — functional, but slower and more prone to mistakes on edge cases like CC `--orgid` handling, pagination, and subcommand naming exceptions.
+
+**The fix:** Use a Claude Desktop **Project** and paste the skill content into the Project instructions. This is the Claude Desktop equivalent of the Claude Code skill system.
+
+### Setup
+
+1. In Claude Desktop, create a new **Project** (e.g., "Webex Admin")
+2. Open **Project Instructions**
+3. Paste the contents of [`skill/SKILL.md`](skill/SKILL.md) — this covers auth, command structure, global flags, and best practices
+4. Optionally add the relevant sub-skill files for the areas your team uses most:
+
+| Area | File | When to include |
+|---|---|---|
+| Admin | [`skill/admin/SKILL.md`](skill/admin/SKILL.md) | Managing people, licenses, orgs |
+| Calling | [`skill/calling/SKILL.md`](skill/calling/SKILL.md) | Locations, queues, devices, recordings |
+| Contact Center | [`skill/cc/SKILL.md`](skill/cc/SKILL.md) | Sites, flows, agents, entry points |
+| Devices | [`skill/device/SKILL.md`](skill/device/SKILL.md) | Device configs, workspaces, xAPI |
+| Meetings | [`skill/meetings/SKILL.md`](skill/meetings/SKILL.md) | Recordings, transcripts, scheduling |
+| Messaging | [`skill/messaging/SKILL.md`](skill/messaging/SKILL.md) | Rooms, messages, teams |
+
+With the skill in Project instructions, Claude will know upfront about `--paginate`, RSQL filters, the CC `--orgid` auto-population, download patterns, and other behaviours that would otherwise require multiple `webex_help` round-trips to discover.
+
+---
+
+## Authentication
+
+The extension uses the same credentials as the Webex CLI — run `webex login` once and the MCP server picks them up automatically. Token refresh is handled transparently.
+
+```bash
+webex auth status          # confirm you are logged in
+webex auth list            # list all stored users
+webex auth switch <email>  # change default user
+webex auth set-org <orgId> # set a persistent org override (partner admins)
+```
+
+Multiple Webex accounts are supported. Switch the default user with `webex auth switch` and restart Claude Desktop (or `webex mcp stop` + re-open for HTTP transport).
+
+---
+
+## Troubleshooting
+
+**"webex: command not found"**
+The install script adds `~/.local/bin` to PATH. If Claude Desktop launches before your shell profile is sourced, the binary may not be found. Fix by setting an absolute path in the extension config or ensuring `~/.local/bin` is in your system PATH (not just shell PATH).
+
+For the HTTP transport option, edit `claude_desktop_config.json` to use an absolute path:
+```json
+{
+  "mcpServers": {
+    "webex": {
+      "command": "/Users/yourname/.local/bin/webex",
+      "args": ["mcp", "serve"]
+    }
+  }
+}
+```
+
+**"No running MCP server found" (HTTP mode)**
+Run `webex mcp serve --http` before opening Claude Desktop, or switch to the DXT extension which starts the server automatically via stdio.
+
+**Not authenticated**
+Run `webex login` in a terminal, then retry. Tokens are stored in the OS keyring and shared with the MCP server automatically.
+
+**Wrong Webex org**
+Use `webex auth set-org <orgId>` to set a persistent org override, or pass `--organization <orgId>` on individual commands via the `flags` parameter.

Makefile

@@ -1,4 +1,4 @@
-.PHONY: build download codegen refresh check clean
+.PHONY: build download codegen refresh check clean extension skill
 
 build:
 	go build -o webex .
@@ -9,12 +9,27 @@ download:
 codegen:
 	cd codegen && python3 extract_api_spec.py
 	cd codegen && python3 generate_cli.py
+	cd codegen && python3 generate_skills.py
 
 refresh: download codegen build
 
 check: build
 	go vet ./...
 
+extension: build
+	cd extension && zip -r ../webex-mcp.dxt manifest.json icon.png
+	@echo "Built webex-mcp.dxt"
+
+skill:
+	@python3 -c "\
+import zipfile; \
+z = zipfile.ZipFile('webex.skill', 'w', zipfile.ZIP_DEFLATED); \
+z.write('skill/SKILL.md', 'webex-cli/SKILL.md'); \
+resources = ['admin','calling','cc','device','meetings','messaging']; \
+[z.write(f'skill/{r}/SKILL.md', f'webex-cli/resources/{r}.md') for r in resources]; \
+z.close()"
+	@echo "Built webex.skill"
+
 clean:
-	rm -f webex webex-cli
+	rm -f webex webex-cli webex-mcp.dxt webex.skill
 	rm -f codegen/api_spec.json codegen/api_outline.json

README.md

@@ -27,12 +27,12 @@ webex login
 # Webex Calling
 webex calling people list --max 10
 webex calling locations list
-webex calling call-queue list
+webex calling call-queue list-cxe
 
 # Contact Center
 webex cc site list
 webex cc team list
-webex cc agents list
+webex cc contact-service-queue list
 webex cc entry-point list
 
 # Admin
@@ -91,23 +91,23 @@ All upload commands support `--dry-run` to preview the request without sending i
 
 ### Calling (`webex calling`)
 
-45 resource groups including auto-attendants, call queues, hunt groups, call controls, call routing (dial plans, route groups, trunks), DECT devices, emergency services, locations, numbers, paging groups, people, workspaces, voicemail, recordings, and more.
+47 resource groups including auto-attendants, call queues (CxE), hunt groups, call controls, call routing (dial plans, route groups, trunks), DECT devices, emergency services, locations, numbers, paging groups, people, workspaces, voicemail, converged recordings, and more.
 
 ### Contact Center (`webex cc`)
 
-54 resource groups including agents, queues, entry points, flows, skills, desktop layouts, campaigns, callbacks, realtime stats, AI assistant, journey analytics, subscriptions, and more.
+54 resource groups including sites, queues, entry points, teams, flows, skills, desktop layouts, global variables, business hours, auxiliary codes, campaigns, callbacks, realtime stats, AI assistant, journey analytics, subscriptions, and more.
 
 ### Admin (`webex admin`)
 
 39 resource groups including people, licenses, organizations, roles, groups, events, reports, recordings, SCIM 2.0 (users/groups/schemas), hybrid clusters/connectors, security audit, service apps, and more.
 
 ### Devices (`webex device`)
 
-9 resource groups including devices, device configurations, workspaces, workspace locations/metrics/personalization, hot-desking, and xAPI (execute commands, query status).
+10 resource groups including devices, device configurations, workspaces, workspace locations/metrics/personalization, hot-desking, and xAPI (execute commands, query status).
 
 ### Meetings (`webex meetings`)
 
-22 resource groups including meetings, participants, recordings, transcripts, summaries, polls, Q&A, chats, invitees, preferences, session types, tracking codes, video mesh, and more.
+23 resource groups including meetings, participants, recordings, transcripts, summaries, polls, Q&A, chats, invitees, preferences, session types, tracking codes, video mesh, and more.
 
 ### Messaging (`webex messaging`)
 
@@ -166,7 +166,7 @@ Control output with `--output`:
 
 ```bash
 webex calling people list --output table
-webex cc agents list --output csv > agents.csv
+webex cc users list --output csv > users.csv
 ```
 
 ## Global Flags
@@ -192,19 +192,95 @@ webex config get client-id               # View current value
 
 Config is stored in `~/.webex-cli/config.json`.
 
+## MCP Server
+
+> **Claude Desktop users:** see [CLAUDE_DESKTOP.md](CLAUDE_DESKTOP.md) for installation, DXT extension setup, and skill configuration specific to Claude Desktop.
+
+
+`webex mcp serve` starts a [Model Context Protocol](https://modelcontextprotocol.io/) server over stdio, letting AI clients query and manage your Webex environment directly.
+
+```bash
+# Register with Claude Code
+claude mcp add webex -- webex mcp serve
+
+# Or register with a specific binary path
+claude mcp add webex -- /path/to/webex mcp serve
+```
+
+The server exposes 4 tools:
+
+| Tool | API methods | Description |
+|---|---|---|
+| `webex_read` | GET | Execute a read-only CLI command (list, get, download, export, search) |
+| `webex_write` | POST / PUT / PATCH / DELETE | Execute a command that creates, updates, or deletes a resource |
+| `webex_help` | — | Get help text for any command or command group |
+| `webex_usage` | — | Query the MCP usage log (recent commands, timing, status) |
+
+Read and write operations are split into separate tools so that `webex_read` can be auto-approved in permissions while `webex_write` always prompts for confirmation.
+
+And 2 MCP resources:
+
+| Resource | Description |
+|---|---|
+| `webex://commands` | JSON array of all available CLI commands with short descriptions |
+| `webex://usage` | Last 50 raw lines of the usage log |
+
+Rather than exposing fixed per-API tools, the dispatcher pattern lets AI clients invoke the full CLI surface via `webex_run` — the command tree expands automatically as new commands are added.
+
+Auth is shared with the CLI — run `webex login` once and the MCP server uses the same stored credentials. Token refresh is handled automatically.
+
+### Usage Log
+
+All `webex_run` invocations are logged to `~/.webex-mcp/usage.log` (JSONL). Configure with serve flags:
+
+```bash
+webex mcp serve --log-path /tmp/webex.log --log-max-size 10485760 --log-max-files 5
+```
+
+| Flag | Default | Description |
+|---|---|---|
+| `--log-path` | `~/.webex-mcp/usage.log` | Log file path |
+| `--log-max-size` | `5242880` (5 MB) | Max file size before rotation |
+| `--log-max-files` | `3` | Number of rotated files to keep |
+
+### Team Distribution via Claude Admin Portal
+
+Package the extension once and upload it to the Claude admin console — Claude Desktop installs it automatically for all team members. Each user's local `webex` installation and credentials are used; no shared server is needed.
+
+```bash
+make extension   # produces webex-mcp.dxt
+```
+
+1. Upload `webex-mcp.dxt` to the Claude admin portal under **Extensions**
+2. Enable it for your team or org
+3. Team members must have `webex` installed and authenticated (`webex login`)
+
+Alternatively, team members can install the extension locally by double-clicking `webex-mcp.dxt` in Finder.
+
 ## Coding Agent Skill
 
-A skill file is included in `skill/SKILL.md` that enables AI coding agents (Claude Code, Claude Cowork, OpenAI Codex, Cursor) to query and manage your Webex environment.
+A set of skill files in `skill/` enables AI coding agents (Claude Code, Claude Cowork, OpenAI Codex, Cursor) to use the CLI via natural language. The root skill (`skill/SKILL.md`) covers auth, command structure, and global flags. Six per-area sub-skills provide comprehensive flag and body-schema documentation for each CLI area:
+
+| Area | Sub-skill |
+|---|---|
+| Admin | `skill/admin/SKILL.md` |
+| Calling | `skill/calling/SKILL.md` |
+| Contact Center | `skill/cc/SKILL.md` |
+| Devices | `skill/device/SKILL.md` |
+| Meetings | `skill/meetings/SKILL.md` |
+| Messaging | `skill/messaging/SKILL.md` |
+
+Each sub-skill also contains an auto-generated **Command Reference** section (updated by `make codegen`) that lists every command and its flags, keeping documentation in sync with the API as Postman collections change.
 
-The installer and `webex post-install` command will offer to install the skill automatically. Skills are also kept up to date when you run `webex update`.
+`webex post-install` offers to install all skill files automatically. They are also updated by `webex update`.
 
 See the [docs](https://cloverhound.github.io/webex-cli/agent-skill/) for manual setup instructions.
 
 ## Development
 
 See [CLAUDE.md](CLAUDE.md) for project structure and development workflow.
 
-Commands in `cmd/calling/` and `cmd/cc/` are **generated** from Postman collections — do not edit by hand. See the [code generation pipeline](CLAUDE.md#code-generation-pipeline) for details.
+Commands in `cmd/calling/`, `cmd/cc/`, and the other area packages are **generated** from Postman collections — do not edit by hand. Run `make refresh` to re-download collections, regenerate Go files, update skill documentation, and rebuild. See the [code generation pipeline](CLAUDE.md#code-generation-pipeline) for details.
 
 ## License