You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Enhanced Go struct tags throughout pkg/api/v0/types.go and pkg/model/types.go to better align with the OpenAPI specification:
- Added comprehensive doc tags with detailed field descriptions
- Added example tags showing valid values for fields
- Added format tags (uri, date-time) for better type specification
- Added pattern and enum tags for validation constraints
- Added placeholder field to Input struct matching OpenAPI spec
- Removed redundant comments in favor of inline struct tags
These changes improve code clarity and make the types more self-documenting, while maintaining compatibility with the OpenAPI schema definitions.
Schemastring`json:"$schema" required:"true" minLength:"1" format:"uri" doc:"JSON Schema URI for this server.json format" example:"https://static.modelcontextprotocol.io/schemas/2025-09-29/server.schema.json"`
36
+
Namestring`json:"name" minLength:"3" maxLength:"200" pattern:"^[a-zA-Z0-9.-]+/[a-zA-Z0-9._-]+$" doc:"Server name in reverse-DNS format. Must contain exactly one forward slash separating namespace from server name." example:"io.github.user/weather"`
37
+
Descriptionstring`json:"description" minLength:"1" maxLength:"100" doc:"Clear human-readable explanation of server functionality." example:"MCP server providing weather data and forecasts via OpenWeatherMap API"`
38
+
Titlestring`json:"title,omitempty" minLength:"1" maxLength:"100" doc:"Optional human-readable title or display name for the MCP server." example:"Weather API"`
39
+
Repository model.Repository`json:"repository,omitempty" doc:"Optional repository metadata for the MCP server source code."`
40
+
Versionstring`json:"version" doc:"Version string for this server. SHOULD follow semantic versioning." example:"1.0.2"`
41
+
WebsiteURLstring`json:"websiteUrl,omitempty" format:"uri" doc:"Optional URL to the server's homepage, documentation, or project website." example:"https://modelcontextprotocol.io/examples"`
42
+
Icons []model.Icon`json:"icons,omitempty" doc:"Optional set of sized icons that the client can display in a user interface."`
43
+
Packages []model.Package`json:"packages,omitempty" doc:"Array of package configurations"`
44
+
Remotes []model.Transport`json:"remotes,omitempty" doc:"Array of remote configurations"`
45
+
Meta*ServerMeta`json:"_meta,omitempty" doc:"Extension metadata using reverse DNS namespacing for vendor-specific data"`
52
46
}
53
47
54
-
// Metadata represents pagination metadata
55
48
typeMetadatastruct {
56
-
NextCursorstring`json:"nextCursor,omitempty"`
57
-
Countint`json:"count"`
49
+
NextCursorstring`json:"nextCursor,omitempty" doc:"Pagination cursor for retrieving the next page of results. Use this exact value in the cursor query parameter of your next request."`
50
+
Countint`json:"count" doc:"Number of items in current page"`
RegistryBaseURLstring`json:"registryBaseUrl,omitempty" format:"uri" doc:"Base URL of the package registry" example:"https://registry.npmjs.org"`
31
29
// Identifier is the package identifier:
32
30
// - For NPM/PyPI/NuGet: package name or ID
33
31
// - For OCI: full image reference (e.g., "ghcr.io/owner/repo:v1.0.0")
34
32
// - For MCPB: direct download URL
35
-
Identifierstring`json:"identifier" minLength:"1"`
33
+
Identifierstring`json:"identifier" minLength:"1" doc:"Package identifier - either a package name (for registries) or URL (for direct downloads)" example:"@modelcontextprotocol/server-brave-search"`
36
34
// Version is the package version (used by npm, pypi, nuget; not used by oci, mcpb where version is in the identifier)
Versionstring`json:"version" minLength:"1" doc:"Package version. Must be a specific version. Version ranges are rejected (e.g., '^1.2.3', '~1.2.3', '>=1.2.3', '1.x', '1.*')." example:"1.0.2"`
38
36
// FileSHA256 is the SHA-256 hash for integrity verification (required for mcpb, optional for others)
39
-
FileSHA256string`json:"fileSha256,omitempty"`
37
+
FileSHA256string`json:"fileSha256,omitempty" pattern:"^[a-f0-9]{64}$" doc:"SHA-256 hash of the package file for integrity verification. Required for MCPB packages and optional for other package types. Authors are responsible for generating correct SHA-256 hashes when creating server.json. If present, MCP clients must validate the downloaded file matches the hash before running packages to ensure file integrity." example:"fe333e598595000ae021bd27117db32ec69af6987f507ba7a63c90638ff633ce"`
40
38
// RunTimeHint suggests the appropriate runtime for the package
41
-
RunTimeHintstring`json:"runtimeHint,omitempty"`
39
+
RunTimeHintstring`json:"runtimeHint,omitempty" doc:"A hint to help clients determine the appropriate runtime for the package. This field should be provided when runtimeArguments are present." example:"npx"`
42
40
// Transport is required and specifies the transport protocol configuration
43
-
TransportTransport`json:"transport"`
41
+
TransportTransport`json:"transport,omitempty" doc:"Transport protocol configuration for the package"`
44
42
// RuntimeArguments are passed to the package's runtime command (e.g., docker, npx)
RuntimeArguments []Argument`json:"runtimeArguments,omitempty" doc:"A list of arguments to be passed to the package's runtime command (such as docker or npx). The runtimeHint field should be provided when runtimeArguments are present."`
46
44
// PackageArguments are passed to the package's binary
EnvironmentVariables []KeyValueInput`json:"environmentVariables,omitempty" doc:"A mapping of environment variables to be set when running the package."`
50
48
}
51
49
52
-
// Repository represents a source code repository as defined in the spec
53
50
typeRepositorystruct {
54
-
URLstring`json:"url"`
55
-
Sourcestring`json:"source"`
56
-
IDstring`json:"id,omitempty"`
57
-
Subfolderstring`json:"subfolder,omitempty"`
51
+
URLstring`json:"url" format:"uri" doc:"Repository URL for browsing source code. Should support both web browsing and git clone operations." example:"https://github.com/modelcontextprotocol/servers"`
52
+
Sourcestring`json:"source" doc:"Repository hosting service identifier. Used by registries to determine validation and API access methods." example:"github"`
53
+
IDstring`json:"id,omitempty" doc:"Repository identifier from the hosting service (e.g., GitHub repo ID). Owned and determined by the source forge. Should remain stable across repository renames and may be used to detect repository resurrection attacks - if a repository is deleted and recreated, the ID should change. For GitHub, use: gh api repos/<owner>/<repo> --jq '.id'" example:"b94b5f7e-c7c6-d760-2c78-a5e9b8a5b8c9"`
54
+
Subfolderstring`json:"subfolder,omitempty" doc:"Optional relative path from repository root to the server location within a monorepo or nested package structure. Must be a clean relative path." example:"src/everything"`
58
55
}
59
56
60
-
// Format represents the input format type
61
57
typeFormatstring
62
58
63
59
const (
@@ -67,57 +63,45 @@ const (
67
63
FormatFilePathFormat="filepath"
68
64
)
69
65
70
-
// Input represents a configuration input
71
66
typeInputstruct {
72
-
Descriptionstring`json:"description,omitempty"`
73
-
IsRequiredbool`json:"isRequired,omitempty"`
74
-
FormatFormat`json:"format,omitempty"`
75
-
Valuestring`json:"value,omitempty"`
76
-
IsSecretbool`json:"isSecret,omitempty"`
77
-
Defaultstring`json:"default,omitempty"`
78
-
Choices []string`json:"choices,omitempty"`
67
+
Descriptionstring`json:"description,omitempty" doc:"A description of the input, which clients can use to provide context to the user."`
68
+
IsRequiredbool`json:"isRequired,omitempty" default:"false" doc:"Whether the input is required"`
69
+
FormatFormat`json:"format,omitempty" default:"string" enum:"string,number,boolean,filepath" doc:"Specifies the input format. Supported values include filepath, which should be interpreted as a file on the user's filesystem."`
70
+
Valuestring`json:"value,omitempty" doc:"The value for the input. If this is not set, the user may be prompted to provide a value. Identifiers wrapped in {curly_braces} will be replaced with the corresponding properties from the input variables map."`
71
+
IsSecretbool`json:"isSecret,omitempty" default:"false" doc:"Indicates whether the input is a secret value (e.g., password, token). If true, clients should handle the value securely."`
72
+
Defaultstring`json:"default,omitempty" doc:"The default value for the input. This should be a valid value for the input. If you want to provide input examples or guidance, use the placeholder field instead."`
73
+
Placeholderstring`json:"placeholder,omitempty" doc:"A placeholder for the input to be displaying during configuration. This is used to provide examples or guidance about the expected form or content of the input."`
74
+
Choices []string`json:"choices,omitempty" doc:"A list of possible values for the input. If provided, the user must select one of these values."`
79
75
}
80
76
81
-
// InputWithVariables represents an input that can contain variables
Variablesmap[string]Input`json:"variables,omitempty" doc:"A map of variable names to their values. Keys in the input value that are wrapped in {curly_braces} will be replaced with the corresponding variable values."`
85
80
}
86
81
87
-
// KeyValueInput represents a named input with variables
88
82
typeKeyValueInputstruct {
89
83
InputWithVariables`json:",inline"`
90
-
Namestring`json:"name"`
84
+
Namestring`json:"name" doc:"Name of the header or environment variable." example:"SOME_VARIABLE"`
91
85
}
92
86
93
-
// ArgumentType represents the type of argument
94
87
typeArgumentTypestring
95
88
96
89
const (
97
90
ArgumentTypePositionalArgumentType="positional"
98
91
ArgumentTypeNamedArgumentType="named"
99
92
)
100
93
101
-
// Argument defines a type that can be either a PositionalArgument or a NamedArgument
102
94
typeArgumentstruct {
103
95
InputWithVariables`json:",inline"`
104
-
TypeArgumentType`json:"type"`
105
-
Namestring`json:"name,omitempty"`
106
-
IsRepeatedbool`json:"isRepeated,omitempty"`
107
-
ValueHintstring`json:"valueHint,omitempty"`
96
+
TypeArgumentType`json:"type" doc:"Argument type: 'positional' or 'named'" example:"positional"`
97
+
Namestring`json:"name,omitempty" doc:"The flag name (for named arguments), including any leading dashes. Empty for positional arguments." example:"--port"`
98
+
ValueHintstring`json:"valueHint,omitempty" doc:"An identifier for positional arguments. Used in transport URL variable substitution." example:"file_path"`
99
+
IsRepeatedbool`json:"isRepeated,omitempty" default:"false" doc:"Whether the argument can be repeated multiple times."`
108
100
}
109
101
110
-
// Icon represents an optionally-sized icon that can be displayed in a user interface
111
102
typeIconstruct {
112
-
// Src is a standard URI pointing to an icon resource (HTTPS URL only for registry)
Srcstring`json:"src" required:"true" format:"uri" maxLength:"255" doc:"A standard URI pointing to an icon resource. Must be an HTTPS URL. Consumers SHOULD take steps to ensure URLs serving icons are from the same domain as the server or a trusted domain. Consumers SHOULD take appropriate precautions when consuming SVGs as they can contain executable JavaScript." example:"https://example.com/icon.png"`
104
+
MimeType*string`json:"mimeType,omitempty" enum:"image/png,image/jpeg,image/jpg,image/svg+xml,image/webp" doc:"Optional MIME type override if the source MIME type is missing or generic. Must be one of: image/png, image/jpeg, image/jpg, image/svg+xml, image/webp." example:"image/png"`
105
+
Sizes []string`json:"sizes,omitempty" doc:"Optional array of strings that specify sizes at which the icon can be used. Each string should be in WxH format (e.g., '48x48', '96x96') or 'any' for scalable formats like SVG. If not provided, the client should assume that the icon can be used at any size." items.pattern:"^(\\d+x\\d+|any)$"`
106
+
Theme*string`json:"theme,omitempty" enum:"light,dark" doc:"Optional specifier for the theme this icon is designed for. 'light' indicates the icon is designed to be used with a light background, and 'dark' indicates the icon is designed to be used with a dark background. If not provided, the client should assume the icon can be used with any theme."`
0 commit comments