alexa-mcp 0.2.2 → 0.2.3

package/README.md

@@ -1,138 +1,136 @@
-# alexa-mcp
+# Alexa MCP
 
-MCP server and CLI for Alexa devices and smart home control via the unofficial Alexa API.
+[![npm version](https://badge.fury.io/js/alexa-mcp.svg)](https://www.npmjs.com/package/alexa-mcp)
+[![CI](https://github.com/m0nkmaster/alexa-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/m0nkmaster/alexa-mcp/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-## Requirements
-
-- Node.js 18+
-- Amazon Alexa account (amazon.com, amazon.co.uk, or amazon.de)
+**Control your Alexa devices and smart home from the command line or AI assistants.**
 
-## Setup
+MCP server and CLI for Alexa/Echo devices and smart home control via the unofficial Alexa API. Works with Claude Desktop, Cursor, VS Code, and other MCP-compatible tools.
 
-1. Install:
-   ```bash
-   npm install alexa-mcp          # local install
-   npm install -g alexa-mcp       # global install (adds alexa-mcp to PATH)
-   npx alexa-mcp auth             # run without installing
-   ```
+## Features
 
-2. Authenticate:
-   ```bash
-   alexa-mcp auth
-   ```
-   Opens a URL (tunnel or localhost) for you to log in to Amazon. Works locally or headless (remote server) — same behaviour either way. Uses cloudflared or localtunnel automatically; no account required.
+- 🎙️ **Voice & Media Control** - TTS, announcements, playback control
+- 💡 **Smart Home** - Control lights, plugs, and devices by name, pattern, or room group
+- 🤖 **Routines** - List and trigger Alexa routines
+- 🌍 **Multi-Region** - Supports US (amazon.com), UK (amazon.co.uk), and DE (amazon.de)
+- 🔌 **MCP Integration** - Use with Claude, Cursor, and other AI assistants
+- 🛠️ **CLI & Programmatic** - Command-line tool or Node.js library
 
-   Or headless:
-   ```bash
-   alexa-mcp auth --token "Atnr|..."
-   alexa-mcp auth --token-file /path/to/token.txt
-   alexa-mcp auth --domain amazon.com   # US account (default: amazon.co.uk)
-   alexa-mcp auth --no-save             # validate token without saving
-   ```
+## Quick Start
 
-3. Config stored in `~/.alexa-mcp/config.json`. Also reads `~/.alexa-cli/config.json` or `ALEXA_REFRESH_TOKEN`.
+### Installation
 
-### Environment variables
+```bash
+# Global install (recommended for CLI usage)
+npm install -g alexa-mcp
 
-| Variable | Description |
-|----------|-------------|
-| `ALEXA_REFRESH_TOKEN` | Refresh token; skips config file lookup |
-| `ALEXA_DOMAIN` | Amazon domain when using env token (default: `amazon.co.uk`; options: `amazon.com`, `amazon.de`) |
-| `ALEXA_DEBUG` | Set to any value to log API request/response details to stderr |
+# Or use without installing
+npx alexa-mcp auth
+```
 
-## CLI
+### Authentication
+**Interactive (browser-based):**
+```bash
+alexa-mcp auth
+```
+Opens a URL for you to log in to Amazon. Works locally or on remote servers using automatic tunneling (cloudflared or localtunnel).
 
+**Headless (token-based):**
 ```bash
-alexa-mcp auth                              # Interactive auth (browser / tunnel URL)
-alexa-mcp auth --token <token>             # Save token (headless)
-alexa-mcp auth --token-file <path>         # Read token from file
-alexa-mcp auth --domain amazon.com         # Specify Amazon domain (default: amazon.co.uk)
-alexa-mcp auth --no-save                   # Validate token without saving
-alexa-mcp auth status [--verify]           # Show auth status (--verify calls API)
-alexa-mcp auth logout                      # Remove credentials
-alexa-mcp devices                          # List Echo devices
-alexa-mcp devices --owners                 # Show device names and owner customer IDs (profile matching)
-alexa-mcp speak "Hello" -d Office          # Speak text on a specific device
-alexa-mcp announce "Dinner ready"          # Announce to all devices
-alexa-mcp command -d Office "play jazz"    # Voice command (no response returned)
-alexa-mcp groups                           # List room/space groups (Kitchen, Living room, etc.)
-alexa-mcp switch-group Kitchen off         # Turn off all lights in a group
-alexa-mcp switch-group Kitchen off --all   # Turn off ALL appliances in group (not just lights)
-alexa-mcp switch-room "kitchen lights" off # Turn off all devices matching name pattern
-alexa-mcp switch "Lounge light 2" off      # Turn off single device by name (direct control; -d for voice fallback)
-alexa-mcp appliances                       # List smart home devices (endpointId + friendlyName when available)
-alexa-mcp control <entityId> turnOn|turnOff|setBrightness [--brightness 50]
-alexa-mcp routines                         # List routines
-alexa-mcp run <automationId>               # Run a routine
-alexa-mcp now-playing -d Office            # Now-playing state (EU/UK)
-alexa-mcp media play|pause|resume|stop|next|previous -d Office  # Transport control (EU/UK)
+alexa-mcp auth --token "Atnr|..."
+alexa-mcp auth --token-file /path/to/token.txt
+alexa-mcp auth --domain amazon.com   # US account (default: amazon.co.uk)
 ```
 
-**Smart home:** For "all lights in group Kitchen", use `switch-group Kitchen off` (use `groups` to list group names). For pattern matching (e.g. "kitchen lights"), use `switch-room`. Both use direct control—avoids voice profile issues. `switch` is for a single device. Voice commands (`command`) do not return Alexa's response. `switch-group` targets only lights by default; add `--all` to include all appliances. `media` commands require active playback (`resume` re-starts paused playback). See [docs/API.md](docs/API.md).
+Configuration is stored in `~/.alexa-mcp/config.json`.
 
-### "Can't control – may need to switch user accounts"
+## Usage
 
-If the Echo says it can't control the device and suggests switching user accounts:
+### CLI Commands
 
-- **Who the CLI uses:** The CLI always acts as the **Amazon account you signed in with** when you last ran `alexa-mcp auth`. It does not use the Echo’s current profile. Changing the Echo’s profile in the Alexa app does **not** change which account the CLI uses.
-- **When you use profiles (e.g. Rob vs Emma):** You must run the CLI as the **same account that owns the smart home device**. So:
-  1. Run `alexa-mcp auth logout`.
-  2. Run `alexa-mcp auth` and sign in as the **household member who can say “Alexa, turn off Lounge Lamp”** on that Echo and have it work (the account that “owns” the lamp in the Alexa app).
-  3. Then run `alexa-mcp switch "Lounge Lamp" off -d "Lounge Echo"` again.
-- **Single account:** If there’s only one account, ensure the lamp is linked to that account in the Alexa app (Devices → Lights/Plugs).
+**Authentication:**
+```bash
+alexa-mcp auth                    # Interactive auth
+alexa-mcp auth status [--verify]  # Check auth status
+alexa-mcp auth logout             # Remove credentials
+```
 
-### Seeing which profile owns devices
+**Devices & Voice:**
+```bash
+alexa-mcp devices                      # List Echo devices
+alexa-mcp speak "Hello" -d Office      # Text-to-speech on device
+alexa-mcp announce "Dinner ready"      # Announce to all devices
+alexa-mcp command -d Office "play jazz" # Voice command
+```
 
-Each Echo and smart home device has a **deviceOwnerCustomerId** (Amazon’s internal account ID). The CLI uses the account you signed in with; that account has one or more such IDs. To see who owns what:
+**Smart Home:**
+```bash
+alexa-mcp groups                           # List room groups
+alexa-mcp appliances                       # List smart home devices
+alexa-mcp switch-group Kitchen off         # Turn off lights in room group
+alexa-mcp switch-room "kitchen lights" off # Turn off devices by pattern
+alexa-mcp switch "Lounge light 2" off      # Turn off single device
+alexa-mcp control <entityId> turnOn        # Direct device control
+```
 
-- **Echo devices:**  
-  `alexa-mcp devices --owners`  
-  Prints each device name and its `deviceOwnerCustomerId`. Use the same account for `alexa-mcp auth` as the one that owns the Echo you’re targeting.
+**Routines & Media:**
+```bash
+alexa-mcp routines                         # List routines
+alexa-mcp run <automationId>               # Run a routine
+alexa-mcp now-playing -d Office            # Show now-playing
+alexa-mcp media play|pause|next -d Office  # Media control
+```
 
-- **Smart home appliances:**  
-  `alexa-mcp appliances`  
-  The JSON includes `deviceOwnerCustomerId` per device (when the API provides it). Match this to the account you use for auth.
+**Tips:**
+- Use `switch-group` for "all lights in [room]" (e.g., `Kitchen`)
+- Use `switch-room` for pattern matching (e.g., `"kitchen lights"`)
+- Use `switch` for single devices by exact name
+- Direct control methods avoid voice profile issues
+- See [docs/API.md](docs/API.md) for full API reference
 
-- **Which account the CLI is using:**  
-  `alexa-mcp auth status --verify`  
-  Shows “Account (deviceOwnerCustomerId): …” for the current session. Control will work when this matches the owner of the Echo and the smart home device.
+### MCP Server Setup
 
-## MCP Server
+### Claude Desktop
 
-**Cursor** (`~/.cursor/mcp.json`) or **VS Code** (`.vscode/mcp.json`):
+Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS):
 
 ```json
 {
   "mcpServers": {
     "alexa": {
-      "command": "node",
-      "args": ["/path/to/alexa-mcp/dist/index.js"]
+      "command": "npx",
+      "args": ["alexa-mcp"]
     }
   }
 }
 ```
 
-**Claude Desktop** (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):
+### Cursor / VS Code
+
+Edit `~/.cursor/mcp.json` or `.vscode/mcp.json`:
 
 ```json
 {
   "mcpServers": {
     "alexa": {
-      "command": "node",
-      "args": ["/path/to/alexa-mcp/dist/index.js"]
+      "command": "npx",
+      "args": ["alexa-mcp"]
     }
   }
 }
 ```
 
-**With environment variable token** (no file-based config needed):
+### Using Environment Variables
+
+Pass token directly (no config file needed):
 
 ```json
 {
   "mcpServers": {
     "alexa": {
-      "command": "node",
-      "args": ["/path/to/alexa-mcp/dist/index.js"],
+      "command": "npx",
+      "args": ["alexa-mcp"],
       "env": {
         "ALEXA_REFRESH_TOKEN": "Atnr|...",
         "ALEXA_DOMAIN": "amazon.co.uk"
@@ -142,52 +140,99 @@ Each Echo and smart home device has a **deviceOwnerCustomerId** (Amazon’s inte
 }
 ```
 
-When installed locally, use the path to `node_modules/alexa-mcp/dist/index.js`. When installed globally (`npm install -g alexa-mcp`), use `npx alexa-mcp` as the command instead of `node`:
+### Local Installation
+
+If installed locally, use the full path:
 
 ```json
 {
   "mcpServers": {
     "alexa": {
-      "command": "npx",
-      "args": ["alexa-mcp"]
+      "command": "node",
+      "args": ["/path/to/node_modules/alexa-mcp/dist/index.js"]
     }
   }
 }
 ```
 
-### MCP Tools
-
-| Tool | Description |
-|------|-------------|
-| `alexa_list_devices` | List Echo devices |
-| `alexa_speak` | TTS on a device |
-| `alexa_announce` | Announce to all |
-| `alexa_command` | Voice command (no response returned; prefer direct control for smart home) |
-| `alexa_list_appliances` | List smart home devices (endpointId + friendlyName when available) |
-| `alexa_control_appliance` | turnOn/turnOff/setBrightness by entity/endpoint ID |
-| `alexa_control_by_group` | Turn on/off lights in a room group (e.g. "Kitchen") — **for "all lights in group X"** |
-| `alexa_control_group` | Alias for `alexa_control_by_group`; also supports `lightsOnly` toggle |
-| `alexa_control_by_pattern` | Turn on/off devices matching name pattern (e.g. "kitchen lights") |
-| `alexa_switch_by_name` | Turn single device on/off by friendly name |
-| `alexa_list_device_groups` | List room groups (Living room, Kitchen, etc.) |
-| `alexa_list_audio_groups` | List multi-room audio groups |
-| `alexa_list_routines` | List routines |
-| `alexa_run_routine` | Run a routine by automation ID |
-| `alexa_now_playing` | Now-playing state for a device (includes `taskSessionId`) |
-| `alexa_media_control` | play, pause, resume, stop, next, previous (EU/UK) |
-| `alexa_auth_status` | Check auth status (configured/valid/deviceCount) |
+### Available MCP Tools
+
+**Devices & Voice:**
+- `alexa_list_devices` - List Echo devices
+- `alexa_speak` - Text-to-speech on a device
+- `alexa_announce` - Announce to all devices
+- `alexa_command` - Send voice command
+
+**Smart Home:**
+- `alexa_list_appliances` - List smart home devices
+- `alexa_list_device_groups` - List room groups
+- `alexa_control_by_group` - Control all lights in a room group
+- `alexa_control_by_pattern` - Control devices by name pattern
+- `alexa_switch_by_name` - Control single device by name
+- `alexa_control_appliance` - Direct control by entity/endpoint ID
+- `alexa_get_brightness_by_name` - Get device brightness
+- `alexa_set_brightness_by_name` - Set device brightness
+
+**Routines & Media:**
+- `alexa_list_routines` - List Alexa routines
+- `alexa_run_routine` - Execute a routine
+- `alexa_list_audio_groups` - List multi-room audio groups
+- `alexa_now_playing` - Get now-playing state
+- `alexa_media_control` - Control playback (play/pause/next/etc.)
+- `alexa_get_volume` / `alexa_set_volume` - Volume control
+
+**Authentication:**
+- `alexa_auth_status` - Check authentication status
+
+## Troubleshooting
+
+### "Can't control – may need to switch user accounts"
+
+This error occurs when the Amazon account you authenticated with doesn't own the device.
+
+**Solution:**
+1. Run `alexa-mcp auth logout`
+2. Run `alexa-mcp auth` and sign in with the account that owns the device
+3. Verify with `alexa-mcp auth status --verify`
+
+**Check device ownership:**
+```bash
+alexa-mcp devices --owners    # Show Echo device owners
+alexa-mcp appliances          # Show smart home device owners
+```
+
+The `deviceOwnerCustomerId` must match between your authenticated account and the device.
 
 ## Development
 
 ```bash
-npm install
-npm run build
-npm test
-npm run test:integration  # Requires ALEXA_REFRESH_TOKEN
+npm install              # Install dependencies
+npm run build           # Compile TypeScript
+npm test                # Run unit tests
+npm run test:integration # Run integration tests (requires auth)
+npm run lint            # Check code style
+npm run lint:fix        # Fix code style issues
 ```
 
-## API Reference
+## Documentation
+
+- **[API Reference](docs/API.md)** - Complete unofficial Alexa API documentation
+- **[Device Capabilities](docs/DEVICE-CAPABILITIES.md)** - Device capability reference
+- **[User Stories](docs/USER-STORIES.md)** - Usage examples and patterns
+
+## Requirements
+
+- Node.js 18+
+- Amazon Alexa account (amazon.com, amazon.co.uk, or amazon.de)
+
+## License
+
+MIT - See LICENSE file for details
+
+## Contributing
+
+Contributions welcome! Please follow [conventional commits](https://www.conventionalcommits.org/) format.
 
-The single authoritative API reference is **[docs/API.md](docs/API.md)** — region base URLs, authentication, all endpoints (devices, routines, smart home, behaviors, alarms, media), request/response bodies, and headers.
+## Acknowledgments
 
-**API usage:** All supported regions use the **app API** (eu-api-alexa for UK/EU, na-api-alexa for US): devices-v2, routinesandgroups, behaviors/preview, smarthome/v2/endpoints, layouts, and GraphQL for smart home control.
+Built on the unofficial Alexa API. Uses [alexa-cookie2](https://github.com/Apollon77/alexa-cookie) for authentication.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "alexa-mcp",
-  "version": "0.2.2",
+  "version": "0.2.3",
   "description": "MCP server and CLI for Alexa devices and smart home control",
   "type": "module",
   "main": "dist/index.js",
@@ -37,6 +37,7 @@
     "@modelcontextprotocol/sdk": "^1.0.0",
     "alexa-cookie2": "^5.0.3",
     "commander": "^12.0.0",
+    "patch-package": "^8.0.1",
     "undici": "^6.19.8",
     "zod": "^3.23.0"
   },
@@ -45,7 +46,6 @@
     "@types/eslint__js": "^8.42.3",
     "@types/node": "^22.0.0",
     "eslint": "^9.39.4",
-    "patch-package": "^8.0.1",
     "tsx": "^4.19.0",
     "typescript": "^5.6.0",
     "typescript-eslint": "^8.57.0",