Overview
RealityAnchor is a grounding companion for OCD and cognitive loops, delivered as an Alexa+ MCP add-on. When a user is spiralling, Alexa+ calls RealityAnchor's tools to name the distortion, read the user's own calm-state rules back to them, and start an ERP (Exposure & Response Prevention) delay. The visual view renders the intervention in the chat surface.
▶ Watch the demo video — three urges, three outcomes, with the real MCP tool calls on screen.
Architecture
There are two surfaces, both served from one Next.js app:
/api/mcp— the MCP server (Streamable HTTP) the AI connects to. It exposes machine-readable tools./mcp-view— the MCP App: the visual grounding UI, hydrated from the tool context Alexa+ passes.
Alexa+ orchestrates the tools; RealityAnchor supplies the analysis and the visual grounding.
Full system diagram
Click the diagram to view it full size.
How the AI works
Two layers of intelligence. Alexa+ is the orchestrator — it reads the plain-English descriptions of our MCP tools and decides which to call during the conversation, then writes the spoken/typed response. That's the point of an add-on: the conversation lives in Alexa+, not in a competing in-app chatbot.
The analysis itself is model-generated. When you call evaluate_cognitive_distortion, the tool calls a real model (first-party Claude API, or Claude via Amazon Bedrock) to classify the distortion, rate the risk, and write the rationale and suggested response — this is what fills the node details. The keyword heuristic is only a fallback for local dev and testing when no model credentials are configured. Each analysis is tagged AI or heuristic in the UI so you can see which path ran.
The in-app Simulate a trigger control runs the same path through /api/analyze — real model when configured, heuristic otherwise — so a standalone demo shows real model output the moment a key is set.
MCP tools
get_baseline_rules— returns the user's calm-state anchors so Alexa+ can read their own words back.evaluate_cognitive_distortion— classifies a trigger against CBT distortions, rates risk, and flags genuine safety signals that are not the loop.trigger_erp_delay— starts a Human-in-the-Loop delay the user urge-surfs before acting on a compulsion.
The visual flow
Each turn draws a lane: a gray Trigger node → a blue Analysis node (distortion, risk, and the matched anchor) → a yellow ERP Delay node with a countdown. A continued conversation appends new lanes rather than wiping the diagram, so the whole session stays visible. Click any node or trace chip to see its details.
The visual app has two layouts, switched from the gear menu. Unified chat (the default for new visits) is two columns after the first turn: the transcript on the left, and one embedded card on the right with Flow and Anchors tabs. With no message yet, only the chat is shown. The ERP countdown lives on the map node so it is not duplicated in the details cards. Three panes is the original side-by-side session / center / side layout; its center can be node details or the flow map.
ERP delay & HITL
The ERP node shows a large countdown. When the user clicks I waited it out, the app POSTs to /api/resume-session — the Human-in-the-Loop callback that closes the loop — and the node flips to a green Resolved state. A genuine safety signal (e.g. a real gas smell) never gets a delay; it tells the user to act.
Anchors
Anchors are the user's calm-state reality rules. In the app they are client-editable (the Anchors tab in unified chat, or the side-panel tab in three-pane layout; persisted locally) and feed the local analysis. The get_baseline_rules tool serves server-side defaults to Alexa+.
Running & testing
Run pnpm dev and open /mcp-view. Point an MCP client (MCP Inspector, Claude Code/Desktop) at /api/mcp over Streamable HTTP to exercise the tools as Alexa+ would. See docs/DEPLOYMENT.md for full local + deploy instructions.