fix(python/server): make MCP discovery work (ucp wrapper + minimal /mcp endpoint)

[dzuluaga]

Summary

Makes the Python reference server's UCP discovery work end-to-end for spec-conformant MCP clients, and keeps the bundled REST happy-path client working with the now-conformant profile. Three related changes:

1. Discovery profile envelope — serve the spec-required top-level ucp wrapper.
2. MCP transport endpoint — implement the /mcp endpoint the profile advertises (minimal: enough for discovery).
3. Client reads the wrapped profile — the happy-path client now reads payment_handlers from inside ucp.

1. Preserve required top-level ucp wrapper (routes/discovery.py)

The /.well-known/ucp handler unwrapped the ucp key from its own template before responding, emitting a flat profile. The UCP discovery-profile schema (discovery/profile.json → $defs.base.required = ["ucp"], for both 2026-01-23 and 2026-04-08) requires the wrapper, so conformant clients reject it:

PROFILE_SCHEMA_INVALID: ... ucp: Invalid input: expected object, received undefined

Fix: return the wrapped template as-is; default payment_handlers inside the ucp object. (The Node sample already serves the wrapped shape.)

2. Add a minimal MCP endpoint (routes/mcp.py)

The profile advertises an mcp transport at <endpoint>/mcp, but only REST routes were mounted, so MCP clients got HTTP 404 at that endpoint:

TRANSPORT_HTTP_ERROR: MCP request returned HTTP 404 from .../mcp

Fix: add a JSON-RPC /mcp route handling initialize and tools/list, advertising the five shopping checkout methods (create_checkout, get_checkout, update_checkout, complete_checkout, cancel_checkout) from the UCP shopping OpenRPC. Tool execution (tools/call) bridging to the existing REST checkout handlers is intentionally left as a follow-up.

3. Client reads payment_handlers from the ucp wrapper (client/flower_shop/simple_happy_path_client.py)

The happy-path client read payment_handlers from the document root, which only worked with the (non-conformant) flat profile. Once the server is fixed (#1), payment_handlers lives under ucp, so the client found 0 handlers and aborted at the payment step. Fix: read from ucp.payment_handlers (with a root fallback for legacy/flat profiles).

Verification

# MCP discovery (spec-conformant client):
$ ucp discover --business http://localhost:8182
SUCCESS  status: success
  negotiated: dev.ucp.shopping = (mcp, http://localhost:8182/mcp)
  tools: cancel_checkout, complete_checkout, create_checkout, get_checkout, update_checkout

# REST happy path (bundled client):
$ python simple_happy_path_client.py --server_url=http://localhost:8182
Merchant supports 3 payment handlers
... create -> items -> discount -> fulfillment -> delivery -> shipping ...
Payment Successful!  Checkout Status: completed
Happy Path completed successfully.

Scope

• Affected: rest/python/server + the bundled rest/python/client/flower_shop client. The Node sample (rest/nodejs) already serves the wrapped profile and is untouched.
• tools/call execution over MCP is out of scope (left as a follow-up).

🤖 Generated with Claude Code

[google-cla]

Thanks for your pull request! It looks like this may be your first contribution to a Google open source project. Before we can look at your pull request, you'll need to sign a Contributor License Agreement (CLA).

View this failed invocation of the CLA check for more information.

For the most up to date status, view the checks section at the bottom of the pull request.

[igrigorik]

Ty for catching and fixing this!

[dzuluaga]

Friendly nudge @westeezy / @jingyli 🙏 This one's approved by @igrigorik and all checks are green, just needs a 2nd approval to land. Would either of you mind taking a quick look?