AI agents, MCP servers, RAG chatbots and voice agents that answer from the source, not a guess · Ex-Samsung R&D · 17+ years of software engineering
by Md. Shihabuddin Sadi
Software Engineer · AI Agents, MCP & RAG · Voice Agents · DevOps & Cloud Native
October 03, 2026
Your dryer beeps and shows tE1. The paper manual went out with the packaging. A web search gives you five forum threads about a different model, and an AI chatbot gives you a confident answer that may or may not match the machine in your laundry room.
FixIt answers from the real manufacturer manual for the appliance you own, and tells you which page it came from. Ask about an error code, or describe a symptom in plain words (“my washer has too many suds”), and you get the manual’s causes and repair steps. If the manual doesn’t say, FixIt says that too.
It is a self-hosted MCP server (spec 2025-11-25, Streamable HTTP) built for Alexa+, deployed on Amazon Bedrock AgentCore, and built for the Build, Ship, Shape: Amazon Developer Hackathon. The design rule that shaped everything: no model runs inside any tool. All the AI work happens offline. Every live answer is a fast, deterministic, testable lookup.
This post covers how it works, what broke, what I measured (including the numbers that don’t flatter it), and what I’d tell anyone building tools for voice assistants.
🎬 Demo video (2 min): youtu.be/EbuSbJQJrXQ
🔗 GitHub Repository (MIT): sadishihab/fixit-mcp
📦 Spin-off library: pdf-encoding-repair on PyPI
Python 3.12 · uv · MCP Python SDK (spec 2025-11-25) · Streamable HTTP · MCP Apps · Amazon Bedrock AgentCore Runtime · AgentCore Memory · Amazon Bedrock (Claude, Nova Pro) · Amazon Polly · CloudWatch · SNS · ECR · Docker (ARM64) · FastAPI · PyMuPDF · pydantic · GitHub Actions
Appliance error codes are a perfect trap for a language model. They are short, cryptic, and model-specific: the same two characters can mean different things on two dryers from the same brand. A model that has read thousands of forum posts will happily produce a fluent, plausible answer, and fluency is exactly the problem. The person reading it has no way to tell whether it came from their manual or from someone else’s.
Voice makes it worse. On a screen you might notice a hedge or check a link. Through a speaker, a confident sentence just sounds true.
So the requirements were simple to state and strict to meet:
The obvious design is RAG at request time: retrieve some manual chunks, hand them to a model, let it write an answer. I deliberately didn’t do that inside the tools.
Instead, the work is split in two:
This buys four things at once:
The assistant (Alexa+, or any MCP client) still does what models are good at: understanding the question and phrasing the answer. It just isn’t allowed to be the source. The model presents, the tool decides.
OFFLINE (once per manual) — the only place models are used
┌──────────────────────────────────────────────────────────────────────────────────────┐
│ Manufacturer PDF ─► PyMuPDF parse ─► encoding repair ─► Bedrock extraction ─► audit │
│ (section-aware) (pdf-encoding- (strict pydantic (row │
│ repair) schema) counts, │
│ verbatim │
│ join) │
│ └──────────────► error codes + symptom data │
└───────────────────────────────────────────────────────────────┬──────────────────────┘
│ baked into the image
ONLINE (every question) ▼ — no model calls, ever
┌──────────────────────┐ MCP · Streamable HTTP ┌──────────────────────────────────────┐
│ Alexa+ │ IAM SigV4 │ Amazon Bedrock AgentCore Runtime │
│ (demo: simulated │ ────────────────────────► │ FixIt MCP server (stateless) │
│ Alexa+ client, │ │ 6 tools · in-memory lookups │
│ clearly labelled) │ ◄──────────────────────── │ 2 MCP Apps cards │
└──────────────────────┘ cited answer / card └───────────────┬──────────────────────┘
│
┌───────────────────────────┼─────────────────────┐
▼ ▼ ▼
AgentCore Memory CloudWatch dashboard SNS alerts
(household appliances) + error/latency alarms
FixIt exposes six MCP tools. What makes them useful isn’t only what they return; it’s what they are not allowed to return.
| Tool | What it does | What it refuses to do |
|---|---|---|
diagnose_error |
Error code → meaning, likely causes, ordered repair steps, safety warnings, page citation | Guess at a code that isn’t in the manual |
diagnose_symptom |
Plain-language problem → the manual’s troubleshooting rows | Invent a cause; it returns not found instead |
check_warranty |
Deterministic date check against the recorded warranty | Claim anything is covered |
list_my_appliances |
What this household owns | — |
add_appliance |
Add by model number, link to its manual | — |
remove_appliance |
Remove one | — |
Here is what it looks like in practice, from the demo:
User: My dryer is showing tE1, what should I do?
FixIt: tE1 — Temperature sensor failure
Likely cause: temperature sensor failure
Repair: 1. Turn off the dryer and call for service
Source: manufacturer manual, p. 31
User: My dryer shows ZZ99.
FixIt: The code ZZ99 isn't in the manuals we have.
diagnose_error and diagnose_symptom also render MCP Apps cards, so a screen-capable client shows the causes, steps, and citation visually, with distinct states for found, not found, and which appliance did you mean?
The first real bug had nothing to do with AI.
Two of the seven manuals extracted as text that looked like text: right length, plausible spacing, plausible punctuation. It was garbage. Every character had been shifted by a constant offset because of a broken font encoding, and the offset was different in each manual.
Nothing errored. PyMuPDF happily returned strings. A RAG pipeline would have embedded them, indexed them, and retrieved them, and nobody would have noticed until a model started answering from nonsense.
The fix detects the pattern, works out the offset per document, repairs the text, and has guards against false positives so clean PDFs are left untouched. Because this is a silent failure that anyone ingesting PDFs can hit, I didn’t leave it buried in FixIt. It became a standalone MIT-licensed library, pdf-encoding-repair, published on PyPI with CI and a tagged release.
The general lesson: the most dangerous ingestion bugs don’t throw exceptions. They produce output that is the right shape and the wrong content.
Offline extraction is where the models earn their keep, and also where they can quietly drop or invent rows. A table with twelve symptoms that comes back with eleven is a silent loss. A “cause” that appears nowhere in the manual is a silent invention.
So extraction runs under two audits:
The symptom tables (114 rows across two manuals) were extracted with Amazon Nova Pro under these audits, for about $0.10. Where a manual’s own text is cut off, the record is marked “incomplete in the manual” rather than completed by the model. You can see that tag on the suds card in the demo.
Today the data covers 7 real manufacturer manuals, 46 error-code records from five of them, and 114 symptom rows from two.
This is the finding I’m proudest of, because it came from watching real conversations rather than reading test output.
A user asked whether an error code was dangerous. The tool returned the record faithfully, and its safety-warning list was empty, because the manual lists no warning for that code. The assistant turned that into: “It’s safe.”
Nothing in the data said that. The model read an absence and reported it as a fact.
The fix was a rule, enforced in the prompt and pinned with tests so it can’t quietly regress:
Say what the tool returned, and stop. An empty warning list becomes “the manual doesn’t list a specific warning for this code”, never “it’s safe.” An unknown code becomes “not found”, never a nearby guess. A warranty date becomes “the recorded warranty ended on…”, never “you’re covered.”
check_warranty is built the same way. It’s a deterministic date comparison that reports only the recorded date. Coverage depends on terms, receipts, and conditions FixIt can’t see, so it never claims coverage at all.
If you’re building tools for assistants, this generalises: design your tool outputs so that the honest sentence is the easy sentence to produce.
Error codes are easy to look up. Symptoms are hard: people say “it’s full of bubbles”, “too much foam”, “soapy mess”. Keeping to the no-model rule meant diagnose_symptom had to be a keyword matcher, which is the honest choice and also the limited one.
So I measured it against a bank of invented paraphrases:
| Measurement | Before tuning | After tuning |
|---|---|---|
| Tuning set recall | 25 / 47 | 43 / 47 |
| Wrong first match | 4 | 0 |
| “None of these” cases wrongly matched | 7 / 31 | 0 / 31 |
| Held-out recall | 4 / 10 | 4 / 10 |
The last row is the important one. On phrasings I hadn’t tuned against, recall didn’t move, and there is one known wrong answer (“rocking back and forth”). Tuning made the matcher better at the examples I’d written, not at language in general.
I publish that row on purpose. A matcher that returns not found on six out of ten novel phrasings is limited. A matcher that confidently matched the wrong manual row would be dangerous. FixIt is designed to fail in the first way.
The server runs on Amazon Bedrock AgentCore Runtime as an ARM64 container (platform V2) with IAM SigV4 inbound auth. Getting there was the most friction-heavy part of the build, and I logged every snag as it happened.
State disappeared between conversations. Each Runtime session runs in its own microVM. My first version kept household appliances in local SQLite, which worked perfectly in Docker and forgot everything in production, because every new session started from a clean slate. Household state moved to AgentCore Memory, which survives across sessions.
IAM permissions fanned out. CreateAgentRuntime needs sub-permissions that the docs didn’t list, so they surfaced one AccessDenied at a time.
The docs pointed the wrong way. The custom-container guide I followed first didn’t fit an MCP server, and an AWS sample broke under mcp 2.x. I pinned mcp>=1.30,<2 and moved on.
Cold starts are real. Warm calls are fine for voice. A brand-new session takes about 5 seconds, and it isn’t documented how often Alexa+ would open one. I also saw an occasional front-door 504 (twice) and a harmless but confusing Session termination failed: 404 log line.
Every deploy follows the same routine: build the image, run it locally and smoke-test it, push it to ECR with a source-drift check that refuses to continue unless the image matches the current git commit, deploy a new runtime version (same ARN, version + 1), smoke-test the live runtime, then confirm a real household’s data in Memory was left untouched.
Observability: a CloudWatch dashboard, alarms on errors and tool latency, and SNS email alerts.
Grounding. I built an evaluation that asks realistic questions end to end and has a second model judge whether every claim in the answer is supported by the tool output. In one run of 63 cases, 62 were fully grounded (Claude Sonnet 4.5 answering, Claude Opus 4.6 judging). The case file has since grown to 72 cases, and I haven’t re-run it on Claude, so 62/63 is the number I can stand behind.
Judges need judging too. I tried Amazon Nova Pro as both answerer and judge on six new symptom cases. Three of six passed, and the Nova judge missed an invented “normal”: the answer called a condition normal when the manual said no such thing, and the judge let it through. A cheap judge that misses fabrications isn’t cheap. It’s blind.
Latency. From Dhaka, with roughly 320 ms of network round trip, warm calls measured about 500–650 ms client side. Cold sessions take about 5 seconds.
None of these numbers are perfect, and that’s the point of publishing them. A number you only share when it flatters you isn’t a measurement.
The hackathon came with a $150 AWS credit, and I planned to spend only that. Most of the stack was covered: AgentCore, Memory, ECR, CloudWatch, SNS, Polly, and Nova all billed against the credit.
Claude models on Bedrock did not. They are sold through AWS Marketplace, and Marketplace charges aren’t covered by promotional credits. I found out from my card statement, about $12 in September, and then confirmed it with the organizers.
The fix was operational rather than clever: an inline IAM deny policy on Anthropic models (Nova stays allowed), lifted only while recording the demo and put straight back, plus a $3 budget alert. It’s now an entry in the friction log, because the next builder deserves to know before the statement arrives.
Alexa+ developer tools (account linking, the local inspector, add-on submission) aren’t available to hackathon participants; the organizers confirmed this by email. So the demo uses a simulated Alexa+ client: a FastAPI backend and a web page that drive the deployed server through a Bedrock tool-use loop and render the MCP Apps cards, with optional Amazon Polly voice.
It is labelled as simulated on every screen, and the project claims no more than that. The MCP server is real and deployed. The client is a stand-in, and the next step is the OAuth account-linking path that would let real Alexa+ call it.
I want FixIt to outlive the hackathon, so it’s set up like a project other people can work on:
make try-it) so contributors can run the server without an AWS accountI built FixIt with AI assistance and the discipline I’d expect from a team:
A few rules did a lot of work. Nothing is “working” until there is output that shows it. Before every push, a leak check greps the outgoing history for account and resource identifiers, which must never land in a public repo. And the deployed image must match the commit it claims to be, or the deploy stops.
Watch the 2-minute demo, then clone the repo and run make try-it. You don’t need an AWS account.
If you’re building AI agents, MCP servers, or voice experiences and need them to be right rather than just fluent, I’m happy to talk: book a 30-minute call or find me on LinkedIn.
This project is open-source and available under the MIT License
tags: MCP - Model Context Protocol - Alexa+ - Amazon Bedrock - AgentCore - AI Agents - RAG - Document AI - Python - Evaluation - Open Source