Skip to content

Commit 13a0e7c

Browse files
committed
feat: support Go modules as a package type
Adds "registryType": "go" so MCP servers distributed as go-install-able modules can be published. Ownership reuses the publisher's GitHub namespace: a server under io.github.<owner> must use a module path rooted at github.com/<owner>/... (compared case-insensitively, since GitHub owners are case-insensitive). Existence is verified against the Go module proxy (proxy.golang.org). Non-GitHub module paths are left for a follow-up. Closes modelcontextprotocol#1307
1 parent 5d91ce7 commit 13a0e7c

5 files changed

Lines changed: 311 additions & 6 deletions

File tree

‎docs/modelcontextprotocol-io/package-types.mdx‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -204,3 +204,37 @@ openssl dgst -sha256 image-processor.mcpb
204204
```
205205

206206
The MCP Registry does not validate this hash; however, MCP clients **do** validate the hash before installation to ensure file integrity. Downstream registries may also implement their own validation.
207+
208+
## Go Packages
209+
210+
For Go packages, the MCP Registry currently supports modules hosted on GitHub and resolved through the official Go module proxy (`https://proxy.golang.org`).
211+
212+
Go packages use `"registryType": "go"` in `server.json`, with the module path as the `identifier`. For example:
213+
214+
```json server.json highlight={9}
215+
{
216+
"$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
217+
"name": "io.github.username/audit-mcp",
218+
"title": "Audit",
219+
"description": "Audit MCP traffic",
220+
"version": "1.0.0",
221+
"packages": [
222+
{
223+
"registryType": "go",
224+
"identifier": "github.com/username/audit-mcp",
225+
"version": "v1.0.0",
226+
"transport": {
227+
"type": "stdio"
228+
}
229+
}
230+
]
231+
}
232+
```
233+
234+
The `version` is the Go module version (e.g. `v1.0.0`, including the leading `v`), and the registry confirms it exists on the Go module proxy.
235+
236+
### Ownership Verification
237+
238+
Go modules are identified by their source location, so ownership is verified through the publisher's GitHub namespace rather than an embedded marker. A server published under the `io.github.<owner>` namespace **MUST** use a module path rooted at `github.com/<owner>/...` (the owner is compared case-insensitively). Because the publisher already authenticates for the `io.github.<owner>` namespace, matching the module owner proves ownership.
239+
240+
Non-GitHub module paths are not yet supported.

‎internal/validators/package.go‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -23,6 +23,8 @@ func ValidatePackage(ctx context.Context, pkg model.Package, serverName string)
2323
return registries.ValidateOCI(ctx, pkg, serverName)
2424
case model.RegistryTypeMCPB:
2525
return registries.ValidateMCPB(ctx, pkg, serverName)
26+
case model.RegistryTypeGo:
27+
return registries.ValidateGo(ctx, pkg, serverName)
2628
default:
2729
return fmt.Errorf("unsupported registry type: %s", pkg.RegistryType)
2830
}
Lines changed: 151 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,151 @@
1+
package registries
2+
3+
import (
4+
"context"
5+
"errors"
6+
"fmt"
7+
"net/http"
8+
"strings"
9+
"time"
10+
11+
"github.com/modelcontextprotocol/registry/pkg/model"
12+
)
13+
14+
var (
15+
ErrMissingIdentifierForGo = errors.New("package identifier (the module path, e.g. github.com/owner/repo) is required for Go packages")
16+
ErrMissingVersionForGo = errors.New("package version is required for Go packages")
17+
)
18+
19+
const (
20+
goGitHubNamespacePrefix = "io.github."
21+
goGitHubModulePrefix = "github.com/"
22+
)
23+
24+
// ValidateGo validates that a Go module package is owned by the publisher and
25+
// exists on the Go module proxy.
26+
//
27+
// Ownership: a Go module path is its own source location, so for the v1
28+
// GitHub-namespace model a server published under "io.github.<owner>" must use
29+
// a module path rooted at "github.com/<owner>/...". The registry already
30+
// authenticated the publisher for that GitHub namespace, so matching the owner
31+
// segment proves ownership without an mcpName-style marker (which would not be
32+
// idiomatic in a go.mod). Non-GitHub module paths are intentionally left for a
33+
// follow-up.
34+
//
35+
// Existence: the module version is verified against the Go module proxy
36+
// (proxy.golang.org), the canonical source of truth.
37+
func ValidateGo(ctx context.Context, pkg model.Package, serverName string) error {
38+
if pkg.RegistryBaseURL == "" {
39+
pkg.RegistryBaseURL = model.RegistryURLGoProxy
40+
}
41+
if pkg.Identifier == "" {
42+
return ErrMissingIdentifierForGo
43+
}
44+
if pkg.Version == "" {
45+
return ErrMissingVersionForGo
46+
}
47+
// Validate that MCPB-specific fields are not present
48+
if pkg.FileSHA256 != "" {
49+
return fmt.Errorf("go packages must not have 'fileSha256' field - this is only for MCPB packages")
50+
}
51+
// Validate that the registry base URL matches the Go module proxy exactly
52+
if pkg.RegistryBaseURL != model.RegistryURLGoProxy {
53+
return fmt.Errorf("registry type and base URL do not match: '%s' is not valid for registry type '%s'. Expected: %s",
54+
pkg.RegistryBaseURL, model.RegistryTypeGo, model.RegistryURLGoProxy)
55+
}
56+
57+
if err := ValidateGoModuleOwnership(pkg.Identifier, serverName); err != nil {
58+
return err
59+
}
60+
61+
return validateGoModuleExists(ctx, pkg.RegistryBaseURL, pkg.Identifier, pkg.Version)
62+
}
63+
64+
// ValidateGoModuleOwnership checks that the module path is rooted at the GitHub
65+
// owner that owns the server's io.github.* namespace. Comparison is
66+
// case-insensitive because GitHub owners are case-insensitive.
67+
func ValidateGoModuleOwnership(modulePath, serverName string) error {
68+
namespace, _, found := strings.Cut(serverName, "/")
69+
if !found || !strings.HasPrefix(namespace, goGitHubNamespacePrefix) {
70+
return fmt.Errorf("go packages are currently only supported for 'io.github.*' server namespaces; '%s' is not supported", serverName)
71+
}
72+
owner := strings.ToLower(strings.TrimPrefix(namespace, goGitHubNamespacePrefix))
73+
74+
lowerModule := strings.ToLower(modulePath)
75+
if !strings.HasPrefix(lowerModule, goGitHubModulePrefix) {
76+
return fmt.Errorf("go module path '%s' must be hosted on github.com to be published under '%s'", modulePath, namespace)
77+
}
78+
moduleOwner, _, _ := strings.Cut(lowerModule[len(goGitHubModulePrefix):], "/")
79+
if moduleOwner == "" {
80+
return fmt.Errorf("go module path '%s' is missing an owner segment", modulePath)
81+
}
82+
if moduleOwner != owner {
83+
return fmt.Errorf("go module ownership validation failed: server '%s' is owned by GitHub user '%s', but module path '%s' belongs to '%s'", serverName, owner, modulePath, moduleOwner)
84+
}
85+
return nil
86+
}
87+
88+
// validateGoModuleExists confirms the module version is available on the Go
89+
// module proxy.
90+
func validateGoModuleExists(ctx context.Context, baseURL, modulePath, version string) error {
91+
escapedModule, err := EscapeGoModulePath(modulePath)
92+
if err != nil {
93+
return fmt.Errorf("invalid Go module path '%s': %w", modulePath, err)
94+
}
95+
escapedVersion, err := EscapeGoModulePath(version)
96+
if err != nil {
97+
return fmt.Errorf("invalid Go module version '%s': %w", version, err)
98+
}
99+
100+
requestURL := fmt.Sprintf("%s/%s/@v/%s.info", strings.TrimRight(baseURL, "/"), escapedModule, escapedVersion)
101+
102+
client := &http.Client{Timeout: 10 * time.Second}
103+
req, err := http.NewRequestWithContext(ctx, http.MethodGet, requestURL, nil)
104+
if err != nil {
105+
return fmt.Errorf("failed to create request: %w", err)
106+
}
107+
req.Header.Set("User-Agent", "MCP-Registry-Validator/1.0")
108+
109+
resp, err := client.Do(req)
110+
if err != nil {
111+
return fmt.Errorf("failed to fetch module metadata from the Go module proxy: %w", err)
112+
}
113+
defer resp.Body.Close()
114+
115+
switch resp.StatusCode {
116+
case http.StatusOK:
117+
return nil
118+
case http.StatusNotFound, http.StatusGone:
119+
return fmt.Errorf("go module '%s' version '%s' was not found on the Go module proxy. If you published it recently, allow a few minutes for the proxy to fetch it", modulePath, version)
120+
default:
121+
return fmt.Errorf("go module proxy returned unexpected status %d for '%s@%s'", resp.StatusCode, modulePath, version)
122+
}
123+
}
124+
125+
// EscapeGoModulePath applies the goproxy case-encoding: every uppercase ASCII
126+
// letter is replaced by '!' followed by its lowercase form. It rejects control
127+
// characters and "."/".." path elements so a crafted identifier cannot escape
128+
// the proxy path.
129+
func EscapeGoModulePath(s string) (string, error) {
130+
if s == "" {
131+
return "", errors.New("empty path")
132+
}
133+
for _, segment := range strings.Split(s, "/") {
134+
if segment == "." || segment == ".." {
135+
return "", fmt.Errorf("contains a %q path element", segment)
136+
}
137+
}
138+
var b strings.Builder
139+
for _, r := range s {
140+
switch {
141+
case r >= 'A' && r <= 'Z':
142+
b.WriteByte('!')
143+
b.WriteRune(r + ('a' - 'A'))
144+
case r < 0x20 || r == 0x7f:
145+
return "", errors.New("contains a control character")
146+
default:
147+
b.WriteRune(r)
148+
}
149+
}
150+
return b.String(), nil
151+
}
Lines changed: 116 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,116 @@
1+
package registries_test
2+
3+
import (
4+
"context"
5+
"strings"
6+
"testing"
7+
8+
"github.com/modelcontextprotocol/registry/internal/validators/registries"
9+
"github.com/modelcontextprotocol/registry/pkg/model"
10+
)
11+
12+
func TestValidateGoModuleOwnership(t *testing.T) {
13+
cases := []struct {
14+
name string
15+
modulePath string
16+
serverName string
17+
wantErr bool
18+
}{
19+
{"matching owner", "github.com/alice/mcp-foo", "io.github.alice/foo", false},
20+
{"matching owner with subpackage path", "github.com/alice/mcp-foo/cmd/foo", "io.github.alice/foo", false},
21+
{"case-insensitive owner match", "github.com/Alice/mcp-foo", "io.github.alice/foo", false},
22+
{"case-insensitive namespace match", "github.com/alice/mcp-foo", "io.github.Alice/foo", false},
23+
{"owner mismatch", "github.com/bob/mcp-foo", "io.github.alice/foo", true},
24+
{"module not on github", "gitlab.com/alice/mcp-foo", "io.github.alice/foo", true},
25+
{"non-github namespace", "github.com/alice/mcp-foo", "com.example/foo", true},
26+
{"missing owner segment", "github.com/", "io.github.alice/foo", true},
27+
}
28+
29+
for _, tc := range cases {
30+
t.Run(tc.name, func(t *testing.T) {
31+
err := registries.ValidateGoModuleOwnership(tc.modulePath, tc.serverName)
32+
if (err != nil) != tc.wantErr {
33+
t.Errorf("ValidateGoModuleOwnership(%q, %q) error = %v, wantErr %v", tc.modulePath, tc.serverName, err, tc.wantErr)
34+
}
35+
})
36+
}
37+
}
38+
39+
func TestEscapeGoModulePath(t *testing.T) {
40+
cases := []struct {
41+
name string
42+
in string
43+
want string
44+
wantErr bool
45+
}{
46+
{"lowercase unchanged", "github.com/alice/mcp-foo", "github.com/alice/mcp-foo", false},
47+
{"uppercase escaped", "github.com/Alice/McpFoo", "github.com/!alice/!mcp!foo", false},
48+
{"version unchanged", "v1.2.3", "v1.2.3", false},
49+
{"parent dir rejected", "github.com/alice/../bob", "", true},
50+
{"current dir rejected", "github.com/alice/./foo", "", true},
51+
{"empty rejected", "", "", true},
52+
}
53+
54+
for _, tc := range cases {
55+
t.Run(tc.name, func(t *testing.T) {
56+
got, err := registries.EscapeGoModulePath(tc.in)
57+
if (err != nil) != tc.wantErr {
58+
t.Fatalf("EscapeGoModulePath(%q) error = %v, wantErr %v", tc.in, err, tc.wantErr)
59+
}
60+
if !tc.wantErr && got != tc.want {
61+
t.Errorf("EscapeGoModulePath(%q) = %q, want %q", tc.in, got, tc.want)
62+
}
63+
})
64+
}
65+
}
66+
67+
func TestValidateGoGuardErrors(t *testing.T) {
68+
ctx := context.Background()
69+
base := model.Package{
70+
RegistryType: model.RegistryTypeGo,
71+
Identifier: "github.com/alice/mcp-foo",
72+
Version: "v1.0.0",
73+
}
74+
server := "io.github.alice/foo"
75+
76+
t.Run("missing identifier", func(t *testing.T) {
77+
pkg := base
78+
pkg.Identifier = ""
79+
if err := registries.ValidateGo(ctx, pkg, server); err == nil {
80+
t.Error("expected error for missing identifier")
81+
}
82+
})
83+
84+
t.Run("missing version", func(t *testing.T) {
85+
pkg := base
86+
pkg.Version = ""
87+
if err := registries.ValidateGo(ctx, pkg, server); err == nil {
88+
t.Error("expected error for missing version")
89+
}
90+
})
91+
92+
t.Run("fileSha256 rejected", func(t *testing.T) {
93+
pkg := base
94+
pkg.FileSHA256 = "deadbeef"
95+
if err := registries.ValidateGo(ctx, pkg, server); err == nil {
96+
t.Error("expected error for fileSha256 on go package")
97+
}
98+
})
99+
100+
t.Run("base URL mismatch", func(t *testing.T) {
101+
pkg := base
102+
pkg.RegistryBaseURL = "https://example.com"
103+
if err := registries.ValidateGo(ctx, pkg, server); err == nil {
104+
t.Error("expected error for non-proxy base URL")
105+
}
106+
})
107+
108+
t.Run("ownership failure returns before network", func(t *testing.T) {
109+
pkg := base
110+
pkg.Identifier = "github.com/someone-else/mcp-foo"
111+
err := registries.ValidateGo(ctx, pkg, server)
112+
if err == nil || !strings.Contains(err.Error(), "ownership validation failed") {
113+
t.Errorf("expected ownership validation error, got %v", err)
114+
}
115+
})
116+
}

‎pkg/model/constants.go‎

Lines changed: 8 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -7,16 +7,18 @@ const (
77
RegistryTypeOCI = "oci"
88
RegistryTypeNuGet = "nuget"
99
RegistryTypeMCPB = "mcpb"
10+
RegistryTypeGo = "go"
1011
)
1112

1213
// Registry Base URLs - supported package registry base URLs
1314
const (
14-
RegistryURLGitHub = "https://github.com"
15-
RegistryURLGitLab = "https://gitlab.com"
16-
RegistryURLNPM = "https://registry.npmjs.org"
17-
RegistryURLNuGet = "https://api.nuget.org/v3/index.json"
18-
RegistryURLPyPI = "https://pypi.org"
19-
RegistryURLQuay = "https://quay.io"
15+
RegistryURLGitHub = "https://github.com"
16+
RegistryURLGitLab = "https://gitlab.com"
17+
RegistryURLNPM = "https://registry.npmjs.org"
18+
RegistryURLNuGet = "https://api.nuget.org/v3/index.json"
19+
RegistryURLPyPI = "https://pypi.org"
20+
RegistryURLQuay = "https://quay.io"
21+
RegistryURLGoProxy = "https://proxy.golang.org"
2022
)
2123

2224
// Transport Types - supported remote transport protocols

0 commit comments

Comments
 (0)