From 7d7a96551f26ce7fd858a5b64add9b156b4d8e09 Mon Sep 17 00:00:00 2001
From: Joel Verhagen <jver@microsoft.com>
Date: Mon, 7 Jul 2025 13:16:15 -0400
Subject: [PATCH] Add new package registry document

---
 docs/README.md               |  6 +++++-
 docs/new_package_registry.md | 39 ++++++++++++++++++++++++++++++++++++
 docs/openapi.yaml            |  2 +-
 3 files changed, 45 insertions(+), 2 deletions(-)
 create mode 100644 docs/new_package_registry.md

diff --git a/docs/README.md b/docs/README.md
index 2fffb8b..7818f0a 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -16,4 +16,8 @@
 
 [`api_examples.md`](./api_examples.md) - Examples of what data will actually look like coming from the official registry API
 
-[`architecture.md`](./architecture.md) - Technical architecture, deployment strategies, and data flows
\ No newline at end of file
+[`architecture.md`](./architecture.md) - Technical architecture, deployment strategies, and data flows
+
+[`server.json` README](./server-json/README.md) - description of the `server.json` purpose and schema
+
+[`new_package_registry.md`](./new_package_registry.md) - steps to add a new package registry for local server packages
diff --git a/docs/new_package_registry.md b/docs/new_package_registry.md
new file mode 100644
index 0000000..76be4dc
--- /dev/null
+++ b/docs/new_package_registry.md
@@ -0,0 +1,39 @@
+# Adding a new package registry
+
+The MCP Registry project is a **metaregistry**, meaning that it hosts metadata for MCP servers but does not host the code for the servers directly.
+
+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/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.
+
+## Prerequisites
+
+The package registry must meet the following requirements:
+
+1. The package registry supports packaging and executing CLI apps. Local MCP servers use the [stdio transport](https://modelcontextprotocol.io/docs/concepts/transports#standard-input%2Foutput-stdio).
+   - npm CLI tools typically express their CLI commands in the [`bin` property of the package.json](https://docs.npmjs.com/cli/v11/configuring-npm/package-json#bin)
+1. The package registry (or associated client tooling) has a widely accepted **single-shot** CLI command.
+   - npm's `npx` tool executes CLI commands using a [documented execution heuristic](https://docs.npmjs.com/cli/v11/commands/npx#description)
+   - 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.
+
+## 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.
+
+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/schema.json)
+     - Add your package registry name to the `registry_name` enum value 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.
+     - 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).
diff --git a/docs/openapi.yaml b/docs/openapi.yaml
index 5dc5517..e7800fa 100644
--- a/docs/openapi.yaml
+++ b/docs/openapi.yaml
@@ -182,7 +182,7 @@ components:
         runtime_hint:
           type: string
           description: A hint to help clients determine the appropriate runtime for the package. This field should be provided when `runtime_arguments` are present.
-          examples: [npx, uvx]
+          examples: [npx, uvx, dnx]
         runtime_arguments:
           type: array
           description: A list of arguments to be passed to the package's runtime command (such as docker or npx). The `runtime_hint` field should be provided when `runtime_arguments` are present.