[P2] Make the MCP App example convention-first; generate its contracts and implement the controls it advertises

[ScriptedAlchemy]

Scope / evidence

User-facing examples/mcp-app, audited at 72a8857ebe968636ac44dfc7ce4eba30664a8445. GitHub source review only; no browser/native execution was run. This is an example-adoption ticket, not a request to remove Agent Bundle's supported custom-server escape hatch.

Hand-rolled responsibilities and concrete drift

examples/mcp-app/src/mcp/status.ts constructs McpServer, indexes apps[0], manually registers the HTML resource and show-status, repeats App metadata and produces raw MCP content/structuredContent. The framework wraps stdio lifecycle, but operation/resource discovery and result projection remain application-authored SDK glue.

views/status-panel.ts already correctly uses createAppClient; do not claim it still owns a raw bridge. However it defines a manual StatusPanelRouteContracts/AppRegister map and loose browser result interfaces because the server is outside the conventional graph. That map includes tool:status/refresh-status, and the UI calls resources/read for ui://mcp-app-example/readiness-policy; the inspected server registers neither that tool nor that resource. Catching those failures and printing unavailable is not a working demonstration of the controls.

Existing replacement

Conventional src/mcp/<server>/tools, resources, and apps routes provide the compiler registry and generated browser contracts. inputSchema, resultSchema, Agent.Result, App metadata and the public appResourceUri association provide the ordinary implementation. Reuse the existing createAppClient and agent-bundle/meta integration. No custom renderer or second App bridge is required.

Work

• Make the primary documented MCP App journey use a generated server with conventional tool/resource/App routes.
• Move service health lookup into a small domain function; remove repeated SDK registration and raw protocol/result assembly from the primary example.
• Replace the browser's handwritten route map with compiler-generated input/result types; derive actual service enums/result fields from canonical schemas.
• Make refresh/read-policy controls invoke real declared operations, or remove/explicitly label an intentionally unavailable demonstration. Do not keep invented successful stubs as product evidence.
• Avoid positional apps[0] binding when the compiler can bind the named App directly.
• Preserve custom-factory interoperability tests separately. If a low-level example remains, label why it exists and do not present its glue as required metaframework authoring.
• Preserve existing opening-error UI, native consent, template appearance, resource identity compatibility and client disposal.

Acceptance

The compiled manifest, real tools/resources listing, generated App types and browser controls agree. A change to a tool schema reaches the browser typecheck without editing a second map. Exercise show status for both services, refresh, policy read, represented error, cancellation and denied calls through the real generated MCP server and the browser harness.

Tests must not make an absent tool/resource succeed solely through a mock host. Keep isolated bridge tests explicitly separate from end-to-end example acceptance. Pack/relocate/delete source and open the actual compiled App; assert all advertised normal controls work. Update README and English/Chinese references that link this example.

Non-goals

No abolition of custom MCP factories, forced JSX browser UI, duplicated test-harness protocol implementation, invented status backend, global auto-approval, or transfer of application status semantics into framework core.