0ffcd36047Adds an optional `subfolder` field to the Repository object in server.json schema to support MCP servers located within subdirectories of monorepo structures. ## Motivation and Context Addresses issue #360 . The current MCP registry schema doesn't explicitly define how to reference servers that are located within a subdirectory of a Git repository (a "monorepo" structure). This is a common pattern (e.g., [microsoft/mcp](https://github.com/microsoft/mcp) & [awslabs/mcp](https://github.com/awslabs/mcp). ## How Has This Been Tested? - **Validator tests**: Added 6 new test cases covering valid subfolders and security validation (path traversal, absolute paths, invalid characters, etc.) - **Schema validation**: All 11 examples in `examples.md` validate successfully against both `server.schema.json` and `registry-schema.json` - **End-to-end validation**: Publisher tool (`mcp-publisher init`) works correctly and generates valid templates without subfolder - **Backward compatibility**: Existing server.json files without subfolder continue to work unchanged ## Breaking Changes **None.** This is a fully backward-compatible change: - The `subfolder` field is optional (uses `omitempty` JSON tag) - Existing server.json files work unchanged - Publisher tools generate valid templates without subfolder by default - All existing validation and schemas remain compatible ## Types of changes - [ ] 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) - [x] Documentation update ## Checklist - [x] I have read the [MCP Documentation](https://modelcontextprotocol.io) - [x] My code follows the repository's style guidelines - [x] New and existing tests pass locally - [x] I have added appropriate error handling - [x] I have added or updated documentation as needed ### Implementation Details **Schema Changes:** - Added `subfolder` property to Repository definition in `server.schema.json` and `openapi.yaml` - Field is optional with description and example (`"src/everything"`) **Go Model:** - Added `Subfolder string` field to Repository struct with `json:"subfolder,omitempty"` tag - Maintains backward compatibility through omitempty behavior **Security-Focused Validation:** - Validates subfolder is a clean relative path (no leading `/`) - Prevents path traversal attacks (no `..` sequences) - Blocks malformed paths (no trailing `/`, empty segments, invalid characters) - Uses regex validation for allowed characters: `^[a-zA-Z0-9\-_./]+$` **Documentation:** - Added monorepo example to `examples.md` demonstrating subfolder usage - Updated `repository_references.md` with concise subfolder documentation - Maintained consistency across all documentation with same example path **Testing:** - 6 new integration tests in validator covering security and format validation - Updated example count validation tool for new example - All existing tests continue to pass ### Design Decisions 1. **Optional by design**: Most servers don't need subfolder (single-repo pattern is common) 2. **Clean separation**: Repository URL stays clean, subfolder is separate metadata 3. **Security first**: Comprehensive validation prevents common path-based attacks 4. **Publisher tool unchanged**: Default templates don't include subfolder to avoid confusion for typical use cases This enables publishers with monorepo structures to clearly specify server locations while maintaining simplicity for the common single-repository case.
97 lines
3.4 KiB
Go
97 lines
3.4 KiB
Go
package model
|
|
|
|
// Status represents the lifecycle status of a server
|
|
type Status string
|
|
|
|
const (
|
|
StatusActive Status = "active"
|
|
StatusDeprecated Status = "deprecated"
|
|
StatusDeleted Status = "deleted"
|
|
)
|
|
|
|
// Transport represents transport configuration with optional URL templating
|
|
type Transport struct {
|
|
Type string `json:"type"`
|
|
URL string `json:"url,omitempty"`
|
|
Headers []KeyValueInput `json:"headers,omitempty"`
|
|
}
|
|
|
|
// Package represents a package configuration
|
|
type Package struct {
|
|
// RegistryType indicates how to download packages (e.g., "npm", "pypi", "oci", "mcpb")
|
|
RegistryType string `json:"registry_type" minLength:"1"`
|
|
// RegistryBaseURL is the base URL of the package registry
|
|
RegistryBaseURL string `json:"registry_base_url,omitempty"`
|
|
// Identifier is the package identifier - either a package name (for registries) or URL (for direct downloads)
|
|
Identifier string `json:"identifier" minLength:"1"`
|
|
Version string `json:"version" minLength:"1"`
|
|
FileSHA256 string `json:"file_sha256,omitempty"`
|
|
RunTimeHint string `json:"runtime_hint,omitempty"`
|
|
Transport Transport `json:"transport,omitempty"`
|
|
RuntimeArguments []Argument `json:"runtime_arguments,omitempty"`
|
|
PackageArguments []Argument `json:"package_arguments,omitempty"`
|
|
EnvironmentVariables []KeyValueInput `json:"environment_variables,omitempty"`
|
|
}
|
|
|
|
// Repository represents a source code repository as defined in the spec
|
|
type Repository struct {
|
|
URL string `json:"url"`
|
|
Source string `json:"source"`
|
|
ID string `json:"id,omitempty"`
|
|
Subfolder string `json:"subfolder,omitempty"`
|
|
}
|
|
|
|
// Format represents the input format type
|
|
type Format string
|
|
|
|
const (
|
|
FormatString Format = "string"
|
|
FormatNumber Format = "number"
|
|
FormatBoolean Format = "boolean"
|
|
FormatFilePath Format = "file_path"
|
|
)
|
|
|
|
// Input represents a configuration input
|
|
type Input struct {
|
|
Description string `json:"description,omitempty"`
|
|
IsRequired bool `json:"is_required,omitempty"`
|
|
Format Format `json:"format,omitempty"`
|
|
Value string `json:"value,omitempty"`
|
|
IsSecret bool `json:"is_secret,omitempty"`
|
|
Default string `json:"default,omitempty"`
|
|
Choices []string `json:"choices,omitempty"`
|
|
}
|
|
|
|
// InputWithVariables represents an input that can contain variables
|
|
type InputWithVariables struct {
|
|
Input `json:",inline"`
|
|
Variables map[string]Input `json:"variables,omitempty"`
|
|
}
|
|
|
|
// KeyValueInput represents a named input with variables
|
|
type KeyValueInput struct {
|
|
InputWithVariables `json:",inline"`
|
|
Name string `json:"name"`
|
|
}
|
|
|
|
// ArgumentType represents the type of argument
|
|
type ArgumentType string
|
|
|
|
const (
|
|
ArgumentTypePositional ArgumentType = "positional"
|
|
ArgumentTypeNamed ArgumentType = "named"
|
|
)
|
|
|
|
// Argument defines a type that can be either a PositionalArgument or a NamedArgument
|
|
type Argument struct {
|
|
InputWithVariables `json:",inline"`
|
|
Type ArgumentType `json:"type"`
|
|
Name string `json:"name,omitempty"`
|
|
IsRepeated bool `json:"is_repeated,omitempty"`
|
|
ValueHint string `json:"value_hint,omitempty"`
|
|
}
|
|
|
|
// VersionDetail represents the version details of a server (pure MCP spec, no registry metadata)
|
|
type VersionDetail struct {
|
|
Version string `json:"version" minLength:"1"`
|
|
}
|