Skip to content

Commit dbe9564

Browse files
benbrandtbenbrandt
committed
Refactor elicitation scopes into named structs
Extract session and request elicitation scopes into reusable `ElicitationSessionScope` and `ElicitationRequestScope` types, update tests to use their constructors, and reuse the new schema definitions in the draft docs and unstable JSON schema.
1 parent 01522e0 commit dbe9564

3 files changed

Lines changed: 201 additions & 139 deletions

File tree

‎docs/protocol/draft/schema.mdx‎

Lines changed: 62 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -3343,13 +3343,9 @@ Form-based elicitation mode where the client renders a form from the provided sc
33433343

33443344
**Variants:**
33453345

3346-
<ResponseField name="Session" type="object">
3346+
<ResponseField name="Session">
33473347
Tied to a session, optionally to a specific tool call within that session.
33483348

3349-
When `tool_call_id` is set, the elicitation is tied to a specific tool call.
3350-
This is useful when an agent receives an elicitation from an MCP server
3351-
during a tool call and needs to redirect it to the user.
3352-
33533349
<Expandable title="Properties">
33543350

33553351
<ResponseField
@@ -3376,7 +3372,7 @@ during a tool call and needs to redirect it to the user.
33763372
</Expandable>
33773373
</ResponseField>
33783374

3379-
<ResponseField name="Request" type="object">
3375+
<ResponseField name="Request">
33803376
Tied to a specific JSON-RPC request outside of a session
33813377
(e.g., during auth/configuration phases before any session is started).
33823378

@@ -3569,6 +3565,27 @@ Multi-select array property.
35693565
</Expandable>
35703566
</ResponseField>
35713567

3568+
## <span class="font-mono">ElicitationRequestScope</span>
3569+
3570+
**UNSTABLE**
3571+
3572+
This capability is not part of the spec yet, and may be removed or changed at any point.
3573+
3574+
Request-scoped elicitation, tied to a specific JSON-RPC request outside of a session
3575+
(e.g., during auth/configuration phases before any session is started).
3576+
3577+
**Type:** Object
3578+
3579+
**Properties:**
3580+
3581+
<ResponseField
3582+
name="requestId"
3583+
type={<a href="#requestid">RequestId</a>}
3584+
required
3585+
>
3586+
The request this elicitation is tied to.
3587+
</ResponseField>
3588+
35723589
## <span class="font-mono">ElicitationSchema</span>
35733590

35743591
Type-safe elicitation schema for requesting structured user input.
@@ -3612,6 +3629,43 @@ Type discriminator for elicitation schemas.
36123629
Object schema type.
36133630
</ResponseField>
36143631

3632+
## <span class="font-mono">ElicitationSessionScope</span>
3633+
3634+
**UNSTABLE**
3635+
3636+
This capability is not part of the spec yet, and may be removed or changed at any point.
3637+
3638+
Session-scoped elicitation, optionally tied to a specific tool call.
3639+
3640+
When `tool_call_id` is set, the elicitation is tied to a specific tool call.
3641+
This is useful when an agent receives an elicitation from an MCP server
3642+
during a tool call and needs to redirect it to the user.
3643+
3644+
**Type:** Object
3645+
3646+
**Properties:**
3647+
3648+
<ResponseField
3649+
name="sessionId"
3650+
type={<a href="#sessionid">SessionId</a>}
3651+
required
3652+
>
3653+
The session this elicitation is tied to.
3654+
</ResponseField>
3655+
<ResponseField
3656+
name="toolCallId"
3657+
type={
3658+
<>
3659+
<span>
3660+
<a href="#toolcallid">ToolCallId</a>
3661+
</span>
3662+
<span> | null</span>
3663+
</>
3664+
}
3665+
>
3666+
Optional tool call within the session.
3667+
</ResponseField>
3668+
36153669
## <span class="font-mono">ElicitationStringType</span>
36163670

36173671
Items definition for untitled multi-select enum properties.
@@ -3668,13 +3722,9 @@ URL-based elicitation mode where the client directs the user to a URL.
36683722

36693723
**Variants:**
36703724

3671-
<ResponseField name="Session" type="object">
3725+
<ResponseField name="Session">
36723726
Tied to a session, optionally to a specific tool call within that session.
36733727

3674-
When `tool_call_id` is set, the elicitation is tied to a specific tool call.
3675-
This is useful when an agent receives an elicitation from an MCP server
3676-
during a tool call and needs to redirect it to the user.
3677-
36783728
<Expandable title="Properties">
36793729

36803730
<ResponseField
@@ -3701,7 +3751,7 @@ during a tool call and needs to redirect it to the user.
37013751
</Expandable>
37023752
</ResponseField>
37033753

3704-
<ResponseField name="Request" type="object">
3754+
<ResponseField name="Request">
37053755
Tied to a specific JSON-RPC request outside of a session
37063756
(e.g., during auth/configuration phases before any session is started).
37073757

‎schema/schema.unstable.json‎

Lines changed: 65 additions & 74 deletions
Original file line numberDiff line numberDiff line change
@@ -2133,47 +2133,22 @@
21332133
"ElicitationFormMode": {
21342134
"anyOf": [
21352135
{
2136-
"description": "Tied to a session, optionally to a specific tool call within that session.\n\nWhen `tool_call_id` is set, the elicitation is tied to a specific tool call.\nThis is useful when an agent receives an elicitation from an MCP server\nduring a tool call and needs to redirect it to the user.",
2137-
"properties": {
2138-
"sessionId": {
2139-
"allOf": [
2140-
{
2141-
"$ref": "#/$defs/SessionId"
2142-
}
2143-
],
2144-
"description": "The session this elicitation is tied to."
2145-
},
2146-
"toolCallId": {
2147-
"anyOf": [
2148-
{
2149-
"$ref": "#/$defs/ToolCallId"
2150-
},
2151-
{
2152-
"type": "null"
2153-
}
2154-
],
2155-
"description": "Optional tool call within the session."
2136+
"allOf": [
2137+
{
2138+
"$ref": "#/$defs/ElicitationSessionScope"
21562139
}
2157-
},
2158-
"required": ["sessionId"],
2159-
"title": "Session",
2160-
"type": "object"
2140+
],
2141+
"description": "Tied to a session, optionally to a specific tool call within that session.",
2142+
"title": "Session"
21612143
},
21622144
{
2163-
"description": "Tied to a specific JSON-RPC request outside of a session\n(e.g., during auth/configuration phases before any session is started).",
2164-
"properties": {
2165-
"requestId": {
2166-
"allOf": [
2167-
{
2168-
"$ref": "#/$defs/RequestId"
2169-
}
2170-
],
2171-
"description": "The request this elicitation is tied to."
2145+
"allOf": [
2146+
{
2147+
"$ref": "#/$defs/ElicitationRequestScope"
21722148
}
2173-
},
2174-
"required": ["requestId"],
2175-
"title": "Request",
2176-
"type": "object"
2149+
],
2150+
"description": "Tied to a specific JSON-RPC request outside of a session\n(e.g., during auth/configuration phases before any session is started).",
2151+
"title": "Request"
21772152
}
21782153
],
21792154
"description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nForm-based elicitation mode where the client renders a form from the provided schema.",
@@ -2282,6 +2257,21 @@
22822257
}
22832258
]
22842259
},
2260+
"ElicitationRequestScope": {
2261+
"description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nRequest-scoped elicitation, tied to a specific JSON-RPC request outside of a session\n(e.g., during auth/configuration phases before any session is started).",
2262+
"properties": {
2263+
"requestId": {
2264+
"allOf": [
2265+
{
2266+
"$ref": "#/$defs/RequestId"
2267+
}
2268+
],
2269+
"description": "The request this elicitation is tied to."
2270+
}
2271+
},
2272+
"required": ["requestId"],
2273+
"type": "object"
2274+
},
22852275
"ElicitationSchema": {
22862276
"description": "Type-safe elicitation schema for requesting structured user input.\n\nThis represents a JSON Schema object with primitive-typed properties,\nas required by the elicitation specification.",
22872277
"properties": {
@@ -2330,6 +2320,32 @@
23302320
}
23312321
]
23322322
},
2323+
"ElicitationSessionScope": {
2324+
"description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nSession-scoped elicitation, optionally tied to a specific tool call.\n\nWhen `tool_call_id` is set, the elicitation is tied to a specific tool call.\nThis is useful when an agent receives an elicitation from an MCP server\nduring a tool call and needs to redirect it to the user.",
2325+
"properties": {
2326+
"sessionId": {
2327+
"allOf": [
2328+
{
2329+
"$ref": "#/$defs/SessionId"
2330+
}
2331+
],
2332+
"description": "The session this elicitation is tied to."
2333+
},
2334+
"toolCallId": {
2335+
"anyOf": [
2336+
{
2337+
"$ref": "#/$defs/ToolCallId"
2338+
},
2339+
{
2340+
"type": "null"
2341+
}
2342+
],
2343+
"description": "Optional tool call within the session."
2344+
}
2345+
},
2346+
"required": ["sessionId"],
2347+
"type": "object"
2348+
},
23332349
"ElicitationStringType": {
23342350
"description": "Items definition for untitled multi-select enum properties.",
23352351
"oneOf": [
@@ -2354,47 +2370,22 @@
23542370
"ElicitationUrlMode": {
23552371
"anyOf": [
23562372
{
2357-
"description": "Tied to a session, optionally to a specific tool call within that session.\n\nWhen `tool_call_id` is set, the elicitation is tied to a specific tool call.\nThis is useful when an agent receives an elicitation from an MCP server\nduring a tool call and needs to redirect it to the user.",
2358-
"properties": {
2359-
"sessionId": {
2360-
"allOf": [
2361-
{
2362-
"$ref": "#/$defs/SessionId"
2363-
}
2364-
],
2365-
"description": "The session this elicitation is tied to."
2366-
},
2367-
"toolCallId": {
2368-
"anyOf": [
2369-
{
2370-
"$ref": "#/$defs/ToolCallId"
2371-
},
2372-
{
2373-
"type": "null"
2374-
}
2375-
],
2376-
"description": "Optional tool call within the session."
2373+
"allOf": [
2374+
{
2375+
"$ref": "#/$defs/ElicitationSessionScope"
23772376
}
2378-
},
2379-
"required": ["sessionId"],
2380-
"title": "Session",
2381-
"type": "object"
2377+
],
2378+
"description": "Tied to a session, optionally to a specific tool call within that session.",
2379+
"title": "Session"
23822380
},
23832381
{
2384-
"description": "Tied to a specific JSON-RPC request outside of a session\n(e.g., during auth/configuration phases before any session is started).",
2385-
"properties": {
2386-
"requestId": {
2387-
"allOf": [
2388-
{
2389-
"$ref": "#/$defs/RequestId"
2390-
}
2391-
],
2392-
"description": "The request this elicitation is tied to."
2382+
"allOf": [
2383+
{
2384+
"$ref": "#/$defs/ElicitationRequestScope"
23932385
}
2394-
},
2395-
"required": ["requestId"],
2396-
"title": "Request",
2397-
"type": "object"
2386+
],
2387+
"description": "Tied to a specific JSON-RPC request outside of a session\n(e.g., during auth/configuration phases before any session is started).",
2388+
"title": "Request"
23982389
}
23992390
],
24002391
"description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nURL-based elicitation mode where the client directs the user to a URL.",

0 commit comments

Comments
 (0)