Watch

History

Repository files (latest commit first)
Filename	Latest commit message	Latest commit date
adam jones 7b211a46d6 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 <domdomegg@users.noreply.github.com>		2025-08-26 14:55:38 +01:00
..
examples.md	Allow for vendor extensions on servers (#298 )	2025-08-23 09:59:03 +01:00
README.md	Add validation tools for server.json schemas and examples (#176 )	2025-07-15 11:32:54 -07:00
registry-schema.json	Split "general" server.json from "registry-specific" server.json (#167 )	2025-07-09 14:02:43 -07:00
repository_references.md	Add documentation for the repository section (#174 )	2025-07-14 09:36:32 -07:00
schema.json	feat: implement server versioning approach with semantic versioning support (#296 )	2025-08-26 14:55:38 +01:00

README.md

server.json file

There are a variety of use cases where a static representation of an MCP server is necessary:

Discoverability on a centralized registry (i.e. our official Registry work)
Discoverability on a decentralized .well-known endpoint
As a response to an initialization call, so the client knows information about the MCP server to which it is connecting
As an input into crafting a DXT file
Packaged in with the source code of an MCP server, so as to have a structured way to identify a server given just its source code

All of these scenarios (and more) would benefit from an agreed-upon, standardized format that makes it easy to port around and maintain a consistent experience for consumers and developers working with the data. At the end of the day, it's all the same data (or a subset of it). MCP server maintainers should have to manage one copy of this file, and all these use cases can serve that file (or a programmatic derivative/subset of it).

Please note: this is different from the file commonly referred to as mcp.json, which is an MCP client's configuration file for running a specific set of MCP servers. See this issue.

References:

schema.json - The official JSON schema specification for this representation
examples.md - Example manifestations of the JSON schema
registry-schema.json - A more constrained version of schema.json that the official registry supports

Validation Tools

Two validation tools are provided in the repository's tools/ directory:

validate-schemas - Validates that schema.json and registry-schema.json are valid JSON Schema documents
validate-examples - Validates that all JSON examples in examples.md conform to both schemas

Usage

From the repository root:

Validate JSON Schemas

./tools/validate-schemas.sh

Validate Examples

./tools/validate-examples.sh