Improve golang type documentation and examples (#631)
Enhanced Go struct tags throughout `pkg/api/v0/types.go` and `pkg/model/types.go` to better align with the OpenAPI specification. ## Changes - Added comprehensive `doc` tags with detailed field descriptions matching OpenAPI - Added `example` tags showing valid values for fields (e.g., `"io.github.user/weather"`, `"npx"`) - 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 in `docs/reference/api/openapi.yaml`. --------- Signed-off-by: Radoslav Dimitrov <radoslav@stacklok.com> Co-authored-by: Claude <noreply@anthropic.com> Co-authored-by: Radoslav Dimitrov <radoslav@stacklok.com>
This commit is contained in:
adam jones
GitHub
parent
ba609e1c17
commit
f870a4c000
1 changed files with 78 additions and 101 deletions
|
|
@ -6,53 +6,46 @@ import (
|
|||
"github.com/modelcontextprotocol/registry/pkg/model"
|
||||
)
|
||||
|
||||
// RegistryExtensions represents registry-generated metadata
|
||||
type RegistryExtensions struct {
|
||||
Status model.Status `json:"status"`
|
||||
PublishedAt time.Time `json:"publishedAt"`
|
||||
UpdatedAt time.Time `json:"updatedAt,omitempty"`
|
||||
IsLatest bool `json:"isLatest"`
|
||||
Status model.Status `json:"status" enum:"active,deprecated,deleted" doc:"Server lifecycle status"`
|
||||
PublishedAt time.Time `json:"publishedAt" format:"date-time" doc:"Timestamp when the server was first published to the registry"`
|
||||
UpdatedAt time.Time `json:"updatedAt,omitempty" format:"date-time" doc:"Timestamp when the server entry was last updated"`
|
||||
IsLatest bool `json:"isLatest" doc:"Whether this is the latest version of the server"`
|
||||
}
|
||||
|
||||
// ResponseMeta represents the top-level metadata in API responses
|
||||
type ResponseMeta struct {
|
||||
Official *RegistryExtensions `json:"io.modelcontextprotocol.registry/official,omitempty"`
|
||||
Official *RegistryExtensions `json:"io.modelcontextprotocol.registry/official,omitempty" doc:"Official MCP registry metadata"`
|
||||
}
|
||||
|
||||
// ServerResponse represents the new API response format with separated metadata
|
||||
type ServerResponse struct {
|
||||
Server ServerJSON `json:"server"`
|
||||
Meta ResponseMeta `json:"_meta"`
|
||||
Server ServerJSON `json:"server" doc:"Server configuration and metadata"`
|
||||
Meta ResponseMeta `json:"_meta" doc:"Registry-managed metadata"`
|
||||
}
|
||||
|
||||
// ServerListResponse represents the paginated server list response
|
||||
type ServerListResponse struct {
|
||||
Servers []ServerResponse `json:"servers"`
|
||||
Metadata Metadata `json:"metadata"`
|
||||
Servers []ServerResponse `json:"servers" doc:"List of server entries"`
|
||||
Metadata Metadata `json:"metadata" doc:"Pagination metadata"`
|
||||
}
|
||||
|
||||
// ServerMeta represents the structured metadata with known extension fields
|
||||
type ServerMeta struct {
|
||||
PublisherProvided map[string]interface{} `json:"io.modelcontextprotocol.registry/publisher-provided,omitempty"`
|
||||
PublisherProvided map[string]interface{} `json:"io.modelcontextprotocol.registry/publisher-provided,omitempty" doc:"Publisher-provided metadata for downstream registries"`
|
||||
}
|
||||
|
||||
// ServerJSON represents complete server information as defined in the MCP spec, with extension support
|
||||
type ServerJSON struct {
|
||||
Schema string `json:"$schema" required:"true" minLength:"1"`
|
||||
Name string `json:"name" minLength:"1" maxLength:"200"`
|
||||
Description string `json:"description" minLength:"1" maxLength:"100"`
|
||||
Title string `json:"title,omitempty" minLength:"1" maxLength:"100"`
|
||||
Repository model.Repository `json:"repository,omitempty"`
|
||||
Version string `json:"version"`
|
||||
WebsiteURL string `json:"websiteUrl,omitempty"`
|
||||
Icons []model.Icon `json:"icons,omitempty"`
|
||||
Packages []model.Package `json:"packages,omitempty"`
|
||||
Remotes []model.Transport `json:"remotes,omitempty"`
|
||||
Meta *ServerMeta `json:"_meta,omitempty"`
|
||||
Schema string `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"`
|
||||
Name string `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"`
|
||||
Description string `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"`
|
||||
Title string `json:"title,omitempty" minLength:"1" maxLength:"100" doc:"Optional human-readable title or display name for the MCP server." example:"Weather API"`
|
||||
Repository model.Repository `json:"repository,omitempty" doc:"Optional repository metadata for the MCP server source code."`
|
||||
Version string `json:"version" doc:"Version string for this server. SHOULD follow semantic versioning." example:"1.0.2"`
|
||||
WebsiteURL string `json:"websiteUrl,omitempty" format:"uri" doc:"Optional URL to the server's homepage, documentation, or project website." example:"https://modelcontextprotocol.io/examples"`
|
||||
Icons []model.Icon `json:"icons,omitempty" doc:"Optional set of sized icons that the client can display in a user interface."`
|
||||
Packages []model.Package `json:"packages,omitempty" doc:"Array of package configurations"`
|
||||
Remotes []model.Transport `json:"remotes,omitempty" doc:"Array of remote configurations"`
|
||||
Meta *ServerMeta `json:"_meta,omitempty" doc:"Extension metadata using reverse DNS namespacing for vendor-specific data"`
|
||||
}
|
||||
|
||||
// Metadata represents pagination metadata
|
||||
type Metadata struct {
|
||||
NextCursor string `json:"nextCursor,omitempty"`
|
||||
Count int `json:"count"`
|
||||
NextCursor string `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."`
|
||||
Count int `json:"count" doc:"Number of items in current page"`
|
||||
}
|
||||
|
|
|
|||
Loading…
Reference in a new issue