Fix misleading server.json schema URL label (#803)

The schema in this repo may contain unreleased changes, so labeling it
with a dated version URL is misleading. Change to use a `draft` URL
instead, and add documentation for the schema contribution process.

- Update $id in server.schema.json to use draft URL
- Update example $schema URL in openapi.yaml
- Add Draft (Unreleased) section to CHANGELOG.md
- Add CONTRIBUTING.md with process for making/releasing schema changes

Written by Claude Code, reviewed and tweaked by me.

Co-authored-by: Claude <noreply@anthropic.com>

docs/reference/api/openapi.yaml

@@ -709,7 +709,7 @@ components:
           type: string
           format: uri
           description: JSON Schema URI for this server.json format
-          example: "https://static.modelcontextprotocol.io/schemas/2025-10-17/server.schema.json"
+          example: "https://static.modelcontextprotocol.io/schemas/draft/server.schema.json"
         packages:
           type: array
           items:

docs/reference/server-json/CHANGELOG.md

@@ -2,6 +2,20 @@
 
 Changes to the server.json schema and format.
 
+## Draft (Unreleased)
+
+This section tracks changes that are in development and not yet released. The draft schema is available at [`server.schema.json`](./server.schema.json) in this repository.
+
+### Changed
+
+- No changes yet.
+
+### Notes
+
+When ready for release, changes in this section will be moved to a dated version section (e.g., `## 2025-XX-XX`) and the schema will be published to a versioned URL.
+
+---
+
 ## 2025-10-17
 
 ### Changed

docs/reference/server-json/CONTRIBUTING.md

@@ -0,0 +1,30 @@
+# Contributing to server.json Schema
+
+This document describes the process for making and releasing changes to the `server.json` schema.
+
+## Making Changes
+
+1. **Modify the OpenAPI spec**: Edit `docs/reference/api/openapi.yaml` with your schema changes. The `ServerDetail` component defines the server.json structure.
+
+2. **Regenerate the schema**: Run `make generate-schema` to update `server.schema.json` from the OpenAPI spec.
+
+3. **Update the changelog**: Add your changes to the "Draft (Unreleased)" section in `CHANGELOG.md`.
+
+4. **Open a PR**: Submit a pull request to this repository for review.
+
+## Releasing Changes
+
+When the draft changes are ready for release:
+
+1. **Update the changelog**: Move changes from "Draft (Unreleased)" to a new dated section (e.g., `## 2025-XX-XX`).
+
+2. **Update the schema URL**: Change the `$id` in the schema and the example URL in `openapi.yaml` from `draft` to the release date (e.g., `2025-XX-XX`).
+
+3. **Merge the PR**: Get approval and merge the changes to main.
+
+4. **Publish to static hosting**: Open a PR on [modelcontextprotocol/static](https://github.com/modelcontextprotocol/static/tree/main/schemas) to add the new versioned schema file. This "locks in" the released schema at its versioned URL.
+
+## Schema Versioning
+
+- **Draft schema**: `https://static.modelcontextprotocol.io/schemas/draft/server.schema.json` - For in-progress changes, may change without notice.
+- **Released schemas**: `https://static.modelcontextprotocol.io/schemas/YYYY-MM-DD/server.schema.json` - Stable, versioned by release date.

docs/reference/server-json/server.schema.json

@@ -1,6 +1,6 @@
 {
   "$comment": "This file is auto-generated from docs/reference/api/openapi.yaml. Do not edit manually. Run 'make generate-schema' to update.",
-  "$id": "https://static.modelcontextprotocol.io/schemas/2025-10-17/server.schema.json",
+  "$id": "https://static.modelcontextprotocol.io/schemas/draft/server.schema.json",
   "$ref": "#/definitions/ServerDetail",
   "$schema": "http://json-schema.org/draft-07/schema#",
   "definitions": {
@@ -373,7 +373,7 @@
       "properties": {
         "$schema": {
           "description": "JSON Schema URI for this server.json format",
-          "example": "https://static.modelcontextprotocol.io/schemas/2025-10-17/server.schema.json",
+          "example": "https://static.modelcontextprotocol.io/schemas/draft/server.schema.json",
           "format": "uri",
           "type": "string"
         },

tools/extract-server-schema/main.go

@@ -88,8 +88,12 @@ func main() {
 		}
 	}
 
-	// Build the JSON Schema document with dynamic version from OpenAPI spec
-	schemaID := fmt.Sprintf("https://static.modelcontextprotocol.io/schemas/%s/server.schema.json", version)
+	// Build the JSON Schema document with draft URL
+	// The in-repo schema uses "draft" since it may contain unreleased changes.
+	// When releasing, the schema is published to a versioned URL (e.g., 2025-10-17)
+	// on https://github.com/modelcontextprotocol/static
+	_ = version // version from OpenAPI spec available if needed
+	schemaID := "https://static.modelcontextprotocol.io/schemas/draft/server.schema.json"
 	jsonSchema := map[string]interface{}{
 		"$comment":    "This file is auto-generated from docs/reference/api/openapi.yaml. Do not edit manually. Run 'make generate-schema' to update.",
 		"$schema":     "http://json-schema.org/draft-07/schema#",