Improve editor experience for server.json using schema

[joelverhagen]

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
• 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 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

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?

I have tried the new schema inside VS Code and I get helpful warning. For example, these are the warnings for the old schema.

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

• 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)
• Documentation update

Checklist

• I have read the MCP Documentation
• 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

Additional context

[rdimitrov]

Should package transport actually be required? Or should stdio be assumed?

I think we should continue to require it. From my experience most community servers are using stdio and it could be a somewhat safe assumption, but there are more and more moving towards http, especially ones that think beyond the local use.

Should package registry_base_url be required? All of the examples have it it's not required by the publish endpoint.

I think so 👍 I expect there are examples where a server can be hosted on multiple registries of the same ecosystem, so it's safer to be specific.

[connor4312]

It uses https://json-schema.org/draft/2020-12/schema which is unfortunately not supported by VS Code

I'm going to try and get this prioritized. Many LM's are using Draft 2020 so we're going to have to support it. So I would not put too much weight on this as far as long term registry plans go.

[domdomegg]

This seems incredibly sensible and I support the change! Will take a look at reviewing this properly later, please poke me if not.

[joelverhagen]

Should package transport actually be required? Or should stdio be assumed?

I think we should continue to require it. From my experience most community servers are using stdio and it could be a somewhat safe assumption, but there are more and more moving towards http, especially ones that think beyond the local use.

Great. I'll leave this requirement in the schema then. Low risk since it matches publish.

Should package registry_base_url be required? All of the examples have it it's not required by the publish endpoint.

I think so 👍 I expect there are examples where a server can be hosted on multiple registries of the same ecosystem, so it's safer to be specific.

@rdimitrov - would you like me to update the publish endpoint to require it? I can totally do that, but it might cause a little disruption for existing server owners. IMO sooner is better than later.

There is also the data back-fill to fix existing JSON in Postgres -- unless we don't care and can just wait until next update.

It uses https://json-schema.org/draft/2020-12/schema which is unfortunately not supported by VS Code

I'm going to try and get this prioritized. Many LM's are using Draft 2020 so we're going to have to support it. So I would not put too much weight on this as far as long term registry plans go.

Thanks @connor4312. I think we should still adjust the schema for now. This is basically running in "maximum compatibility mode" until we have a good reason to update, such as needing a 2020 feature or we have data to support that consumers have moved to 2020-compatible tools/clients. I have not run into any compatibility issues with editors and Draft 7.

[domdomegg]

Should package registry_base_url be required? All of the examples have it it's not required by the publish endpoint.

I think it's probably fine to omit, if you're using the obvious default? Appreciate some benefits in being very specific, but also don't want to introduce too much friction to server developers.

[joelverhagen]

Should package registry_base_url be required? All of the examples have it it's not required by the publish endpoint.

I think it's probably fine to omit, if you're using the obvious default? Appreciate some benefits in being very specific, but also don't want to introduce too much friction to server developers.

Thanks, I was slowly coming to the same conclusion. I was running the integration tests as "proof" to myself that registry_base_url was not required but noticed that when cfg.EnableRegistryValidation is true (I assume this is true in PROD), the ommitted value is filed in with the central registry for the package type and validated. So, I think it's good as-is.