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
feat: implement server versioning approach with semantic versioning support (#296)
This implements the versioning approach agreed upon in issue #158:
## Key Changes
### Documentation
- Added comprehensive versioning guide (docs/versioning.md)
- Updated FAQ with versioning guidance and best practices
- Enhanced schema description with SHOULD recommendations
### Schema Updates
- Added 255-character limit for version strings in schema.json
- Enhanced version field description with semantic versioning guidance
### Implementation
- New isSemanticVersion() function for proper semver detection
- Enhanced compareSemanticVersions() with prerelease support
- Implemented compareVersions() strategy:
* Both semver: use semantic comparison
* Neither semver: use timestamp comparison
* Mixed: semver versions always take precedence
- Updated publish logic to determine "latest" using new strategy
- Added version length validation (255 char max)
### Versioning Strategy
1. Version MUST be string up to 255 characters
2. SHOULD use semantic versioning for predictable ordering
3. SHOULD align with package versions to reduce confusion
4. MAY use prerelease labels for registry-specific versions
5. Registry attempts semver parsing, falls back to timestamp ordering
6. Clients SHOULD follow same comparison logic
Resolves#158
---------
Co-authored-by: claude[bot] <209825114+claude[bot]@users.noreply.github.com>
Co-authored-by: adam jones <[email protected]>
Copy file name to clipboardExpand all lines: docs/faq.md
+13-3Lines changed: 13 additions & 3 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -72,13 +72,23 @@ More can be added as the community desires; feel free to open an issue if you ar
72
72
Yes, versioning is supported:
73
73
74
74
- Each version gets its own immutable metadata
75
-
- Version bumps are required for updates
75
+
- Version strings must be unique for each server
76
76
- Old versions remain accessible for compatibility
77
-
- The registry tracks which version is "latest"
77
+
- The registry tracks which version is "latest" based on semantic version ordering when possible
78
78
79
79
### How do I update my server metadata?
80
80
81
-
Submit a new `server.json` with an incremented version number. Once published, version metadata is immutable (similar to npm).
81
+
Submit a new `server.json` with a unique version string. Once published, version metadata is immutable (similar to npm).
82
+
83
+
### What version format should I use?
84
+
85
+
The registry accepts any version string up to 255 characters, but we recommend:
86
+
87
+
-**SHOULD use semantic versioning** (e.g., "1.0.2", "2.1.0-alpha") for predictable ordering
88
+
-**SHOULD align with package versions** to reduce confusion
89
+
-**MAY use prerelease labels** (e.g., "1.0.0-1") for registry-specific versions
90
+
91
+
The registry attempts to parse versions as semantic versions for proper ordering. Non-semantic versions are allowed but will be ordered by publication timestamp. See the [versioning guide](./versioning.md) for detailed guidance.
Copy file name to clipboardExpand all lines: docs/server-json/schema.json
+2-1Lines changed: 2 additions & 1 deletion
Original file line number
Diff line number
Diff line change
@@ -36,8 +36,9 @@
36
36
"properties": {
37
37
"version": {
38
38
"type": "string",
39
+
"maxLength": 255,
39
40
"example": "1.0.2",
40
-
"description": "Equivalent of Implementation.version in MCP specification."
41
+
"description": "Version string for this server. SHOULD follow semantic versioning (e.g., '1.0.2', '2.1.0-alpha'). Equivalent of Implementation.version in MCP specification. Non-semantic versions are allowed but may not sort predictably."
This document describes the versioning approach for MCP servers published to the registry.
4
+
5
+
## Overview
6
+
7
+
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.
8
+
9
+
## Version Requirements
10
+
11
+
1.**Version String**: `version` MUST be a string up to 255 characters
12
+
2.**Uniqueness**: Each version for a given server name must be unique
13
+
3.**Immutability**: Once published, version metadata cannot be changed
14
+
15
+
## Best Practices
16
+
17
+
### 1. Use Semantic Versioning
18
+
Server authors SHOULD use [semantic versions](https://semver.org/) following the `MAJOR.MINOR.PATCH` format:
19
+
20
+
```json
21
+
{
22
+
"version_detail": {
23
+
"version": "1.2.3"
24
+
}
25
+
}
26
+
```
27
+
28
+
### 2. Align with Package Versions
29
+
Server authors SHOULD use versions aligned with their underlying packages to reduce confusion:
30
+
31
+
```json
32
+
{
33
+
"version_detail": {
34
+
"version": "1.2.3"
35
+
},
36
+
"packages": [{
37
+
"registry_name": "npm",
38
+
"name": "@myorg/my-server",
39
+
"version": "1.2.3"
40
+
}]
41
+
}
42
+
```
43
+
44
+
### 3. Multiple Registry Versions
45
+
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:
46
+
47
+
```json
48
+
{
49
+
"version_detail": {
50
+
"version": "1.2.3-1"
51
+
},
52
+
"packages": [{
53
+
"registry_name": "npm",
54
+
"name": "@myorg/my-server",
55
+
"version": "1.2.3"
56
+
}]
57
+
}
58
+
```
59
+
60
+
**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`.
61
+
62
+
## Version Ordering and "Latest" Determination
63
+
64
+
### For Semantic Versions
65
+
The registry attempts to parse versions as semantic versions. If successful, it uses semantic version comparison rules to determine:
66
+
- Version ordering in lists
67
+
- Which version is marked as `is_latest`
68
+
69
+
### For Non-Semantic Versions
70
+
If version parsing as semantic version fails:
71
+
- The registry will always mark the version as latest (overriding any previous version)
72
+
- Clients should fall back to using publish timestamp for ordering
73
+
74
+
**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.
75
+
76
+
## Implementation Details
77
+
78
+
### Registry Behavior
79
+
1.**Validation**: Versions are validated for uniqueness within a server name
80
+
2.**Parsing**: The registry attempts to parse each version as semantic version
81
+
3.**Comparison**: Uses semantic version rules when possible, falls back to timestamp
82
+
4.**Latest Flag**: The `is_latest` field is set based on the comparison results
83
+
84
+
### Client Recommendations
85
+
Registry clients SHOULD:
86
+
1. Attempt to interpret versions as semantic versions when possible
87
+
2. Use the following ordering rules:
88
+
- If one version is marked as is_latest: it is later
89
+
- If both versions are valid semver: use semver comparison
90
+
- If neither are valid semver: use publish timestamp
91
+
- If one is semver and one is not: semver version is considered higher
92
+
93
+
## Examples
94
+
95
+
### Valid Semantic Versions
96
+
```javascript
97
+
"1.0.0"// Basic semantic version
98
+
"2.1.3-alpha"// Prerelease version
99
+
"1.0.0-beta.1"// Prerelease with numeric suffix
100
+
"3.0.0-rc.2"// Release candidate
101
+
```
102
+
103
+
### Non-Semantic Versions (Allowed)
104
+
```javascript
105
+
"v1.0"// Version with prefix
106
+
"2021.03.15"// Date-based versioning
107
+
"snapshot"// Development snapshots
108
+
"latest"// Custom versioning scheme
109
+
```
110
+
111
+
### Alignment Examples
112
+
```json
113
+
{
114
+
"version_detail": {
115
+
"version": "1.2.3-1"
116
+
},
117
+
"packages": [{
118
+
"registry_name": "npm",
119
+
"name": "@myorg/k8s-server",
120
+
"version": "1.2.3"
121
+
}]
122
+
}
123
+
```
124
+
125
+
## Migration Path
126
+
127
+
Existing servers with non-semantic versions will continue to work without changes. However, to benefit from proper version ordering, server maintainers are encouraged to:
128
+
129
+
1. Adopt semantic versioning for new releases
130
+
2. Consider the ordering implications when transitioning from non-semantic to semantic versions
131
+
3. Use prerelease labels for registry-specific versioning needs
132
+
133
+
## Future Considerations
134
+
135
+
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.
ErrInvalidVersion=errors.New("invalid version: cannot publish older version after newer version")
17
+
ErrMaxServersReached=errors.New("maximum number of versions for this server reached (10000): please reach out at https://github.com/modelcontextprotocol/registry to explain your use case")
17
18
)
18
19
19
20
// Database defines the interface for database operations with extension wrapper architecture
@@ -23,7 +24,10 @@ type Database interface {
23
24
// GetByID retrieves a single ServerRecord by its ID
![claude[bot]](https://avatars.githubusercontent.com/in/1236702?v=4&size=40){kind=avatar}
0 commit comments