From 772e2f48ae9a661463f07a4ea6d59d6d44f385f0 Mon Sep 17 00:00:00 2001 From: "claude[bot]" <209825114+claude[bot]@users.noreply.github.com> Date: Fri, 5 Sep 2025 13:20:13 +0000 Subject: [PATCH 1/2] Update docs for new package registry contributions Following PR #350, added documentation for new validation requirements: - Registry validators now require ownership verification metadata - Updated prerequisites to include validation mechanism requirement - Added implementation steps for registry validators - Included validation examples for existing registries (npm, pypi, nuget, oci, mcpb) Fixes #361 Co-authored-by: adam jones --- docs/new_package_registry.md | 24 ++++++++++++++++++++++++ 1 file changed, 24 insertions(+) diff --git a/docs/new_package_registry.md b/docs/new_package_registry.md index 9d6d2da33..8e7265d33 100644 --- a/docs/new_package_registry.md +++ b/docs/new_package_registry.md @@ -10,6 +10,8 @@ For remote MCP servers, the package registry is not relevant. The MCP client con For the sake of illustration, this document will use npm (the Node.js package manager) as an example at each step. +**Note:** As of PR #350, the registry now includes validation to prevent misattribution. New package registries must implement validation that requires specific metadata in packages to prove ownership of the server name. + ## Prerequisites The package registry must meet the following requirements: @@ -21,6 +23,10 @@ The package registry must meet the following requirements: - For example, the MCP client can map the `server.json` metadata to an `npx` CLI execution, with args and environment variables populated via user input. 1. The package registry supports anonymous package downloads. This allows the MCP client software to use the metadata found in the MCP registry to discover, download, and execute package-based local MCP servers with minimal user intervention. - `npx` by default connects to the public npmjs.com registry, allowing simple consumption of public npm packages. +1. The package registry must support a validation mechanism to verify ownership of the server name. This prevents misattribution and ensures that only the actual package owner can reference their packages in server registrations. + - npm requires an `mcpName` field in `package.json` that matches the server name being registered + - PyPI requires a `mcp-name:` line in the package README/description + - Each registry type must implement a validation mechanism accessible via public API ## Steps @@ -37,3 +43,21 @@ These steps are currently very brief because the MCP Registry service is not yet - Add the single-shot CLI command name to the `runtime_hint` example value array. - This duplicates the previous step and will be improved with [issue #159](https://github.com/modelcontextprotocol/registry/issues/159). - Add a sample, minimal `server.json` to the [`server.json` examples](server-json/examples.md). + - **Implement a registry validator** (required for package validation): + - Create a new validator file: `internal/validators/registries/yourregistry.go` + - Implement the validation function following the pattern of existing validators (npm, pypi, nuget, oci, mcpb) + - Add corresponding unit tests: `internal/validators/registries/yourregistry_test.go` + - Register your validator in `internal/validators/validators.go` + - See existing validators for reference on implementing ownership verification via your registry's API + +## Validation Examples + +For reference, here's how existing package registries implement validation: + +- **npm**: Checks for an `mcpName` field in `package.json` that matches the server name +- **PyPI**: Searches for `mcp-name: server-name` format in the package description/README content +- **NuGet**: Looks for `mcp-name: server-name` format in the package README file +- **Docker/OCI**: Validates a Docker image label `io.modelcontextprotocol.server.name` in the image manifest +- **MCPB**: Ensures the package URL contains "mcp" somewhere in the identifier (URL or filename) + +Each validator fetches metadata from the respective registry's public API and verifies that the required ownership proof exists. From df82690d3e620fc1544b93b90dd412a869abc65d Mon Sep 17 00:00:00 2001 From: Adam Jones Date: Fri, 5 Sep 2025 13:32:23 +0000 Subject: [PATCH 2/2] Tidy up docs a little :house: Remote-Dev: homespace --- docs/new_package_registry.md | 43 ++++++++++++++---------------------- 1 file changed, 16 insertions(+), 27 deletions(-) diff --git a/docs/new_package_registry.md b/docs/new_package_registry.md index 8e7265d33..c9e294157 100644 --- a/docs/new_package_registry.md +++ b/docs/new_package_registry.md @@ -4,14 +4,12 @@ The MCP Registry project is a **metaregistry**, meaning that it hosts metadata f For local MCP servers, the MCP Registry has pointers in the `packages` node of the [`server.json`](server-json/README.md) schema that refer to packages in supported package managers. -The list of supported package managers for hosting MCP servers is defined by the `properties.packages[N].properties.registry_name` string enum in the [`server.json` schema](server-json/server.schema.json). For example, this could be "npm" (for npmjs.com packages) or "pypi" (for PyPI packages). +The list of supported package managers for hosting MCP servers is defined by the `properties.packages[N].properties.registry_type` string enum in the [`server.json` schema](server-json/server.schema.json). For example, this could be "npm" (for npmjs.com packages) or "pypi" (for PyPI packages). For remote MCP servers, the package registry is not relevant. The MCP client consumes the server via a URL instead of by downloading and running a package. In other words, this document only applies to local MCP servers. For the sake of illustration, this document will use npm (the Node.js package manager) as an example at each step. -**Note:** As of PR #350, the registry now includes validation to prevent misattribution. New package registries must implement validation that requires specific metadata in packages to prove ownership of the server name. - ## Prerequisites The package registry must meet the following requirements: @@ -23,41 +21,32 @@ The package registry must meet the following requirements: - For example, the MCP client can map the `server.json` metadata to an `npx` CLI execution, with args and environment variables populated via user input. 1. The package registry supports anonymous package downloads. This allows the MCP client software to use the metadata found in the MCP registry to discover, download, and execute package-based local MCP servers with minimal user intervention. - `npx` by default connects to the public npmjs.com registry, allowing simple consumption of public npm packages. -1. The package registry must support a validation mechanism to verify ownership of the server name. This prevents misattribution and ensures that only the actual package owner can reference their packages in server registrations. +1. The package registry should support a validation mechanism to verify ownership of the server name. This prevents misattribution and ensures that only the actual package owner can reference their packages in server registrations. For example: - npm requires an `mcpName` field in `package.json` that matches the server name being registered - PyPI requires a `mcp-name:` line in the package README/description - Each registry type must implement a validation mechanism accessible via public API ## Steps -These steps are currently very brief because the MCP Registry service is not yet deployed to production. These steps may evolve as additional validations or details are discovered and mandated. +These steps may evolve as additional validations or details are discovered and mandated. 1. [Create a feature request issue](https://github.com/modelcontextprotocol/registry/issues/new?template=feature_request.md) on the MCP Registry repository to begin the discussion about adding the package registry. - Example for NuGet: https://github.com/modelcontextprotocol/registry/issues/126 1. Open a PR with the following changes: - Update the [`server.json` schema](server-json/server.schema.json) - - Add your package registry name to the `registry_name` enum value array. + - Add your package registry name to the `registry_type` example array. + - Add your package registry base url to the `registry_base_url` example array. - Add the single-shot CLI command name to the `runtime_hint` example value array. - - Update the [`openapi.yaml`](openapi.yaml) - - Add your package registry name to the `registry_name` enum value array. + - Update the [`openapi.yaml`](server-registry-api/openapi.yaml) + - Add your package registry name to the `registry_type` enum value array. + - Add your package registry base url to the `registry_base_url` enum value array. - Add the single-shot CLI command name to the `runtime_hint` example value array. - - This duplicates the previous step and will be improved with [issue #159](https://github.com/modelcontextprotocol/registry/issues/159). - Add a sample, minimal `server.json` to the [`server.json` examples](server-json/examples.md). - - **Implement a registry validator** (required for package validation): - - Create a new validator file: `internal/validators/registries/yourregistry.go` - - Implement the validation function following the pattern of existing validators (npm, pypi, nuget, oci, mcpb) - - Add corresponding unit tests: `internal/validators/registries/yourregistry_test.go` - - Register your validator in `internal/validators/validators.go` - - See existing validators for reference on implementing ownership verification via your registry's API - -## Validation Examples - -For reference, here's how existing package registries implement validation: - -- **npm**: Checks for an `mcpName` field in `package.json` that matches the server name -- **PyPI**: Searches for `mcp-name: server-name` format in the package description/README content -- **NuGet**: Looks for `mcp-name: server-name` format in the package README file -- **Docker/OCI**: Validates a Docker image label `io.modelcontextprotocol.server.name` in the image manifest -- **MCPB**: Ensures the package URL contains "mcp" somewhere in the identifier (URL or filename) - -Each validator fetches metadata from the respective registry's public API and verifies that the required ownership proof exists. + - Implement a registry validator: + - Create a new validator file: `internal/validators/registries/yourregistry.go`, following the pattern of existing validators. Examples: + - **npm**: Checks for an `mcpName` field in `package.json` that matches the server name + - **PyPI**: Searches for `mcp-name: server-name` format in the package README content + - **NuGet**: Looks for `mcp-name: server-name` format in the package README file + - **Docker/OCI**: Validates a Docker image label `io.modelcontextprotocol.server.name` in the image manifest + - Add corresponding unit tests: `internal/validators/registries/yourregistry_test.go` + - Register your validator in `internal/validators/validators.go`