Split "general" server.json from "registry-specific" server.json #167

tadasant · 2025-07-09T15:35:25Z

Closes #155

The "generalized" server.json is the one that can be used in a variety of situations:

Discoverability on a centralized registry (i.e. our official Registry work)
Discoverability on a decentralized .well-known endpoint
As a response to an initialization call, so the client knows information about the MCP server to which it is connecting
As an input into crafting a DXT file
Packaged in with the source code of an MCP server, so as to have a structured way context

Of these, the official Registry is but one use case. The Registry has a unique set of concerns for which we are optimizing, like whitelisting of specific registries we trust to host MCP server source code for the public community (npm, pypi, etc). It is not necessary to have such a constraint for the generalized server.json, which may be used in, for example, an internal context where such a validation doesn't make sense.

So I've done the following at a high level:

Renamed the prior schema.json to be registry-schema.json
Introduced a more generic schema.json to serve as the schema for the generalized server.json
Refactored registry-schema.json to be simply a constraint on the base schema.json

I made a few small changes in this transition:

Removed gitlab as an option in repository.source for registry-schema.json. I'm fine going live with just GitHub support; would be happy to take a contribution from e.g. Gitlab employees or a motivated Gitlab customer to expand anytime.
Removed homebrew as an option in packages.registry_name; never really made sense, not a place where folks are publishing MCP servers
Added docker to packages.runtime_hint; was just a missing oversight
Gave both schemas a global $id
- Removed release_date from both schemas. Certainly not something that makes sense for the generalized schema. It actually doesn't make sense for the Registry schema either, because this is the server.json that users will submit, i.e. the input into the Registry publication API. release_date will be a piece of output metadata. The Registry API will be free to append such extra metadata for GET /:id requests of servers, and the data can be present in the OpenAPI spec, but it does not need to be in the registry-server.json JSON schema.
- Note this is no longer in this PR; rebased on Align the server.json schema with the YAML #168 which included it
Removed unnecessary enums from the generalized schema.json

tadasant · 2025-07-09T15:36:36Z

cc @joelverhagen @felixrieseberg

docs/server-json/schema.json

joelverhagen · 2025-07-09T15:52:56Z

docs/server-json/schema.json

          "description": "Server version (equivalent to Implementation.version in MCP spec)",
          "example": "1.0.2"
-        },
-        "release_date": {


Oh, haha, I just found this in my PR. #168.

I can rebase my PR after you merge this.

joelverhagen · 2025-07-09T15:57:17Z

docs/server-json/registry-schema.json

+  "title": "MCP Server Detail - Registry Schema",
+  "description": "Registry-specific constraints for MCP server representation. Extends the base schema with additional validation rules.",
+  "$ref": "https://modelcontextprotocol.io/schemas/draft/server.json",
+  "properties": {


Cool, I didn't know you could do overrides like this.

joelverhagen · 2025-07-09T15:57:41Z

Looks good to me.

@tadasant

## Motivation and Context This is in support of #159, to make it easier, I hope. My team noticed some differences in the JSON schema, most notably the "choices" property was missing. I tried to write a tool to do this but slowed down since I am not experienced with Go. This is a first pass, maybe someone else can finish the tooling. I restructured the JSON schema to break out child objects like the YAML file, and brought the descriptions and example into sync. The only differences are two extra properties in the YAML which are computed by the server: - `VersionDetail.is_latest` is not present in the JSON schema, computed by the registry based on #158 - `Server.id` is not present in the JSON schema, generated by the registry The idea is the a tool could look at ServerDetail in the YAML and then generate the schema.json with minimal fix-ups (add a root title, remove `VersionDetail.is_latest` and `Server.id`. ~Question for @tadasant - should `VersionDetail.release_date` be in the JSON schema? I think _no_ (and let it be computed) but it's there right now.~ - aligned with #167 and removed ## How Has This Been Tested? I have tested the JSON schema against the sample server.json in the repo (files and markdown blocks). ## Breaking Changes None. ## Types of changes  - [x] 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  - [x] I have read the [MCP Documentation](https://modelcontextprotocol.io) - [x] 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

tadasant · 2025-07-09T17:49:48Z

Did a rebase on #168 which makes this PR a lot simpler :)

@tadasant

## Motivation and Context This is in support of #159, to make it easier, I hope. My team noticed some differences in the JSON schema, most notably the "choices" property was missing. I tried to write a tool to do this but slowed down since I am not experienced with Go. This is a first pass, maybe someone else can finish the tooling. I restructured the JSON schema to break out child objects like the YAML file, and brought the descriptions and example into sync. The only differences are two extra properties in the YAML which are computed by the server: - `VersionDetail.is_latest` is not present in the JSON schema, computed by the registry based on #158 - `Server.id` is not present in the JSON schema, generated by the registry The idea is the a tool could look at ServerDetail in the YAML and then generate the schema.json with minimal fix-ups (add a root title, remove `VersionDetail.is_latest` and `Server.id`. ~Question for @tadasant - should `VersionDetail.release_date` be in the JSON schema? I think _no_ (and let it be computed) but it's there right now.~ - aligned with #167 and removed ## How Has This Been Tested? I have tested the JSON schema against the sample server.json in the repo (files and markdown blocks). ## Breaking Changes None. ## Types of changes  - [x] 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  - [x] I have read the [MCP Documentation](https://modelcontextprotocol.io) - [x] 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

Closes #155 The "generalized" `server.json` is the one that can be used in a variety of situations: - Discoverability on a centralized registry (i.e. our official Registry work) - Discoverability on a decentralized .well-known endpoint - As a response to an initialization call, so the client knows information about the MCP server to which it is connecting - As an input into crafting a [DXT file](https://www.anthropic.com/engineering/desktop-extensions) - Packaged in with the source code of an MCP server, so as to have a structured way context Of these, the official Registry is but one use case. The Registry has a unique set of concerns for which we are optimizing, like whitelisting of specific registries we trust to host MCP server source code for the public community (`npm`, `pypi`, etc). It is not necessary to have such a constraint for the generalized server.json, which may be used in, for example, an internal context where such a validation doesn't make sense. So I've done the following at a high level: - Renamed the prior `schema.json` to be `registry-schema.json` - Introduced a more generic `schema.json` to serve as the schema for the generalized `server.json` - Refactored `registry-schema.json` to be simply a constraint on the base `schema.json` I made a few small changes in this transition: - Removed `gitlab` as an option in `repository.source` for `registry-schema.json`. I'm fine going live with just GitHub support; would be happy to take a contribution from e.g. Gitlab employees or a motivated Gitlab customer to expand anytime. - Removed `homebrew` as an option in `packages.registry_name`; never really made sense, not a place where folks are publishing MCP servers - Added `docker` to `packages.runtime_hint`; was just a missing oversight - Gave both schemas a global `$id` ~- Removed `release_date` from both schemas. Certainly not something that makes sense for the generalized schema. It actually doesn't make sense for the Registry schema either, because this is the server.json that _users will submit_, i.e. the _input_ into the Registry publication API. `release_date` will be a piece of _output_ metadata. The Registry API will be free to append such extra metadata for GET /:id requests of servers, and the data can be present in the OpenAPI spec, but it does not need to be in the registry-server.json JSON schema.~ - Note this is no longer in this PR; rebased on #168 which included it - Removed unnecessary enums from the generalized `schema.json`

@tadasant

## Motivation and Context This is in support of modelcontextprotocol/registry#159, to make it easier, I hope. My team noticed some differences in the JSON schema, most notably the "choices" property was missing. I tried to write a tool to do this but slowed down since I am not experienced with Go. This is a first pass, maybe someone else can finish the tooling. I restructured the JSON schema to break out child objects like the YAML file, and brought the descriptions and example into sync. The only differences are two extra properties in the YAML which are computed by the server: - `VersionDetail.is_latest` is not present in the JSON schema, computed by the registry based on modelcontextprotocol/registry#158 - `Server.id` is not present in the JSON schema, generated by the registry The idea is the a tool could look at ServerDetail in the YAML and then generate the schema.json with minimal fix-ups (add a root title, remove `VersionDetail.is_latest` and `Server.id`. ~Question for @tadasant - should `VersionDetail.release_date` be in the JSON schema? I think _no_ (and let it be computed) but it's there right now.~ - aligned with modelcontextprotocol/registry#167 and removed ## How Has This Been Tested? I have tested the JSON schema against the sample server.json in the repo (files and markdown blocks). ## Breaking Changes None. ## Types of changes  - [x] 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  - [x] I have read the [MCP Documentation](https://modelcontextprotocol.io) - [x] 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

tadasant requested review from connor4312, sridharavinash and toby July 9, 2025 15:36

joelverhagen reviewed Jul 9, 2025

View reviewed changes

docs/server-json/schema.json Outdated Show resolved Hide resolved

joelverhagen reviewed Jul 9, 2025

View reviewed changes

joelverhagen mentioned this pull request Jul 9, 2025

Align the server.json schema with the YAML #168

Merged

9 tasks

joelverhagen reviewed Jul 9, 2025

View reviewed changes

Rebase

5739f24

tadasant force-pushed the tadasant/split-server-json branch from 9c674b8 to 5739f24 Compare July 9, 2025 17:48

sridharavinash approved these changes Jul 9, 2025

View reviewed changes

tadasant merged commit a5f417b into main Jul 9, 2025
10 checks passed

tadasant deleted the tadasant/split-server-json branch July 9, 2025 21:02

joelverhagen mentioned this pull request Jul 14, 2025

Add schema version to server.json in MCP template dotnet/extensions#6606

Merged

joelverhagen mentioned this pull request Aug 20, 2025

Plan for schema version changes in the ServerDetail model #139

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Split "general" server.json from "registry-specific" server.json #167

Split "general" server.json from "registry-specific" server.json #167

Uh oh!

tadasant commented Jul 9, 2025 •

edited

Loading

Uh oh!

tadasant commented Jul 9, 2025

Uh oh!

Uh oh!

joelverhagen Jul 9, 2025

Uh oh!

joelverhagen Jul 9, 2025

Uh oh!

joelverhagen commented Jul 9, 2025

Uh oh!

tadasant commented Jul 9, 2025

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Split "general" server.json from "registry-specific" server.json #167

Split "general" server.json from "registry-specific" server.json #167

Uh oh!

Conversation

tadasant commented Jul 9, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

tadasant commented Jul 9, 2025

Uh oh!

Uh oh!

joelverhagen Jul 9, 2025

Choose a reason for hiding this comment

Uh oh!

joelverhagen Jul 9, 2025

Choose a reason for hiding this comment

Uh oh!

joelverhagen commented Jul 9, 2025

Uh oh!

tadasant commented Jul 9, 2025

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

tadasant commented Jul 9, 2025 •

edited

Loading