ViewingGuardian Lingo

AI Guardian & Language Layer for Fire TV

Comment

Inspiration

I wanted to make something that used both Alexa and Fire TV, and was useful not only for my self but also for my kids. We are a multilanguage family and having the option to easily translate the content to different languages is something that is not available seamlessly and also when sharing some old movies with my kids some of the scenes can be a little bit uncomfortable to watch so having a way to skip them without having to think about it is something that many families / users will appreciate.

What it does

ViewingGuardian + Lingo is an Alexa+ MCP server that gives Fire TV real-time, scene-level awareness of what's playing and who's watching. It does two things existing parental controls and language settings cannot:

Guardian interventions — Analyzes scenes live, checks them against a child's profile (age, sensitivities, household rules), and intervenes before harmful content hits: skipping jump scares, softening peril, replacing profanity, pausing intense moments.

Language transformation — Translates subtitles in real time, dubs scenes while preserving the original actor's voice, and replaces specific dialogue with family-friendly alternatives — all without leaving playback.

How I built it

The system runs as a self-hosted MCP server (spec 2025-11-25, Streamable HTTP transport) that Alexa+ discovers and invokes. The server exposes two tool namespaces:

  • Guardian tools — get_current_context, analyze_scene_for_child, skip_scene, get_child_profile, log_decision, set_boundary
  • Lingo tools — translate_subtitles, dub_scene, replace_dialogue, get_lingo_status

Alexa+ handles natural language understanding and orchestration. The MCP server handles scene analysis (Amazon Bedrock + Claude 3 Sonnet), child profile matching, intervention decisions, and language transformation (ElevenLabs for voice-preserving dubbing). Playback control and audio/subtitle stream switching are wired through a Home Assistant bridge to Fire TV.

For the Developer Console path, I built a small ASK-to-MCP shim at /alexa that translates traditional Alexa Skills Kit requests into calls against the guardian tools. This lets the official simulator exercise the skill end-to-end without waiting on the MCP Toolkit private preview.

The whole thing runs locally: FastMCP + Uvicorn on port 8000, exposed publicly via Cloudflare Tunnel, with OAuth 2.1 + PKCE S256 for auth discovery.

Challenges I ran into

1. The Alexa MCP Toolkit is behind a private preview. The official @alexa-ai/cli package returned a 404 on the public npm registry. I pivoted to a traditional Custom Skill + ASK-to-MCP shim, which required building the translation layer myself.

2. OAuth 2.1 discovery had undocumented requirements. Alexa+ silently rejects discovery if the 401 response includes a WWW-Authenticate header — this isn't in the docs. I also had to add S256 to code_challenge_methods_supported explicitly, or account linking fails without a clear error.

3. The Developer Console rejects space-separated scopes. The Scope field error message only shows the regex ^[\w:]*$ — it doesn't tell you to use commas. I lost time on this.

4. Meeting the 500ms latency budget. Live Bedrock calls clock in at ~1.8s cold. I solved this by pre-fetching scene analysis on a rolling 30-second buffer and caching verdicts keyed by scene ID.

5. NoCredentialsError isn't caught by botocore.exceptions.ClientError. My first Bedrock call crashed the tool when AWS creds weren't configured. I added explicit handling so the server falls back to rule-based verdicts from scene metadata — which also makes the demo runnable without AWS credentials.

6. Cloudflare quick tunnels rotate URLs on every restart. Each rotation required updating .env, restarting the server, and re-saving the Developer Console endpoint. I learned to keep the tunnel terminal open and prevent the laptop from sleeping.

7. Producing the demo film. I wrote, shot, and edited The Whispering Woods — a 4-minute original short film with a jump scare, mild profanity, and a peril sequence, each mapped to a specific timestamp in the scene metadata. Keeping it royalty-free and original meant I couldn't rely on stock footage.

Accomplishments that I'm proud of

  • A working end-to-end Alexa skill that responds to ask view guardian is this okay for mia with a real jump scare verdict, not a scripted response.
  • A self-hosted MCP server at spec 2025-11-25 with 10 registered tools, verified through the MCP Inspector and the Alexa Developer Console simulator.
  • OAuth 2.1 + PKCE S256 discovery — the full auth chain works, including the account linking flow in the Developer Console.
  • Graceful degradation — the demo runs without AWS or ElevenLabs credentials and still produces correct verdicts, but the Bedrock and dubbing paths are fully wired for when credentials are present.
  • A complete open source repo with README, license, tests, and a reproducible setup.

What I learned

  • MCP is the right abstraction for stateful assistants. Separating "Alexa orchestrates" from "the server reasons" makes the system composable and testable.
  • Latency budgets shape architecture. A 500ms cap forces you to pre-fetch and cache aggressively — you can't call an LLM on the hot path.
  • Discovery protocols are unforgiving. A missing S256 or an extra header will silently break account linking. Testing the discovery endpoints with curl before plugging them into Alexa saved me hours.
  • Fallbacks are features. Building the rule-based fallback for scene analysis made the demo reliable and made the code more robust.
  • Shipping is a different skill from building. Making the video, writing the README, and structuring the repo for judges took as much care as the code.

What's next for ViewingGuardian + Lingo

  • Multi-language expansion. Currently English → Spanish; next is full support for any language pair via the ElevenLabs dubbing API.
  • Per-user mood profiles. Let each family member define their own sensitivities (not just by age — by mood, time of day, or context).
  • Native Fire TV companion app. Removes the Home Assistant dependency and enables frame-accurate seeks and true audio track switching.
  • Production AWS deployment. Lambda + API Gateway + DynamoDB for child profiles and intervention logs, with Bedrock as the reasoning layer.
  • Caregiver dashboard. A companion web UI where parents can review flagged scenes, adjust boundaries, and see weekly reports.

Built With

  • alexa
  • alexa-skills-kit
  • amazon-bedrock
  • aws-lambda
  • elevenlabs
  • fastmcp
  • fire-tv
  • home-assistant
  • http
  • mcp
  • oauth
  • pkce
  • python
  • sqlite
  • starlette
  • uvicorn
Share this project:

Updates

Submission history