Added /validate endpoint and modified mcp-publish so that all validation happens there (#896)

## Motivation and Context

Per discussion with @rdimitrov - all validation now happens in a new
`/validate` endpoint. For details, see below.

## Breaking Changes

None. Validation on /publish only validates schema version and semantic
checks (manual checks) as before. We can add schema validation by
changing a flag in the called to `ValidateJSONSchema` when we're ready.

## Types of changes
- [X] New feature (non-breaking change which adds functionality)

## Checklist
- [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

## Additional context

## API Changes

### 1. New `/validate` Endpoint

A new public endpoint was added for validating `server.json` files
without publishing them.

**Details:**
- **Paths:** `/v0/validate` and `/v0.1/validate`
- **Method:** `POST`
- **Authentication:** None required (public endpoint)
- **Request:** JSON body containing `ServerJSON`
- **Response:** `200 OK` with `ValidationResult` containing:
  - `valid` (boolean)
- `issues` (array of validation issues with type, path, message,
severity, reference)

**Implementation:**
- New handler file: `internal/api/handlers/v0/validate.go`
- Performs comprehensive validation using `ValidationAll` option:
  - Schema version validation
  - Full schema validation
  - Semantic validation
- Always returns `200 OK` - validity is indicated in `result.Valid`
field
- Registered in router for both `/v0` and `/v0.1` prefixes

### 2. `/publish` Endpoint Validation Flow Changes

The publish endpoint now validates earlier in the request flow and
provides clearer error responses.

**Before:** Validation was mixed into `ValidatePublishRequest()` (which
also handled publisher extensions and registry ownership).

**After:**
1. Validates `ServerJSON` structure first using `ValidateServerJSON()`
(schema version + semantic validation)
2. Returns `422 Unprocessable Entity` with message: "Failed to publish
server, invalid schema: call /validate for details"
3. Only proceeds to publisher extensions/registry validation if schema
validation passes
4. No longer calls `ValidatePublishRequest()` internally for schema
validation

**Key Changes:**
- Validation happens before `CreateServer()` call
- Returns `422` on schema/semantic validation failures
- Error message directs users to `/validate` endpoint for details
- `ValidatePublishRequest()` no longer performs schema validation (added
note in comments)

### 3. `/edit` Endpoint Validation Flow Changes

Similar validation changes were applied to the edit endpoint.

**Changes:**
- Added `ValidateServerJSON()` call before server update
- Returns `422` with same error message format on validation failure
- Matches the `/publish` endpoint behavior

### 4. Validator Functions Refactoring

Updated validator functions to reflect that schema validation is now
done separately.

**Changes to `ValidatePublishRequest()`:**
- Removed internal `ValidateServerJSON()` call
- Added note: "ValidateServerJSON should be called separately before
this function"
- Now only validates publisher extensions and registry ownership

**Changes to `ValidateUpdateRequest()`:**
- Same change (removed schema validation, added note)
- Now only validates registry ownership

## CLI Changes

### 1. `validate` Command: Now Uses API Endpoint

**Before:** Performed local validation using
`validators.ValidateServerJSON()`.

**After:** Calls the `/v0/validate` endpoint on the registry.

**Details:**
- Reads `server.json` and sends it to the registry API
- Displays validation results returned by the server
- Uses the same error formatting as before
- Registry URL comes from token file (or default)
- No authentication required (public endpoint)

**Implementation:**
- Added `validateViaAPI()` function that POSTs to `/v0/validate`
- Parses `ValidationResult` response from server
- Uses shared `printValidationIssues()` for formatting

### 2. `publish` Command: Validation Only on 422 Errors

**Before:** Performed upfront local schema validation before publishing.

**After:** Attempts publish first, then validates only if server returns
422.

**Details:**
- Attempts publish immediately (no upfront validation)
- If publish returns 422 (Unprocessable Entity):
  - Calls `/v0/validate` endpoint to get detailed validation errors
  - Formats and displays them using same logic as `validate` command
  - Returns error with migration links
- For non-422 errors (401, 403, etc.), returns original error (no
validation call)

**Implementation Changes:**
- Removed upfront `runValidationAndPrintIssues()` call
- Modified `publishToRegistry()` to return HTTP status code alongside
response/error
- Added 422 detection logic that calls `validateViaAPI()`

### 3. Shared Validation Error Formatting

**Before:** `runValidationAndPrintIssues()` function handled both
validation and printing together.

**After:** Refactored to separate printing logic.

**Details:**
- Created `printValidationIssues()` function - just prints validation
issues (no validation logic)
- Removed `runValidationAndPrintIssues()` function (no longer used)
- Both `validate` and `publish` commands use `printValidationIssues()`
for consistent output

**Behavior:**
- Prints schema validation errors with migration guidance
- Prints all other validation issues with formatting
- Returns formatted error message string for schema issues

## Summary

Both CLI commands now use the `/validate` API endpoint for validation
instead of local validation. The `publish` command validates only after
receiving a 422 error response, and both commands share the same error
formatting via `printValidationIssues()`.

### Benefits

- **Centralized validation logic** - All validation happens on the
server
- **Always up-to-date** - CLI always uses current server validation
rules
- **Consistent experience** - Same validation behavior whether using CLI
or API directly
- **Better separation of concerns** - Schema validation separated from
publisher-specific validation

Author: BobDickinson

CHANGES.md

@@ -12,7 +12,6 @@ import (
 	"path/filepath"
 	"strings"
 
-	"github.com/modelcontextprotocol/registry/internal/validators"
 	apiv0 "github.com/modelcontextprotocol/registry/pkg/api/v0"
 )
 
@@ -38,22 +37,6 @@ func PublishCommand(args []string) error {
 		return fmt.Errorf("invalid server.json: %w", err)
 	}
 
-	// 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
 	homeDir, err := os.UserHomeDir()
 	if err != nil {
@@ -82,8 +65,33 @@ func PublishCommand(args []string) error {
 
 	// Publish to registry
 	_, _ = fmt.Fprintf(os.Stdout, "Publishing to %s...\n", registryURL)
-	response, err := publishToRegistry(registryURL, serverData, token)
+	response, statusCode, err := publishToRegistry(registryURL, serverData, token)
 	if err != nil {
+		// If publish failed with 422, call validate endpoint to show detailed errors
+		if statusCode == http.StatusUnprocessableEntity {
+			_, _ = fmt.Fprintln(os.Stdout, "Validation failed. Checking detailed validation errors...")
+			_, _ = fmt.Fprintln(os.Stdout)
+
+			// Call validate endpoint (same as validate command does)
+			result, validateErr := validateViaAPI(registryURL, serverData)
+			if validateErr != nil {
+				// If validate also fails, return original publish error
+				return fmt.Errorf("publish failed: %w", err)
+			}
+
+			// Print validation results using shared formatting logic
+			formattedErrorMsg := printValidationIssues(result, &serverJSON)
+
+			if !result.Valid {
+				// Return error with formatted message if available
+				if formattedErrorMsg != "" {
+					return fmt.Errorf("%s", formattedErrorMsg)
+				}
+				return fmt.Errorf("validation failed")
+			}
+		}
+
+		// For non-422 errors, return the original error
 		return fmt.Errorf("publish failed: %w", err)
 	}
 
@@ -93,18 +101,18 @@ func PublishCommand(args []string) error {
 	return nil
 }
 
-func publishToRegistry(registryURL string, serverData []byte, token string) (*apiv0.ServerResponse, error) {
+func publishToRegistry(registryURL string, serverData []byte, token string) (*apiv0.ServerResponse, int, error) {
 	// Parse the server JSON data
 	var serverJSON apiv0.ServerJSON
 	err := json.Unmarshal(serverData, &serverJSON)
 	if err != nil {
-		return nil, fmt.Errorf("error parsing server.json file: %w", err)
+		return nil, 0, fmt.Errorf("error parsing server.json file: %w", err)
 	}
 
 	// Convert to JSON
 	jsonData, err := json.Marshal(serverJSON)
 	if err != nil {
-		return nil, fmt.Errorf("error serializing request: %w", err)
+		return nil, 0, fmt.Errorf("error serializing request: %w", err)
 	}
 
 	// Ensure URL ends with the publish endpoint
@@ -116,32 +124,32 @@ func publishToRegistry(registryURL string, serverData []byte, token string) (*ap
 	// Create and send request
 	req, err := http.NewRequestWithContext(context.Background(), http.MethodPost, publishURL, bytes.NewBuffer(jsonData))
 	if err != nil {
-		return nil, fmt.Errorf("error creating request: %w", err)
+		return nil, 0, fmt.Errorf("error creating request: %w", err)
 	}
 	req.Header.Set("Content-Type", "application/json")
 	req.Header.Set("Authorization", "Bearer "+token)
 
 	client := &http.Client{}
 	resp, err := client.Do(req)
 	if err != nil {
-		return nil, fmt.Errorf("error sending request: %w", err)
+		return nil, 0, fmt.Errorf("error sending request: %w", err)
 	}
 	defer resp.Body.Close()
 
 	// Read response
 	body, err := io.ReadAll(resp.Body)
 	if err != nil {
-		return nil, fmt.Errorf("error reading response: %w", err)
+		return nil, resp.StatusCode, fmt.Errorf("error reading response: %w", err)
 	}
 
 	if resp.StatusCode != http.StatusCreated && resp.StatusCode != http.StatusOK {
-		return nil, fmt.Errorf("server returned status %d: %s", resp.StatusCode, body)
+		return nil, resp.StatusCode, fmt.Errorf("server returned status %d: %s", resp.StatusCode, body)
 	}
 
 	var serverResponse apiv0.ServerResponse
 	if err := json.Unmarshal(body, &serverResponse); err != nil {
-		return nil, err
+		return nil, resp.StatusCode, err
 	}
 
-	return &serverResponse, nil
+	return &serverResponse, resp.StatusCode, nil
 }