Skip to content

Commit b03da23

Browse files
authored
Merge pull request #482 from koic/elicitation_enum_schema
Add `MCP::Elicitation::EnumSchema` builders for SEP-1330
2 parents 2c3c307 + b54eeba commit b03da23

6 files changed

Lines changed: 361 additions & 34 deletions

File tree

‎README.md‎

Lines changed: 58 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1984,6 +1984,64 @@ server.define_tool(name: "configure_deploy", description: "Configure a deploymen
19841984
end
19851985
```
19861986

1987+
#### Enum Schemas
1988+
1989+
For enumerated choices, use `MCP::Elicitation::EnumSchema` to construct the canonical schema shapes per
1990+
[SEP-1330](https://github.com/modelcontextprotocol/modelcontextprotocol/issues/1330) instead of building
1991+
the underlying Hash by hand. The five class methods cover titled and untitled, single-select and multi-select,
1992+
plus the legacy `enumNames` form retained for backward compatibility:
1993+
1994+
```ruby
1995+
size_schema = MCP::Elicitation::EnumSchema.titled_single_select(
1996+
options: [
1997+
{ value: "s", title: "Small" },
1998+
{ value: "m", title: "Medium" },
1999+
{ value: "l", title: "Large" },
2000+
],
2001+
default: "m",
2002+
)
2003+
2004+
tags_schema = MCP::Elicitation::EnumSchema.untitled_multi_select(
2005+
values: ["urgent", "billing", "feedback"],
2006+
)
2007+
2008+
result = server_context.create_form_elicitation(
2009+
message: "Tell us about your order",
2010+
requested_schema: {
2011+
type: "object",
2012+
properties: {
2013+
size: size_schema.to_h,
2014+
tags: tags_schema.to_h,
2015+
},
2016+
required: ["size"],
2017+
},
2018+
)
2019+
```
2020+
2021+
The available builders are `untitled_single_select`, `titled_single_select`, `untitled_multi_select`, `titled_multi_select`,
2022+
and `legacy_titled`. Each accepts optional `default:`, `title:`, and `description:`.
2023+
2024+
The same builders produce the `requestedSchema` of an `elicitation/create` request embedded in a SEP-2322 `input_required` result,
2025+
which is how elicitation reaches clients on the stateless 2026-07-28 lifecycle:
2026+
2027+
```ruby
2028+
MCP::Server::InputRequiredResult.new(
2029+
input_requests: {
2030+
"size" => {
2031+
method: "elicitation/create",
2032+
params: {
2033+
message: "Pick a size",
2034+
requestedSchema: {
2035+
type: "object",
2036+
properties: { size: size_schema.to_h },
2037+
required: ["size"],
2038+
},
2039+
},
2040+
},
2041+
},
2042+
)
2043+
```
2044+
19872045
#### URL Mode
19882046

19892047
URL mode directs the user to an external URL for out-of-band interactions such as OAuth flows:

‎conformance/server.rb‎

Lines changed: 28 additions & 34 deletions
Original file line numberDiff line numberDiff line change
@@ -257,7 +257,9 @@ def call(server_context:, **_args)
257257
name: { type: "string", default: "John Doe" },
258258
age: { type: "integer", default: 30 },
259259
score: { type: "number", default: 95.5 },
260-
status: { type: "string", enum: ["active", "inactive", "pending"], default: "active" },
260+
status: MCP::Elicitation::EnumSchema.untitled_single_select(
261+
values: ["active", "inactive", "pending"], default: "active",
262+
).to_h,
261263
verified: { type: "boolean", default: true },
262264
},
263265
},
@@ -273,45 +275,37 @@ class TestElicitationSep1330Enums < MCP::Tool
273275

274276
class << self
275277
def call(server_context:, **_args)
278+
# Built with the SEP-1330 builders so the conformance run exercises the same schemas
279+
# the SDK produces for users.
276280
result = server_context.create_form_elicitation(
277281
message: "Please select options",
278282
requested_schema: {
279283
type: "object",
280284
properties: {
281-
untitledSingle: {
282-
type: "string",
283-
enum: ["option1", "option2", "option3"],
284-
},
285-
titledSingle: {
286-
type: "string",
287-
oneOf: [
288-
{ const: "value1", title: "First Option" },
289-
{ const: "value2", title: "Second Option" },
290-
{ const: "value3", title: "Third Option" },
285+
untitledSingle: MCP::Elicitation::EnumSchema.untitled_single_select(
286+
values: ["option1", "option2", "option3"],
287+
).to_h,
288+
titledSingle: MCP::Elicitation::EnumSchema.titled_single_select(
289+
options: [
290+
{ value: "value1", title: "First Option" },
291+
{ value: "value2", title: "Second Option" },
292+
{ value: "value3", title: "Third Option" },
291293
],
292-
},
293-
legacyEnum: {
294-
type: "string",
295-
enum: ["opt1", "opt2", "opt3"],
296-
enumNames: ["Option One", "Option Two", "Option Three"],
297-
},
298-
untitledMulti: {
299-
type: "array",
300-
items: {
301-
type: "string",
302-
enum: ["option1", "option2", "option3"],
303-
},
304-
},
305-
titledMulti: {
306-
type: "array",
307-
items: {
308-
anyOf: [
309-
{ const: "value1", title: "First Choice" },
310-
{ const: "value2", title: "Second Choice" },
311-
{ const: "value3", title: "Third Choice" },
312-
],
313-
},
314-
},
294+
).to_h,
295+
legacyEnum: MCP::Elicitation::EnumSchema.legacy_titled(
296+
values: ["opt1", "opt2", "opt3"],
297+
value_titles: ["Option One", "Option Two", "Option Three"],
298+
).to_h,
299+
untitledMulti: MCP::Elicitation::EnumSchema.untitled_multi_select(
300+
values: ["option1", "option2", "option3"],
301+
).to_h,
302+
titledMulti: MCP::Elicitation::EnumSchema.titled_multi_select(
303+
options: [
304+
{ value: "value1", title: "First Choice" },
305+
{ value: "value2", title: "Second Choice" },
306+
{ value: "value3", title: "Third Choice" },
307+
],
308+
).to_h,
315309
},
316310
},
317311
)

‎lib/mcp.rb‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,7 @@ module MCP
1414
autoload :CancelledError, "mcp/cancelled_error"
1515
autoload :Client, "mcp/client"
1616
autoload :Content, "mcp/content"
17+
autoload :Elicitation, "mcp/elicitation"
1718
autoload :ErrorCodes, "mcp/error_codes"
1819
autoload :Icon, "mcp/icon"
1920
autoload :Prompt, "mcp/prompt"

‎lib/mcp/elicitation.rb‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
# frozen_string_literal: true
2+
3+
module MCP
4+
# Builders for elicitation `requestedSchema` definitions per MCP 2025-11-25.
5+
# Each builder returns an instance whose `to_h` produces the JSON-Schema-shaped Hash
6+
# a server passes as a property value in `create_form_elicitation(requested_schema:)`.
7+
module Elicitation
8+
autoload :EnumSchema, "mcp/elicitation/enum_schema"
9+
end
10+
end

‎lib/mcp/elicitation/enum_schema.rb‎

Lines changed: 121 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,121 @@
1+
# frozen_string_literal: true
2+
3+
module MCP
4+
module Elicitation
5+
# Builds the four enum schema variants defined by MCP 2025-11-25 (SEP-1330) plus the legacy `enumNames` form
6+
# retained for backward compatibility.
7+
#
8+
# Each class method returns an `EnumSchema` instance; call `to_h` to get the property-value Hash and
9+
# pass it through `requested_schema` to `ServerSession#create_form_elicitation`.
10+
class EnumSchema
11+
class << self
12+
# Single-select with plain string values: `{ type: "string", enum: [...] }`.
13+
def untitled_single_select(values:, default: nil, title: nil, description: nil)
14+
validate_values!(values)
15+
16+
new(
17+
type: "string",
18+
extras: { enum: values },
19+
default: default,
20+
title: title,
21+
description: description,
22+
)
23+
end
24+
25+
# Single-select with display titles per option: `{ type: "string", oneOf: [{ const, title }, ...] }`.
26+
# `options` is an Array of `{ value:, title: }` hashes.
27+
def titled_single_select(options:, default: nil, title: nil, description: nil)
28+
validate_titled_options!(options)
29+
30+
new(
31+
type: "string",
32+
extras: { oneOf: options.map { |o| { const: o[:value], title: o[:title] } } },
33+
default: default,
34+
title: title,
35+
description: description,
36+
)
37+
end
38+
39+
# Multi-select with plain string values: `{ type: "array", items: { type: "string", enum: [...] } }`.
40+
def untitled_multi_select(values:, default: nil, title: nil, description: nil)
41+
validate_values!(values)
42+
43+
new(
44+
type: "array",
45+
extras: { items: { type: "string", enum: values } },
46+
default: default,
47+
title: title,
48+
description: description,
49+
)
50+
end
51+
52+
# Multi-select with display titles per option: `{ type: "array", items: { anyOf: [{ const, title }, ...] } }`.
53+
def titled_multi_select(options:, default: nil, title: nil, description: nil)
54+
validate_titled_options!(options)
55+
56+
items_anyof = options.map { |o| { const: o[:value], title: o[:title] } }
57+
new(
58+
type: "array",
59+
extras: { items: { anyOf: items_anyof } },
60+
default: default,
61+
title: title,
62+
description: description,
63+
)
64+
end
65+
66+
# Legacy single-select retained for backward compatibility with clients implementing
67+
# the pre-SEP-1330 form: `{ enum, enumNames }`.
68+
def legacy_titled(values:, value_titles:, default: nil, title: nil, description: nil)
69+
validate_values!(values)
70+
unless value_titles.is_a?(Array) && value_titles.length == values.length
71+
raise ArgumentError, "value_titles must be an Array of the same length as values"
72+
end
73+
74+
new(
75+
type: "string",
76+
extras: { enum: values, enumNames: value_titles },
77+
default: default,
78+
title: title,
79+
description: description,
80+
)
81+
end
82+
83+
private
84+
85+
def validate_values!(values)
86+
unless values.is_a?(Array) && !values.empty?
87+
raise ArgumentError, "values must be a non-empty Array"
88+
end
89+
end
90+
91+
def validate_titled_options!(options)
92+
unless options.is_a?(Array) && !options.empty?
93+
raise ArgumentError, "options must be a non-empty Array of {value:, title:} hashes"
94+
end
95+
96+
options.each do |option|
97+
unless option.is_a?(Hash) && option.key?(:value) && option.key?(:title)
98+
raise ArgumentError, "each option must be a Hash with :value and :title keys"
99+
end
100+
end
101+
end
102+
end
103+
104+
def initialize(type:, extras:, default: nil, title: nil, description: nil)
105+
@type = type
106+
@extras = extras
107+
@default = default
108+
@title = title
109+
@description = description
110+
end
111+
112+
def to_h
113+
hash = { type: @type }.merge(@extras)
114+
hash[:title] = @title if @title
115+
hash[:description] = @description if @description
116+
hash[:default] = @default unless @default.nil?
117+
hash
118+
end
119+
end
120+
end
121+
end

0 commit comments

Comments
 (0)