Skip to content

Commit f32ecf0

Browse files
joelverhagenjoelverhagen
authored
Improve editor experience for server.json using schema (#441)
<!-- Provide a brief summary of your changes --> ## Motivation and Context Currently there are a couple shortcomings I found in the server.schema.json: - It uses `https://json-schema.org/draft/2020-12/schema` which is unfortunately [not supported by VS Code](microsoft/vscode#165219) - The Package schema does not require properties that are required by the service This means that need to round trip with the publish endpoint (perhaps spinning CI builds) to get the server.json right. It would be great if we could shift left and get indications in VS Code easier. I propose we downgrade the schema to `http://json-schema.org/draft-07/schema#`. The only difference for us is the name of `$def` pointers. I looked that [SchemaStore](https://github.com/SchemaStore/schemastore) and it looks like `draft-07` is by far the most popular. I believe the concession of using an older schema is worth it to get VS Code editor hints. Schema version | Count in SchemaStore -- | -- `http://json-schema.org/draft-04/schema#` | 292 `http://json-schema.org/draft-07/schema#` | 1972 `https://json-schema.org/draft/2019-09/schema` | 4 `https://json-schema.org/draft/2020-12/schema` | 4 <!-- Why is this change needed? What problem does it solve? --> ## Open questions - [ ] Should package `transport` actually be required? Or should `stdio` be assumed? - [ ] Should package `registry_base_url` be required? All of the examples have it it's not required by the publish endpoint. ## How Has This Been Tested? <!-- Have you tested this in a real application? Which scenarios were tested? --> I have tried the new schema inside VS Code and I get helpful warning. For example, these are the warnings for the old schema. <img width="1561" height="919" alt="image" src="https://github.com/user-attachments/assets/474170b8-acf8-4dca-a3d9-66c68c0d1902" /> I have run these: `go run .\tools\validate-examples\main.go` `go run .\tools\validate-schemas\main.go ` ## Breaking Changes I don't think these are breaking changes. I am expressing what the publish endpoint enforces at runtime. ## Types of changes <!-- What types of changes does your code introduce? Put an `x` in all the boxes that apply: --> - [ ] Bug fix (non-breaking change which fixes an issue) - [ ] New feature (non-breaking change which adds functionality) - [ ] Breaking change (fix or feature that would cause existing functionality to change) - [x] Documentation update ## Checklist <!-- Go over all the following points, and put an `x` in all the boxes that apply. --> - [ ] 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 - [x] I have added or updated documentation as needed ## Additional context <!-- Add any other context, implementation notes, or design decisions -->
1 parent 78c482b commit f32ecf0

File tree

2 files changed

+34
-24
lines changed

2 files changed

+34
-24
lines changed

‎docs/reference/server-json/server.schema.json‎

Lines changed: 33 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,9 @@
11
{
2-
"$schema": "https://json-schema.org/draft/2020-12/schema",
2+
"$schema": "http://json-schema.org/draft-07/schema#",
33
"$id": "https://static.modelcontextprotocol.io/schemas/2025-07-09/server.schema.json",
44
"title": "MCP Server Detail",
5-
"$ref": "#/$defs/ServerDetail",
6-
"$defs": {
5+
"$ref": "#/definitions/ServerDetail",
6+
"definitions": {
77
"Repository": {
88
"type": "object",
99
"description": "Repository metadata for the MCP server source code. Enables users and security experts to inspect the code, improving transparency.",
@@ -65,7 +65,7 @@
6565
"description": "Server lifecycle status. 'deprecated' indicates the server is no longer recommended for new usage. 'deleted' indicates the server should never be installed and existing installations should be uninstalled - this is rare, and usually indicates malware or a legal takedown."
6666
},
6767
"repository": {
68-
"$ref": "#/$defs/Repository",
68+
"$ref": "#/definitions/Repository",
6969
"description": "Optional repository metadata for the MCP server source code. Recommended for transparency and security inspection."
7070
},
7171
"version": {
@@ -84,6 +84,13 @@
8484
},
8585
"Package": {
8686
"type": "object",
87+
"additionalProperties": false,
88+
"required": [
89+
"registry_type",
90+
"identifier",
91+
"version",
92+
"transport"
93+
],
8794
"properties": {
8895
"registry_type": {
8996
"type": "string",
@@ -104,6 +111,9 @@
104111
"version": {
105112
"type": "string",
106113
"description": "Package version",
114+
"not": {
115+
"const": "latest"
116+
},
107117
"example": "1.0.2",
108118
"minLength": 1,
109119
"remarks": "Must be a specific version. Version ranges are rejected (e.g., '^1.2.3', '~1.2.3', '>=1.2.3', '1.x', '1.*')."
@@ -127,13 +137,13 @@
127137
"transport": {
128138
"anyOf": [
129139
{
130-
"$ref": "#/$defs/StdioTransport"
140+
"$ref": "#/definitions/StdioTransport"
131141
},
132142
{
133-
"$ref": "#/$defs/StreamableHttpTransport"
143+
"$ref": "#/definitions/StreamableHttpTransport"
134144
},
135145
{
136-
"$ref": "#/$defs/SseTransport"
146+
"$ref": "#/definitions/SseTransport"
137147
}
138148
],
139149
"description": "Transport protocol configuration for the package"
@@ -142,21 +152,21 @@
142152
"type": "array",
143153
"description": "A list of arguments to be passed to the package's runtime command (such as docker or npx). The `runtime_hint` field should be provided when `runtime_arguments` are present.",
144154
"items": {
145-
"$ref": "#/$defs/Argument"
155+
"$ref": "#/definitions/Argument"
146156
}
147157
},
148158
"package_arguments": {
149159
"type": "array",
150160
"description": "A list of arguments to be passed to the package's binary.",
151161
"items": {
152-
"$ref": "#/$defs/Argument"
162+
"$ref": "#/definitions/Argument"
153163
}
154164
},
155165
"environment_variables": {
156166
"type": "array",
157167
"description": "A mapping of environment variables to be set when running the package.",
158168
"items": {
159-
"$ref": "#/$defs/KeyValueInput"
169+
"$ref": "#/definitions/KeyValueInput"
160170
}
161171
}
162172
}
@@ -209,7 +219,7 @@
209219
"InputWithVariables": {
210220
"allOf": [
211221
{
212-
"$ref": "#/$defs/Input"
222+
"$ref": "#/definitions/Input"
213223
},
214224
{
215225
"type": "object",
@@ -218,7 +228,7 @@
218228
"type": "object",
219229
"description": "A map of variable names to their values. Keys in the input `value` that are wrapped in `{curly_braces}` will be replaced with the corresponding variable values.",
220230
"additionalProperties": {
221-
"$ref": "#/$defs/Input"
231+
"$ref": "#/definitions/Input"
222232
}
223233
}
224234
}
@@ -229,7 +239,7 @@
229239
"description": "A positional input is a value inserted verbatim into the command line.",
230240
"allOf": [
231241
{
232-
"$ref": "#/$defs/InputWithVariables"
242+
"$ref": "#/definitions/InputWithVariables"
233243
},
234244
{
235245
"type": "object",
@@ -274,7 +284,7 @@
274284
"description": "A command-line `--flag={value}`.",
275285
"allOf": [
276286
{
277-
"$ref": "#/$defs/InputWithVariables"
287+
"$ref": "#/definitions/InputWithVariables"
278288
},
279289
{
280290
"type": "object",
@@ -307,7 +317,7 @@
307317
"KeyValueInput": {
308318
"allOf": [
309319
{
310-
"$ref": "#/$defs/InputWithVariables"
320+
"$ref": "#/definitions/InputWithVariables"
311321
},
312322
{
313323
"type": "object",
@@ -328,10 +338,10 @@
328338
"description": "Warning: Arguments construct command-line parameters that may contain user-provided input. This creates potential command injection risks if clients execute commands in a shell environment. For example, a malicious argument value like ';rm -rf ~/Development' could execute dangerous commands. Clients should prefer non-shell execution methods (e.g., posix_spawn) when possible to eliminate injection risks entirely. Where not possible, clients should obtain consent from users or agents to run the resolved command before execution.",
329339
"anyOf": [
330340
{
331-
"$ref": "#/$defs/PositionalArgument"
341+
"$ref": "#/definitions/PositionalArgument"
332342
},
333343
{
334-
"$ref": "#/$defs/NamedArgument"
344+
"$ref": "#/definitions/NamedArgument"
335345
}
336346
]
337347
},
@@ -375,7 +385,7 @@
375385
"type": "array",
376386
"description": "HTTP headers to include",
377387
"items": {
378-
"$ref": "#/$defs/KeyValueInput"
388+
"$ref": "#/definitions/KeyValueInput"
379389
}
380390
}
381391
}
@@ -405,7 +415,7 @@
405415
"type": "array",
406416
"description": "HTTP headers to include",
407417
"items": {
408-
"$ref": "#/$defs/KeyValueInput"
418+
"$ref": "#/definitions/KeyValueInput"
409419
}
410420
}
411421
}
@@ -414,7 +424,7 @@
414424
"description": "Schema for a static representation of an MCP server. Used in various contexts related to discovery, installation, and configuration.",
415425
"allOf": [
416426
{
417-
"$ref": "#/$defs/Server"
427+
"$ref": "#/definitions/Server"
418428
},
419429
{
420430
"type": "object",
@@ -428,18 +438,18 @@
428438
"packages": {
429439
"type": "array",
430440
"items": {
431-
"$ref": "#/$defs/Package"
441+
"$ref": "#/definitions/Package"
432442
}
433443
},
434444
"remotes": {
435445
"type": "array",
436446
"items": {
437447
"anyOf": [
438448
{
439-
"$ref": "#/$defs/StreamableHttpTransport"
449+
"$ref": "#/definitions/StreamableHttpTransport"
440450
},
441451
{
442-
"$ref": "#/$defs/SseTransport"
452+
"$ref": "#/definitions/SseTransport"
443453
}
444454
]
445455
}

‎tools/validate-examples/main.go‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -160,7 +160,7 @@ func extractExamples(path string) ([]example, error) {
160160

161161
// Regex to match JSON code blocks in markdown
162162
// Captures everything between ```json and ```
163-
re := regexp.MustCompile("(?s)```json\n(.*?)\n```")
163+
re := regexp.MustCompile("(?s)```json\r?\n(.*?)\r?\n```")
164164
matches := re.FindAllStringSubmatchIndex(content, -1)
165165

166166
var examples []example

0 commit comments

Comments
 (0)