diff --git a/docs/README.md b/docs/README.md index 2fffb8b7..7818f0a5 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/architecture.md b/docs/architecture.md index bd55b0a0..01b5f326 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -31,6 +31,7 @@ graph TB NPM[npm Registry] PYPI[PyPI Registry] DOCKER[Docker Hub] + NUGET[NuGet Gallery] DNS[DNS Services] GH[GitHub OAuth] end @@ -46,6 +47,7 @@ graph TB API -.-> |Verify| DNS API -.-> |Reference| NPM API -.-> |Reference| PYPI + API -.-> |Reference| NUGET API -.-> |Reference| DOCKER ``` diff --git a/docs/design_principles.md b/docs/design_principles.md index ef400c2c..d76627ab 100644 --- a/docs/design_principles.md +++ b/docs/design_principles.md @@ -9,7 +9,7 @@ The registry serves as the authoritative metadata repository for publicly-availa ## 2. Minimal Operational Burden - Design for low maintenance and operational overhead -- Delegate complexity to existing services where possible (GitHub for auth, npm/PyPI for packages) +- Delegate complexity to existing services where possible (GitHub for auth, npm/PyPI/NuGet for packages) - Avoid features that require constant human intervention or moderation - Build for reasonable downtime tolerance (24h acceptable) by having consumers cache data for their end-users @@ -21,7 +21,7 @@ The registry serves as the authoritative metadata repository for publicly-availa ## 4. Meets Industry Security Standards -- Leverage existing package registries (npm, PyPI, Docker Hub, etc.) for source code distribution, obviating the need to reinvent source code security +- Leverage existing package registries (npm, PyPI, NuGet, Docker Hub, etc.) for source code distribution, obviating the need to reinvent source code security - Use mechanisms like DNS verification, OAuth to provide base layer of authentication and trust - Implement rate limiting, field validation, and blacklisting to prevent abuse diff --git a/docs/faq.md b/docs/faq.md index a8a19e70..8f44e06b 100644 --- a/docs/faq.md +++ b/docs/faq.md @@ -15,7 +15,7 @@ The MCP Registry is the official centralized metadata repository for publicly-ac ### Is the MCP Registry a package registry? -No. The MCP Registry stores metadata about MCP servers and references to where they're hosted (npm, PyPI, Docker Hub, etc.), but does not host the actual source code or packages. +No. The MCP Registry stores metadata about MCP servers and references to where they're hosted (npm, PyPI, NuGet, Docker Hub, etc.), but does not host the actual source code or packages. ### Who should use the MCP Registry directly? @@ -37,7 +37,7 @@ Servers are published by submitting a `server.json` file through our CLI tool. T 1. GitHub authentication 2. A public GitHub repository (even for closed-source servers - just for the metadata) -3. Your server package published to a supported registry (npm, PyPI, Docker Hub, etc.) +3. Your server package published to a supported registry (npm, PyPI, NuGet, Docker Hub, etc.) 4. Optional: DNS verification for custom namespacing ### What namespaces are available? @@ -54,6 +54,7 @@ No. While open source code is encouraged, it is not required for either locally - npm (Node.js packages) - PyPI (Python packages) +- NuGet.org (.NET packages) - GitHub Container Registry (GHCR) More can be added as the community desires; feel free to open an issue if you are interested in building support for another registry. diff --git a/docs/new_package_registry.md b/docs/new_package_registry.md new file mode 100644 index 00000000..76be4dc2 --- /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 9f611950..e7800fab 100644 --- a/docs/openapi.yaml +++ b/docs/openapi.yaml @@ -171,7 +171,7 @@ components: properties: registry_name: type: string - enum: [npm, docker, pypi, homebrew] + enum: [npm, docker, pypi, homebrew, nuget] example: "npm" name: type: string @@ -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. diff --git a/docs/server-json/examples.md b/docs/server-json/examples.md index ff2da127..de87c1c2 100644 --- a/docs/server-json/examples.md +++ b/docs/server-json/examples.md @@ -179,6 +179,41 @@ } ``` +## NuGet (.NET) Package Example + +The `dnx` tool ships with the .NET 10 SDK, starting with Preview 6. + +```json +{ + "name": "Knapcode.SampleMcpServer", + "description": "Sample NuGet MCP server for a random number and random weather", + "repository": { + "url": "https://github.com/joelverhagen/Knapcode.SampleMcpServer", + "source": "github" + }, + "version_detail": { + "version": "0.3.0", + "release_date": "2025-07-02T18:54:28.00Z" + }, + "packages": [ + { + "registry_name": "nuget", + "name": "Knapcode.SampleMcpServer", + "version": "0.3.0-beta", + "runtime_hint": "dnx", + "environment_variables": [ + { + "name": "WEATHER_CHOICES", + "description": "Comma separated list of weather descriptions to randomly select.", + "is_required": true, + "is_secret": false + } + ] + } + ] +} +``` + ## Complex Docker Server with Multiple Arguments ```json diff --git a/docs/server-json/schema.json b/docs/server-json/schema.json index 596c762a..3d46b668 100644 --- a/docs/server-json/schema.json +++ b/docs/server-json/schema.json @@ -88,7 +88,8 @@ "npm", "docker", "pypi", - "homebrew" + "homebrew", + "nuget" ], "description": "Package registry type", "example": "npm" @@ -105,10 +106,11 @@ }, "runtime_hint": { "type": "string", - "description": "Hint for appropriate runtime (e.g., npx, uvx)", + "description": "Hint for appropriate runtime (e.g., npx, uvx, dnx)", "examples": [ "npx", - "uvx" + "uvx", + "dnx" ] }, "runtime_arguments": { diff --git a/tools/publisher/server.json b/tools/publisher/server.json index 6c4b1687..97e6c652 100644 --- a/tools/publisher/server.json +++ b/tools/publisher/server.json @@ -24,7 +24,7 @@ } ] },{ - "registry_name": "docker>", + "registry_name": "docker", "name": "io.github./-cli", "version": "0.123.223", "runtime_hint": "docker",