Owns the product
Question and answer contract, API client, status wording, fonts, branding, attribution treatment, HTTP configuration and platform entry points.
One question, end to end
The answer service owns the answer. Ansari owns the application. The SAGA stack connects that meaning to an MCP card.
HostAnsari appSAGA stackAnsari API
HostConversationDiscovers, invokes and displays
→
Ansari appHono + MCP operationDeclares the input, answer envelope and view
↔
Ansari APIComplete answerReturns text and attribution unchanged
→
SAGA stackFaithfulCardRenders inside the host’s card surface
The answer, and every way it can arrive
The application supplies the presentation and every user-facing status sentence. The stack supplies the shared rendering and interaction mechanics.
Illustrative UI only. This is an explanation, not the running SDK card or a live Ansari answer.
What the code does
Image permission and external-link confirmation are different controls. The stack manages content policy and answer-scoped outcomes; the host decides how an allowed external navigation is confirmed.
Fonts before answers
Kitab Regular and Bold are embedded as bytes and loaded through FontFace. Font readiness has its own failure sentence; no device font is silently substituted for an answer.
Reading follows context
readingProfile comes from the stack. Ansari maps host colors, reading tokens and direction without changing answer data or applying a second root scale.
Attribution stays in the answer
The card renders the full answer once. Ansari watches the rendered closing block to style the attribution; the optional framework credit is separate.
Application meaning, shared mechanics
The browser imports one public stack. Hosting adapters inject their platform-specific inputs into one fetch application. Explore a module to see its real source and its boundary.
Owns the card connection
Host bridge, held/latest results, Markdown content, document policy, image consent, host links, own sizing and teardown. Server exports own view linkage and request-lifetime attachment.
Owns the conversation
Tool selection, permissions, discovery/cache behavior, card sandbox and external-navigation experience. The app does not dictate host refresh timing.
The root lockfile is authoritative. Frozen workspace installation and a root-context Docker smoke check protect packaging; they do not establish an actual host connection.
| Setting | Where it belongs | Why it matters |
|---|---|---|
| Upstream URL, client label, optional auth | Node environment / Worker bindings | Same client contract; secrets stay out of source. |
| Allowed Host and Origin | Named deployment environment | Validation matches the selected public endpoint. |
| Dev / Beta / Production | Distinct native Wrangler environment configuration | Select an explicit target and keep release/rollback decisions separate. |
| Application, SDK and resource identity | Built and served card metadata | Inspect the card actually loaded by the host, rather than assuming its cache is current. |
Four lifecycles meet at one card
A server release, a host catalog, a request and an embedded view each have a different owner and lifetime. Keeping them distinct explains refreshes, retries and teardown.
Build & serve
Install exact packages, build artifacts, configure a named target, start the application and prepare immutable view bytes.
Discover & refresh
Register an MCP endpoint and discover its tool and UI association. After a release, verify the host sees the current resource identity.
Invoke & finish
Send a question, call the API, return one full result and release the per-request server lifetime. Calls remain independent.
Mount & retire
Connect the bridge, wait for fonts, present the latest result and apply host context. Teardown releases owned browser resources.
What this walkthrough establishes
It explains checked application source, using real names and exact excerpts. The interactive diagrams and card examples are synthetic and make no network requests.
- Runtime and view composition are grounded in the complete application source of app
0.16.6as it is committed in this folder. - SAGA
0.7.6is installed from the public npm registry as one exact release; the root lockfile record its registry integrity. - This document is a fresh explanation of the full architecture, not a summary of changes from an earlier version.
What must be verified in a host
- A real tool invocation and an actual embedded answer card.
- Matching application revision, SDK identity and served resource bytes.
- Fonts, language direction, attribution, sizing and the relevant consent interactions.
- First-load success distinguished from recovery after Retry.
Rendering inside ChatGPT, Claude and Alexa+ is a separate host acceptance. Neither this document nor this repository’s automated checks establish it.
Read the source offline
Each path links to its exact source commit on GitHub. The embedded source remains available offline through “Read embedded source”.
Four lifecycles meet at one card
A server release, a host catalog, a request and an embedded view each have a different owner and lifetime. Keeping them distinct explains refreshes, retries and teardown.
Build & serve
Install exact packages, build artifacts, configure a named target, start the application and prepare immutable view bytes.
Discover & refresh
Register an MCP endpoint and discover its tool and UI association. After a release, verify the host sees the current resource identity.
Invoke & finish
Send a question, call the API, return one full result and release the per-request server lifetime. Calls remain independent.
Mount & retire
Connect the bridge, wait for fonts, present the latest result and apply host context. Teardown releases owned browser resources.
What this walkthrough establishes
It explains checked application source, using real names and exact excerpts. The interactive diagrams and card examples are synthetic and make no network requests.
- Runtime and view composition are grounded in the complete application source of app
0.16.6as it is committed in this folder. - SAGA
0.7.6is installed from the public npm registry as one exact release; the root lockfile records its registry integrity. - This document is a fresh explanation of the full architecture, not a summary of changes from an earlier version.
What must be verified in a host
- A real tool invocation and an actual embedded answer card.
- Matching application revision, SDK identity and served resource bytes.
- Fonts, language direction, attribution, sizing and the relevant consent interactions.
- First-load success distinguished from recovery after Retry.
Rendering inside ChatGPT, Claude and Alexa+ is a separate host acceptance. Neither this document nor this repository’s automated checks establish it.
Read the source offline
Each path links to its exact source commit on GitHub. The embedded source remains available offline through “Read embedded source”.
Why build on SAGA
Ansari could build this card directly on the MCP Apps SDK. Building on SAGA instead means Ansari starts from A2UI’s published protocol and a complete answer component, so its own code deals with answers and branding rather than MCP Apps wiring.
A published binding contract
A2UI specifies how component properties bind to data-model paths and how model updates converge. SAGA uses the upstream A2UI processor and React surface rather than a second binding engine. Ansari’s card binds two fields: the contract version and the answer Markdown.
A complete answer card
FaithfulCard renders the whole answer: nested lists, quotes, code, mixed-direction text, labelled scrollable tables, and links that open through the host with their hostname shown. It also handles answer replacement and view readiness. Ansari styles its documented surface with its own theme.css.
MCP Apps stays behind the stack
An MCP App has two ends of one iframe channel: the view’s App and the host’s AppBridge, with mirrored methods. A view can ask with requestTeardown(), but only the host’s AppBridge.teardownResource() tears the view down. The specification describes wire messages, with host and view rules side by side, and names neither class. AppBridge’s host role appears only in the overview diagram and its API reference, so a view author has to work out which half applies. Ansari’s source imports nothing from @modelcontextprotocol/ext-apps.
What a direct build would add
Rough estimate for the same card built on ext-apps, React and a maintained Markdown renderer:
- View: about 700–1,500 TS/TSX lines plus 100–200 CSS lines for the rendering rules, host links, readiness, sizing and lifecycle.
- Server: about 50–150 lines for the content-addressed card resource, output validation, failure mapping, the 60-second deadline and per-request cleanup.
- Together, about 750–1,850 lines, next to the app’s current 1,394 lines of source.
Tests are not counted. No direct version has been built, so these figures are order-of-magnitude estimates, not measured savings.
What Ansari still owns
- What an answer means and every user-facing status sentence.
- The theme, host-color mapping, Kitab fonts, floral artwork and attribution treatment.
- Hono hosting, the Node and Worker entry points, and deployment.
- SAGA upgrades and host acceptance.
In exchange, fixes to parsing, the card and delivery arrive from upstream with their regression tests (saga-a2ui, Apache-2.0).