Add a status field indicating if a server is deprecated or active (#210)

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>
This commit is contained in:
Radoslav Dimitrov 2025-07-31 17:18:35 +03:00 • committed by GitHub
commit d461400055
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
9 changed files with 78 additions and 3 deletions

1
.gitignore vendored
View file

@ -7,3 +7,4 @@ cmd/registry/registry
publisher publisher
validate-examples validate-examples
validate-schemas validate-schemas
.idea/

View file

@ -6,6 +6,7 @@
{ {
"name": "io.modelcontextprotocol/brave-search", "name": "io.modelcontextprotocol/brave-search",
"description": "MCP server for Brave Search API integration", "description": "MCP server for Brave Search API integration",
"status": "active",
"repository": { "repository": {
"url": "https://github.com/modelcontextprotocol/servers", "url": "https://github.com/modelcontextprotocol/servers",
"source": "github", "source": "github",
@ -71,6 +72,7 @@ This will essentially instruct the MCP client to execute `dnx Knapcode.SampleMcp
{ {
"name": "io.modelcontextprotocol/filesystem", "name": "io.modelcontextprotocol/filesystem",
"description": "Node.js server implementing Model Context Protocol (MCP) for filesystem operations.", "description": "Node.js server implementing Model Context Protocol (MCP) for filesystem operations.",
"status": "active",
"repository": { "repository": {
"url": "https://github.com/modelcontextprotocol/servers", "url": "https://github.com/modelcontextprotocol/servers",
"source": "github", "source": "github",
@ -386,3 +388,36 @@ The `dnx` tool ships with the .NET 10 SDK, starting with Preview 6.
] ]
} }
``` ```
## Deprecated Server Example
```json
{
"name": "io.legacy/old-weather-server",
"description": "Legacy weather server - DEPRECATED: Use weather-v2 instead for new projects",
"status": "deprecated",
"repository": {
"url": "https://github.com/example/old-weather",
"source": "github",
"id": "legacy-abc123-def456-789012-345678-901234567890"
},
"version_detail": {
"version": "0.9.5"
},
"packages": [
{
"registry_name": "npm",
"name": "@legacy/old-weather-server",
"version": "0.9.5",
"environment_variables": [
{
"name": "WEATHER_API_KEY",
"description": "Weather API key",
"is_required": true,
"is_secret": true
}
]
}
]
}
```

View file

@ -60,6 +60,12 @@
"description": "Human-readable description of the server's functionality", "description": "Human-readable description of the server's functionality",
"example": "Node.js server implementing Model Context Protocol (MCP) for filesystem operations." "example": "Node.js server implementing Model Context Protocol (MCP) for filesystem operations."
}, },
"status": {
"type": "string",
"enum": ["active", "deprecated"],
"default": "active",
"description": "Server lifecycle status. 'deprecated' indicates the server is no longer recommended for new usage."
},
"repository": { "repository": {
"$ref": "#/$defs/Repository" "$ref": "#/$defs/Repository"
}, },

View file

@ -17,6 +17,7 @@ GET /v0/servers?limit=5000&offset=0
"id": "a5e8a7f0-d4e4-4a1d-b12f-2896a23fd4f1", "id": "a5e8a7f0-d4e4-4a1d-b12f-2896a23fd4f1",
"name": "io.modelcontextprotocol/filesystem", "name": "io.modelcontextprotocol/filesystem",
"description": "Node.js server implementing Model Context Protocol (MCP) for filesystem operations.", "description": "Node.js server implementing Model Context Protocol (MCP) for filesystem operations.",
"status": "active",
"repository": { "repository": {
"url": "https://github.com/modelcontextprotocol/servers", "url": "https://github.com/modelcontextprotocol/servers",
"source": "github", "source": "github",
@ -49,6 +50,7 @@ GET /v0/servers/a5e8a7f0-d4e4-4a1d-b12f-2896a23fd4f1?version=0.0.3
"id": "a5e8a7f0-d4e4-4a1d-b12f-2896a23fd4f1", "id": "a5e8a7f0-d4e4-4a1d-b12f-2896a23fd4f1",
"name": "io.modelcontextprotocol/filesystem", "name": "io.modelcontextprotocol/filesystem",
"description": "Node.js server implementing Model Context Protocol (MCP) for filesystem operations.", "description": "Node.js server implementing Model Context Protocol (MCP) for filesystem operations.",
"status": "active",
"repository": { "repository": {
"url": "https://github.com/modelcontextprotocol/servers", "url": "https://github.com/modelcontextprotocol/servers",
"source": "github", "source": "github",
@ -143,6 +145,7 @@ API Response:
"id": "brave-search-12345", "id": "brave-search-12345",
"name": "io.modelcontextprotocol/brave-search", "name": "io.modelcontextprotocol/brave-search",
"description": "MCP server for Brave Search API integration", "description": "MCP server for Brave Search API integration",
"status": "active",
"repository": { "repository": {
"url": "https://github.com/modelcontextprotocol/servers", "url": "https://github.com/modelcontextprotocol/servers",
"source": "github", "source": "github",
@ -195,6 +198,7 @@ API Response:
"id": "filesystem-67890", "id": "filesystem-67890",
"name": "io.modelcontextprotocol/filesystem", "name": "io.modelcontextprotocol/filesystem",
"description": "Node.js server implementing Model Context Protocol (MCP) for filesystem operations", "description": "Node.js server implementing Model Context Protocol (MCP) for filesystem operations",
"status": "active",
"repository": { "repository": {
"url": "https://github.com/modelcontextprotocol/servers", "url": "https://github.com/modelcontextprotocol/servers",
"source": "github", "source": "github",
@ -268,6 +272,7 @@ API Response:
"id": "remote-fs-54321", "id": "remote-fs-54321",
"name": "Remote Brave Search Server", "name": "Remote Brave Search Server",
"description": "Cloud-hosted MCP Brave Search server", "description": "Cloud-hosted MCP Brave Search server",
"status": "active",
"repository": { "repository": {
"url": "https://github.com/example/remote-fs", "url": "https://github.com/example/remote-fs",
"source": "github", "source": "github",

View file

@ -109,6 +109,12 @@ components:
description: description:
type: string type: string
example: "Node.js server implementing Model Context Protocol (MCP) for filesystem operations." example: "Node.js server implementing Model Context Protocol (MCP) for filesystem operations."
status:
type: string
enum: [active, deprecated]
default: active
description: "Server lifecycle status. 'deprecated' indicates the server is no longer recommended for new usage."
example: "active"
repository: repository:
$ref: '#/components/schemas/Repository' $ref: '#/components/schemas/Repository'
version_detail: version_detail:

View file

@ -10,6 +10,16 @@ const (
AuthMethodNone AuthMethod = "none" AuthMethodNone AuthMethod = "none"
) )
// ServerStatus represents the lifecycle status of a server
type ServerStatus string
const (
// ServerStatusActive represents an actively maintained server (as asserted by the publisher)
ServerStatusActive ServerStatus = "active"
// ServerStatusDeprecated represents a server that is no longer actively maintained
ServerStatusDeprecated ServerStatus = "deprecated"
)
// Authentication holds information about the authentication method and credentials // Authentication holds information about the authentication method and credentials
type Authentication struct { type Authentication struct {
Method AuthMethod `json:"method,omitempty"` Method AuthMethod `json:"method,omitempty"`
@ -114,6 +124,7 @@ type Server struct {
ID string `json:"id" bson:"id"` ID string `json:"id" bson:"id"`
Name string `json:"name" bson:"name"` Name string `json:"name" bson:"name"`
Description string `json:"description" bson:"description"` Description string `json:"description" bson:"description"`
Status ServerStatus `json:"status,omitempty" bson:"status,omitempty"`
Repository Repository `json:"repository" bson:"repository"` Repository Repository `json:"repository" bson:"repository"`
VersionDetail VersionDetail `json:"version_detail" bson:"version_detail"` VersionDetail VersionDetail `json:"version_detail" bson:"version_detail"`
} }

View file

@ -55,6 +55,7 @@ type Package struct {
type ServerJSON struct { type ServerJSON struct {
Name string `json:"name"` Name string `json:"name"`
Description string `json:"description"` Description string `json:"description"`
Status string `json:"status,omitempty"`
Repository Repository `json:"repository"` Repository Repository `json:"repository"`
VersionDetail VersionDetail `json:"version_detail"` VersionDetail VersionDetail `json:"version_detail"`
Packages []Package `json:"packages"` Packages []Package `json:"packages"`
@ -176,6 +177,7 @@ func createCommand() error {
var repoURL string var repoURL string
var repoSource string var repoSource string
var output string var output string
var status string
// Package information flags // Package information flags
var registryName string var registryName string
@ -198,6 +200,7 @@ func createCommand() error {
createFlags.StringVar(&repoSource, "repo-source", "github", "Repository source") createFlags.StringVar(&repoSource, "repo-source", "github", "Repository source")
createFlags.StringVar(&output, "output", "server.json", "Output file path") createFlags.StringVar(&output, "output", "server.json", "Output file path")
createFlags.StringVar(&output, "o", "server.json", "Output file path (shorthand)") createFlags.StringVar(&output, "o", "server.json", "Output file path (shorthand)")
createFlags.StringVar(&status, "status", "active", "Server status (active or deprecated)")
createFlags.StringVar(&registryName, "registry", "npm", "Package registry name") createFlags.StringVar(&registryName, "registry", "npm", "Package registry name")
createFlags.StringVar(&packageName, "package-name", "", "Package name (defaults to server name)") createFlags.StringVar(&packageName, "package-name", "", "Package name (defaults to server name)")
@ -229,6 +232,7 @@ func createCommand() error {
fmt.Fprint(os.Stdout, " --description/-d string Server description (required)\n") fmt.Fprint(os.Stdout, " --description/-d string Server description (required)\n")
fmt.Fprint(os.Stdout, " --repo-url string Repository URL (required)\n") fmt.Fprint(os.Stdout, " --repo-url string Repository URL (required)\n")
fmt.Fprint(os.Stdout, " --version/-v string Server version (default: 1.0.0)\n") fmt.Fprint(os.Stdout, " --version/-v string Server version (default: 1.0.0)\n")
fmt.Fprint(os.Stdout, " --status string Server status (active or deprecated) (default: active)\n")
fmt.Fprint(os.Stdout, " --execute/-e string Command to execute the server\n") fmt.Fprint(os.Stdout, " --execute/-e string Command to execute the server\n")
fmt.Fprint(os.Stdout, " --output/-o string Output file path (default: server.json)\n") fmt.Fprint(os.Stdout, " --output/-o string Output file path (default: server.json)\n")
fmt.Fprint(os.Stdout, " --registry string Package registry name (default: npm)\n") fmt.Fprint(os.Stdout, " --registry string Package registry name (default: npm)\n")
@ -255,6 +259,11 @@ func createCommand() error {
return errors.New("--repo-url is required") return errors.New("--repo-url is required")
} }
// Validate status field
if status != "active" && status != "deprecated" {
return errors.New("--status must be either 'active' or 'deprecated'")
}
// Set defaults // Set defaults
if packageName == "" { if packageName == "" {
packageName = name packageName = name
@ -275,7 +284,7 @@ func createCommand() error {
// Create server structure // Create server structure
server := createServerStructure(name, description, version, repoURL, repoSource, server := createServerStructure(name, description, version, repoURL, repoSource,
registryName, packageName, packageVersion, runtimeHint, execute, envVars, packageArgs) registryName, packageName, packageVersion, runtimeHint, execute, envVars, packageArgs, status)
// Convert to JSON // Convert to JSON
jsonData, err := json.MarshalIndent(server, "", " ") jsonData, err := json.MarshalIndent(server, "", " ")
@ -352,7 +361,7 @@ func publishToRegistry(registryURL string, mcpData []byte, token string) error {
} }
func createServerStructure(name, description, version, repoURL, repoSource, registryName, func createServerStructure(name, description, version, repoURL, repoSource, registryName,
packageName, packageVersion, runtimeHint, execute string, envVars []string, packageArgs []string) ServerJSON { packageName, packageVersion, runtimeHint, execute string, envVars []string, packageArgs []string, status string) ServerJSON {
// Parse environment variables // Parse environment variables
var environmentVariables []EnvironmentVariable var environmentVariables []EnvironmentVariable
for _, envVar := range envVars { for _, envVar := range envVars {
@ -442,6 +451,7 @@ func createServerStructure(name, description, version, repoURL, repoSource, regi
return ServerJSON{ return ServerJSON{
Name: name, Name: name,
Description: description, Description: description,
Status: status,
Repository: Repository{ Repository: Repository{
URL: repoURL, URL: repoURL,
Source: repoSource, Source: repoSource,

View file

@ -1,6 +1,7 @@
{ {
"description": "<your description here>", "description": "<your description here>",
"name": "io.github.<owner>/<server-name>", "name": "io.github.<owner>/<server-name>",
"status": "active",
"packages": [ "packages": [
{ {
"registry_name": "npm", "registry_name": "npm",

View file

@ -22,7 +22,7 @@ const (
// IMPORTANT: Only change this count if you have intentionally added or removed examples // IMPORTANT: Only change this count if you have intentionally added or removed examples
// from the examples.md file. This check prevents accidental formatting changes from // from the examples.md file. This check prevents accidental formatting changes from
// causing examples to be skipped during validation. // causing examples to be skipped during validation.
expectedExampleCount = 8 expectedExampleCount = 9
) )
func main() { func main() {