d461400055The 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>
423 lines
No EOL
10 KiB
Markdown
423 lines
No EOL
10 KiB
Markdown
# Server JSON Examples
|
|
|
|
## Basic Server with NPM Package
|
|
|
|
```json
|
|
{
|
|
"name": "io.modelcontextprotocol/brave-search",
|
|
"description": "MCP server for Brave Search API integration",
|
|
"status": "active",
|
|
"repository": {
|
|
"url": "https://github.com/modelcontextprotocol/servers",
|
|
"source": "github",
|
|
"id": "abc123de-f456-7890-ghij-klmnopqrstuv"
|
|
},
|
|
"version_detail": {
|
|
"version": "1.0.2"
|
|
},
|
|
"packages": [
|
|
{
|
|
"registry_name": "npm",
|
|
"name": "@modelcontextprotocol/server-brave-search",
|
|
"version": "1.0.2",
|
|
"environment_variables": [
|
|
{
|
|
"name": "BRAVE_API_KEY",
|
|
"description": "Brave Search API Key",
|
|
"is_required": true,
|
|
"is_secret": true
|
|
}
|
|
]
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
## Constant (fixed) arguments needed to start the MCP server
|
|
|
|
Suppose your MCP server application requires a `mcp start` CLI arguments to start in MCP server mode. Express these as positional arguments like this:
|
|
|
|
```json
|
|
{
|
|
"name": "Knapcode.SampleMcpServer",
|
|
"description": "Sample NuGet MCP server for a random number and random weather",
|
|
"version_detail": {
|
|
"version": "0.4.0-beta"
|
|
},
|
|
"packages": [
|
|
{
|
|
"registry_name": "nuget",
|
|
"name": "Knapcode.SampleMcpServer",
|
|
"version": "0.4.0-beta",
|
|
"package_arguments": [
|
|
{
|
|
"type": "positional",
|
|
"value": "mcp"
|
|
},
|
|
{
|
|
"type": "positional",
|
|
"value": "start"
|
|
}
|
|
]
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
This will essentially instruct the MCP client to execute `dnx Knapcode.SampleMcpServer@0.4.0-beta -- mcp start` instead of the default `dnx Knapcode.SampleMcpServer@0.4.0-beta` (when no `package_arguments` are provided).
|
|
|
|
## Filesystem Server with Multiple Packages
|
|
|
|
```json
|
|
{
|
|
"name": "io.modelcontextprotocol/filesystem",
|
|
"description": "Node.js server implementing Model Context Protocol (MCP) for filesystem operations.",
|
|
"status": "active",
|
|
"repository": {
|
|
"url": "https://github.com/modelcontextprotocol/servers",
|
|
"source": "github",
|
|
"id": "b94b5f7e-c7c6-d760-2c78-a5e9b8a5b8c9"
|
|
},
|
|
"version_detail": {
|
|
"version": "1.0.2"
|
|
},
|
|
"packages": [
|
|
{
|
|
"registry_name": "npm",
|
|
"name": "@modelcontextprotocol/server-filesystem",
|
|
"version": "1.0.2",
|
|
"package_arguments": [
|
|
{
|
|
"type": "positional",
|
|
"value_hint": "target_dir",
|
|
"description": "Path to access",
|
|
"default": "/Users/username/Desktop",
|
|
"is_required": true,
|
|
"is_repeated": true
|
|
}
|
|
],
|
|
"environment_variables": [
|
|
{
|
|
"name": "LOG_LEVEL",
|
|
"description": "Logging level (debug, info, warn, error)",
|
|
"default": "info"
|
|
}
|
|
]
|
|
},
|
|
{
|
|
"registry_name": "docker",
|
|
"name": "mcp/filesystem",
|
|
"version": "1.0.2",
|
|
"runtime_arguments": [
|
|
{
|
|
"type": "named",
|
|
"description": "Mount a volume into the container",
|
|
"name": "--mount",
|
|
"value": "type=bind,src={source_path},dst={target_path}",
|
|
"is_required": true,
|
|
"is_repeated": true,
|
|
"variables": {
|
|
"source_path": {
|
|
"description": "Source path on host",
|
|
"format": "filepath",
|
|
"is_required": true
|
|
},
|
|
"target_path": {
|
|
"description": "Path to mount in the container. It should be rooted in `/project` directory.",
|
|
"is_required": true,
|
|
"default": "/project"
|
|
}
|
|
}
|
|
}
|
|
],
|
|
"package_arguments": [
|
|
{
|
|
"type": "positional",
|
|
"value_hint": "target_dir",
|
|
"value": "/project"
|
|
}
|
|
],
|
|
"environment_variables": [
|
|
{
|
|
"name": "LOG_LEVEL",
|
|
"description": "Logging level (debug, info, warn, error)",
|
|
"default": "info"
|
|
}
|
|
]
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
## Remote Server Example
|
|
|
|
```json
|
|
{
|
|
"name": "Remote Filesystem Server",
|
|
"description": "Cloud-hosted MCP filesystem server",
|
|
"repository": {
|
|
"url": "https://github.com/example/remote-fs",
|
|
"source": "github",
|
|
"id": "xyz789ab-cdef-0123-4567-890ghijklmno"
|
|
},
|
|
"version_detail": {
|
|
"version": "2.0.0"
|
|
},
|
|
"remotes": [
|
|
{
|
|
"transport_type": "sse",
|
|
"url": "https://mcp-fs.example.com/sse"
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
## Python Package Example
|
|
|
|
```json
|
|
{
|
|
"name": "weather-mcp-server",
|
|
"description": "Python MCP server for weather data access",
|
|
"repository": {
|
|
"url": "https://github.com/example/weather-mcp",
|
|
"source": "github",
|
|
"id": "def456gh-ijkl-7890-mnop-qrstuvwxyz12"
|
|
},
|
|
"version_detail": {
|
|
"version": "0.5.0"
|
|
},
|
|
"packages": [
|
|
{
|
|
"registry_name": "pypi",
|
|
"name": "weather-mcp-server",
|
|
"version": "0.5.0",
|
|
"runtime_hint": "uvx",
|
|
"environment_variables": [
|
|
{
|
|
"name": "WEATHER_API_KEY",
|
|
"description": "API key for weather service",
|
|
"is_required": true,
|
|
"is_secret": true
|
|
},
|
|
{
|
|
"name": "WEATHER_UNITS",
|
|
"description": "Temperature units (celsius, fahrenheit)",
|
|
"default": "celsius"
|
|
}
|
|
]
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
## NuGet (.NET) Package Example
|
|
|
|
The `dnx` tool ships with the .NET 10 SDK, starting with Preview 6.
|
|
|
|
```json
|
|
{
|
|
"name": "Knapcode.SampleMcpServer",
|
|
"description": "Sample NuGet MCP server for a random number and random weather",
|
|
"repository": {
|
|
"url": "https://github.com/joelverhagen/Knapcode.SampleMcpServer",
|
|
"source": "github",
|
|
"id": "example-nuget-id-0000-1111-222222222222"
|
|
},
|
|
"version_detail": {
|
|
"version": "0.5.0"
|
|
},
|
|
"packages": [
|
|
{
|
|
"registry_name": "nuget",
|
|
"name": "Knapcode.SampleMcpServer",
|
|
"version": "0.5.0",
|
|
"runtime_hint": "dnx",
|
|
"environment_variables": [
|
|
{
|
|
"name": "WEATHER_CHOICES",
|
|
"description": "Comma separated list of weather descriptions to randomly select.",
|
|
"is_required": true,
|
|
"is_secret": false
|
|
}
|
|
]
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
## Complex Docker Server with Multiple Arguments
|
|
|
|
```json
|
|
{
|
|
"name": "mcp-database-manager",
|
|
"description": "MCP server for database operations with support for multiple database types",
|
|
"repository": {
|
|
"url": "https://github.com/example/mcp-database",
|
|
"source": "github",
|
|
"id": "ghi789jk-lmno-1234-pqrs-tuvwxyz56789"
|
|
},
|
|
"version_detail": {
|
|
"version": "3.1.0"
|
|
},
|
|
"packages": [
|
|
{
|
|
"registry_name": "docker",
|
|
"name": "mcp/database-manager",
|
|
"version": "3.1.0",
|
|
"runtime_arguments": [
|
|
{
|
|
"type": "named",
|
|
"name": "--network",
|
|
"value": "host",
|
|
"description": "Use host network mode"
|
|
},
|
|
{
|
|
"type": "named",
|
|
"name": "-e",
|
|
"value": "DB_TYPE={db_type}",
|
|
"description": "Database type to connect to",
|
|
"is_repeated": true,
|
|
"variables": {
|
|
"db_type": {
|
|
"description": "Type of database",
|
|
"choices": ["postgres", "mysql", "mongodb", "redis"],
|
|
"is_required": true
|
|
}
|
|
}
|
|
}
|
|
],
|
|
"package_arguments": [
|
|
{
|
|
"type": "named",
|
|
"name": "--host",
|
|
"description": "Database host",
|
|
"default": "localhost",
|
|
"is_required": true
|
|
},
|
|
{
|
|
"type": "named",
|
|
"name": "--port",
|
|
"description": "Database port",
|
|
"format": "number"
|
|
},
|
|
{
|
|
"type": "positional",
|
|
"value_hint": "database_name",
|
|
"description": "Name of the database to connect to",
|
|
"is_required": true
|
|
}
|
|
],
|
|
"environment_variables": [
|
|
{
|
|
"name": "DB_USERNAME",
|
|
"description": "Database username",
|
|
"is_required": true
|
|
},
|
|
{
|
|
"name": "DB_PASSWORD",
|
|
"description": "Database password",
|
|
"is_required": true,
|
|
"is_secret": true
|
|
},
|
|
{
|
|
"name": "SSL_MODE",
|
|
"description": "SSL connection mode",
|
|
"default": "prefer",
|
|
"choices": ["disable", "prefer", "require"]
|
|
}
|
|
]
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
## Server with Remote and Package Options
|
|
|
|
```json
|
|
{
|
|
"name": "hybrid-mcp-server",
|
|
"description": "MCP server available as both local package and remote service",
|
|
"repository": {
|
|
"url": "https://github.com/example/hybrid-mcp",
|
|
"source": "github",
|
|
"id": "klm012no-pqrs-3456-tuvw-xyz789abcdef"
|
|
},
|
|
"version_detail": {
|
|
"version": "1.5.0"
|
|
},
|
|
"packages": [
|
|
{
|
|
"registry_name": "npm",
|
|
"name": "@example/hybrid-mcp-server",
|
|
"version": "1.5.0",
|
|
"runtime_hint": "npx",
|
|
"package_arguments": [
|
|
{
|
|
"type": "named",
|
|
"name": "--mode",
|
|
"description": "Operation mode",
|
|
"default": "local",
|
|
"choices": ["local", "cached", "proxy"]
|
|
}
|
|
]
|
|
}
|
|
],
|
|
"remotes": [
|
|
{
|
|
"transport_type": "sse",
|
|
"url": "https://hybrid-mcp.example.com/sse",
|
|
"headers": [
|
|
{
|
|
"name": "X-API-Key",
|
|
"description": "API key for authentication",
|
|
"is_required": true,
|
|
"is_secret": true
|
|
},
|
|
{
|
|
"name": "X-Region",
|
|
"description": "Service region",
|
|
"default": "us-east-1",
|
|
"choices": ["us-east-1", "eu-west-1", "ap-southeast-1"]
|
|
}
|
|
]
|
|
},
|
|
{
|
|
"transport_type": "streamable",
|
|
"url": "https://hybrid-mcp.example.com/stream"
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
## 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
|
|
}
|
|
]
|
|
}
|
|
]
|
|
}
|
|
``` |