Merge branch 'main' into adamj/filtered-servers-test

Author: rdimitrov

docs/guides/publishing/publish-server.md

@@ -152,7 +152,7 @@ Include your server name in your package README file using this format:
 
 **MCP name format**: `mcp-name: io.github.username/server-name`
 
-Add it to your README.md file (which becomes the package description on PyPI).
+Add it to your README.md file (which becomes the package description on PyPI). This can be in a comment if you want to hide it from display elsewhere.
 
 ### How It Works
 - Registry fetches `https://pypi.org/pypi/your-package/json`
@@ -184,7 +184,7 @@ Include your server name in your package's README using this format:
 
 **MCP name format**: `mcp-name: io.github.username/server-name`
 
-Add a README file to your NuGet package that includes the server name.
+Add a README file to your NuGet package that includes the server name. This can be in a comment if you want to hide it from display elsewhere.
 
 ### How It Works
 - Registry fetches README from `https://api.nuget.org/v3-flatcontainer/{id}/{version}/readme`

docs/reference/api/openapi.yaml

@@ -233,6 +233,11 @@ components:
           type: string
           example: "1.0.2"
           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."
+        website_url:
+          type: string
+          format: uri
+          description: "Optional URL to the server's homepage, documentation, or project website. This provides a central link for users to learn more about the server. Particularly useful when the server has custom installation instructions or setup requirements."
+          example: "https://modelcontextprotocol.io/examples"
         created_at:
           type: string
           format: date-time

docs/reference/server-json/generic-server-json.md

@@ -23,9 +23,10 @@ The official registry has some more restrictions on top of this. See the [offici
 ```json
 {
   "$schema": "https://static.modelcontextprotocol.io/schemas/2025-07-09/server.schema.json",
-  "name": "io.modelcontextprotocol/brave-search",
+  "name": "io.modelcontextprotocol.anonymous/brave-search",
   "description": "MCP server for Brave Search API integration",
   "status": "active",
+  "website_url": "https://anonymous.modelcontextprotocol.io/examples",
   "repository": {
     "url": "https://github.com/modelcontextprotocol/servers",
     "source": "github"
@@ -654,6 +655,21 @@ Some CLI tools bundle an MCP server, without a standalone MCP package or a publi
 }
 ```
 
+### Server with Custom Installation Path
+
+For MCP servers that follow a custom installation path or are embedded in applications without standalone packages, use the `website_url` field to direct users to setup documentation:
+
+```json
+{
+  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-07-09/server.schema.json",
+  "name": "io.modelcontextprotocol.anonymous/embedded-mcp",
+  "description": "MCP server embedded in a Desktop app",
+  "status": "active",
+  "website_url": "https://anonymous.modelcontextprotocol.io/embedded-mcp-guide",
+  "version": "0.1.0"
+}
+```
+
 ### Deprecated Server Example
 
 ```json

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

@@ -73,6 +73,12 @@
           "maxLength": 255,
           "example": "1.0.2",
           "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."
+        },
+        "website_url": {
+          "type": "string",
+          "format": "uri",
+          "description": "Optional URL to the server's homepage, documentation, or project website. This provides a central link for users to learn more about the server. Particularly useful when the server has custom installation instructions or setup requirements.",
+          "example": "https://modelcontextprotocol.io/examples"
         }
       }
     },

internal/api/handlers/v0/publish.go

@@ -50,7 +50,7 @@ func RegisterPublishEndpoint(api huma.API, registry service.RegistryService, cfg
 
 		// Verify that the token has permission to publish the server
 		if !jwtManager.HasPermission(input.Body.Name, auth.PermissionActionPublish, claims.Permissions) {
-			return nil, huma.Error403Forbidden("You do not have permission to publish this server")
+			return nil, huma.Error403Forbidden(buildPermissionErrorMessage(input.Body.Name, claims.Permissions))
 		}
 
 		// Publish the server with extensions
@@ -65,3 +65,24 @@ func RegisterPublishEndpoint(api huma.API, registry service.RegistryService, cfg
 		}, nil
 	})
 }
+
+// buildPermissionErrorMessage creates a detailed error message showing what permissions
+// the user has and what they're trying to publish
+func buildPermissionErrorMessage(attemptedResource string, permissions []auth.Permission) string {
+	var permissionStrs []string
+	for _, perm := range permissions {
+		if perm.Action == auth.PermissionActionPublish {
+			permissionStrs = append(permissionStrs, perm.ResourcePattern)
+		}
+	}
+	
+	errorMsg := "You do not have permission to publish this server"
+	if len(permissionStrs) > 0 {
+		errorMsg += ". You have permission to publish: " + strings.Join(permissionStrs, ", ")
+	} else {
+		errorMsg += ". You do not have any publish permissions"
+	}
+	errorMsg += ". Attempting to publish: " + attemptedResource
+	
+	return errorMsg
+}

internal/api/router/router.go

@@ -2,6 +2,8 @@
 package router
 
 import (
+	"encoding/json"
+	"fmt"
 	"net/http"
 	"strings"
 	"time"
@@ -91,6 +93,40 @@ func WithSkipPaths(paths ...string) MiddlewareOption {
 	}
 }
 
+// handle404 returns a helpful 404 error with suggestions for common mistakes
+func handle404(w http.ResponseWriter, r *http.Request) {
+	w.Header().Set("Content-Type", "application/problem+json")
+	w.WriteHeader(http.StatusNotFound)
+
+	path := r.URL.Path
+	detail := "Endpoint not found. See /docs for the API documentation."
+
+	// Provide suggestions for common API endpoint mistakes
+	if !strings.HasPrefix(path, "/v0/") {
+		detail = fmt.Sprintf(
+			"Endpoint not found. Did you mean '%s'? See /docs for the API documentation.",
+			"/v0"+path,
+		)
+	}
+
+	errorBody := map[string]interface{}{
+		"title":  "Not Found",
+		"status": 404,
+		"detail": detail,
+	}
+
+	// Use JSON marshal to ensure consistent formatting
+	jsonData, err := json.Marshal(errorBody)
+	if err != nil {
+		http.Error(w, "Internal Server Error", http.StatusInternalServerError)
+		return
+	}
+	_, err = w.Write(jsonData)
+	if err != nil {
+		http.Error(w, "Internal Server Error", http.StatusInternalServerError)
+	}
+}
+
 // NewHumaAPI creates a new Huma API with all routes registered
 func NewHumaAPI(cfg *config.Config, registry service.RegistryService, mux *http.ServeMux, metrics *telemetry.Metrics) huma.API {
 	// Create Huma API configuration
@@ -113,11 +149,15 @@ func NewHumaAPI(cfg *config.Config, registry service.RegistryService, mux *http.
 	// Add /metrics for Prometheus metrics using promhttp
 	mux.Handle("/metrics", metrics.PrometheusHandler())
 
-	// Add redirect from / to docs
+	// Add redirect from / to docs and 404 handler for all other routes
 	mux.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
 		if r.URL.Path == "/" {
 			http.Redirect(w, r, "https://github.com/modelcontextprotocol/registry/tree/main/docs", http.StatusTemporaryRedirect)
+			return
 		}
+
+		// Handle 404 for all other routes
+		handle404(w, r)
 	})
 
 	return api

internal/api/server.go

@@ -4,6 +4,7 @@ import (
 	"context"
 	"log"
 	"net/http"
+	"strings"
 	"time"
 
 	"github.com/danielgtaylor/huma/v2"
@@ -14,6 +15,24 @@ import (
 	"github.com/modelcontextprotocol/registry/internal/telemetry"
 )
 
+// TrailingSlashMiddleware redirects requests with trailing slashes to their canonical form
+func TrailingSlashMiddleware(next http.Handler) http.Handler {
+	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		// Only redirect if the path is not "/" and ends with a "/"
+		if r.URL.Path != "/" && strings.HasSuffix(r.URL.Path, "/") {
+			// Create a copy of the URL and remove the trailing slash
+			newURL := *r.URL
+			newURL.Path = strings.TrimSuffix(r.URL.Path, "/")
+			
+			// Use 308 Permanent Redirect to preserve the request method
+			http.Redirect(w, r, newURL.String(), http.StatusPermanentRedirect)
+			return
+		}
+		
+		next.ServeHTTP(w, r)
+	})
+}
+
 // Server represents the HTTP server
 type Server struct {
 	config   *config.Config
@@ -29,13 +48,16 @@ func NewServer(cfg *config.Config, registryService service.RegistryService, metr
 
 	api := router.NewHumaAPI(cfg, registryService, mux, metrics)
 
+	// Wrap the mux with trailing slash middleware
+	handler := TrailingSlashMiddleware(mux)
+
 	server := &Server{
 		config:   cfg,
 		registry: registryService,
 		humaAPI:  api,
 		server: &http.Server{
 			Addr:              cfg.ServerAddress,
-			Handler:           mux,
+			Handler:           handler,
 			ReadHeaderTimeout: 10 * time.Second,
 		},
 	}

internal/api/server_test.go

@@ -0,0 +1,95 @@
+package api_test
+
+import (
+	"net/http"
+	"net/http/httptest"
+	"testing"
+
+	"github.com/modelcontextprotocol/registry/internal/api"
+)
+
+func TestTrailingSlashMiddleware(t *testing.T) {
+	// Create a simple handler that returns "OK"
+	handler := http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+		w.WriteHeader(http.StatusOK)
+		_, _ = w.Write([]byte("OK"))
+	})
+
+	// Wrap with our middleware
+	middleware := api.TrailingSlashMiddleware(handler)
+
+	tests := []struct {
+		name             string
+		path             string
+		expectedStatus   int
+		expectedLocation string
+		expectRedirect   bool
+	}{
+		{
+			name:           "root path should not redirect",
+			path:           "/",
+			expectedStatus: http.StatusOK,
+			expectRedirect: false,
+		},
+		{
+			name:           "path without trailing slash should pass through",
+			path:           "/v0/servers",
+			expectedStatus: http.StatusOK,
+			expectRedirect: false,
+		},
+		{
+			name:             "path with trailing slash should redirect",
+			path:             "/v0/servers/",
+			expectedStatus:   http.StatusPermanentRedirect,
+			expectedLocation: "/v0/servers",
+			expectRedirect:   true,
+		},
+		{
+			name:             "nested path with trailing slash should redirect",
+			path:             "/v0/servers/123/",
+			expectedStatus:   http.StatusPermanentRedirect,
+			expectedLocation: "/v0/servers/123",
+			expectRedirect:   true,
+		},
+		{
+			name:             "deep nested path with trailing slash should redirect",
+			path:             "/v0/auth/github/token/",
+			expectedStatus:   http.StatusPermanentRedirect,
+			expectedLocation: "/v0/auth/github/token",
+			expectRedirect:   true,
+		},
+		{
+			name:           "path with query params and no trailing slash should pass through",
+			path:           "/v0/servers?limit=10",
+			expectedStatus: http.StatusOK,
+			expectRedirect: false,
+		},
+		{
+			name:             "path with query params and trailing slash should redirect preserving query params",
+			path:             "/v0/servers/?limit=10",
+			expectedStatus:   http.StatusPermanentRedirect,
+			expectedLocation: "/v0/servers?limit=10",
+			expectRedirect:   true,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			req := httptest.NewRequest(http.MethodGet, tt.path, nil)
+			w := httptest.NewRecorder()
+
+			middleware.ServeHTTP(w, req)
+
+			if w.Code != tt.expectedStatus {
+				t.Errorf("expected status %d, got %d", tt.expectedStatus, w.Code)
+			}
+
+			if tt.expectRedirect {
+				location := w.Header().Get("Location")
+				if location != tt.expectedLocation {
+					t.Errorf("expected Location header %q, got %q", tt.expectedLocation, location)
+				}
+			}
+		})
+	}
+}

internal/validators/registries/npm.go

@@ -22,6 +22,18 @@ func ValidateNPM(ctx context.Context, pkg model.Package, serverName string) erro
 		pkg.RegistryBaseURL = model.RegistryURLNPM
 	}
 
+	if pkg.Identifier == "" {
+		return fmt.Errorf("package identifier is required for NPM packages")
+	}
+
+	// we need version to look up the package metadata
+	// not providing version will return all the versions
+	// and we won't be able to validate the mcpName field
+	// against the server name
+	if pkg.Version == "" {
+		return fmt.Errorf("package version is required for NPM packages")
+	}
+
 	// Validate that the registry base URL matches NPM exactly
 	if pkg.RegistryBaseURL != model.RegistryURLNPM {
 		return fmt.Errorf("registry type and base URL do not match: '%s' is not valid for registry type '%s'. Expected: %s",

internal/validators/registries/npm_test.go

@@ -20,6 +20,30 @@ func TestValidateNPM_RealPackages(t *testing.T) {
 		expectError  bool
 		errorMessage string
 	}{
+		{
+			name:         "empty package identifier should fail",
+			packageName:  "",
+			version:      "1.0.0",
+			serverName:   "com.example/test",
+			expectError:  true,
+			errorMessage: "package identifier is required for NPM packages",
+		},
+		{
+			name:         "empty package version should fail",
+			packageName:  "test-package",
+			version:      "",
+			serverName:   "com.example/test",
+			expectError:  true,
+			errorMessage: "package version is required for NPM packages",
+		},
+		{
+			name:         "both empty identifier and version should fail with identifier error first",
+			packageName:  "",
+			version:      "",
+			serverName:   "com.example/test",
+			expectError:  true,
+			errorMessage: "package identifier is required for NPM packages",
+		},
 		{
 			name:         "non-existent package should fail",
 			packageName:  generateRandomPackageName(),