Hermes Home

Alexa+ on the front. Hermes as the agent underneath.

Amazon Developer Hackathon — Alexa+ track (self-hosted MCP server, Streamable HTTP, spec 2025-11-25) · also entered in the Open Source mini challenge (MIT).

Alexa+ integrates through remote Streamable-HTTP MCP servers; the Hermes personal-agent runtime only ships a stdio MCP server. Hermes Home is the bridge: it exposes a small, hand-picked set of tools to Alexa+ and keeps every long task asynchronous, so a voice assistant never waits on a slow agent.

Try it in 2 minutes (simulated Alexa+)

No Alexa+ Preview access is needed. apps/dashboard contains an Alexa+ simulator: a voice/chat web app that acts as the MCP client (official @modelcontextprotocol/sdk), lists the server's tools, calls them over Streamable HTTP, and shows every tools/call in a live trace panel.

npm install
copy .env.example .env      # set HERMES_API_URL / HERMES_API_KEY (and PORT if 3000 is busy)
npm run demo                # tunnel -> MCP bridge -> simulator, verified
# open http://127.0.0.1:3100/sim

Things to say: "Ask Hermes what a good question to reflect on today is" · "Send me a message on Discord with a question to think about" · "Ask Hermes to plan a productive Saturday" → "Is Hermes done?"

Optional: set GOOGLE_API_KEY and the simulator lets Gemini pick tools by function-calling (like real Alexa+); without it a keyword router is used. Anything that mentions "Hermes" is routed straight to the agent.

Related MCP server: AlexaTasker

What is exposed (14 tools — never the whole Hermes catalogue)

hermes_ask · hermes_start_task · hermes_task_status · hermes_task_result · home_get_state · home_control (two-step confirm) · hermes_memory_search · hermes_remember · calendar_today · calendar_tomorrow · calendar_events · github_my_issues · github_repo_issues · send_message. Calendar, Home Assistant and GitHub activate when their credentials are in .env; otherwise they return a clear "not configured" result.

Safety design

Fail-closed Hermes gate (server refuses to boot without a live agent) · per-user run/memory isolation · DNS-rebind guard · RS256/JWKS OAuth2 mode for internet exposure · home control requires explicit confirmation · the simulator redacts DM handles/IDs from its trace. See docs/privacy.md.

Submission notes

Hackathon deliverables live in docs/submission.md (description, product feedback, friction log pointers). Audit/continuation guide: docs/handoff.md. Hermes VM wiring: docs/hermes-vm.md.

Current state — local-only, MVP track. This repo contains the working Alexa+ ↔ Hermes bridge: a public-safe Streamable HTTP MCP server (apps/mcp-server) that answers quickly, safely, and only from a real Hermes runtime. It runs loopback-first: out of the box it is intentionally reachable only from the machine it's on (DNS-rebind guard on Host/Origin). Alexa+ onboarding (Cloudflare Tunnel + OAuth 2.1/PKCE) is documented in docs/alexa.md and docs/oauth-reference/README.md and is the explicit next step — everything before it already works on localhost. If the Hermes gateway is down the server refuses to start rather than demo against a stub (HERMES_REQUIRED=false exists for tests only).

┌──────────────┐       ┌───────────────┐
│    USER      │──────▶│    ALEXA+     │  voice + display
└──────────────┘       └──────┬────────┘
                              │ Streamable HTTP MCP
                              ▼
               ┌─────────────────────────────┐
               │  HERMES HOME — MCP SERVER   │  the only public component
               └──────────────┬──────────────┘
                              │
              ┌───────────────┼───────────────┐
              ▼               ▼               ▼
        fast tools      Hermes HTTP API    local state
        (home, memory)  (127.0.0.1:8642)   (memory · runs)
                              │
                              ▼
                     ┌─────────────────┐
                     │  HERMES AGENT   │ memory · browser · subagents · MCP
                     └────────┬────────┘
                              ▼
          Home Assistant · Calendar · GitHub · Messages · Muse …

📋 New here? Read docs/handoff.md first — it's a proof-oriented audit & continuation guide: what's built, what each red onboarding row means, and the exact commands to re-verify every claim.

Why

Alexa is a great conversational surface; Hermes is a persistent personal agent (memory, long-running tasks, tools, integrations). Hermes Home gives the user a single conversational doorway into both (spec §1) — no new intents, no hard-coded commands: Alexa+ decides when Hermes' tools apply.

Quick start — everything, one command

git clone <this-repo>; cd hermes-home
npm run dev                 # installs, builds, spawns MCP server + dashboard + optional tunnel

Then prove it's ready to connect before touching Alexa:

npm run onboard             # runs the full spec §41 readiness ladder with colored pass/fail

You'll get a line-by-line readiness report for: MCP health, Hermes reachability, protocol handshake, tool discovery, the DNS-rebind guard, OAuth discovery documents, and which integrations are configured. When the top sections are green, expose and onboard:

cloudflared tunnel --url http://localhost:3000
# then follow docs/alexa.md onboarding checklist

Or run pieces by hand: npm run dev:mcp, npm run dev:dashboard.

Tools exposed to Alexa+

Deliberately small (spec §10) — never the whole Hermes catalog:

Repository layout

apps/
  mcp-server/         the public Alexa+ MCP bridge (this is the product)
  dashboard/          developer/debug surface on :3100 (spec §46)
integrations/         adapter skeletons (Home Assistant done; calendar/message/muse/config stubs)
packages/shared/      types, zod schemas, constants
docs/                 architecture, alexa, hermes, oauth reference, memory, privacy, friction log

Commands

npm run dev              # everything: builds, starts MCP server (:3000) + dashboard (:3100)
npm run dev:mcp          # MCP server only (tsx watch)
npm run dev:dashboard    # debug dashboard only
npm run onboard          # full readiness ladder (spec §41) — the "is it ready to connect?" check
npm run smoke            # lighter pass/fail smoke
npm test                 # unit + protocol + safety tests
npm run build            # type-check + build all workspaces
hermes gateway           # Hermes HTTP API (separate runtime)
cloudflared tunnel --url http://localhost:3000  # public HTTPS for Alexa+

Safety & trust boundaries (what reviewers should notice)

• Bound-local default: Host/Origin DNS-rebind guard — a web page can't drive your laptop's MCP port.

• Fail-closed on Hermes: no reachable gateway, no server. No canned answers.

• Confirmation-before-execution for every physical action; security-sensitive domains (locks/alarms/covers) never act without an explicit out-loud confirm.

• Per-user run & memory ownership: another user's runId is "unknown".

• Latency budget honored: long work is always async via /v1/runs — Alexa+ never waits on a 20 s agent loop (spec §36).

Roadmap

• Bridge MVP (ask / start / status / result / memory / home)

• Alexa+ onboarding via tunnel + OAuth 2.1 account linking

• Home Assistant live test on real devices

• Physical Alexa device validation

• Calendar / messaging / GitHub adapters (config-driven, integrations/generic-mcp)

• Muse adapter (optional; license-gated, descriptive metrics only)

• Registry-remote track: export tool-config.json so Hermes consumes Hermes Home as MCP (hermes/registrations.ts)

License

MIT — see LICENSE.