Skip to content

docs(mcp): refresh the walkthrough and add a Why SAGA chapter - #5

Merged
timeleft-- merged 3 commits into
codex/ansari-faithful-answers-076from
claude/mcp-walkthrough-repairs
Oct 29, 2026
Merged

timeleft-- merged 3 commits into
codex/ansari-faithful-answers-076from
claude/mcp-walkthrough-repairs

Conversation

@timeleft--

@timeleft-- timeleft-- commented Oct 29, 2026 •

Copy link
Copy Markdown
Member

Repairs the stale parts of apps/mcp/docs/show-me-ansari-mcp.html found while checking it against the PR head (822c1cf) for iaser-ai#323.

Changes

  • Source links. The links pointed at 8b5da23 (app 0.16.5 on SAGA 0.7.6-rc.1) under the old apps/ansari-faithful-answers/ path. Five of the linked files differ there from the copies the page embeds, and scripts/third-party-licences.ts doesn't exist there. They now point at apps/mcp/ at 822c1cf.
  • Licence notice. The "Assets and licenses" dialog had the earlier artwork wording. It now carries the MIT grant from apps/mcp/assets/NOTICE.md, and says that SAGA's licence and third-party notices are retained in the distributed card HTML.
  • Typo. "the root lockfile record its" becomes "records".
  • README. Removed the apps/mcp/README.md sentence describing a hosted lifecycle addendum. The walkthrough hasn't contained one since 8b5da23.
  • 301 review. codev/reviews/301-faithful-answers-mcp.md records the link and notice update in its PR feat: add Ansari MCP app with stable saga a2ui 0.7.6 iaser-ai/ansari#323 repairs section. The section about the workspace move still says the walkthrough keeps its original links. The opening section now has an "Original contribution" heading, since it describes CI before the review repairs.

Everything else on the page already matched the head: all 17 embedded source files and every excerpt are byte-identical to 822c1cf, and the stated versions, commands, limits and environments are correct. Lint is already applied: eslint . --fix changes no file, so the linked sources are stable.

  • Why SAGA chapter. A new seventh tab explains why the app builds on SAGA instead of directly on the MCP Apps SDK. It covers A2UI's published binding contract, FaithfulCard as a complete answer component, and how the stack keeps MCP Apps' two-sided App/AppBridge API out of Ansari's code (Ansari's source imports nothing from @modelcontextprotocol/ext-apps). It also gives the rough estimate for a direct build (about 750–1,850 more lines, tests excluded, nothing built to measure it) and lists what Ansari still owns. The README's description of the walkthrough mentions the new chapter.

Validation

  • The embedded walkthrough data parses, and none of the old commit, the old path or the typo remain.
  • All 17 source links the page builds return HTTP 200.
  • Rechecked the 301 review's repair claims at 822c1cf: 142 of 142 server/packaging tests and 73 of 73 browser checks pass, and all 1,669 lockfile snapshots match 137c96a.
  • Rendered headlessly with the app's Playwright Chromium at 1280, 900 and 375 px, plus dark theme. The new tab selects and hides the other panels, arrow keys wrap across all seven tabs, there is no horizontal overflow and no script errors. Desktop shows the seven tabs in one row; narrower layouts wrap as before.
  • The four new external links return HTTP 200, including the A2UI binding-scope anchor.

Docs only, so no version bump.

🤖 Generated with Claude Code

The walkthrough's source links pointed at the app 0.16.5 / SAGA 0.7.6-rc.1
commit under the old apps/ansari-faithful-answers path, where five linked
files differ from the embedded copies and third-party-licences.ts is absent.
They now point at apps/mcp at 822c1cf, whose files match the embedded
sources byte for byte.

The Assets and licenses notice now carries the MIT artwork grant from
assets/NOTICE.md and says SAGA's notices travel in the card HTML. Also fix
a typo, and drop the README's mention of a hosted lifecycle addendum the
walkthrough no longer contains.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

@yia-mw-agent yia-mw-agent left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Reviewed the full merge-base-to-head diff (base codex/ansari-faithful-answers-076 at 822c1cf, head cd4d1f3, two files, +11/-10). No material defects.

Checked:

  • SOURCE_BASE now points at MachineWisdomAI/ansari, commit 822c1cf, apps/mcp/. That commit is the PR base, and all 17 files in the embedded sources map are byte-identical to apps/mcp/ there, including scripts/third-party-licences.ts.
  • The licence block in the footer matches the opening of apps/mcp/assets/NOTICE.md exactly (copyright line, MIT grant, SAGA/OFL sentence), apart from the OFL text the page already carried. LICENSE at the repo root is MIT, so the relative link text is accurate.
  • The "records" typo fix and the README sentence removal are correct. No references to 8b5da23, the old apps/ansari-faithful-answers path, or a hosted lifecycle addendum remain in either file.
  • Nothing else in the repo references the walkthrough, so there is no downstream breakage. Docs only, so no version bump is needed.

Non-blocking: when I submitted, the api, auth and MCP application checks were still in progress. frontend and gitleaks had passed. The diff touches neither code nor tests. The page was not rendered in a browser, which the PR description also notes.

Helmet-Review-Request: #5 (comment)

The placement section says the walkthrough keeps its source links at the
original revision. Record in the repairs section that they now point at
apps/mcp at 822c1cf, along with the MIT artwork notice. Head the opening
section as the original contribution, since its standalone-CI account
predates the review repairs.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

@yia-mw-agent yia-mw-agent left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Helmet-Review-Request: #5 (comment)

Reviewed the full merge-base-to-head diff (base codex/ansari-faithful-answers-076 at merge-base 822c1cf, head 571e838; 3 docs files, +16/-10). The live head matched the selected head when I started and again before submitting.

Checked:

  • SOURCE_BASE now points at MachineWisdomAI/ansari apps/mcp/ at 822c1cf. That commit exists in the repository. No 8b5da23, apps/ansari-faithful-answers/ or timeleft-- reference remains in the page.
  • All 17 embedded source files in the walkthrough data are byte-identical to apps/mcp/<file> at the PR head. I compared them programmatically.
  • The "Assets and licenses" dialog opens with the same text as apps/mcp/assets/NOTICE.md, including the MIT grant and the revised SAGA/OFL sentence. The OFL text that follows is unchanged. The "record" to "records" typo is fixed.
  • The README sentence about a hosted lifecycle addendum is removed. The page has no such section, and nothing else references that sentence.
  • The codev/reviews/301-faithful-answers-mcp.md additions are consistent with the diff. The new "Original contribution" heading and the blank line before the next heading are cosmetic.
  • Docs only, with no code or version change. The one script change swaps a string constant.

No material defects.

Non-blocking:

  • The dialog text repeats the [MIT licence](../../../LICENSE) Markdown link from NOTICE.md inside a <pre>, so it shows as literal text and not as a working link. This matches the source notice and is harmless.
  • The PR says the page was not rendered in a browser, so I did not render it either. Given the change size, I do not consider that blocking.

A seventh chapter explains why the app builds on SAGA rather than
directly on the MCP Apps SDK: A2UI's published binding contract,
FaithfulCard as a complete answer component, and a view that never
touches MCP Apps' two-sided App/AppBridge API. It gives the rough
code estimate for a direct build and what Ansari still owns. The tab
grid widens to seven columns on desktop; narrower layouts already wrap.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@timeleft-- timeleft-- changed the title docs(mcp): point the walkthrough at the current source and licence docs(mcp): refresh the walkthrough and add a Why SAGA chapter Oct 29, 2026

@yia-mw-agent yia-mw-agent left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Helmet-Review-Request: #5 (comment)

Reviewed the full merge-base (822c1cf) to head (6a1ba66) diff against codex/ansari-faithful-answers-076: 3 files, docs only (README, walkthrough HTML, 301 review). No material defects.

Checked:

  • All 17 sources embedded in the walkthrough are byte-identical to apps/mcp/ at the head, and SOURCE_BASE now points at MachineWisdomAI/ansari at 822c1cf under apps/mcp/. No 8b5da23, apps/ansari-faithful-answers/ or record its text remains. The embedded JSON parses.
  • The licence dialog text matches apps/mcp/assets/NOTICE.md, which this PR does not change, so the packaging test that compares the notice with the built artifact is unaffected. The root LICENSE is MIT.
  • Why SAGA chapter: the tab and panel IDs and ARIA wiring are consistent. The tab script is generic over all tabs, so arrow keys wrap across seven. The CSS media rules scope the 7-column layout to wide screens. The four external links return HTTP 200. apps/mcp/src contains no ext-apps import, as claimed (it is a devDependency only). The app source is 1,394 lines across 25 files, matching the text. The estimate is labelled as unmeasured.
  • The README sentence no longer describes the missing lifecycle addendum. The 301 review additions are consistent with the PR description.
  • No runtime, source or test files are touched, so I did not rerun the install-dependent suites.

Non-blocking: none.

@timeleft--
timeleft-- merged commit 052fbaf into codex/ansari-faithful-answers-076 Oct 29, 2026
5 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants