Ambient

A self-hosted Model Context Protocol (MCP) server and web dashboard for Alexa+, powered by AWS Bedrock.

Overview

Ambient connects an Alexa+ interface to smart home devices through the Model Context Protocol (MCP). Unlike traditional single-turn voice skills, Ambient can break down complex requests into multi-step routines, save user preferences across sessions, and show interactive controls directly on screen.

It uses the open Streamable HTTP transport (MCP Spec 2025-11-25+) with Server-Sent Events (SSE) and JSON-RPC 2.0. For reasoning, it calls AWS Bedrock (Claude 3.5 Sonnet and Amazon Nova). If AWS credentials are not set, it uses a local simulator so you can test everything out of the box.

Related MCP server: Aura+

Architecture

graph TD
    User["User Voice / Text Input"] --> Client["Alexa+ Web Interface"]

    subgraph Transport["Streamable HTTP Transport"]
        Client <-->|"SSE Stream /sse"| MCP["MCP Server (Express)"]
        Client <-->|"JSON-RPC /messages"| MCP
    end

    subgraph AWS["AWS Cloud"]
        MCP <-->|"Bedrock SDK"| Bedrock["Amazon Bedrock"]
    end

    subgraph Tools["MCP Tools"]
        MCP --> T1["smart_home_control"]
        MCP --> T2["execute_multi_step_routine"]
        MCP --> T3["manage_context_memory"]
        MCP --> T4["render_interactive_card"]
    end

Screenshots

Features

• Streamable HTTP MCP Server: Conforms to the MCP Spec (2025-11-25+) with /sse for event streaming and /messages for JSON-RPC 2.0 requests.

• AWS Bedrock Integration: Uses @aws-sdk/client-bedrock-runtime for tool calling and reasoning with Claude 3.5 Sonnet and Amazon Nova Pro.

• Model Fallback: If Bedrock hits a rate limit (HTTP 429 / ThrottlingException), the server automatically falls back to secondary models or the local simulator.

• Interactive Web Interface: 4 tab views (Console, Trace, Energy, Devices) with voice input, audio cues, and responsive controls.

• Context Memory: Persists user settings and preferences across sessions via MCP resource and tool endpoints.

Getting Started

Prerequisites

• Node.js 18+

• npm 9+

Run Locally

1. Clone the repository and install dependencies:

   git clone https://github.com/Sidopolis/ambient-alexa-mcp.git
   cd ambient-alexa-mcp
   npm install

2. Start the server:

   npm start

3. Open http://localhost:3000 in your browser.

4. Run the test suite:

   npm test

   Runs 16 unit tests covering MCP tool schemas, tool execution, intent parsing, and fallback logic.

AWS Bedrock Configuration (Optional)

To connect directly to AWS Bedrock instead of the local simulator, add a server/.env file:

AWS_REGION=us-east-1
AWS_ACCESS_KEY_ID=your_access_key
AWS_SECRET_ACCESS_KEY=your_secret_key
BEDROCK_MODEL_ID=anthropic.claude-3-5-sonnet-20240620-v1:0
PORT=3000

Restart the server to apply the changes.

MCP Tools & Resources

Registered Tools (tools/list & tools/call)

Resources (resources/list & resources/read)

Developer Experience & Friction Log

See FRICTION_LOG.md for notes on MCP session binding, Bedrock tool schema formats, and client-server state synchronization.

Contributing

See CONTRIBUTING.md for guidelines on code standards, adding new MCP tools, and running tests.

License

MIT