Movatterモバイル変換

[0]ホーム
URL:

Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly

 Sign up
Appearance settings

SEP-1330: Elicitation Enum Schema Improvements and Standards Compliance #1330

Assignees
cliffhall
Labels
SEPacceptedSEP accepted by core maintainers, but still requires final wording and reference implementation.enhancementNew feature or requestfinalSEP finalized.
@chughtapan

Description

@chughtapan

Preamble

Title: Elicitation Enum Schema Improvements and Standards Compliance
Author(s): Cliff Hall (@cliffhall), Tapan Chugh (@chughtapan)
Track: Standards Track
Status: Proposal
Created: 2025-08-11

Abstract

This SEP proposes improvements to enum schema definitions in MCP, deprecating the non-standardenumNames property in favor of JSON Schema-compliant patterns, and introducing additional support for multi-select enum schemas in addition to single choice schemas. The new schemas have been validated against the JSON specification.

Schema Changes:#1148
Typescript SDK Changes:modelcontextprotocol/typescript-sdk#1077
Python SDK Changes:modelcontextprotocol/python-sdk#1246
Client Implementation:https://github.com/evalstate/fast-agent/pull/324/files
Working Demo:https://asciinema.org/a/anBvJdqEmTjw0JkKYOooQa5Ta

Motivation

The existing schema for enums uses a non-standard approach to adding titles to enumerated values. It also limits use of enums in Elicitation (and any other schema object that should adoptEnumSchema in the future) to a single selection model. It is a common pattern to ask the user to select multiple entries. In the UI, this amounts to the difference between using checkboxes or radio buttons.

For these reasons, we propose the following non-breaking minor improvements to theEnumSchema for improving user and developer experience.

  • Keep the existingEnumSchema as "Legacy"
    • It uses a non-standard approach for adding titles to enumerated values
    • Mark it as Legacy but still support it for now.
    • As per@dsp-ant When we have a proper deprecation strategy, we'll mark it deprecated
  • Introduce the distinction between Untitled and Titled enums.
    • If the enumerated values are sufficient, no separate title need be specified for each value.
    • If the enumerated values are not optimal for display, a title may be specified for each value.
  • Introduce the distinction between Single and Multi-select enums.
    • If only one value can be selected, a Single select schema can be used
    • If more than one value can be selected, a Multi-select schema can be used
  • InElicitResponse, add array as anadditionalProperty type
    • Allows multiple selection of enumerated values to be returned to the server

Specification

1. Mark CurrentEnumSchema with Non-StandardenumNames Property as "Legacy"

The current MCP specification uses a non-standardenumNames property for providing display names for enum values. We propose to markenumNames property as legacy, suggest usingTitledSingleSelectEnum, a standards compliant enum type we define below.

// Continue to support the current EnumSchema as Legacy/**  * Legacy: Use TitledSingleSelectEnumSchema instead.  * This interface will be removed in a future version.  */exportinterfaceLegacyEnumSchema{type:"string";title?:string;description?:string;enum:string[];enumNames?:string[];// Titles for enum values (non-standard, legacy)}

2. Define Single Selection Enums (with Titled and Untitled varieties)

Enums may or may not need titles. The enumerated values may be human readable and fine for display. In which case an untitled implementation using the JSON Schema keywordenum is simpler. Adding titles requires theenum array to be replaced with an array of objects usingconst andtitle.

// Single select enum without titlesexporttypeUntitledSingleSelectEnumSchema={type:"string";title?:string;description?:string;enum:string[];// Plain enum without titles};// Single select enum with titlesexporttypeTitledSingleSelectEnumSchema={type:"string";title?:string;description?:string;oneOf:Array<{const:string;// Enum valuetitle:string;// Display name for enum value}>;};// Combined single selection enumerationexporttypeSingleSelectEnumSchema=|UntitledSingleSelectEnumSchema|TitledSingleSelectEnumSchema;

3. Introduce Multiple Selection Enums (with Titled and Untitled varieties)

While elicitation does not support arbitrary JSON types like arrays and objects so clients can display the selection choice easily, multiple selection enumerations can be easily implemented.

// Multiple select enums without titlesexporttypeUntitledMultiSelectEnumSchema={type:"array";title?:string;description?:string;minItems?:number;// Minimum number of items to choosemaxItems?:number;// Maximum number of items to chooseitems:{type:"string";enum:string[];// Plain enum without titles};};// Multiple select enums with titlesexporttypeTitledMultiSelectEnumSchema={type:"array";title?:string;description?:string;minItems?:number;// Minimum number of items to choosemaxItems?:number;// Maximum number of items to chooseitems:{oneOf:Array<{const:string;// Enum valuetitle:string;// Display name for enum value}>;};};// Combined Multiple select enumerationexporttypeMultiSelectEnumSchema=|UntitledMultiSelectEnumSchema|TitledMultiSelectEnumSchema;

4. Combine All Varieties asEnumSchema

The finalEnumSchema rolls up the legacy, multi-select, and single-select schemas as one, defined as:

// Combined legacy, multiple, and single select enumerationexporttypeEnumSchema=|SingleSelectEnumSchema|MultiSelectEnumSchema|LegacyEnumSchema;

5. Extend ElicitResult

The current elicitation result schema only allows returning primitive types. We extend this to include string arrays for MultiSelectEnums:

exportinterfaceElicitResultextendsResult{action:"accept"|"decline"|"cancel";content?:{[key:string]:string|number|boolean|string[]};// string[] is new}

Instance Schema Examples

Single-Select Without Titles (No change)

{"type":"string","title":"Color Selection","description":"Choose your favorite color","enum": ["Red","Green","Blue"],"default":"Green"}

Legacy Single Select With Titles

{"type":"string","title":"Color Selection","description":"Choose your favorite color","enum": ["#FF0000","#00FF00","#0000FF"],“enumNames”: ["Red", "Green", "Blue"],"default":"Green"}

Single-Select with Titles

{"type":"string","title":"Color Selection","description":"Choose your favorite color","oneOf": [   {"const":"#FF0000","title":"Red" },   {"const":"#00FF00","title":"Green" },   {"const":"#0000FF","title":"Blue" } ],"default":"#00FF00"}

Multi-Select Without Titles

{"type":"array","title":"Color Selection","description":"Choose your favorite colors","minItems":1,"maxItems":3,"items": {"type":"string","enum": ["Red","Green","Blue"]  },"default": ["Green"]}

Multi-Select with Titles

{"type":"array","title":"Color Selection","description":"Choose your favorite colors","minItems":1,"maxItems":3,"items": {"anyOf": [      {"const":"#FF0000","title":"Red" },      {"const":"#00FF00","title":"Green" },      {"const":"#0000FF","title":"Blue" }    ]  },"default": ["Green"]}

Rationale

  1. Standards Compliance: Aligns with official JSON Schema specification. Standard patterns work with existing JSON Schema validators
  2. Flexibility: Supports both plain enums and enums with display names for single and multiple choice enums.
  3. Client Implementation: shows that the additional overhead of implementing a group of checkboxes v/s a single checkbox is minimal:https://github.com/evalstate/fast-agent/pull/324/files

Backwards Compatibility

TheLegacyEnumSchema type maintains backwards compatible during the migration period. Existing implementations usingenumNames will continue to work until a protocol-wide deprecation strategy is implemented, and this schema is removed.

Reference Implementation

Schema Changes:#1148
Typescript SDK Changes:modelcontextprotocol/typescript-sdk#1077
Python SDK Changes:modelcontextprotocol/python-sdk#1246
Client Implementation:https://github.com/evalstate/fast-agent/pull/324/files
Working Demo:https://asciinema.org/a/anBvJdqEmTjw0JkKYOooQa5Ta

Security Considerations

No security implications identified. This change is purely about schema structure and standards compliance.

Appendix

Validations

Using stored validations in the JSON Schema Validator athttps://www.jsonschemavalidator.net/ we validate:

  • All of the example instance schemas from this document against the proposed JSON meta-schemaEnumSchema in the next section.
  • Valid and invalid values against the example instance schemas from this document.

Legacy Single Selection

Single Selection

Multiple Selection

JSON meta-schema

This is our proposal for the replacement of the currentEnumSchema in the specification’sschema.json.

{"$schema":"https://json-schema.org/draft-07/schema","definitions": {// New Definitions Follow"UntitledSingleSelectEnumSchema": {"type":"object","properties": {"type": {"const":"string" },"title": {"type":"string" },"description": {"type":"string" },"enum": {"type":"array","items": {"type":"string" },"minItems":1        }      },"required": ["type","enum"],"additionalProperties":false    },"UntitledMultiSelectEnumSchema": {"type":"object","properties": {"type": {"const":"array" },"title": {"type":"string" },"description": {"type":"string" },"minItems": {"type":"number","minimum":0        },"maxItems": {"type":"number","minimum":0        },"items": {"type":"object","properties": {"type": {"const":"string" },"enum": {"type":"array","items": {"type":"string" },"minItems":1            }          },"required": ["type","enum"],"additionalProperties":false        }      },"required": ["type","items"],"additionalProperties":false    },"TitledSingleSelectEnumSchema": {"type":"object","required": ["type","anyOf"],"properties": {"type": {"const":"string" },"title": {"type":"string" },"description": {"type":"string" },"anyOf": {"type":"array","items": {"type":"object","required": ["const","title"],"properties": {"const": {"type":"string" },"title": {"type":"string" }            },"additionalProperties":false          }        }      },"additionalProperties":false    },"TitledMultiSelectEnumSchema": {"type":"object","required": ["type","anyOf"],"properties": {"type": {"const":"array" },"title": {"type":"string" },"description": {"type":"string" },"anyOf": {"type":"array","items": {"type":"object","required": ["const","title"],"properties": {"const": {"type":"string" },"title": {"type":"string" }            },"additionalProperties":false          }        }      },"additionalProperties":false    },"LegacyEnumSchema": {"properties": {"type": {"type":"string","const":"string",          },"title": {"type":"string" },"description": {"type":"string" },"enum": {"type":"array","items": {"type":"string" },          },"enumNames": {"type":"array","items": {"type":"string" },          },      },"required": ["enum","type" ],"type":"object"    },"EnumSchema": {"oneOf": [           {"$ref":"#/definitions/UntitledSingleSelectEnumSchema"},           {"$ref":"#/definitions/UntitledMultiSelectEnumSchema"},          {"$ref":"#/definitions/TitledSingleSelectEnumSchema"},           {"$ref":"#/definitions/TitledMultiSelectEnumSchema"},          {"$ref":"#/definitions/LegacyEnumSchema"},      ]    }  }}

Metadata

Metadata

Assignees

Labels

SEPacceptedSEP accepted by core maintainers, but still requires final wording and reference implementation.enhancementNew feature or requestfinalSEP finalized.

Projects

Status

Accepted

Status

Done

Relationships

None yet

Development

No branches or pull requests

Issue actions

    [8]ページ先頭
    ©2009-2025 Movatter.jp