docs: improve MCP Apps integration guide with step-by-step walkthrough

[zeroasterisk]

Summary

Walked through the MCP Apps guide as a new developer and found several issues. This PR improves the guide with clearer step-by-step instructions, correct paths, and troubleshooting tips.

Issues Found & Fixed

1. Wrong agent path: Guide referenced samples/agent/adk/contact_multiple_surfaces/ which doesn't exist — the correct path is samples/agent/adk/contact_lookup/
2. Wrong Lit client path: Guide said to run npm run dev in samples/client/lit/contact/ but that directory has no package.json — the actual commands should run from samples/client/lit/
3. Missing prerequisite steps: No mention of npm install, npm run build:renderer (Lit), or npm run build:sandbox (Angular) — these are required before clients will work
4. No Python version note: The contact_lookup agent requires Python ≥ 3.13 per its pyproject.toml, but the guide only said "3.12 or higher suggested"
5. No multi-terminal guidance: Samples need 2-3 simultaneous processes but the guide didn't mention this
6. Missing GEMINI_API_KEY setup details: Only said "requires GEMINI_API_KEY in .env" without explaining how to set it up (export vs .env file)
7. Fixed source link: Updated mcp-apps-component.ts GitHub link to correct path under custom-components-example
8. Added demo:contact shortcut: Mentioned the convenient npm script that runs everything together
9. Added troubleshooting table: Common errors and solutions for new developers

[gemini-code-assist]

Code Review

This pull request updates the documentation for MCP Apps in A2UI, providing comprehensive prerequisites, step-by-step execution guides for the Lit and Angular samples, and a troubleshooting section. A security review identified critical discrepancies between the documentation's security model and the actual implementation in the linked Lit sample code, specifically regarding iframe sandboxing and the use of the allow-same-origin attribute.

[gemini-code-assist]

The linked Lit example (mcp-apps-component.ts) contains two discrepancies with the security model described in this guide:

1. Outer Iframe Sandboxing: The guide states that the host template should not sandbox the proxy iframe (line 24). However, the Lit component includes a sandbox attribute with allow-same-origin (line 79 of that file).
2. Inner Iframe Isolation: The guide emphasizes that the inner iframe MUST NOT include allow-same-origin (lines 19 and 27). However, the Lit component explicitly includes it when calling sendSandboxResourceReady (line 179 of that file).

These should be corrected in the sample code to ensure it serves as a secure and consistent reference implementation. The Angular example (mcp-app.ts) correctly follows these principles.

[zeroasterisk]

Good catch — verified this is a real issue.

Angular sample correctly passes sandbox: 'allow-scripts' to sendSandboxResourceReady() (line ~89 of mcp-app.ts), so the inner iframe ends up with only allow-scripts.

Lit sample passes sandbox: 'allow-scripts allow-forms allow-popups allow-modals allow-same-origin' (line ~179 of mcp-apps-component.ts), which violates the guide's security model.

Additionally:

• The outer iframe in Lit has sandbox="allow-scripts allow-forms allow-popups allow-modals allow-same-origin" (line 79) — the guide says the proxy iframe should not be sandboxed.
• The shared sandbox.ts (line 66) sets an initial default of allow-scripts allow-same-origin allow-forms on the inner iframe before sendSandboxResourceReady overrides it — this means there's a brief window where the inner iframe has allow-same-origin.

This is a docs PR so fixing the Lit sample code is out of scope here, but it should be filed as a separate issue. The guide's security model description is correct — the Lit sample doesn't follow it.