Big docs tidy up in preparation for launch (#364)
## Motivation and Context Docs currently don't have very clear organisation, and don't explain core flows. This fixes #89 (although we still might want to push these to `https://modelcontextprotocol.io/docs/`), based on the plan there. One minor change from that plan is that I merged tutorials and guides, because they ended up basically being duplicates which I thought would be annoying for us to keep in sync. Additionally in the Diátaxis framework, tutorials and guides are separated by whether they are focused on acquisition of skills (e.g. in a learning environment) or application of skills (e.g. in a work environment). I expect the registry to be something that will be used occasionally in a work environment, rather than a fundamental 'learnable' skill so I think it's reasonable not to have tutorials and fold these into guides. ## How Has This Been Tested? - Read through all these updated docs - Unit and integration tests (that previously used examples.md and use the schema) working - Ran `npx markdown-link-check .` to check all the links work ## Breaking Changes Links to old docs will break, but I don't think there are any. All internal links have been checked and updated. ## 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) - [ ] New feature (non-breaking change which adds functionality) - [ ] Breaking change (fix or feature that would cause existing functionality to change) - [x] Documentation update
This commit is contained in:
adam jones
GitHub
parent
e9884c1d7b
commit
2e7108d366
1 changed files with 1200 additions and 376 deletions
|
|
@ -1,135 +0,0 @@
|
|||
# Server Versioning Guide
|
||||
|
||||
This document describes the versioning approach for MCP servers published to the registry.
|
||||
|
||||
## Overview
|
||||
|
||||
The MCP Registry supports flexible versioning while encouraging semantic versioning best practices. The registry attempts to parse versions as semantic versions for ordering and comparison, but falls back gracefully for non-semantic versions.
|
||||
|
||||
## Version Requirements
|
||||
|
||||
1. **Version String**: `version` MUST be a string up to 255 characters
|
||||
2. **Uniqueness**: Each version for a given server name must be unique
|
||||
3. **Immutability**: Once published, version metadata cannot be changed
|
||||
|
||||
## Best Practices
|
||||
|
||||
### 1. Use Semantic Versioning
|
||||
Server authors SHOULD use [semantic versions](https://semver.org/) following the `MAJOR.MINOR.PATCH` format:
|
||||
|
||||
```json
|
||||
{
|
||||
"version_detail": {
|
||||
"version": "1.2.3"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 2. Align with Package Versions
|
||||
Server authors SHOULD use versions aligned with their underlying packages to reduce confusion:
|
||||
|
||||
```json
|
||||
{
|
||||
"version_detail": {
|
||||
"version": "1.2.3"
|
||||
},
|
||||
"packages": [{
|
||||
"registry_name": "npm",
|
||||
"name": "@myorg/my-server",
|
||||
"version": "1.2.3"
|
||||
}]
|
||||
}
|
||||
```
|
||||
|
||||
### 3. Multiple Registry Versions
|
||||
If server authors expect to have multiple registry versions for the same package version, they SHOULD follow the semantic version spec using the prerelease label:
|
||||
|
||||
```json
|
||||
{
|
||||
"version_detail": {
|
||||
"version": "1.2.3-1"
|
||||
},
|
||||
"packages": [{
|
||||
"registry_name": "npm",
|
||||
"name": "@myorg/my-server",
|
||||
"version": "1.2.3"
|
||||
}]
|
||||
}
|
||||
```
|
||||
|
||||
**Note**: According to semantic versioning, `1.2.3-1` is considered lower than `1.2.3`, so if you expect to need a `1.2.3-1`, you should publish that before `1.2.3`.
|
||||
|
||||
## Version Ordering and "Latest" Determination
|
||||
|
||||
### For Semantic Versions
|
||||
The registry attempts to parse versions as semantic versions. If successful, it uses semantic version comparison rules to determine:
|
||||
- Version ordering in lists
|
||||
- Which version is marked as `is_latest`
|
||||
|
||||
### For Non-Semantic Versions
|
||||
If version parsing as semantic version fails:
|
||||
- The registry will always mark the version as latest (overriding any previous version)
|
||||
- Clients should fall back to using publish timestamp for ordering
|
||||
|
||||
**Important Note**: This behavior means that for servers with mixed semantic and non-semantic versions, the `is_latest` flag may not align with the total ordering. A non-semantic version published after semantic versions will be marked as latest, even if semantic versions are considered "higher" in the ordering.
|
||||
|
||||
## Implementation Details
|
||||
|
||||
### Registry Behavior
|
||||
1. **Validation**: Versions are validated for uniqueness within a server name
|
||||
2. **Parsing**: The registry attempts to parse each version as semantic version
|
||||
3. **Comparison**: Uses semantic version rules when possible, falls back to timestamp
|
||||
4. **Latest Flag**: The `is_latest` field is set based on the comparison results
|
||||
|
||||
### Client Recommendations
|
||||
Registry clients SHOULD:
|
||||
1. Attempt to interpret versions as semantic versions when possible
|
||||
2. Use the following ordering rules:
|
||||
- If one version is marked as is_latest: it is later
|
||||
- If both versions are valid semver: use semver comparison
|
||||
- If neither are valid semver: use publish timestamp
|
||||
- If one is semver and one is not: semver version is considered higher
|
||||
|
||||
## Examples
|
||||
|
||||
### Valid Semantic Versions
|
||||
```javascript
|
||||
"1.0.0" // Basic semantic version
|
||||
"2.1.3-alpha" // Prerelease version
|
||||
"1.0.0-beta.1" // Prerelease with numeric suffix
|
||||
"3.0.0-rc.2" // Release candidate
|
||||
```
|
||||
|
||||
### Non-Semantic Versions (Allowed)
|
||||
```javascript
|
||||
"v1.0" // Version with prefix
|
||||
"2021.03.15" // Date-based versioning
|
||||
"snapshot" // Development snapshots
|
||||
"latest" // Custom versioning scheme
|
||||
```
|
||||
|
||||
### Alignment Examples
|
||||
```json
|
||||
{
|
||||
"version_detail": {
|
||||
"version": "1.2.3-1"
|
||||
},
|
||||
"packages": [{
|
||||
"registry_name": "npm",
|
||||
"name": "@myorg/k8s-server",
|
||||
"version": "1.2.3"
|
||||
}]
|
||||
}
|
||||
```
|
||||
|
||||
## Migration Path
|
||||
|
||||
Existing servers with non-semantic versions will continue to work without changes. However, to benefit from proper version ordering, server maintainers are encouraged to:
|
||||
|
||||
1. Adopt semantic versioning for new releases
|
||||
2. Consider the ordering implications when transitioning from non-semantic to semantic versions
|
||||
3. Use prerelease labels for registry-specific versioning needs
|
||||
|
||||
## Future Considerations
|
||||
|
||||
This versioning approach is designed to be compatible with potential future changes to the MCP specification's `Implementation.version` field. Any SHOULD requirements introduced here may be proposed as updates to the specification through the SEP (Specification Enhancement Proposal) process.
|
||||
Loading…
Reference in a new issue