Merge pull request github#328 from xenoscopic/version-pinning

security: enable version pinning for local MCP servers

Author: xenoscopic

CONTRIBUTING.md

@@ -64,6 +64,7 @@ about:
   icon: https://avatars.githubusercontent.com/u/182288589?s=200&v=4
 source:
   project: https://github.com/myorg/my-orgdb-mcp
+  commit: 0123456789abcdef0123456789abcdef01234567
 config:
   description: Configure the connection to TODO
   secrets:

cmd/build/main.go

@@ -12,7 +12,6 @@ import (
 	"strings"
 
 	"github.com/docker/mcp-registry/internal/mcp"
-	"github.com/docker/mcp-registry/pkg/github"
 	"github.com/docker/mcp-registry/pkg/servers"
 )
 
@@ -117,39 +116,19 @@ func buildDockerEnv(additionalEnv ...string) []string {
 }
 
 func buildMcpImage(ctx context.Context, server servers.Server) error {
-	projectURL := server.Source.Project
-	branch := server.Source.Branch
-	directory := server.Source.Directory
-
-	client := github.New()
-
-	repository, err := client.GetProjectRepository(ctx, projectURL)
-	if err != nil {
-		return err
-	}
-
-	if branch == "" {
-		branch = repository.GetDefaultBranch()
+	commit := server.Source.Commit
+	if commit == "" {
+		return fmt.Errorf("local server %s must specify source.commit before building", server.Name)
 	}
 
-	sha, err := client.GetCommitSHA1(ctx, projectURL, branch)
-	if err != nil {
-		return err
-	}
-
-	gitURL := projectURL + ".git#"
-	if branch != "" {
-		gitURL += branch
-	}
-	if directory != "" && directory != "." {
-		gitURL += ":" + directory
-	}
+	gitURL := server.GetContext()
 
 	var cmd *exec.Cmd
 	token := os.Getenv("GITHUB_TOKEN")
 
 	buildArgs := []string{
-		"-f", server.GetDockerfile(), "-t", "check", "-t", server.Image, "--label", "org.opencontainers.image.revision=" + sha, "--load",
+		"-f", server.GetDockerfile(), "-t", "check", "-t", server.Image,
+		"--label", "org.opencontainers.image.revision=" + commit, "--load",
 	}
 
 	if server.Source.BuildTarget != "" {

cmd/clean/main.go

@@ -1,3 +1,25 @@
+/*
+Copyright © 2025 Docker, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.
+*/
+
 package main
 
 import (

cmd/create/main.go

@@ -128,10 +128,7 @@ func run(ctx context.Context, buildURL, name, category, userProvidedImage string
 	}
 
 	if build && userProvidedImage == "" {
-		gitURL := projectURL + ".git#"
-		if branch != "" {
-			gitURL += branch
-		}
+		gitURL := projectURL + ".git#" + sha
 		if directory != "" && directory != "." {
 			gitURL += ":" + directory
 		}
@@ -219,6 +216,7 @@ func run(ctx context.Context, buildURL, name, category, userProvidedImage string
 			Project:   projectURL,
 			Upstream:  upstream,
 			Branch:    branch,
+			Commit:    sha,
 			Directory: directory,
 		},
 		Run: servers.Run{

cmd/validate/main.go

@@ -43,6 +43,10 @@ func run(name string) error {
 		return err
 	}
 
+	if err := isCommitPinnedIfNecessary(name); err != nil {
+		return err
+	}
+
 	if err := areSecretsValid(name); err != nil {
 		return err
 	}
@@ -72,10 +76,21 @@ func run(name string) error {
 	return nil
 }
 
+// legacyNameExceptions enumerates catalog entries added before current naming rules.
+var legacyNameExceptions = map[string]bool{
+	"SQLite":              true,
+	"osp_marketing_tools": true,
+	"youtube_transcript":  true,
+}
+
 // check if the name is a valid
 func isNameValid(name string) error {
 	// check if name has only letters, numbers, and hyphens
 	if !regexp.MustCompile(`^[a-z0-9-]+$`).MatchString(name) {
+		if legacyNameExceptions[name] {
+			fmt.Printf("⚠️ Name %s is grandfathered and bypasses naming rules.\n", name)
+			return nil
+		}
 		return fmt.Errorf("name is not valid. It must be a lowercase string with only letters, numbers, and hyphens")
 	}
 
@@ -104,21 +119,63 @@ func isDirectoryValid(name string) error {
 	return nil
 }
 
+var commitSHA1Pattern = regexp.MustCompile(`^[a-f0-9]{40}$`)
+
+// isCommitPinnedIfNecessary ensures that every local server is pinned to a specific commit.
+func isCommitPinnedIfNecessary(name string) error {
+	server, err := readServerYaml(name)
+	if err != nil {
+		return err
+	}
+
+	if server.Type != "server" {
+		fmt.Println("✅ Commit pin not required (non-local server)")
+		return nil
+	}
+
+	if server.Source.Commit == "" {
+		return fmt.Errorf("local server must specify source.commit to pin the audited revision")
+	}
+
+	if !commitSHA1Pattern.MatchString(strings.ToLower(server.Source.Commit)) {
+		return fmt.Errorf("source.commit must be a 40-character lowercase SHA1 (got %q)", server.Source.Commit)
+	}
+
+	fmt.Println("✅ Commit is pinned")
+	return nil
+}
+
+// secretNamePattern validates that secret names match the expected prefix.name
+// format requirement.
+var secretNamePattern = regexp.MustCompile(`^[A-Za-z0-9_-]+\.[A-Za-z0-9._-]+$`)
+
+// legacySecretNameExceptions enumerates secrets defined before the current
+// naming rules were introduced.
+var legacySecretNameExceptions = map[string]map[string]bool{
+	"nasdaq-data-link": {
+		"nasdaq_data_link_api_key": true,
+	},
+	"sec-edgar": {
+		"sec_edgar_user_agent": true,
+	},
+}
+
 // check if the secrets are valid
-// secrets must be prefixed with the name of the server
 func areSecretsValid(name string) error {
-	// read the server.yaml file
 	server, err := readServerYaml(name)
 	if err != nil {
 		return err
 	}
 
-	// check if the server.yaml file has a valid secrets
-	if len(server.Config.Secrets) > 0 {
-		for _, secret := range server.Config.Secrets {
-			if !strings.HasPrefix(secret.Name, name+".") {
-				return fmt.Errorf("secret %s is not valid. It must be prefixed with the name of the server", secret.Name)
+	// Ensure that all secrets match the expected format. We no longer require
+	// that the prefix matches the server name.
+	for _, secret := range server.Config.Secrets {
+		if !secretNamePattern.MatchString(secret.Name) {
+			if legacySecretNameExceptions[name][secret.Name] {
+				fmt.Printf("⚠️ Secret %s for %s is grandfathered and bypasses naming rules.\n", secret.Name, name)
+				continue
 			}
+			return fmt.Errorf("secret %s is not valid. It must use prefix.name format with alphanumeric characters, hyphen, period, or underscore", secret.Name)
 		}
 	}
 
@@ -182,44 +239,51 @@ func isIconValid(name string) error {
 	}
 
 	if server.About.Icon == "" {
-		fmt.Println("🛑 No icon found")
+		fmt.Println("⚠️ No icon found")
 		return nil
 	}
 	// fetch the image and check the size
 	resp, err := http.Get(server.About.Icon)
 	if err != nil {
-		fmt.Println("🛑 Icon could not be fetched")
+		fmt.Println("⚠️ Icon could not be fetched")
 		return nil
 	}
 	defer resp.Body.Close()
 
 	if resp.StatusCode != 200 {
-		fmt.Printf("🛑 Icon could not be fetched, status code: %d, url: %s\n", resp.StatusCode, server.About.Icon)
+		fmt.Printf("⚠️ Icon could not be fetched, status code: %d, url: %s\n", resp.StatusCode, server.About.Icon)
 		return nil
 	}
 	if resp.ContentLength > 2*1024*1024 {
-		fmt.Println("🛑 Icon is too large. It must be less than 2MB")
+		fmt.Println("⚠️ Icon is too large. It must be less than 2MB")
 		return nil
 	}
 
-	// Check content type for SVG support
+	// Check content type for SVG, favicon, and WebP support
 	contentType := resp.Header.Get("Content-Type")
-	if contentType == "image/svg+xml" {
+	switch contentType {
+	case "image/svg+xml":
 		fmt.Println("✅ Icon is valid (SVG)")
 		return nil
+	case "image/x-icon":
+		fmt.Println("✅ Icon is valid (favicon)")
+		return nil
+	case "image/webp":
+		fmt.Println("✅ Icon is valid (WebP)")
+		return nil
 	}
 
 	img, format, err := image.DecodeConfig(resp.Body)
 	if err != nil {
 		return err
 	}
-	if format != "png" {
-		fmt.Println("🛑 Icon is not a png or svg. It must be a png or svg")
+	if format != "png" && format != "jpeg" {
+		fmt.Println("⚠️ Icon is not a png or svg. It must be a png or svg")
 		return nil
 	}
 
 	if img.Width > 512 || img.Height > 512 {
-		fmt.Println("🛑 Icon is too large. It must be less than 512x512")
+		fmt.Println("⚠️ Icon is too large. It must be less than 512x512")
 		return nil
 	}
 
@@ -304,6 +368,11 @@ func hasValidTools(server servers.Server) error {
 	return nil
 }
 
+// Some special entries bypass the dynamic tools requirement.
+var oauthDynamicToolExceptions = map[string]bool{
+	"github-official": true,
+}
+
 // check if servers with OAuth have dynamic tools enabled
 func isOAuthDynamicValid(name string) error {
 	server, err := readServerYaml(name)
@@ -314,7 +383,11 @@ func isOAuthDynamicValid(name string) error {
 	// If server has OAuth configuration, it must have dynamic tools enabled
 	if len(server.OAuth) > 0 {
 		if server.Dynamic == nil || !server.Dynamic.Tools {
-			return fmt.Errorf("server with OAuth must have 'dynamic: tools: true' configuration")
+			if oauthDynamicToolExceptions[name] {
+				fmt.Printf("⚠️ OAuth dynamic rule bypassed for %s (special configuration).\n", name)
+			} else {
+				return fmt.Errorf("server with OAuth must have 'dynamic: tools: true' configuration")
+			}
 		}
 	}
 

cmd/validate/main_test.go

@@ -88,6 +88,20 @@ func Test_isNameValid(t *testing.T) {
 			},
 			wantError: true,
 		},
+		{
+			name: "legacy uppercase name",
+			args: args{
+				name: "SQLite",
+			},
+			wantError: false,
+		},
+		{
+			name: "legacy underscore name",
+			args: args{
+				name: "youtube_transcript",
+			},
+			wantError: false,
+		},
 	}
 	for _, tt := range tests {
 		t.Run(tt.name, func(t *testing.T) {

cmd/wizard/main.go

@@ -87,6 +87,7 @@ type WizardData struct {
 	ServerName  string
 	GitHubRepo  string
 	Branch      string
+	Commit      string
 	Category    string
 	Title       string
 	Description string
@@ -506,6 +507,7 @@ func generateAndSave(data *WizardData) error {
 		},
 		Source: servers.Source{
 			Project: data.GitHubRepo,
+			Commit:  data.Commit,
 		},
 	}
 
@@ -618,6 +620,14 @@ func validateGithubRepo(data *WizardData) error {
 		return err
 	}
 
+	sha, err := client.GetCommitSHA1(ctx, detectedInfo.ProjectURL, detectedInfo.Branch)
+	if err != nil {
+		return err
+	}
+
+	data.GitHubRepo = detectedInfo.ProjectURL
+	data.Commit = sha
+
 	parts := strings.Split(strings.ToLower(data.GitHubRepo), "/")
 	name := parts[len(parts)-1]
 

docs/configuration.md

@@ -85,6 +85,10 @@ run:
     - --transport=stdio
 ```
 
+## Source Pinning
+
+Local servers must pin their source repository to a specific Git commit using the `source.commit` field. Once an initial revision is accepted into the registry, an automated nightly GitHub Action will drive PRs to perform updates.
+
 ## User
 
 If you need to run the container with a specific user, you can do it in the `run` block. If you want the user to be able to define the container user, you will need to create a parameter first and then add the `run` block to the server.
@@ -119,6 +123,7 @@ about:
   icon: https://...
 source:
   project: https://github.com/my-org/my-mcp-server
+  commit: 0123456789abcdef0123456789abcdef01234567
 run:
   command:
   - --transport=stdio