chore: import upstream snapshot with attribution

2026-07-13 12:10:27 +08:00
commit 49b9bb6724
992 changed files with 161690 additions and 0 deletions
@@ -0,0 +1,73 @@
+# legacy-elicitation
+
+> **Legacy mechanism (2025 handshake era).** This story shows the push-style
+> server→client `elicitation/create` request; the 2026-07-28 protocol carries
+> elicitation as an `InputRequiredResult` round-trip instead — that path is the
+> [`mrtr/`](../mrtr/) story. Elicitation itself is **not** deprecated.
+> TODO(maxisbey): unify once the MRTR runtime lands
+> ([#2898](https://github.com/modelcontextprotocol/python-sdk/issues/2898)).
+> The TypeScript SDK ships a single dual-era `elicitation/` story; this
+> directory re-merges back into `elicitation/` once MRTR lands.
+
+A tool pauses mid-call to ask the user for structured input. On the
+handshake-era protocol the server pushes an `elicitation/create` *request* to
+the client and blocks until the client's `elicitation_callback` answers
+`accept` / `decline` / `cancel`. Two modes: **form** (`ctx.elicit(message,
+PydanticModel)` — schema derived from the model, accepted content validated
+back into it) and **url** (`ctx.elicit_url(...)` — directs the user out-of-band
+for OAuth / payment flows; `send_elicit_complete` notifies the client when the
+flow finishes).
+
+## Run it
+
+```bash
+# stdio (default — the client spawns the server as a subprocess)
+uv run python -m stories.legacy_elicitation.client
+
+# HTTP — the client self-hosts the server on a free port, runs, then tears it
+# down (--legacy: the push request needs the handshake era)
+uv run python -m stories.legacy_elicitation.client --http --legacy
+# same, against the lowlevel-API server variant
+uv run python -m stories.legacy_elicitation.client --http --legacy --server server_lowlevel
+```
+
+## What to look at
+
+- `client.py` `main` — the whole client setup is one visible construction:
+  `Client(target, mode=mode, elicitation_callback=on_elicit)`. Supplying
+  `elicitation_callback` is what advertises the `elicitation: {form, url}`
+  capability; `on_elicit` serves *both* modes by branching on
+  `isinstance(params, ElicitRequestURLParams)`.
+- `server.py` `register_user` — `await ctx.elicit("...", Registration)` derives
+  the form schema from the pydantic model and returns a typed
+  `ElicitationResult[Registration]`; narrow with `isinstance(answer,
+  AcceptedElicitation)` before reading `answer.data`.
+- `server.py` `link_account` — `ctx.elicit_url(...)` for out-of-band flows;
+  after the user finishes, `send_elicit_complete` emits
+  `notifications/elicitation/complete` so the client can correlate.
+- `server_lowlevel.py` — the same flow via `ctx.session.elicit_form` /
+  `ctx.session.elicit_url` and a hand-written `requestedSchema`.
+
+## Caveats
+
+- **Context paths.** `ctx.elicit` / `ctx.elicit_url` and the 2-hop
+  `ctx.request_context.session.send_elicit_complete` are interim; a later
+  release will shorten these.
+- **No per-mode opt-in.** Supplying any `elicitation_callback` advertises both
+  form and url support; there is currently no way to advertise form-only from
+  `Client`.
+- **Throw-style URL elicitation** (`raise UrlElicitationRequiredError([...])` →
+  wire `-32042`) is the stateless-transport alternative to `ctx.elicit_url`;
+  see `tests/interaction/lowlevel/test_elicitation.py` and the `error_handling`
+  story.
+
+## Spec
+
+[Elicitation — client features](https://modelcontextprotocol.io/specification/2025-11-25/client/elicitation)
+
+## See also
+
+`sampling/` (same push-request shape, deprecated per SEP-2577), `mrtr/`
+(the 2026-era carrier), `error_handling/`
+(`UrlElicitationRequiredError`), `refund_desk/` (resolver DI rides this push
+mechanism on handshake-era connections).