🛡️ ScamShield for Alexa+

"Alexa, I got a text from 'USPS' asking for a $1.99 fee. Is this a scam?" "Alexa, someone's on the phone saying he's from my bank." "Alexa, what scams are going around?"

ScamShield is a free, private scam checker you can use four ways, all powered by one self-hosted MCP server (Streamable HTTP, MCP spec 2025-11-25) that answers in plain language, out loud if you like:

The website is itself an MCP client: every check it does goes through the same MCP tools that assistants use. Privacy · Terms

Built for the Build, Ship, Shape: Amazon Developer Hackathon, Alexa+ track. The Alexa skill is tested end to end in the Alexa simulator (transcript). Hosted on Render, kept awake by a GitHub Actions ping every 10 minutes so Alexa never hits a cold start.

Why voice?

Scams hit the people least likely to open a laptop and research a link: older adults, busy parents, non-native speakers. Asking the assistant already in the kitchen is the most natural way to get a second opinion before you tap, pay or call back.

Related MCP server: ScamCheck MCP Server

MCP tools

Examples of live verify_with_official_source answers:

• USPS: "These phishing emails and smishing texts appear to be from the US Postal Service, but they are not, and individuals should not interact with them."

• PayPal: "PayPal will never ask for sensitive information in an email."

• Amazon: "Amazon never asks for your password or for sensitive personal information over the phone or on any external website."

Second opinion via MCP sampling. If the connected assistant supports sampling, check_message asks the assistant's own model to double-check anything the rules didn't call a scam, with the rules' evidence attached. No API key is needed, since the client runs the model, and the second opinion can only raise caution, never lower it. Clients that declare sampling get a session (SSE) automatically; everyone else keeps the fast stateless JSON path.

check_message also answers in the message's language: full Spanish, plus Hindi and Indonesian (verdict and key action).

Every tool returns a short spoken sentence first (content[0]), then structured details (structuredContent, with an outputSchema for check_message). All tools carry readOnlyHint annotations.

Also provided:

• Prompt is_this_a_scam: a guided workflow for assistants.

• Resource scamshield://guides/top-scams: a read-aloud guide to common scams.

• Server instructions: tell the assistant the recommended flow and safety rules (never suggest clicking the link).

A real Alexa skill, too

Besides the MCP server for Alexa+, ScamShield ships a classic Alexa custom skill endpoint (POST /alexa) with the interaction model in skill-package/. Say "Alexa, open Scam Shield", then:

• "Is this a scam? It says: your package is on hold…", then "yes" for how to report it, then "yes" for a warning to send your family

• "Someone's on the phone saying he's from my bank", then answer yes/no until Alexa says "Hang up now"

• "What scams are going around?" or "Let's practice", then "scam" / "real"

• "I think I got scammed" → "I paid with a gift card": the first steps out loud, the full plan in the Alexa phone app ("creo que me estafaron" in Spanish). The handler is live; the updated interaction model goes out with the next skill update, since the model can't change while the skill is in certification.

Built for how people actually talk to Alexa:

• Links read aloud work. "usps dot com dash track dash redelivery dot top slash pkg" is rebuilt into usps.com-track-redelivery.top/pkg and caught as a disguised link (Spanish too: "punto com guion … barra").

• A voice made for warnings. SSML stresses "This looks like a scam" and "Hang up now", pauses between sentences, and slows down slightly when warning, which helps older listeners.

• No dead air. When ScamShield checks the impersonated company's official website, Alexa first says "One moment…" through the Progressive Response API, so the listener isn't left in silence.

• A card on Echo Show. Devices with a screen get an APL card: SCAM / BE CAREFUL / LOOKS OK in big letters, the evidence quoted from the message, and one thing to remember. Practice-quiz messages are shown on screen so you can read along.

• En español. An es-US model (es-US.json): "Alexa, abre escudo antiestafas", then "es esto una estafa…" or "alguien me está llamando del banco". Message checks, the phone-call interview, reporting and the family warning are fully in Spanish (the briefing and quiz are English-only for now, and it says so).

Remembers across sessions, only with permission (built and tested; switched on after the current certification, see below). Judges of this track asked for skills that "keep context across sessions", and so do the people ScamShield serves:

• "Warn my daughter Maria" → "Want me to remember Maria as the person to warn next time?" Next time, "warn my family" just works.

• "My bank is Chase" → when someone calls claiming to be your bank, the verdict ends with "Call Chase yourself, using the number on the back of your card."

• After "I think I got scammed": "Want me to check in about this next time?" Next launch: "Welcome back. Last time, we talked about this: paid with a gift card. Did you reach the company that issued the gift card?" "No" repeats the first step, "yes" closes the case.

• "Forget me" deletes everything. Nothing is saved without a yes (or an explicit "my bank is…"), entries expire after 90 days, and the store is keyed by a salted hash of Alexa's user ID, so it never holds Amazon's identifier (lib/memory.js, Upstash Redis over REST, no extra dependency). If the store is slow or down, the skill answers normally, as if it remembers nothing. It is off unless ALEXA_MEMORY=on: the skill was submitted for certification as storing nothing, so it goes live together with its updated privacy policy and interaction model.

It has been run end to end in the Alexa developer console simulator against the live Render deployment: see the transcript and screenshot.

Every request is verified as coming from Amazon: the certificate URL and chain (issued for echo-api.amazon.com, chained to a trusted root), the RSA-SHA256 body signature, and a 150-second timestamp window. Set ALEXA_SKILL_ID to also pin the skill ID.

Works with real AI assistants

docs/real-client-transcripts.md has unedited runs with Claude Code as the MCP client. Given only the user's words, the assistant chained check_message → verify_with_official_source → check_link for a USPS text, and used check_phone_call for a live "bank fraud department" call, answering: "Hang up now. This is a scam. A real bank will never ask you to read out a code."

Agent Skill

skills/scam-check/ follows the Agent Skills specification: SKILL.md with the workflow, answer shape and safety rules, a reference guide, and scripts/check.mjs, which calls the MCP server from any agent that can run Node.

Simulated Alexa+ experience

Open http://localhost:3000/: an Echo-style assistant in the browser.

1. Tap the mic and say "Alexa, is this a scam? I got a text saying…" (or paste the message).

2. The page acts as the Alexa+ client: it runs the MCP handshake, calls check_message, then verify_with_official_source when a known brand is impersonated.

3. It speaks the answer (in Spanish for Spanish messages), shows the red flags, and offers "How do I report it?" and "Warn my mom".

4. Say "Someone's on the phone saying he's from my bank" for the call interview (answer yes/no by voice), or "What scams are going around?" for a briefing.

5. An MCP activity panel shows every live tools/call, with arguments and timing.

Accuracy (honest numbers)

We measured three configurations on the same held-out messages, including real SMS from a published research dataset¹ (full results):

The rules alone are precise but miss scams they weren't written for (on all 5,971 real messages: 27% of smishing caught, 1.7% false alarms). With the assistant's own model taking a second look, nearly every scam is caught. That's why ScamShield is designed as a toolbox for an AI assistant, not a standalone classifier.

We keep ourselves honest: once we learn from a test set's mistakes it becomes a development set (dev-a/b/c, now 100%), and new held-out sets are written or sourced separately. Reproduce with npm run bench, npm run bench:real, npm run eval:agent -- <set> and node scripts/eval-sampling.mjs <set>.

¹ Mishra & Soni, SMS Phishing Dataset for Machine Learning and Pattern Recognition, Mendeley Data 2022, doi:10.17632/f45bkkt8pr.1, CC BY 4.0 (source notes).

The detection engine is also published as a standalone open-source library: scam-signals.

Run it

Requirements: Node.js 22.9+ (for --env-file-if-exists; npm start works on 20+).

npm install
cp .env.example .env     # optional: add TAVILY_API_KEY for the web tools
npm run dev              # MCP: http://localhost:3000/mcp · demo: http://localhost:3000/
npm test                 # protocol tests with the official MCP client + analyzer tests
npm run bench            # accuracy benchmark

Connect an MCP client

• MCP Inspector: npx @modelcontextprotocol/inspector, then choose Streamable HTTP with http://localhost:3000/mcp.

• Claude Code: claude mcp add --transport http scamshield http://localhost:3000/mcp

• Any client that supports Streamable HTTP: point it at /mcp. The server is stateless and returns JSON responses.

Deploy (Render, free)

Push to GitHub → Render New → Blueprint (uses render.yaml) → set TAVILY_API_KEY.

MCP spec: ready for 2026-07-28

ScamShield speaks MCP 2025-11-25, the newest version the official TypeScript SDK (1.30.1) supports. The 2026-07-28 revision makes MCP stateless and deprecates sampling. We're already most of the way there:

• Stateless by default. Every request gets a fresh server and a plain JSON response; no tool depends on a session.

• State travels as tool arguments. Multi-step flows pass their state back explicitly: check_phone_call takes the answers so far, scam_recovery takes the situations. That is the 2026-07-28 model ("explicit handles passed as ordinary tool arguments").

• Deterministic tools/list, which the new revision recommends for client caching.

• Sampling is the one thing to migrate. Sessions exist only so check_message can ask the client's model for a second opinion. The new spec deprecates sampling in favor of calling a model provider directly. Our plan: keep rules-first answers (explainable, instant, free), and move the second opinion to a direct, optional model call, while every tool already returns red_flags with evidence so the assistant's own model can take that second look itself.

Project structure

server.js              Express + Streamable HTTP transport (stateless), static demo app
lib/mcp.js             MCP server: tools, prompt, resource, instructions
lib/scan.js            check_message analysis + spoken answer
lib/i18n.js            Language detection + Spanish/Hindi/Indonesian answers
lib/call.js            check_phone_call guided interview
lib/briefing.js        scam_briefing from official consumer alerts
lib/family.js          warn_family message
lib/practice.js        practice_quiz
lib/second-opinion.js  MCP sampling second opinion
lib/alexa.js           Alexa custom-skill conversation handler (English + Spanish, SSML, progressive responses)
lib/alexa-apl.js       Visual verdict card for Echo Show (APL)
lib/alexa-verify.js    Alexa request signature verification
lib/memory.js          Opt-in memory across Alexa sessions (hashed keys, 90-day expiry, "forget me")
lib/recovery.js        scam_recovery: ordered steps after someone already paid, clicked or shared
skill-package/         Alexa interaction models (en-US, es-US)
lib/clues.js           Link/phone analysis, clue extraction
lib/tavily.js          Tavily search + multi-page extract
lib/official.js        Picks the official page and the sentence that answers the question
lib/report.js          Reporting channels by country
lib/guide.js           Read-aloud scam guide (MCP resource)
public/                Website (MCP client): checker, call helper, alerts, privacy, terms, PWA
public/demo/           Simulated Alexa+ web app (voice in/out, browser MCP client)
skills/scam-check/     Agent Skill
docs/                  Real MCP client transcripts
eval/                  Labeled message sets + results
test/                  node:test suites (official MCP client end-to-end)

Safety and privacy

ScamShield never opens, fetches or clicks suspicious links; it analyzes them as text. It stores nothing about the person unless they opt in to the Alexa memory described above (off until the skill's next certified version), never logs message text, and only sends company names or short queries to web search. Full details: PRIVACY.md. ScamShield gives guidance, not legal or financial advice.

License

MIT