wehub-resource-sync
49b9bb6724
Deploy Docs / deploy-docs (push) Failing after 1s
Conformance Tests / client-conformance (push) Failing after 3s
Conformance Tests / server-conformance (push) Failing after 1s
GitHub Actions Security Analysis / zizmor (push) Failing after 1s
CI / checks (push) Failing after 59m20s
CI / all-green (push) Has been cancelled
74 lines
3.5 KiB
Markdown
74 lines
3.5 KiB
Markdown
# 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).
|