modelcontextprotocol/registry
Watch
1
0
Fork
You've already forked registry
 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Allow for vendor extensions on servers (#298)

Browse source 
<!-- Provide a brief summary of your changes -->
This PR serves as a placeholder and brings together all of the changes
related to supporting vendor extensions passed through the API. The idea
is to have a single place to track and review the work as it comes
together (even if it’s still a bit of a work in progress).

**The changes in this PR cover:**
* Updates on the data model
* Updates on both databases (in-memory and postgresql), added a new
table to PSQL for tracking the extensions leaving the server table only
for the clean server.json properties
* Updates the seed.json file (thus the big line change)
* Adds a seed-migrate tool to help migrating an existing seed file to
the new format
* Updates the seed import mechanism to support this
* Updates the existing tests - unit, integration and validation tests
* Adds the publish handler to the OpenAPI spec (it was missing)
* Fixes linting errors
* Updates on the API side on (publish, list, get) to support the new
format of `ServerResponse` -
```
{
  "server": {},
  "x-io.modelcontextprotocol.registry": {}, /*not available for publish since this gets populated by the registry*/
  "x-publisher": {}
}
```

## Motivation and Context
<!-- Why is this change needed? What problem does it solve? -->
Motivated by the discussions in:
https://github.com/modelcontextprotocol/registry/discussions/284

## How Has This Been Tested?
<!-- Have you tested this in a real application? Which scenarios were
tested? -->
Locally and by running all of the tests

## Breaking Changes
<!-- Will users need to update their code or configurations? -->
Yes, it changes both the API and the format of the seed file
 
## 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)
- [ ] New feature (non-breaking change which adds functionality)
- [x] Breaking change (fix or feature that would cause existing
functionality to change)
- [ ] Documentation update

---

Signed-off-by: Radoslav Dimitrov <radoslav@stacklok.com>
Co-authored-by: adam jones <domdomegg+git@gmail.com>
This commit is contained in:
Radoslav Dimitrov 2025-08-23 11:59:03 +03:00 • committed by GitHub
commit 8d7e471fd3
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
2 changed files with 19980 additions and 15589 deletions
Download patch file Download diff file Expand all files Collapse all files

177
internal/model/model.go
View file

@ -1,5 +1,11 @@
package model
import (
"encoding/json"
"fmt"
"time"
)
// AuthMethod represents the authentication method used
type AuthMethod string
@ -26,10 +32,6 @@ const (
ServerStatusDeprecated ServerStatus = "deprecated"
)
// PublishRequest represents a request to publish a server to the registry
type PublishRequest struct {
ServerDetail `json:",inline"`
}
// Repository represents a source code repository as defined in the spec
type Repository struct {
@ -38,12 +40,6 @@ type Repository struct {
ID string `json:"id,omitempty" bson:"id,omitempty"`
}
// ServerList represents the response for listing servers as defined in the spec
type ServerList struct {
Servers []Server `json:"servers" bson:"servers"`
Next string `json:"next,omitempty" bson:"next,omitempty"`
TotalCount int `json:"total_count" bson:"total_count"`
}
// create an enum for Format
type Format string
@ -107,26 +103,163 @@ type Remote struct {
Headers []KeyValueInput `json:"headers,omitempty" bson:"headers,omitempty"`
}
// VersionDetail represents the version details of a server
// VersionDetail represents the version details of a server (pure MCP spec, no registry metadata)
type VersionDetail struct {
Version string `json:"version" bson:"version"`
ReleaseDate string `json:"release_date,omitempty" bson:"release_date"`
IsLatest bool `json:"is_latest,omitempty" bson:"is_latest"`
Version string `json:"version" bson:"version"`
}
// Server represents a basic server information as defined in the spec
type Server struct {
ID string `json:"id,omitempty" bson:"id"`
// ServerDetail represents complete server information as defined in the MCP spec (pure, no registry metadata)
type ServerDetail struct {
Name string `json:"name" bson:"name"`
Description string `json:"description" bson:"description"`
Status ServerStatus `json:"status,omitempty" bson:"status,omitempty"`
Repository Repository `json:"repository,omitempty" bson:"repository"`
VersionDetail VersionDetail `json:"version_detail" bson:"version_detail"`
Packages []Package `json:"packages,omitempty" bson:"packages,omitempty"`
Remotes []Remote `json:"remotes,omitempty" bson:"remotes,omitempty"`
}
// ServerDetail represents detailed server information as defined in the spec
type ServerDetail struct {
Server `json:",inline" bson:",inline"`
Packages []Package `json:"packages,omitempty" bson:"packages,omitempty"`
Remotes []Remote `json:"remotes,omitempty" bson:"remotes,omitempty"`
// RegistryMetadata represents registry-generated metadata
type RegistryMetadata struct {
ID string `json:"id" bson:"_id"`
PublishedAt time.Time `json:"published_at" bson:"published_at"`
UpdatedAt time.Time `json:"updated_at,omitempty" bson:"updated_at,omitempty"`
IsLatest bool `json:"is_latest" bson:"is_latest"`
ReleaseDate string `json:"release_date" bson:"release_date"`
}
// ServerRecord represents the complete storage model that separates server.json from registry metadata
type ServerRecord struct {
ServerJSON ServerDetail `json:"server" bson:"server"` // Pure MCP server.json
RegistryMetadata RegistryMetadata `json:"registry_metadata" bson:"registry_metadata"` // Registry-generated data
PublisherExtensions map[string]interface{} `json:"publisher_extensions" bson:"publisher_extensions"` // x-publisher extensions
}
// ServerResponse represents the API response format with wrapper and extensions
type ServerResponse struct {
Server ServerDetail `json:"server"`
XIOModelContextProtocolRegistry interface{} `json:"x-io.modelcontextprotocol.registry,omitempty"`
XPublisher interface{} `json:"x-publisher,omitempty"`
}
// ServerListResponse represents the paginated server list response
type ServerListResponse struct {
Servers []ServerResponse `json:"servers"`
Metadata *Metadata `json:"metadata,omitempty"`
}
// PublishRequest represents the API request format for publishing servers
type PublishRequest struct {
Server ServerDetail `json:"server"`
XPublisher interface{} `json:"x-publisher,omitempty"`
}
// Metadata represents pagination metadata
type Metadata struct {
NextCursor string `json:"next_cursor,omitempty"`
Count int `json:"count,omitempty"`
Total int `json:"total,omitempty"`
}
// Helper functions
// ValidatePublisherExtensions validates that publisher extensions are within size limits
func ValidatePublisherExtensions(req PublishRequest) error {
const maxExtensionSize = 4 * 1024 // 4KB limit
// Check size limit for x-publisher extension
if req.XPublisher != nil {
extensionsJSON, err := json.Marshal(req.XPublisher)
if err != nil {
return fmt.Errorf("failed to marshal x-publisher extension: %w", err)
}
if len(extensionsJSON) > maxExtensionSize {
return fmt.Errorf("x-publisher extension exceeds 4KB limit (%d bytes)", len(extensionsJSON))
}
}
return nil
}
// ValidatePublishRequestExtensions validates that only allowed extension fields are present
func ValidatePublishRequestExtensions(requestData []byte) error {
// Parse the raw JSON to check for unknown fields
var rawRequest map[string]interface{}
if err := json.Unmarshal(requestData, &rawRequest); err != nil {
return fmt.Errorf("failed to parse request JSON: %w", err)
}
// Define allowed top-level fields
allowedFields := map[string]bool{
"server": true,
"x-publisher": true,
}
// Check for any disallowed fields
var invalidFields []string
for field := range rawRequest {
if !allowedFields[field] {
invalidFields = append(invalidFields, field)
}
}
if len(invalidFields) > 0 {
return fmt.Errorf("invalid extension fields: %v. Only 'server' and 'x-publisher' fields are allowed", invalidFields)
}
return nil
}
// ExtractPublisherExtensions extracts publisher extensions from a PublishRequest
func ExtractPublisherExtensions(req PublishRequest) map[string]interface{} {
publisherExtensions := make(map[string]interface{})
if req.XPublisher != nil {
// Cast to map and copy fields directly, avoiding double nesting
if publisherMap, ok := req.XPublisher.(map[string]interface{}); ok {
for k, v := range publisherMap {
publisherExtensions[k] = v
}
}
}
return publisherExtensions
}
// CreateRegistryExtensions generates the x-io.modelcontextprotocol.registry extension from registry metadata
func (rm *RegistryMetadata) CreateRegistryExtensions() map[string]interface{} {
return map[string]interface{}{
"x-io.modelcontextprotocol.registry": map[string]interface{}{
"id": rm.ID,
"published_at": rm.PublishedAt,
"updated_at": rm.UpdatedAt,
"is_latest": rm.IsLatest,
"release_date": rm.ReleaseDate,
},
}
}
// ParseServerName extracts the server name from a ServerDetail for validation purposes
func ParseServerName(serverDetail ServerDetail) (string, error) {
name := serverDetail.Name
if name == "" {
return "", fmt.Errorf("server name is required and must be a string")
}
return name, nil
}
// ToServerResponse converts a ServerRecord to API response format
func (sr *ServerRecord) ToServerResponse() ServerResponse {
response := ServerResponse{
Server: sr.ServerJSON,
}
// Add registry metadata extension
response.XIOModelContextProtocolRegistry = sr.RegistryMetadata.CreateRegistryExtensions()["x-io.modelcontextprotocol.registry"]
// Add publisher extensions directly
if len(sr.PublisherExtensions) > 0 {
response.XPublisher = sr.PublisherExtensions
}
return response
}

265
internal/model/model_test.go Normal file
View file

@ -0,0 +1,265 @@
//nolint:testpackage
package model
import (
"encoding/json"
"testing"
"time"
"github.com/stretchr/testify/assert"
"github.com/stretchr/testify/require"
)
func TestExtractPublisherExtensions(t *testing.T) {
tests := []struct {
name string
request PublishRequest
expected map[string]interface{}
}{
{
name: "nil publisher extensions",
request: PublishRequest{
Server: ServerDetail{Name: "test"},
},
expected: map[string]interface{}{},
},
{
name: "empty publisher extensions",
request: PublishRequest{
Server: ServerDetail{Name: "test"},
XPublisher: map[string]interface{}{},
},
expected: map[string]interface{}{},
},
{
name: "simple publisher extensions",
request: PublishRequest{
Server: ServerDetail{Name: "test"},
XPublisher: map[string]interface{}{
"build_info": map[string]interface{}{
"version": "1.2.3",
"commit": "abc123",
},
"publisher_metadata": "test-publisher",
},
},
expected: map[string]interface{}{
"build_info": map[string]interface{}{
"version": "1.2.3",
"commit": "abc123",
},
"publisher_metadata": "test-publisher",
},
},
{
name: "nested publisher extensions",
request: PublishRequest{
Server: ServerDetail{Name: "test"},
XPublisher: map[string]interface{}{
"ci": map[string]interface{}{
"pipeline": map[string]interface{}{
"id": "12345",
"branch": "main",
},
"artifacts": []string{"binary", "docs"},
},
},
},
expected: map[string]interface{}{
"ci": map[string]interface{}{
"pipeline": map[string]interface{}{
"id": "12345",
"branch": "main",
},
"artifacts": []string{"binary", "docs"},
},
},
},
{
name: "non-map publisher extensions (should be ignored)",
request: PublishRequest{
Server: ServerDetail{Name: "test"},
XPublisher: "invalid-string-data",
},
expected: map[string]interface{}{},
},
}
for _, tt := range tests {
t.Run(tt.name, func(t *testing.T) {
result := ExtractPublisherExtensions(tt.request)
assert.Equal(t, tt.expected, result)
})
}
}
func TestExtractPublisherExtensions_DoesNotDoubleNest(t *testing.T) {
// This test specifically verifies the bug we fixed - no double nesting
request := PublishRequest{
Server: ServerDetail{Name: "test"},
XPublisher: map[string]interface{}{
"tool": "publisher-cli",
"version": "1.0.0",
},
}
result := ExtractPublisherExtensions(request)
// Verify we get the data directly, not wrapped in another "x-publisher" key
assert.Equal(t, "publisher-cli", result["tool"])
assert.Equal(t, "1.0.0", result["version"])
// Verify we don't have double nesting
assert.NotContains(t, result, "x-publisher")
}
func TestRegistryMetadata_CreateRegistryExtensions(t *testing.T) {
publishedTime := time.Date(2023, 12, 1, 10, 30, 0, 0, time.UTC)
updatedTime := time.Date(2023, 12, 1, 11, 0, 0, 0, time.UTC)
metadata := RegistryMetadata{
ID: "test-id-123",
PublishedAt: publishedTime,
UpdatedAt: updatedTime,
IsLatest: true,
ReleaseDate: "2023-12-01T10:30:00Z",
}
result := metadata.CreateRegistryExtensions()
expected := map[string]interface{}{
"x-io.modelcontextprotocol.registry": map[string]interface{}{
"id": "test-id-123",
"published_at": publishedTime,
"updated_at": updatedTime,
"is_latest": true,
"release_date": "2023-12-01T10:30:00Z",
},
}
assert.Equal(t, expected, result)
}
func TestServerResponse_JSONSerialization(t *testing.T) {
// Test that ServerResponse properly serializes to extension wrapper format
publishedTime := time.Date(2023, 12, 1, 10, 30, 0, 0, time.UTC)
response := ServerResponse{
Server: ServerDetail{
Name: "test-server",
Description: "A test server",
Repository: Repository{
URL: "https://github.com/test/server",
Source: "github",
ID: "test/server",
},
VersionDetail: VersionDetail{
Version: "1.0.0",
},
},
XIOModelContextProtocolRegistry: map[string]interface{}{
"id": "registry-id-123",
"published_at": publishedTime.Format(time.RFC3339),
"is_latest": true,
},
XPublisher: map[string]interface{}{
"build_tool": "ci-pipeline",
"commit": "abc123def",
},
}
// Serialize to JSON
jsonData, err := json.Marshal(response)
require.NoError(t, err)
// Parse back to verify structure
var parsed map[string]interface{}
err = json.Unmarshal(jsonData, &parsed)
require.NoError(t, err)
// Verify three-layer structure exists
assert.Contains(t, parsed, "server")
assert.Contains(t, parsed, "x-io.modelcontextprotocol.registry")
assert.Contains(t, parsed, "x-publisher")
// Verify server data
serverData := parsed["server"].(map[string]interface{})
assert.Equal(t, "test-server", serverData["name"])
// Verify registry metadata
registryData := parsed["x-io.modelcontextprotocol.registry"].(map[string]interface{})
assert.Equal(t, "registry-id-123", registryData["id"])
// Verify publisher extensions
publisherData := parsed["x-publisher"].(map[string]interface{})
assert.Equal(t, "ci-pipeline", publisherData["build_tool"])
assert.Equal(t, "abc123def", publisherData["commit"])
}
func TestPublishRequest_WithPublisherExtensions(t *testing.T) {
// Test that PublishRequest properly deserializes publisher extensions
jsonData := `{
"server": {
"name": "test-server",
"description": "Test server",
"version_detail": {
"version": "1.0.0"
}
},
"x-publisher": {
"tool": "publisher-cli",
"metadata": {
"build_date": "2023-12-01",
"commit": "abc123"
}
}
}`
var request PublishRequest
err := json.Unmarshal([]byte(jsonData), &request)
require.NoError(t, err)
// Verify server data
assert.Equal(t, "test-server", request.Server.Name)
assert.Equal(t, "Test server", request.Server.Description)
// Verify publisher extensions
require.NotNil(t, request.XPublisher)
publisherMap := request.XPublisher.(map[string]interface{})
assert.Equal(t, "publisher-cli", publisherMap["tool"])
metadata := publisherMap["metadata"].(map[string]interface{})
assert.Equal(t, "2023-12-01", metadata["build_date"])
assert.Equal(t, "abc123", metadata["commit"])
}
func TestServerResponse_EmptyExtensions(t *testing.T) {
// Test behavior with empty/nil extensions
response := ServerResponse{
Server: ServerDetail{
Name: "minimal-server",
Description: "Minimal test",
},
XIOModelContextProtocolRegistry: map[string]interface{}{
"id": "min-id",
},
XPublisher: nil,
}
jsonData, err := json.Marshal(response)
require.NoError(t, err)
var parsed map[string]interface{}
err = json.Unmarshal(jsonData, &parsed)
require.NoError(t, err)
// Should still have the structure, even with nil publisher extensions
assert.Contains(t, parsed, "server")
assert.Contains(t, parsed, "x-io.modelcontextprotocol.registry")
// x-publisher should be null/nil in JSON when empty
publisherValue, exists := parsed["x-publisher"]
if exists {
assert.Nil(t, publisherValue)
}
}