feat(server): /.well-known/adcp-agents.json discovery endpoint (#381)

[bokelley]

Summary

• Implements AdCP PR #3903 (commit 5c3e3e626) — every AdCP host now publishes an origin-scoped multi-agent topology manifest at /.well-known/adcp-agents.json.
• Wires the route into serve() for every HTTP transport (streamable-http, a2a, both); stdio has no HTTP surface and skips the route.
• Manifest builder lives in adcp.server.discovery as a pure function (also exposed via make_discovery_route) so adopters can publish a static manifest from CI.

What buyers see

$ curl http://localhost:3001/.well-known/adcp-agents.json
{
  "$schema": "/schemas/adcp-agents.json",
  "version": "1.0",
  "agents": [
    {
      "agent_id": "my-seller-mcp",
      "url": "https://sales.example.com/mcp",
      "transport": "mcp",
      "specialisms": ["sales-non-guaranteed"]
    },
    {
      "agent_id": "my-seller-a2a",
      "url": "https://sales.example.com",
      "transport": "a2a",
      "specialisms": ["sales-non-guaranteed"]
    }
  ],
  "contact": {"name": "my-seller"},
  "last_updated": "2026-05-02T00:00:00Z"
}

New serve() kwargs

• base_url — public origin used in manifest URLs. Defaults to http://<bind-host>:<port>; production deployments behind a TLS-terminating proxy SHOULD set this.
• specialisms — list of AdCP specialism tags (e.g. ["sales-non-guaranteed"]). Falls back to a placeholder; adopters who know their specialism SHOULD pass it.
• description — human-readable description surfaced in operator UIs.

Known gaps / TODOs

• Specialism inference — build_manifest() currently accepts specialisms verbatim. The handler's advertised tools could in principle infer a default specialism (e.g. get_products → sales-non-guaranteed), but that's a non-trivial mapping and would conflate "implements the tool" with "operator declares the specialism." Left as a TODO(#381) in discovery.py; placeholder works for adopters who haven't classified yet.
• auth_hint — schema-optional; not surfaced because the SDK doesn't own auth wiring. Adopters who want to advertise it can build their own manifest via build_manifest() and serve it through a custom route.

Test plan

• ruff check src/
• mypy src/adcp/
• pytest tests/ -k "discovery" (31 passed, 9 skipped)
• pytest tests/test_unified_mcp_a2a.py tests/test_serve_dx_polish.py tests/test_serve_asgi_middleware.py tests/test_a2a_server.py tests/test_server_dx.py tests/test_server_framework.py tests/test_server_helpers.py (194 passed) — no regressions
• New tests/test_discovery_endpoint.py covers GET on each transport, JSON-schema validation, POST falls through, agent_id normalization, builder unit tests
• CI green

🤖 Generated with Claude Code