René's URL Explorer Experiment

{"@context":"https://schema.org","@type":"DiscussionForumPosting","headline":"SEP-1440: Enhanced Completion Values with Rich Metadata Support","articleBody":"**Author:** Kent C. Dodds \u003c[me@kentcdodds.com]\u003e\n**Status:** proposal\n**Type:** Standards Track\n**Created:** 2025-09-08\n**Discussion:** https://github.com/modelcontextprotocol/modelcontextprotocol/pull/589\n\n## Abstract\n\nThis SEP proposes extending the Model Context Protocol (MCP) completion system to support rich metadata in completion values. Currently, completion values are limited to simple strings, which restricts the ability to provide contextual information about completion options. This proposal introduces a union type that allows completion values to be either simple strings (maintaining backward compatibility) or rich objects containing `value`, `title`, and optional `description` fields. This enhancement enables better user experiences with IDE-like completion interfaces that can display meaningful titles and descriptions alongside completion values while maintaining backward compatibility with existing string-based completions.\n\n## Motivation\n\nThe current MCP completion system only supports string values in the `CompleteResult.values` array. This limitation creates several problems:\n\n1. **Poor User Experience**: When completion values are technical identifiers (e.g., `\"py-3.11\"`), users cannot easily understand what they represent without additional context.\n\n2. **Limited Context**: There's no way to provide descriptions or alternative display names for completion options, making it difficult for users to distinguish between similar options.\n\n3. **Inconsistent Display**: Clients must choose between showing cryptic technical values or implementing their own mapping to user-friendly names, leading to inconsistent experiences across different MCP clients.\n\n4. **Missing IDE-like Features**: Modern development environments provide rich completion experiences with descriptions, documentation, and categorized suggestions. The current MCP specification cannot support these features.\n\n5. **Server Complexity**: Servers that want to provide rich completion experiences must work around the limitation by encoding metadata into string values or providing separate documentation endpoints.\n\nThis proposal addresses these issues by allowing servers to provide rich completion objects while maintaining full backward compatibility with existing string-based completions.\n\n## Specification\n\n### Type Definition\n\nThe `CompleteResult.values` field is extended from:\n\n```typescript\nvalues: string[]\n```\n\nTo:\n\n```typescript\nvalues: Array\u003cstring | CompletionValue\u003e;\n```\n\nWhere `CompletionValue` is defined as:\n\n```typescript\ninterface CompletionValue {\n  value: string; // The actual completion value\n  title: string; // Display name for the completion\n  description?: string; // Optional description/context\n}\n```\n\n### Field Semantics\n\n- **`value`**: The actual completion value that will be inserted/used by the client. This is equivalent to the current string values.\n- **`title`**: A human-readable display name for the completion option. This is what should be shown to users in completion interfaces.\n- **`description`**: Optional additional context or documentation about the completion option. This can be used for tooltips, help text, or detailed descriptions.\n\nThe `value` is what will be sent back in `context.arguments` of subsequent completion requests.\n\n\n### Examples\n\n#### Rich Completion Objects\n\n```json\n{\n  \"jsonrpc\": \"2.0\",\n  \"id\": 1,\n  \"result\": {\n    \"completion\": {\n      \"values\": [\n        {\n          \"value\": \"py-3.11\",\n          \"title\": \"Python 3.11\",\n          \"description\": \"Python programming language version 3.11\"\n        },\n        {\n          \"value\": \"torch-2.0\",\n          \"title\": \"PyTorch 2.0\",\n          \"description\": \"Open source machine learning framework\"\n        }\n      ],\n      \"total\": 2,\n      \"hasMore\": false\n    }\n  }\n}\n```\n\n#### Mixed String and Object Values\n\n```json\n{\n  \"jsonrpc\": \"2.0\",\n  \"id\": 1,\n  \"result\": {\n    \"completion\": {\n      \"values\": [\n        \"python\",\n        {\n          \"value\": \"torch-2.0\",\n          \"title\": \"PyTorch 2.0\",\n          \"description\": \"Open source machine learning framework\"\n        },\n        \"pyside\"\n      ],\n      \"total\": 3,\n      \"hasMore\": false\n    }\n  }\n}\n```\n\n#### Simple String Values (Backward Compatible)\n\n```json\n{\n  \"jsonrpc\": \"2.0\",\n  \"id\": 1,\n  \"result\": {\n    \"completion\": {\n      \"values\": [\"python\", \"pytorch\", \"pyside\"],\n      \"total\": 3,\n      \"hasMore\": false\n    }\n  }\n}\n```\n\n### Client Behavior\n\nClients should:\n\n1. Handle both string and object completion values gracefully\n2. Clients SHOULD search on both value and title fields when filtering completions.\n3. Use the `title` field for display purposes when available\n4. Use the `value` field for the actual completion insertion\n5. Display `description` as tooltips or help text when available\n6. Fall back to displaying the string value directly for simple string completions\n\n### Server Behavior\n\nServers may:\n\n1. Return only string values (maintaining current behavior)\n2. Return only rich completion objects\n3. Mix string and object values in the same response\n4. Gradually migrate from strings to rich objects over time\n\nNOTE: Servers should be aware that hosts may search on titles, which could make results appear inconsistent if only values are considered.\n\n## Rationale\n\n### Union Type Design\n\nThe union type `string | CompletionValue` was chosen over always requiring objects because:\n\n1. **Backward Compatibility**: Existing implementations continue to work without modification\n2. **Simplicity**: Simple use cases don't require the overhead of object creation\n3. **Migration Path**: Servers can gradually adopt rich completions without breaking changes\n\n### Field Selection\n\nThe three fields (`value`, `title`, `description`) were chosen because:\n\n1. **`value`**: Essential for actual completion functionality\n2. **`title`**: Provides user-friendly display names without changing completion behavior\n3. **`description`**: Optional field allows for rich context without requiring it\n\nAlternative designs considered:\n\n- **Always objects**: Would break backward compatibility\n- **Additional fields**: Would complicate the specification without clear use cases\n- **Nested structure**: Would add unnecessary complexity for the core use case\n\n### Schema Validation\n\nThe JSON Schema uses `anyOf` to validate the union type, ensuring that:\n\n- String values are validated as before\n- Object values must have required `value` and `title` fields\n- Optional `description` field is validated when present\n- Additional properties are not allowed to prevent confusion\n\n## Backward Compatibility\n\nThis change is fully backward compatible:\n\n1. **Existing Clients**: Will continue to work unchanged, treating object values as strings (though this may not be ideal UX)\n2. **Existing Servers**: Can continue returning string arrays without modification\n3. **Protocol Version**: No protocol version changes required\n4. **Schema Evolution**: Uses standard JSON Schema union types for validation\n\n### Migration Strategy\n\n1. **Phase 1**: Deploy the specification changes (this SEP)\n2. **Phase 2**: Clients update to handle rich completion objects\n3. **Phase 3**: Servers gradually adopt rich completions where beneficial\n\n## Reference Implementation\n\nThe reference implementation includes:\n\n1. **Schema Changes**: Updated `schema.json` and `schema.ts` with the new union type\n2. **Documentation**: Enhanced `completion.mdx` with comprehensive examples\n3. **Type Definitions**: Updated TypeScript interfaces in the schema\n\n## Security Implications\n\nThis change introduces no new security concerns:\n\n1. **Input Validation**: Same validation requirements as existing string completions\n2. **Data Exposure**: No additional sensitive information is exposed through the new fields\n3. **Rate Limiting**: Existing rate limiting mechanisms continue to apply\n4. **Access Control**: Same access control requirements as current completion system\n\nServers should:\n\n- Validate all completion metadata before returning it\n- Ensure `title` and `description` fields don't contain sensitive information\n- Apply the same security policies to rich completions as string completions\n\n## References\n\n- [MCP Specification - Completion](https://modelcontextprotocol.io/docs/specification/draft/server/utilities/completion)\n- [JSON Schema Union Types](https://json-schema.org/understanding-json-schema/reference/combining.html#anyof)\n- [TypeScript Union Types](https://www.typescriptlang.org/docs/handbook/2/everyday-types.html#union-types)\n","author":{"url":"https://github.com/kentcdodds","@type":"Person","name":"kentcdodds"},"datePublished":"2025-09-08T14:51:24.000Z","interactionStatistic":{"@type":"InteractionCounter","interactionType":"https://schema.org/CommentAction","userInteractionCount":14},"url":"https://github.com/1440/modelcontextprotocol/issues/1440"}