Enhanced server.json validation (phase 1) (#636)

Added schema validation and support for exhaustive and more detailed
validation to existing validators. Added new `mcp-publisher validate`
command. No change to any existing tests or behavior other than the new
command.

## Motivation and Context

Many currently published servers fail schema validation. Of those that
pass, many have semantic/logical errors or other errors that make them
impossible to configure, or their configuration when applied doesn't
generate correct MCP server configuration (per their own documentation).

To address this, we need better tooling to validate servers and to
inform server publishers of errors, issues, and best practices in a way
that is clear and actionable, both during server development and at time
of publishing.

I have started a discussion about the broader topic:
https://github.com/modelcontextprotocol/registry/discussions/635

There is also a fairly detailed document describing the design,
architecture, implementation, future plans, etc. See [Enhanced
Validation Design](docs/explanations/proposed-enhanced-validation.md)

This PR is the first step in the process of improving validation. It
adds schema validation and updates all existing validators to use a new
model that allows them to track context and return rich and exhaustive
results. This has been done in a way that is backward compatible
(ValidateServerJSON is unchanged as are all existing validation unit
tests).

There is a new `mcp-publisher` command called `validate` that is
currenty the only place that schema validation and enhanced
(exhaustive/rich) validation results are exposed.

### Changes

Internal Validation improvements
- Schema validation has been implemented and is available as an option
in validation methods (defaults to off)
- Existing validators track the JSON path (context) of the attribute
they're evaluating, passing it to any child validators
- Existing validators are exhaustive (return all issues, not failing
fast on the first error)
- Existing validators return rich validation results, including:
  - type (schema, semantic, linter)
  - severity (error, warn, info)
  - path (JSON path to server.json element)
  - reference (to the schema element or rule that triggered the result)
  - message (currently the same as previous error message)

A new `validate` command has been added to `mcp-publisher` so publishers
can evaluate their server.json before publishing
- Includes new schema validation and previous semantic validation
- Shows full details of all issues encountered during validation

### Usage

Given a server.json that looks like this:

```json
{
  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-09-29/server.schema.json",
  "name": "io.github.BobDickinson/registry",
  "description": "An MCP server that provides [describe what your server does]",
  "repository": {
    "url": "",
    "source": ""
  },
  "version": "=1.0.0",
  "packages": [
    {
      "registryType": "oci",
      "registryBaseUrl": "https://docker.io",
      "identifier": "registry",
      "version": "1.0.0",
      "transport": {
        "type": "sse"
      },
      "packageArguments": [
        {
          "type": "named",
          "name": "--mode",
          "description": "Operation mode",
          "format": "foo"
        }
      ],
      "environmentVariables": [
        {
          "description": "Your API key for the service",
          "isRequired": true,
          "format": "string",
          "isSecret": true,
          "name": "YOUR_API_KEY"
        }
      ]
    }
  ]
}
```

Run the command: 

`mcp-publisher validate server.json`

Which will produce the output:

```bash
❌ Validation failed with 5 issue(s):

1. [error] packages.0.packageArguments.0.format (schema)
   value must be one of "string", "number", "boolean", "filepath"
   Reference: #/definitions/Input/properties/format/enum from: [#/definitions/ServerDetail]/properties/packages/items/[#/definitions/Package]/properties/packageArguments/items/[#/definitions/Argument]/else/[#/definitions/NamedArgument]/allOf/0/[#/definitions/InputWithVariables]/allOf/0/[#/definitions/Input]/properties/format/enum

2. [error] packages.0.transport (schema)
   missing required fields: 'url'
   Reference: #/definitions/SseTransport/required from: [#/definitions/ServerDetail]/properties/packages/items/[#/definitions/Package]/properties/transport/else/else/[#/definitions/SseTransport]/required

3. [error] repository.url (schema)
   '' has invalid format 'uri'
   Reference: #/definitions/Repository/properties/url/format from: [#/definitions/ServerDetail]/properties/repository/[#/definitions/Repository]/properties/url/format

4. [error] version (semantic)
   version must be a specific version, not a range: "=1.0.0"
   Reference: version-looks-like-range

5. [error] packages[0].transport.url (semantic)
   url is required for sse transport type
   Reference: streamable-transport-url-required

Error: validation failed
```

Note in the results above:
- All errors contain the JSON path of the triggering element from
server.json.
- The first three errors are schema errors detected during schema
validation. The `Reference` provided contains an absolute path to the
schema rule that was violated, followed by the full schema path that
enforced that rule (with $ref redirect values substited and enclosed in
square brackets).
- The error messages provided by the existing semantic validators are
exactly the same as the previous error messages those validators
produced.

In the final solution we would remove semantic validators that are
redundant to schema validation (as in number 5 above). We have the
option to use the structured data produced by schema validation to
replace the generic schema validation message with a more descriptive
message if that is an issue (in particular, if the only argument for an
ad-hoc validator is that is produces a better/cleaner message, we would
just move that message creation code to the schema error result
formatter and special case it as opposed to having a redundant
validator).

### What's Next

If this general direction is supported and this PR is accepted, a fast
follow would include:

- Add new validators (infliuenced by observed issues) for both semantic
errors and best practices
- Require passing schema validation (in addition to improved semantic
validation) in order to publish
- Remove existing validation code that is redundant to schema validation
(ensuring error messages remain intelligible)
- Update validation client code and tests to handle the new rich return
types natively

### Issues

Schema validation requires embedding the `server.schema.json` file into
the validators package via `go:embed`, which is restricted from
embedding files outside of the package. For this reason we copy the
schema file into a schema subdir (via a prep target in the makefile) and
we .gitignore it. I tried cleaning up the copy in the make clean target,
but then the linter would complain about the embed target being missing
if it wasn't there during development. I also considered just checking
in the schema file and assuming a separate workflow for updating the
embedded schema file, but it's not clear what that workflow would be or
how it would be maintained. I'm open to a different approach, but the
schema file does need to be embedded somehow for schema validation to
work.

## How Has This Been Tested?
All existing validation tests pass, new tests implemented and all pass.

## Breaking Changes
No breaking changes, no behavior change except new `validate` command

## 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)
- [X] New feature (non-breaking change which adds functionality)
- [ ] Breaking change (fix or feature that would cause existing
functionality to change)
- [ ] Documentation update

## Checklist
<!-- Go over all the following points, and put an `x` in all the boxes
that apply. -->
- [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

---------

Co-authored-by: GitHub Action <action@github.com>

cmd/publisher/commands/init.go

@@ -58,7 +58,7 @@ func InitCommand() error {
 
 	// Create the server structure
 	server := createServerJSON(
-		name, description, version, repoURL, repoSource, subfolder,
+		model.CurrentSchemaURL, name, description, version, repoURL, repoSource, subfolder,
 		packageType, packageIdentifier, version, envVars,
 	)
 
@@ -327,7 +327,7 @@ func detectPackageIdentifier(serverName string, packageType string) string {
 }
 
 func createServerJSON(
-	name, description, version, repoURL, repoSource, subfolder,
+	currentSchema, name, description, version, repoURL, repoSource, subfolder,
 	packageType, packageIdentifier, packageVersion string,
 	envVars []model.KeyValueInput,
 ) apiv0.ServerJSON {
@@ -406,7 +406,7 @@ func createServerJSON(
 
 	// Create server structure
 	return apiv0.ServerJSON{
-		Schema:      model.CurrentSchemaURL,
+		Schema:      currentSchema,
 		Name:        name,
 		Description: description,
 		Repository:  repo,

cmd/publisher/commands/publish.go

@@ -12,8 +12,8 @@ import (
 	"path/filepath"
 	"strings"
 
+	"github.com/modelcontextprotocol/registry/internal/validators"
 	apiv0 "github.com/modelcontextprotocol/registry/pkg/api/v0"
-	"github.com/modelcontextprotocol/registry/pkg/model"
 )
 
 func PublishCommand(args []string) error {
@@ -38,15 +38,20 @@ func PublishCommand(args []string) error {
 		return fmt.Errorf("invalid server.json: %w", err)
 	}
 
-	// Check for deprecated schema and recommend migration
-	// Allow empty schema (will use default) but reject old schemas
-	if serverJSON.Schema != "" && !strings.Contains(serverJSON.Schema, model.CurrentSchemaVersion) {
-		return fmt.Errorf(`deprecated schema detected: %s.
-
-Migrate to the current schema format for new servers.
-
-📋 Migration checklist: https://github.com/modelcontextprotocol/registry/blob/main/docs/reference/server-json/CHANGELOG.md#migration-checklist-for-publishers
-📖 Full changelog with examples: https://github.com/modelcontextprotocol/registry/blob/main/docs/reference/server-json/CHANGELOG.md`, serverJSON.Schema)
+	// Validate schema version (non-empty schema, valid schema, and current schema)
+	// This performs schema version checks without full schema validation
+	// Note: When we enable full validation, use validators.ValidationAll instead
+	result, formattedErrorMsg := runValidationAndPrintIssues(&serverJSON, validators.ValidationSchemaVersionOnly)
+	if !result.Valid {
+		// Return error after printing (all errors already printed by validateServerJSON)
+		// Prefer formatted error message for schema validation errors, otherwise use first error
+		if formattedErrorMsg != "" {
+			return fmt.Errorf("%s", formattedErrorMsg)
+		}
+		if firstErr := result.FirstError(); firstErr != nil {
+			return firstErr
+		}
+		return fmt.Errorf("validation failed")
 	}
 
 	// Load saved token

cmd/publisher/commands/publish_test.go

@@ -41,7 +41,7 @@ func TestPublishCommand_DeprecatedSchema(t *testing.T) {
 			name:        "deprecated 2025-07-09 schema should show warning",
 			schema:      "https://static.modelcontextprotocol.io/schemas/2025-07-09/server.schema.json",
 			expectError: true,
-			errorSubstr: "deprecated schema detected",
+			errorSubstr: "schema version 2025-07-09 is not the current version",
 		},
 		{
 			name:        "current 2025-12-11 schema should pass validation",
@@ -54,10 +54,10 @@ func TestPublishCommand_DeprecatedSchema(t *testing.T) {
 			expectError: false,
 		},
 		{
-			name:        "custom schema without 2025-07-09 should pass validation",
+			name:        "custom schema without 2025-07-09 should fail validation",
 			schema:      "https://example.com/custom.schema.json",
 			expectError: true,
-			errorSubstr: "deprecated schema detected",
+			errorSubstr: "failed to extract schema version from URL",
 		},
 	}
 

cmd/publisher/commands/validate.go

@@ -0,0 +1,162 @@
+package commands
+
+import (
+	"encoding/json"
+	"fmt"
+	"os"
+	"strings"
+
+	"github.com/modelcontextprotocol/registry/internal/validators"
+	apiv0 "github.com/modelcontextprotocol/registry/pkg/api/v0"
+	"github.com/modelcontextprotocol/registry/pkg/model"
+)
+
+// printSchemaValidationErrors prints nicely formatted error messages for schema validation issues
+// (empty schema or non-current schema) with migration guidance to stdout.
+// Returns the formatted error message string if any schema errors were printed, empty string otherwise.
+func printSchemaValidationErrors(result *validators.ValidationResult, serverJSON *apiv0.ServerJSON) string {
+	currentSchemaURL := model.CurrentSchemaURL
+	migrationURL := "https://github.com/modelcontextprotocol/registry/blob/main/docs/reference/server-json/CHANGELOG.md"
+	checklistURL := migrationURL + "#migration-checklist-for-publishers"
+
+	var formattedMsg strings.Builder
+
+	for _, issue := range result.Issues {
+		switch issue.Reference {
+		case "schema-field-required":
+			// Empty/missing schema
+			_, _ = fmt.Fprintf(os.Stdout, "$schema field is required.\n")
+			_, _ = fmt.Fprintln(os.Stdout)
+			_, _ = fmt.Fprintf(os.Stdout, "Expected current schema: %s\n", currentSchemaURL)
+			_, _ = fmt.Fprintln(os.Stdout)
+			_, _ = fmt.Fprintln(os.Stdout, "Run 'mcp-publisher init' to create a new server.json with the correct schema, or update your existing server.json file.")
+			_, _ = fmt.Fprintln(os.Stdout)
+			_, _ = fmt.Fprintf(os.Stdout, "📋 Migration checklist: %s\n", checklistURL)
+			_, _ = fmt.Fprintf(os.Stdout, "📖 Full changelog with examples: %s\n", migrationURL)
+			_, _ = fmt.Fprintln(os.Stdout)
+
+			// Build formatted error message
+			_, _ = fmt.Fprintf(&formattedMsg, "$schema field is required. Expected current schema: %s. 📋 Migration checklist: %s 📖 Full changelog with examples: %s", currentSchemaURL, checklistURL, migrationURL)
+			return formattedMsg.String() // Only one schema error at a time
+
+		case "schema-version-deprecated":
+			// Non-current schema
+			if issue.Severity == validators.ValidationIssueSeverityWarning {
+				// Warning format (for validate command)
+				_, _ = fmt.Fprintf(os.Stdout, "⚠️  Deprecated schema detected: %s\n", serverJSON.Schema)
+			} else {
+				// Error format (for publish command)
+				_, _ = fmt.Fprintf(os.Stdout, "deprecated schema detected: %s.\n", serverJSON.Schema)
+			}
+			_, _ = fmt.Fprintln(os.Stdout)
+			_, _ = fmt.Fprintf(os.Stdout, "Expected current schema: %s\n", currentSchemaURL)
+			_, _ = fmt.Fprintln(os.Stdout)
+			_, _ = fmt.Fprintln(os.Stdout, "Migrate to the current schema format for new servers.")
+			_, _ = fmt.Fprintln(os.Stdout)
+			_, _ = fmt.Fprintf(os.Stdout, "📋 Migration checklist: %s\n", checklistURL)
+			_, _ = fmt.Fprintf(os.Stdout, "📖 Full changelog with examples: %s\n", migrationURL)
+			_, _ = fmt.Fprintln(os.Stdout)
+
+			// Build formatted error message - include the original issue message for test compatibility
+			_, _ = fmt.Fprintf(&formattedMsg, "%s. deprecated schema detected: %s. Expected current schema: %s. Migrate to the current schema format for new servers. 📋 Migration checklist: %s 📖 Full changelog with examples: %s", issue.Message, serverJSON.Schema, currentSchemaURL, checklistURL, migrationURL)
+			return formattedMsg.String() // Only one schema error at a time
+
+		case "schema-version-extraction-error":
+			// Invalid schema URL format - also include migration links for consistency
+			// Build formatted error message with migration links
+			_, _ = fmt.Fprintf(&formattedMsg, "%s. 📋 Migration checklist: %s 📖 Full changelog with examples: %s", issue.Message, checklistURL, migrationURL)
+			return formattedMsg.String()
+		}
+	}
+
+	return ""
+}
+
+// runValidationAndPrintIssues validates the server JSON, prints schema validation errors, and prints all issues.
+// Validation failures are always printed (for both validate and publish commands).
+// Returns the validation result and a formatted error message string for schema validation errors.
+func runValidationAndPrintIssues(serverJSON *apiv0.ServerJSON, opts validators.ValidationOptions) (*validators.ValidationResult, string) {
+	result := validators.ValidateServerJSON(serverJSON, opts)
+
+	// Print schema validation errors/warnings with friendly messages
+	formattedErrorMsg := printSchemaValidationErrors(result, serverJSON)
+
+	if result.Valid {
+		return result, ""
+	}
+
+	// Print all issues
+	_, _ = fmt.Fprintf(os.Stdout, "❌ Validation failed with %d issue(s):\n", len(result.Issues))
+	_, _ = fmt.Fprintln(os.Stdout)
+
+	// Track which schema issues we've already printed to avoid duplicates
+	issueNum := 1
+
+	for _, issue := range result.Issues {
+		// Skip schema issues that were already printed (they're printed by printSchemaValidationErrors above)
+		if issue.Reference == "schema-field-required" || issue.Reference == "schema-version-deprecated" {
+			continue
+		}
+
+		// Print other issues normally
+		_, _ = fmt.Fprintf(os.Stdout, "%d. [%s] %s (%s)\n", issueNum, issue.Severity, issue.Path, issue.Type)
+		_, _ = fmt.Fprintf(os.Stdout, "   %s\n", issue.Message)
+		if issue.Reference != "" {
+			_, _ = fmt.Fprintf(os.Stdout, "   Reference: %s\n", issue.Reference)
+		}
+		_, _ = fmt.Fprintln(os.Stdout)
+		issueNum++
+	}
+
+	return result, formattedErrorMsg
+}
+
+func ValidateCommand(args []string) error {
+	// Parse arguments
+	serverFile := "server.json"
+
+	for _, arg := range args {
+		if arg == "--help" || arg == "-h" {
+			_, _ = fmt.Fprintln(os.Stdout, "Usage: mcp-publisher validate [file]")
+			_, _ = fmt.Fprintln(os.Stdout)
+			_, _ = fmt.Fprintln(os.Stdout, "Validate a server.json file without publishing.")
+			_, _ = fmt.Fprintln(os.Stdout)
+			_, _ = fmt.Fprintln(os.Stdout, "Arguments:")
+			_, _ = fmt.Fprintln(os.Stdout, "  file    Path to server.json file (default: ./server.json)")
+			_, _ = fmt.Fprintln(os.Stdout)
+			_, _ = fmt.Fprintln(os.Stdout, "The validate command performs exhaustive validation, reporting all issues at once.")
+			_, _ = fmt.Fprintln(os.Stdout, "It validates JSON syntax, schema compliance, and semantic rules.")
+			return nil
+		}
+		if !strings.HasPrefix(arg, "-") {
+			serverFile = arg
+		}
+	}
+
+	// Read server file
+	serverData, err := os.ReadFile(serverFile)
+	if err != nil {
+		if os.IsNotExist(err) {
+			return fmt.Errorf("%s not found, please check the file path", serverFile)
+		}
+		return fmt.Errorf("failed to read %s: %w", serverFile, err)
+	}
+
+	// Validate JSON
+	var serverJSON apiv0.ServerJSON
+	if err := json.Unmarshal(serverData, &serverJSON); err != nil {
+		return fmt.Errorf("invalid JSON: %w", err)
+	}
+
+	// Run detailed validation (this is the whole point of the validate command)
+	// Include schema validation for comprehensive validation
+	// Warn about non-current schemas (don't error, just inform)
+	result, _ := runValidationAndPrintIssues(&serverJSON, validators.ValidationAll)
+
+	if result.Valid {
+		_, _ = fmt.Fprintln(os.Stdout, "✅ server.json is valid")
+		return nil
+	}
+
+	return fmt.Errorf("validation failed")
+}

cmd/publisher/main.go

@@ -43,6 +43,8 @@ func main() {
 		err = commands.LogoutCommand()
 	case "publish":
 		err = commands.PublishCommand(os.Args[2:])
+	case "validate":
+		err = commands.ValidateCommand(os.Args[2:])
 	case "--version", "-v", "version":
 		log.Printf("mcp-publisher %s (commit: %s, built: %s)", Version, GitCommit, BuildTime)
 		return
@@ -71,6 +73,7 @@ func printUsage() {
 	_, _ = fmt.Fprintln(os.Stdout, "  login         Authenticate with the registry")
 	_, _ = fmt.Fprintln(os.Stdout, "  logout        Clear saved authentication")
 	_, _ = fmt.Fprintln(os.Stdout, "  publish       Publish server.json to the registry")
+	_, _ = fmt.Fprintln(os.Stdout, "  validate      Validate server.json without publishing")
 	_, _ = fmt.Fprintln(os.Stdout)
 	_, _ = fmt.Fprintln(os.Stdout, "Use 'mcp-publisher <command> --help' for more information about a command.")
 }