From 9ce229d337b7526366b6fdc8ddf8523774cfd7db Mon Sep 17 00:00:00 2001
From: Bob Dickinson <bob.dickinson@gmail.com>
Date: Mon, 6 Oct 2025 16:39:49 -0700
Subject: [PATCH] Recommended server.json schema field descriptions and new
 Input placeholder property (#601)

- Clarified `value` field description to remove incorrect 'default'
wording
- Improved `valueHint` description to clarify its form and purpose
(labels and variable substitution)
- Fixed NamedArgument `description` to use correct flag syntax (--flag
{value})
- Enhanced `default` field description with guidance on valid values and
when to use placeholder instead
- Added optional Input `placeholder` field for input guidance and
examples

<!-- Provide a brief summary of your changes -->

## Motivation and Context
After implementing a configuration UX for the registry supporting all
schema elements, performing schema validation on all published servers
and analyzing failures, and hand reviewing approximately a hundred
server configurations, I found a number of concerning issues
(essentially misconfigurations, verified by the docs of the server in
question, which often did not fail schema validation). I also found
"proper" configurations which disagreed with the schema guidance (for
example, all named args usage).

I documented those issues and my recommendations here:
https://github.com/modelcontextprotocol/registry/discussions/572

The fairly modest changes in this PR will address these issues (or at
least make the correct usage more clear so that we can give more
explicit guidance that is consistent with the new schema, and generally
clean up these misconfiguration).

## How Has This Been Tested?
I used my own schema validation script to apply this schema to all
published servers. The changes are only documentation (description
updates) and the addition of a new field property, so no validation
behavior change was intended nor was any observed.

## Breaking Changes
No breaking changes

## Types of changes
<!-- What types of changes does your code introduce? Put an `x` in all
the boxes that apply: -->
- [X] New feature (non-breaking change which adds functionality)
- [X] Documentation update

## Checklist
<!-- Go over all the following points, and put an `x` in all the boxes
that apply. -->
- [X] I have read the [MCP
Documentation](https://modelcontextprotocol.io)
- [ ] My code follows the repository's style guidelines
- [ ] New and existing tests pass locally
- [ ] I have added appropriate error handling
- [ ] I have added or updated documentation as needed
---
 docs/reference/server-json/server.schema.json | 12 ++++++++----
 1 file changed, 8 insertions(+), 4 deletions(-)

diff --git a/docs/reference/server-json/server.schema.json b/docs/reference/server-json/server.schema.json
index 19e6183..9f6f218 100644
--- a/docs/reference/server-json/server.schema.json
+++ b/docs/reference/server-json/server.schema.json
@@ -147,7 +147,7 @@
         },
         "value": {
           "type": "string",
-          "description": "The default value for the input. If this is not set, the user may be prompted to provide a value. If a value is set, it should not be configurable by end users.\n\nIdentifiers wrapped in `{curly_braces}` will be replaced with the corresponding properties from the input `variables` map. If an identifier in braces is not found in `variables`, or if `variables` is not provided, the `{curly_braces}` substring should remain unchanged.\n"
+          "description": "The value for the input. If this is not set, the user may be prompted to provide a value. If a value is set, it should not be configurable by end users.\n\nIdentifiers wrapped in `{curly_braces}` will be replaced with the corresponding properties from the input `variables` map. If an identifier in braces is not found in `variables`, or if `variables` is not provided, the `{curly_braces}` substring should remain unchanged.\n"
         },
         "isSecret": {
           "type": "boolean",
@@ -156,7 +156,11 @@
         },
         "default": {
           "type": "string",
-          "description": "The default value for the input."
+          "description": "The default value for the input.  This should be a valid value for the input.  If you want to provide input examples or guidance, use the `placeholder` field instead."
+        },
+        "placeholder": {
+          "type": "string",
+          "description": "A placeholder for the input to be displaying during configuration. This is used to provide examples or guidance about the expected form or content of the input."
         },
         "choices": {
           "type": "array",
@@ -208,7 +212,7 @@
             },
             "valueHint": {
               "type": "string",
-              "description": "An identifier-like hint for the value. This is not part of the command line, but can be used by client configuration and to provide hints to users.",
+              "description": "An identifier for the positional argument. It is not part of the command line. It may be used by client configuration as a label identifying the argument. It is also used to identify the value in transport URL variable substitution.",
               "example": "file_path"
             },
             "isRepeated": {
@@ -233,7 +237,7 @@
       ]
     },
     "NamedArgument": {
-      "description": "A command-line `--flag={value}`.",
+      "description": "A command-line `--flag {value}`.",
       "allOf": [
         {
           "$ref": "#/definitions/InputWithVariables"