The following PR adds a new server `status` field to support the status
of servers, like deprecated or active
Details:
* Add status field to server.json schema with 'active' and 'deprecated'
values
* Update OpenAPI spec to include status field in Server responses
* Add ServerStatus enum and field to Go model structs
* Update examples to demonstrate status field usage (`active` and
`deprecated`)
Since this is my first PR there's a good chance I might have missed
something so I'll appreciate any feedback to make this and any PRs in
the future easier for you to review 😃Fixes: #181
## Motivation and Context
<!-- Why is this change needed? What problem does it solve? -->
The main goal is to have a way for server authors to notify registry
consumers that a server may no longer be maintained and shouldn't be
considered for using.
## How Has This Been Tested?
<!-- Have you tested this in a real application? Which scenarios were
tested? -->
## Breaking Changes
<!-- Will users need to update their code or configurations? -->
## 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)
- [x] New feature (non-breaking change which adds functionality)
- [ ] Breaking change (fix or feature that would cause existing
functionality to change)
- [ ] 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
## Additional context
<!-- Add any other context, implementation notes, or design decisions
-->
---------
Signed-off-by: Radoslav Dimitrov <radoslav@stacklok.com>
Co-authored-by: Tadas Antanavicius <tadas@tadasant.com>
<!-- Provide a brief summary of your changes -->
## Motivation and Context
<!-- Why is this change needed? What problem does it solve? -->
This is one attempt to resolve
https://github.com/modelcontextprotocol/registry/issues/169.
Instead of adding a new "constant" argument type, I expanded the
existing positional one and just dropped the `value_hint` requirement. I
am not sure if this has VS Code impact @sandy081, @connor4312.
Also, removed unneeded release_date values from the samples.
## How Has This Been Tested?
<!-- Have you tested this in a real application? Which scenarios were
tested? -->
I tested the current server.json samples in the repo against the new
(less strict) schema. Of course they passed (aside from an unrelated bug
in my previous NuGet sample 🤦).
## Breaking Changes
<!-- Will users need to update their code or configurations? -->
## 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. -->
- [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
<!-- Add any other context, implementation notes, or design decisions
-->
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`
<!-- Provide a brief summary of your changes -->
## Motivation and Context
This is in support of
https://github.com/modelcontextprotocol/registry/issues/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
https://github.com/modelcontextprotocol/registry/issues/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
https://github.com/modelcontextprotocol/registry/pull/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
<!-- What types of changes does your code introduce? Put an `x` in all
the boxes that apply: -->
- [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
<!-- 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)
- [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
<!-- Add any other context, implementation notes, or design decisions
-->
