{"_id":"@bobmatnyc/mcp-smartthings","_rev":"3-1da2083fe178639f454c271af0a6fbed","name":"@bobmatnyc/mcp-smartthings","dist-tags":{"latest":"1.0.3"},"versions":{"1.0.1":{"name":"@bobmatnyc/mcp-smartthings","version":"1.0.1","keywords":["mcp","smartthings","home-automation","model-context-protocol","llm"],"author":{"name":"masa"},"license":"MIT","_id":"@bobmatnyc/mcp-smartthings@1.0.1","maintainers":[{"name":"bobmatnyc","email":"bob@matsuoka.com"}],"bin":{"mcp-smartthings":"dist/index.js"},"dist":{"shasum":"f8bd1b4dec500265bd8d33eedc3d219e3b41b7e1","tarball":"https://registry.npmjs.org/@bobmatnyc/mcp-smartthings/-/mcp-smartthings-1.0.1.tgz","fileCount":76,"integrity":"sha512-NTIiV2W3DTdDk0tuk4PAk/cotFbHyVQz9hgGHwmb7cBYMNaOnKTvcScMm7Qi/czSneON/aC7RoIyQZc1X8aOGg==","signatures":[{"sig":"MEQCIFxZP0sowxlLv0UwaMnAxhZ2RawRWJ0yR1Dsafy/cvDpAiBZFbsW1ihwopCjUYmPLVEc7TwIDs362V2zo74kW7oxIQ==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":259733},"main":"./dist/index.js","type":"module","types":"./dist/index.d.ts","engines":{"node":">=18.0.0"},"gitHead":"27f55a59133ce603a7b29a9f5f15cffe55802d5d","scripts":{"dev":"tsx watch src/index.ts","chat":"pnpm run build && node dist/cli/chat.js","lint":"eslint src --ext .ts","test":"vitest run","build":"tsc","start":"node dist/index.js","format":"prettier --write \"src/**/*.ts\"","release":"standard-version","version":"pnpm build","chat:dev":"tsx src/cli/chat.ts","lint:fix":"eslint src --ext .ts --fix","test:unit":"vitest run tests/unit","typecheck":"tsc --noEmit","preversion":"pnpm test || true","test:watch":"vitest","postversion":"git push --follow-tags origin main","format:check":"prettier --check \"src/**/*.ts\"","test-gateway":"tsx tools/mcp-test-gateway.ts","release:major":"standard-version --release-as major","release:minor":"standard-version --release-as minor","release:patch":"standard-version --release-as patch","test:coverage":"vitest run --coverage","test:inspector":"pnpx @modelcontextprotocol/inspector node dist/index.js","test:integration":"vitest run tests/integration"},"_npmUser":{"name":"bobmatnyc","email":"bob@matsuoka.com"},"_npmVersion":"11.6.2","description":"Model Context Protocol (MCP) server for SmartThings home automation","directories":{},"_nodeVersion":"24.9.0","dependencies":{"zod":"^3.25.0","chalk":"^5.3.0","dotenv":"^16.4.5","openai":"^4.20.0","express":"^4.19.2","winston":"^3.15.0","mustache":"^4.2.0","@types/mustache":"^4.2.6","@smartthings/core-sdk":"^8.0.0","@modelcontextprotocol/sdk":"^1.22.0"},"_hasShrinkwrap":false,"packageManager":"pnpm@10.18.3","devDependencies":{"tsx":"^4.19.0","eslint":"^8.57.0","vitest":"^3.0.0","prettier":"^3.3.0","typescript":"^5.6.0","@types/node":"^22.0.0","@types/express":"^4.17.21","standard-version":"^9.5.0","@vitest/coverage-v8":"^3.0.0","eslint-config-prettier":"^9.1.0","eslint-plugin-prettier":"^5.2.0","@typescript-eslint/parser":"^8.0.0","@typescript-eslint/eslint-plugin":"^8.0.0"},"_npmOperationalInternal":{"tmp":"tmp/mcp-smartthings_1.0.1_1764125900633_0.12112494136206742","host":"s3://npm-registry-packages-npm-production"}},"1.0.2":{"name":"@bobmatnyc/mcp-smartthings","version":"1.0.2","keywords":["mcp","smartthings","home-automation","model-context-protocol","llm"],"author":{"name":"masa"},"license":"MIT","_id":"@bobmatnyc/mcp-smartthings@1.0.2","maintainers":[{"name":"bobmatnyc","email":"bob@matsuoka.com"}],"bin":{"mcp-smartthings":"dist/index.js"},"dist":{"shasum":"ff310c5bf3fc4ac4bb569d8e29453045725433af","tarball":"https://registry.npmjs.org/@bobmatnyc/mcp-smartthings/-/mcp-smartthings-1.0.2.tgz","fileCount":97,"integrity":"sha512-xckHRlNO9MSu9p3ZOfb0dGMlhwRO5r44DEch5av00GmQdjbNqNB9Wmb4V6ZWvPP34kbQrczyyO7eEkVEU5cwIQ==","signatures":[{"sig":"MEQCIDcW5eTzmHBazgiPRCybZGJG8mf753noFpUjW3/5+3cuAiAhsrh0AcYQKiYF9FDRTelCCX4UX0fF722ICHbf7vvU3w==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":376519},"main":"./dist/index.js","type":"module","types":"./dist/index.d.ts","engines":{"node":">=18.0.0"},"gitHead":"e7a84c27ef399e297fa50193761442f3fad99202","scripts":{"dev":"tsx watch src/index.ts","chat":"pnpm run build && node dist/cli/chat.js","lint":"eslint src --ext .ts","test":"vitest run","build":"tsc","start":"node dist/index.js","format":"prettier --write \"src/**/*.ts\"","release":"standard-version","version":"pnpm build","chat:dev":"tsx src/cli/chat.ts","lint:fix":"eslint src --ext .ts --fix","test:unit":"vitest run tests/unit","typecheck":"tsc --noEmit","preversion":"pnpm test || true","test:watch":"vitest","postversion":"git push --follow-tags origin main","alexa-server":"pnpm run build && node dist/cli/alexa-server.js","format:check":"prettier --check \"src/**/*.ts\"","test-gateway":"tsx tools/mcp-test-gateway.ts","release:major":"standard-version --release-as major","release:minor":"standard-version --release-as minor","release:patch":"standard-version --release-as patch","test:coverage":"vitest run --coverage","test:inspector":"pnpx @modelcontextprotocol/inspector node dist/index.js","alexa-server:dev":"tsx src/cli/alexa-server.ts","test:integration":"vitest run tests/integration"},"_npmUser":{"name":"bobmatnyc","email":"bob@matsuoka.com"},"_npmVersion":"11.6.2","description":"Model Context Protocol (MCP) server for SmartThings home automation","directories":{},"_nodeVersion":"24.9.0","dependencies":{"zod":"^3.25.0","chalk":"^5.3.0","dotenv":"^16.4.5","openai":"^4.20.0","express":"^4.19.2","fastify":"^5.6.2","winston":"^3.15.0","mustache":"^4.2.0","@fastify/cors":"^11.1.0","alexa-verifier":"^4.0.0","@fastify/helmet":"^13.0.2","@types/mustache":"^4.2.6","@smartthings/core-sdk":"^8.0.0","@modelcontextprotocol/sdk":"^1.22.0"},"_hasShrinkwrap":false,"packageManager":"pnpm@10.18.3","devDependencies":{"tsx":"^4.19.0","eslint":"^8.57.0","vitest":"^3.0.0","prettier":"^3.3.0","typescript":"^5.6.0","@types/node":"^22.0.0","@types/express":"^4.17.21","standard-version":"^9.5.0","@vitest/coverage-v8":"^3.0.0","eslint-config-prettier":"^9.1.0","eslint-plugin-prettier":"^5.2.0","@typescript-eslint/parser":"^8.0.0","@typescript-eslint/eslint-plugin":"^8.0.0"},"_npmOperationalInternal":{"tmp":"tmp/mcp-smartthings_1.0.2_1764182236028_0.37250011496717295","host":"s3://npm-registry-packages-npm-production"}},"1.0.3":{"name":"@bobmatnyc/mcp-smartthings","version":"1.0.3","description":"Model Context Protocol (MCP) server for SmartThings home automation","type":"module","main":"./dist/index.js","types":"./dist/index.d.ts","bin":{"mcp-smartthings":"dist/index.js"},"scripts":{"dev":"tsx watch src/index.ts","build":"tsc","start":"node dist/index.js","chat":"pnpm run build && node dist/cli/chat.js","chat:dev":"tsx src/cli/chat.ts","alexa-server":"pnpm run build && node dist/cli/alexa-server.js","alexa-server:dev":"tsx src/cli/alexa-server.ts","test":"vitest run","test:watch":"vitest","test:coverage":"vitest run --coverage","test:unit":"vitest run tests/unit","test:integration":"vitest run tests/integration","test-gateway":"tsx tools/mcp-test-gateway.ts","test:inspector":"pnpx @modelcontextprotocol/inspector node dist/index.js","lint":"eslint src --ext .ts","lint:fix":"eslint src --ext .ts --fix","format":"prettier --write \"src/**/*.ts\"","format:check":"prettier --check \"src/**/*.ts\"","typecheck":"tsc --noEmit","release":"standard-version","release:patch":"standard-version --release-as patch","release:minor":"standard-version --release-as minor","release:major":"standard-version --release-as major","preversion":"pnpm test || true","version":"pnpm build","postversion":"git push --follow-tags origin main"},"packageManager":"pnpm@10.18.3","keywords":["mcp","smartthings","home-automation","model-context-protocol","llm"],"author":{"name":"masa"},"license":"MIT","dependencies":{"@fastify/cors":"^11.1.0","@fastify/helmet":"^13.0.2","@modelcontextprotocol/sdk":"^1.22.0","@smartthings/core-sdk":"^8.0.0","@types/mustache":"^4.2.6","alexa-verifier":"^4.0.0","chalk":"^5.3.0","dotenv":"^16.4.5","express":"^4.19.2","fastify":"^5.6.2","mustache":"^4.2.0","openai":"^4.20.0","winston":"^3.15.0","zod":"^3.25.0"},"devDependencies":{"@types/express":"^4.17.21","@types/node":"^22.0.0","@typescript-eslint/eslint-plugin":"^8.0.0","@typescript-eslint/parser":"^8.0.0","@vitest/coverage-v8":"^3.0.0","eslint":"^8.57.0","eslint-config-prettier":"^9.1.0","eslint-plugin-prettier":"^5.2.0","prettier":"^3.3.0","standard-version":"^9.5.0","tsx":"^4.19.0","typescript":"^5.6.0","vitest":"^3.0.0"},"engines":{"node":">=18.0.0"},"gitHead":"dc69b5c2905abacb1942398e2711815741371656","_id":"@bobmatnyc/mcp-smartthings@1.0.3","_nodeVersion":"24.9.0","_npmVersion":"11.6.2","dist":{"integrity":"sha512-lDZKcEnbT2TS7XIeFX4IcqsexlkobKKjCZiB73w34uozU7spN54EeCbJwWeGfUu+WtdCTEGrxae86Xh7LM+TyA==","shasum":"b914cca6bdb9dfd4ff117873d9905e2f7a1b8fd5","tarball":"https://registry.npmjs.org/@bobmatnyc/mcp-smartthings/-/mcp-smartthings-1.0.3.tgz","fileCount":121,"unpackedSize":513408,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIAcDakcjU00BTEj4sYyQJwoOUKI25S8Pf9TISpLyJ2a4AiAht3dfiFL3e6gsoZIWdMdHRxJNLY66WDZG7ypr3P0gnQ=="}]},"_npmUser":{"name":"bobmatnyc","email":"bob@matsuoka.com"},"directories":{},"maintainers":[{"name":"bobmatnyc","email":"bob@matsuoka.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/mcp-smartthings_1.0.3_1764182576323_0.2353299113690237"},"_hasShrinkwrap":false}},"time":{"created":"2025-11-26T02:58:20.563Z","modified":"2025-11-26T18:42:56.727Z","1.0.1":"2025-11-26T02:58:20.870Z","1.0.2":"2025-11-26T18:37:16.244Z","1.0.3":"2025-11-26T18:42:56.521Z"},"author":{"name":"masa"},"license":"MIT","keywords":["mcp","smartthings","home-automation","model-context-protocol","llm"],"description":"Model Context Protocol (MCP) server for SmartThings home automation","maintainers":[{"name":"bobmatnyc","email":"bob@matsuoka.com"}],"readme":"# MCP SmartThings Server\n\nA Model Context Protocol (MCP) server that provides LLM-driven control and automation for SmartThings home automation systems. Built with TypeScript and the official SmartThings SDK.\n\n## Features\n\n- **Device Control**: Turn devices on/off, get status\n- **Device Discovery**: List all devices and their capabilities\n- **Scene Management**: List and execute SmartThings scenes\n- **Room Organization**: Filter devices and scenes by room\n- **Type-Safe**: Built with TypeScript 5.6+ strict mode and branded types\n- **Resilient**: Automatic retry with exponential backoff for API failures\n- **MCP Protocol**: Full compliance with MCP SDK 1.22.0\n- **Multiple Transports**: Stdio (CLI) and HTTP/SSE (web)\n- **Structured Logging**: Winston with JSON format for production monitoring\n\n## Prerequisites\n\n- **Node.js**: 18.0.0 or higher\n- **pnpm**: 9.0.0 or higher (recommended package manager)\n- **SmartThings Account**: With at least one device configured\n- **SmartThings Personal Access Token (PAT)**: Required for API authentication\n\n## Getting Started\n\n### 1. Installation\n\n```bash\n# Install pnpm if you haven't already\nnpm install -g pnpm\n\n# Install dependencies\npnpm install\n```\n\n### 2. SmartThings Personal Access Token (PAT)\n\nTo control your SmartThings devices, you need a Personal Access Token:\n\n1. Go to [SmartThings Personal Access Tokens](https://account.smartthings.com/tokens)\n2. Click \"Generate new token\"\n3. Enter a token name (e.g., \"MCP Server\")\n4. Select the following scopes:\n   - `r:devices:*` (Read devices)\n   - `x:devices:*` (Execute commands on devices)\n   - `r:scenes:*` (Read scenes)\n   - `x:scenes:*` (Execute scenes)\n   - `r:locations:*` (Read locations/rooms)\n5. Click \"Generate token\"\n6. **Copy the token immediately** (you won't be able to see it again)\n\n### 3. Configuration\n\nCreate a `.env` file in the project root:\n\n```bash\ncp .env.example .env\n```\n\nEdit `.env` and add your SmartThings PAT:\n\n```env\nSMARTTHINGS_PAT=your_personal_access_token_here\nMCP_SERVER_NAME=smartthings-mcp\nMCP_SERVER_VERSION=1.0.0\nMCP_SERVER_PORT=3000\nNODE_ENV=development\nLOG_LEVEL=info\nTRANSPORT_MODE=stdio\n```\n\n### 4. Build\n\n```bash\npnpm build\n```\n\n### 5. Run the Server\n\n**Development mode with auto-reload:**\n```bash\npnpm dev\n```\n\n**Production mode:**\n```bash\nnpm start\n```\n\nThe server will start with the configured transport mode (stdio or http).\n\n## Available MCP Tools\n\n### Device Control\n\n#### `turn_on_device`\nTurn on a SmartThings device (requires switch capability).\n\n**Input:**\n```json\n{\n  \"deviceId\": \"device-uuid-here\"\n}\n```\n\n**Output:**\n```\nDevice {deviceId} turned on successfully\n```\n\n#### `turn_off_device`\nTurn off a SmartThings device (requires switch capability).\n\n**Input:**\n```json\n{\n  \"deviceId\": \"device-uuid-here\"\n}\n```\n\n**Output:**\n```\nDevice {deviceId} turned off successfully\n```\n\n#### `get_device_status`\nGet current status and state of a SmartThings device.\n\n**Input:**\n```json\n{\n  \"deviceId\": \"device-uuid-here\"\n}\n```\n\n**Output:**\n```\nDevice: Living Room Light\nLabel: Main Light\nSwitch State: on\nType: LIGHT\n```\n\n### Device Discovery\n\n#### `list_devices`\nList all SmartThings devices accessible with the configured token. Optionally filter by room name.\n\n**Input:**\n```json\n{\n  \"roomName\": \"Living Room\"  // Optional\n}\n```\n\n**Output:**\n```\nFound 5 device(s):\n\n- Living Room Light (abc-123-...)\n  Type: LIGHT\n  Room: Living Room\n  Capabilities: switch, switchLevel\n\n- Kitchen Switch (def-456-...)\n  Type: SWITCH\n  Room: Kitchen\n  Capabilities: switch\n```\n\n**Features:**\n- List all devices across all rooms (no parameters)\n- Filter devices by room name (shows only devices in that room)\n- Supports case-insensitive, partial room name matching\n\n#### `list_devices_by_room`\nList all SmartThings devices in a specific room. More explicit than `list_devices` with optional `roomName` parameter - use this when room filtering is required.\n\n**Input:**\n```json\n{\n  \"roomName\": \"Living Room\"  // Required\n}\n```\n\n**Output:**\n```\nFound 2 device(s) in room \"Living Room\":\n\n- Living Room Light (abc-123-...)\n  Type: LIGHT\n  Room: Living Room\n  Capabilities: switch, switchLevel\n\n- Living Room Thermostat (def-456-...)\n  Type: THERMOSTAT\n  Room: Living Room\n  Capabilities: temperatureMeasurement, thermostatMode\n```\n\n**Features:**\n- Dedicated room-specific tool with required parameter\n- Clearer API intent than optional parameter\n- Returns error if room not found or name is ambiguous\n- Supports case-insensitive, partial room name matching\n\n**Design Decision:**\nThis tool provides better API design for room-specific queries by making the room parameter required. Use `list_devices_by_room` when you specifically want to filter by room, and `list_devices` when you want flexibility of optional filtering or listing all devices.\n\n#### `get_device_capabilities`\nGet the capabilities supported by a specific SmartThings device.\n\n**Input:**\n```json\n{\n  \"deviceId\": \"device-uuid-here\"\n}\n```\n\n**Output:**\n```\nDevice: Living Room Light\nCapabilities (3):\n- switch\n- switchLevel\n- colorControl\n```\n\n#### `list_rooms`\nList all SmartThings rooms/locations with device counts.\n\n**Input:**\n```json\n{}\n```\n\n**Output:**\n```\nFound 3 room(s):\n\n- Living Room (room-uuid-1)\n  Location: location-uuid\n  Devices: 5\n\n- Bedroom (room-uuid-2)\n  Location: location-uuid\n  Devices: 3\n```\n\n### Scene Management\n\n#### `list_scenes`\nList all SmartThings scenes accessible with the configured token. Optionally filter by room name to show scenes in that location.\n\n**Input:**\n```json\n{\n  \"roomName\": \"Living Room\"  // Optional\n}\n```\n\n**Output:**\n```\nFound 2 scene(s) in location for room \"Living Room\":\n\n- Movie Night 🎬 (scene-uuid-1)\n  Last Executed: 11/24/2025, 8:30:00 PM\n\n- Good Morning ☀️ (scene-uuid-2)\n  Last Executed: 11/25/2025, 7:00:00 AM\n```\n\n**Features:**\n- List all scenes across all locations (no parameters)\n- Filter scenes by room name (shows scenes in that room's location)\n- Shows scene icons, names, and last execution time\n- Supports case-insensitive, partial room name matching\n\n**Note:** SmartThings API scenes are filtered by location, not room. When you provide a room name, the tool finds the room and returns all scenes in that room's location.\n\n#### `list_scenes_by_room`\nList all SmartThings scenes for a specific room. More explicit than `list_scenes` with optional `roomName` parameter - use this when room filtering is required.\n\n**Input:**\n```json\n{\n  \"roomName\": \"Living Room\"  // Required\n}\n```\n\n**Output:**\n```\nFound 2 scene(s) in location for room \"Living Room\":\n\n- Movie Night 🎬 (scene-uuid-1)\n  Last Executed: 11/24/2025, 8:30:00 PM\n\n- Bright Lights 💡 (scene-uuid-2)\n  Last Executed: 11/24/2025, 6:00:00 PM\n```\n\n**Features:**\n- Dedicated room-specific tool with required parameter\n- Clearer API intent than optional parameter\n- Returns error if room not found or name is ambiguous\n- Supports case-insensitive, partial room name matching\n- Shows all scenes in the location for the specified room\n\n**Design Decision:**\nThis tool provides better API design for room-specific queries by making the room parameter required. Use `list_scenes_by_room` when you specifically want to filter by room, and `list_scenes` when you want flexibility of optional filtering or listing all scenes.\n\n**Technical Note:** SmartThings API scenes are organized by location, not room. This tool resolves the room to its location, then returns all scenes in that location.\n\n#### `execute_scene`\nExecute a SmartThings scene by ID or name.\n\n**Input:**\n```json\n{\n  \"sceneId\": \"scene-uuid-here\"  // Option 1: Use UUID\n}\n```\n\nOr:\n\n```json\n{\n  \"sceneName\": \"Movie Night\"  // Option 2: Use name (case-insensitive)\n}\n```\n\n**Output:**\n```\nScene \"Movie Night\" executed successfully.\nScene ID: scene-uuid-here\n```\n\n**Features:**\n- Execute by UUID (faster, direct execution)\n- Execute by name (convenient, supports partial matching)\n- Case-insensitive name matching\n- Returns execution confirmation with scene details\n\n## Usage with Interactive Chatbot\n\nThe MCP SmartThings server includes a built-in chatbot that provides a natural language interface for controlling your devices. The chatbot connects to the MCP server via the MCP protocol, validating that the server works correctly while providing an intuitive user experience.\n\n### Quick Start\n\n```bash\n# Build the project\npnpm build\n\n# Start chatbot (ensure .env.local is configured)\npnpm chat\n```\n\n### Configuration\n\nThe chatbot requires two environment variables in `.env.local`:\n\n```env\n# SmartThings Personal Access Token (required)\nSMARTTHINGS_PAT=your_smartthings_token_here\n\n# OpenRouter API Key (required for LLM access)\nOPENROUTER_API_KEY=sk-or-v1-your_openrouter_key_here\n```\n\n**Getting an OpenRouter API Key:**\n\n1. Visit [OpenRouter](https://openrouter.ai/)\n2. Sign up for a free account\n3. Navigate to API Keys section\n4. Generate a new API key\n5. Add to `.env.local`\n\n**Free Tier Models:**\n- `deepseek/deepseek-chat` (default) - Free, fast, good for home automation\n- Other free models available at [OpenRouter Models](https://openrouter.ai/models)\n\n### Using the Chatbot\n\nOnce started, you can control your devices using natural language:\n\n```\nYou: Turn on the living room lights\n├── package.json\n├── tsconfig.json\n├── vitest.config.ts\n└── README.md\n```\n\n## Development\n\n### Type Checking\n\n```bash\npnpm typecheck\n```\n\n### Linting\n\n```bash\npnpm lint\npnpm lint:fix\n```\n\n### Code Formatting\n\n```bash\npnpm format\npnpm format:check\n```\n\n### Testing\n\nThe project provides multiple testing approaches:\n\n#### Unit Tests\n```bash\n# Run all tests\npnpm test\n\n# Run unit tests only\nppnpm test:unit\n\n# Run tests in watch mode\nppnpm test:watch\n\n# Run tests with coverage\nppnpm test:coverage\n```\n\n#### Integration Tests\n```bash\n# Run integration tests (requires built server)\npnpm build\nppnpm test:integration\n```\n\n#### Interactive Test Gateway\n```bash\n# Launch interactive REPL client\nppnpm test-gateway\n\n# Interactive session:\n# mcp> connect\n# mcp> devices\n# mcp> on abc-123-device-id\n# mcp> status abc-123-device-id\n# mcp> help\n# mcp> exit\n```\n\n#### MCP Inspector (Official GUI Tool)\n```bash\n# Launch MCP Inspector GUI\nppnpm test:inspector\n\n# Opens browser at http://localhost:6274\n# - Visual interface for testing tools\n# - View request/response JSON-RPC messages\n# - Test tool execution with real devices\n```\n\n#### Shell Helper Functions\n```bash\n# Source helper functions\nsource tools/test-helpers.sh\n\n# Use helper commands\nmcp_list_tools              # List all MCP tools\nst_list_devices             # List SmartThings devices\nst_turn_on \"device-id\"      # Turn device on\nst_turn_off \"device-id\"     # Turn device off\nst_status \"device-id\"       # Get device status\nmcp_test_all                # Run all basic tests\n```\n\nSee [Testing Guide](#testing-guide) for comprehensive testing documentation.\n\n## Architecture\n\n### Strict Type Safety\n\nThis project uses TypeScript strict mode with branded types for domain safety:\n\n- **DeviceId**: Branded string type prevents mixing device IDs with regular strings\n- **LocationId**: Branded type for SmartThings locations\n- **CapabilityName**: Branded type for capability identifiers\n\n### Error Handling\n\nAll MCP tools return structured error responses:\n\n```typescript\n{\n  isError: true,\n  code: \"VALIDATION_ERROR\" | \"DEVICE_NOT_FOUND\" | \"SMARTTHINGS_API_ERROR\" | ...,\n  message: \"Human-readable error message\",\n  details?: { /* Additional error context */ }\n}\n```\n\n### Retry Logic\n\nSmartThings API calls use exponential backoff retry:\n\n- **Max Retries**: 3\n- **Initial Delay**: 1 second\n- **Backoff Multiplier**: 2x\n- **Max Delay**: 30 seconds\n\nRetries occur for:\n- Network errors (ECONNRESET, ETIMEDOUT)\n- HTTP 5xx server errors\n- HTTP 429 rate limit errors\n\nNon-retryable errors (fail immediately):\n- HTTP 4xx client errors (except 429)\n- Authentication failures\n- Validation errors\n\n## Environment Variables\n\n| Variable | Required | Default | Description |\n|----------|----------|---------|-------------|\n| `SMARTTHINGS_PAT` | Yes | - | SmartThings Personal Access Token |\n| `MCP_SERVER_NAME` | No | `smartthings-mcp` | MCP server name |\n| `MCP_SERVER_VERSION` | No | `1.0.0` | MCP server version |\n| `MCP_SERVER_PORT` | No | `3000` | HTTP server port (http mode only) |\n| `NODE_ENV` | No | `development` | Node environment |\n| `LOG_LEVEL` | No | `info` | Logging level (error, warn, info, debug) |\n| `TRANSPORT_MODE` | No | `stdio` | Transport mode (stdio or http) |\n\n## Troubleshooting\n\n### \"Environment validation failed: SMARTTHINGS_PAT is required\"\n\n- Ensure you've created a `.env` file with a valid `SMARTTHINGS_PAT`\n- Verify the token is not empty or expired\n\n### \"Unauthorized\" or \"Forbidden\" errors\n\n- Check that your PAT has the required scopes: `r:devices:*` and `x:devices:*`\n- Verify the token hasn't expired\n\n### \"Device not found\"\n\n- Ensure the device UUID is correct (use `list_devices` to verify)\n- Check that the device is still registered in your SmartThings account\n\n### No devices returned by `list_devices`\n\n- Verify your SmartThings account has devices configured\n- Check that your PAT has access to the correct location\n\n## License\n\nMIT\n\n## Contributing\n\nContributions are welcome! Please ensure:\n\n1. All tests pass (`pnpm test`)\n2. Code is properly formatted (`pnpm format`)\n3. No linting errors (`pnpm lint`)\n4. Type checking passes (`pnpm typecheck`)\n\n## Testing Guide\n\nThis project provides multiple testing approaches to suit different workflows:\n\n### 1. MCP Inspector (Recommended for Interactive Testing)\n\nThe official MCP Inspector provides a visual interface for testing:\n\n```bash\npnpm build\nppnpm test:inspector\n```\n\n**Features:**\n- Visual GUI for testing tools\n- View JSON-RPC request/response messages\n- Test with real SmartThings devices\n- Schema validation and error inspection\n- Opens at `http://localhost:6274`\n\n**Use Cases:**\n- Initial testing and debugging\n- Interactive tool exploration\n- Real device testing\n- Protocol validation\n\n### 2. Interactive Test Gateway (CLI REPL)\n\nA command-line REPL for testing without a GUI:\n\n```bash\nppnpm test-gateway\n```\n\n**Available Commands:**\n```\nConnection:\n  connect              - Connect to MCP server\n  disconnect           - Disconnect from server\n\nMCP Protocol:\n  tools                - List all available tools\n  call <tool> <args>   - Call a tool with JSON arguments\n\nSmartThings Shortcuts:\n  devices              - List all devices\n  status <deviceId>    - Get device status\n  on <deviceId>        - Turn device on\n  off <deviceId>       - Turn device off\n  capabilities <id>    - Get device capabilities\n\nUtility:\n  help                 - Show commands\n  clear                - Clear screen\n  exit                 - Exit gateway\n```\n\n**Example Session:**\n```bash\n$ ppnpm test-gateway\n\nmcp> connect\n✓ Connected successfully!\n\nmcp> devices\nFound 3 device(s):\n- Living Room Light (abc-123-...)\n- Kitchen Switch (def-456-...)\n\nmcp> on abc-123-...\n✓ Device turned on successfully\n\nmcp> exit\n```\n\n### 3. Shell Helper Functions\n\nQuick one-liners for scripting and automation:\n\n```bash\nsource tools/test-helpers.sh\n```\n\n**Core Functions:**\n```bash\n# MCP Protocol\nmcp_initialize                      # Initialize MCP connection\nmcp_list_tools                      # List all tools\nmcp_call_tool <name> <args>         # Call any tool\n\n# SmartThings\nst_list_devices                     # List devices\nst_turn_on <deviceId>               # Turn device on\nst_turn_off <deviceId>              # Turn device off\nst_status <deviceId>                # Get device status\nst_capabilities <deviceId>          # Get capabilities\n\n# Testing\nmcp_test_all                        # Run all basic tests\nst_test_device <deviceId>           # Test device control\nmcp_test_errors                     # Test error handling\n```\n\n**Example Usage:**\n```bash\n# List devices\nst_list_devices\n\n# Control a device\nst_turn_on \"abc-123-device-id\"\nsleep 2\nst_turn_off \"abc-123-device-id\"\n\n# Run full test suite\nmcp_test_all\n```\n\n### 4. Integration Tests (Automated)\n\nAutomated tests using Vitest and MCP SDK:\n\n```bash\n# Build server first\npnpm build\n\n# Run integration tests\nppnpm test:integration\n```\n\n**Test Coverage:**\n- MCP protocol compliance\n- Tool listing and metadata\n- Device query operations\n- Device control operations\n- Error handling and validation\n- Concurrent execution\n- Performance benchmarks\n\n**Environment Variables:**\n- `SMARTTHINGS_PAT`: Your SmartThings token (required)\n- `TEST_DEVICE_ID`: Optional device ID for real device tests\n\n### 5. Command-Line JSON-RPC Testing\n\nDirect JSON-RPC testing via stdio:\n\n```bash\n# List tools\necho '{\"jsonrpc\":\"2.0\",\"method\":\"tools/list\",\"id\":1}' | \\\n  node dist/index.js | jq\n\n# List devices\necho '{\n  \"jsonrpc\":\"2.0\",\n  \"method\":\"tools/call\",\n  \"params\":{\n    \"name\":\"list_devices\",\n    \"arguments\":{}\n  },\n  \"id\":2\n}' | node dist/index.js | jq\n\n# Turn on device\necho '{\n  \"jsonrpc\":\"2.0\",\n  \"method\":\"tools/call\",\n  \"params\":{\n    \"name\":\"turn_on_device\",\n    \"arguments\":{\"deviceId\":\"your-device-id\"}\n  },\n  \"id\":3\n}' | node dist/index.js | jq\n```\n\n### Testing Best Practices\n\n**1. Use Test Environment**\n- Create separate `.env.test` with test credentials\n- Use different SmartThings PAT for testing\n- Avoid testing on production devices\n\n**2. Test Device Selection**\n- Use non-critical devices for testing\n- Document test device IDs in environment variables\n- Consider using virtual devices or simulators\n\n**3. CI/CD Integration**\n```bash\n# Example GitHub Actions workflow\npnpm build\npnpm typecheck\npnpm lint\nppnpm test:unit\nppnpm test:integration  # With test credentials\n```\n\n**4. Logging and Debugging**\n```bash\n# Enable debug logging\nLOG_LEVEL=debug pnpm dev\n\n# Capture logs separately\nnode dist/index.js 2>error.log | jq\n```\n\n### Test Project Structure\n\n```\ntests/\n├── integration/\n│   └── mcp-client.test.ts       # Integration tests with MCP SDK\n├── unit/\n│   └── error-handler.test.ts    # Unit tests\n└── setup.ts                     # Test configuration\n\ntools/\n├── mcp-test-gateway.ts          # Interactive REPL client\n└── test-helpers.sh              # Shell helper functions\n```\n\n## Documentation\n\nComprehensive documentation is available in the [docs/](docs/) directory:\n\n- **[Setup Guides](docs/setup/)** - Installation and configuration\n  - [Alexa Quick Start](docs/setup/ALEXA_CUSTOM_SKILL_QUICK_START.md)\n  - [Diagnostic Tools Setup](docs/setup/DIAGNOSTIC_TOOLS_GUIDE.md)\n  - [ngrok Configuration](docs/setup/NGROK_QUICKSTART.md)\n\n- **[Implementation Guides](docs/implementation/)** - Development documentation\n  - [Alexa Custom Skill](docs/implementation/ALEXA_CUSTOM_SKILL_IMPLEMENTATION.md)\n  - [Chatbot Interface](docs/implementation/CHATBOT_IMPLEMENTATION.md)\n  - [Diagnostic Tools](docs/implementation/DIAGNOSTIC_TOOLS_IMPLEMENTATION.md)\n\n- **[Testing Documentation](docs/testing/)** - Test guides and verification\n  - [Testing Quick Start](docs/testing/TESTING_QUICK_START.md)\n  - [Verification Checklist](docs/testing/VERIFICATION_CHECKLIST.md)\n\n- **[QA Reports](docs/qa/)** - Quality assurance documentation\n\n- **[Research](docs/research/)** - Technical research and analysis\n\nFor a complete index, see [docs/README.md](docs/README.md).\n\n## Support\n\nFor issues and questions:\n\n1. Check the [SmartThings API Documentation](https://developer.smartthings.com/docs/api/public)\n2. Review the [MCP SDK Documentation](https://modelcontextprotocol.io/)\n3. Open an issue on GitHub\n\n## Acknowledgments\n\n- Built with [@modelcontextprotocol/sdk](https://www.npmjs.com/package/@modelcontextprotocol/sdk)\n- Powered by [@smartthings/core-sdk](https://www.npmjs.com/package/@smartthings/core-sdk)\n- Inspired by the Model Context Protocol specification\n","readmeFilename":"README.md"}