80cb03ff7a<!-- Provide a brief summary of your changes --> ## Motivation and Context <!-- Why is this change needed? What problem does it solve? --> This resolves https://github.com/modelcontextprotocol/registry/issues/738. There are two issues with the NuGet.org integration today: 1. Change the `registryBaseUrl` for NuGet to `https://api.nuget.org/v3/index.json`. `https://api.nuget.org` is not the entry point for our service and is not specific enough. `https://api.nuget.org/v3/index.json` is the value that users put into their tooling to connect to our public registry (it is installed by default in .NET client tooling). 2. Use the service index API to get the URL pattern for package READMEs. - This URL is not guaranteed to be stable. The service index URL (`registryBaseUrl`) is, however. Additionally, I polished up the error messages so various error modes are clearer. When packages are published to NuGet.org, they take 2-5 minutes to become available due to validations we run. Some possible states that are now handled and described more helpfully are: - Version exists, but the package has no README - The ID exists, but the version does not - The ID does not exist at all There are only 3 authors (me, another MSFT person, and a community member) explicitly setting the old value. The DB migration will fix the issue. A future publish will fail with the validation error but the error message is clear. `registry type and base URL do not match: 'https://api.nuget.org' is not valid for registry type 'nuget'. Expected: https://api.nuget.org/v3/index.json` ## How Has This Been Tested? <!-- Have you tested this in a real application? Which scenarios were tested? --> - Unit tests, new and existing - Manual test locally - Set old data in the DB, `docker compose up`, confirm the migration updates the specific package ## Breaking Changes Yes, but minimal impact expected, unless there is a dependency on the specific `https://api.nuget.org` value downstream. I am not aware of any such dependency, and the new value is more proper and specific. ## 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) - [x] New feature (non-breaking change which adds functionality) - [x] Breaking change (fix or feature that would cause existing functionality to change) - [x] Documentation update ## Checklist <!-- Go over all the following points, and put an `x` in all the boxes that apply. --> - [x] I have read the [MCP Documentation](https://modelcontextprotocol.io) - [x] My code follows the repository's style guidelines - [x] New and existing tests pass locally - [x] I have added appropriate error handling - [x] I have added or updated documentation as needed ## Additional context <!-- Add any other context, implementation notes, or design decisions --> For more information about the NuGet API see: https://learn.microsoft.com/en-us/nuget/api/overview#service-index (I wrote most of the docs).
201 lines
6.5 KiB
Text
201 lines
6.5 KiB
Text
---
|
|
title: MCP Registry Supported Package Types
|
|
sidebarTitle: Package Types
|
|
---
|
|
|
|
# Package Types
|
|
|
|
The MCP Registry supports several different package types, and each package type has its own verification method.
|
|
|
|
## npm Packages
|
|
|
|
For npm packages, the MCP Registry currently supports the npm public registry (`https://registry.npmjs.org`) only.
|
|
|
|
npm packages use `"registryType": "npm"` in `server.json`. For example:
|
|
|
|
```json server.json highlight={9}
|
|
{
|
|
"$schema": "https://static.modelcontextprotocol.io/schemas/2025-10-17/server.schema.json",
|
|
"name": "io.github.username/email-integration-mcp",
|
|
"title": "Email Integration",
|
|
"description": "Send emails and manage email accounts",
|
|
"version": "1.0.0",
|
|
"packages": [
|
|
{
|
|
"registryType": "npm",
|
|
"identifier": "@username/email-integration-mcp",
|
|
"version": "1.0.0",
|
|
"transport": {
|
|
"type": "stdio"
|
|
}
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
### Ownership Verification
|
|
|
|
The MCP Registry verifies ownership of npm packages by checking `mcpName` in `package.json`. The `mcpName` property **MUST** match the server name from `server.json`. For example:
|
|
|
|
```json package.json
|
|
{
|
|
"name": "@username/email-integration-mcp",
|
|
"version": "1.0.0",
|
|
"mcpName": "io.github.username/email-integration-mcp"
|
|
}
|
|
```
|
|
|
|
## PyPI Packages
|
|
|
|
For PyPI packages, the MCP Registry currently supports the official PyPI registry (`https://pypi.org`) only.
|
|
|
|
PyPI packages use `"registryType": "pypi"` in `server.json`. For example:
|
|
|
|
```json server.json highlight={9}
|
|
{
|
|
"$schema": "https://static.modelcontextprotocol.io/schemas/2025-10-17/server.schema.json",
|
|
"name": "io.github.username/database-query-mcp",
|
|
"title": "Database Query",
|
|
"description": "Execute SQL queries and manage database connections",
|
|
"version": "1.0.0",
|
|
"packages": [
|
|
{
|
|
"registryType": "pypi",
|
|
"identifier": "database-query-mcp",
|
|
"version": "1.0.0",
|
|
"transport": {
|
|
"type": "stdio"
|
|
}
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
### Ownership Verification
|
|
|
|
The MCP Registry verifies ownership of PyPI packages by checking for the existence of an `mcp-name: $SERVER_NAME` string in the package README (which becomes the package description on PyPI). The string may be hidden in a comment, but the `$SERVER_NAME` portion **MUST** match the server name from `server.json`. For example:
|
|
|
|
```markdown README.md highlight={5}
|
|
# Database Query MCP Server
|
|
|
|
This MCP server executes SQL queries and manages database connections.
|
|
|
|
<!-- mcp-name: io.github.username/database-query-mcp -->
|
|
```
|
|
|
|
## NuGet Packages
|
|
|
|
For NuGet packages, the MCP Registry currently supports the official NuGet registry (`https://api.nuget.org/v3/index.json`) only.
|
|
|
|
NuGet packages use `"registryType": "nuget"` in `server.json`. For example:
|
|
|
|
```json server.json highlight={9}
|
|
{
|
|
"$schema": "https://static.modelcontextprotocol.io/schemas/2025-10-17/server.schema.json",
|
|
"name": "io.github.username/azure-devops-mcp",
|
|
"title": "Azure DevOps",
|
|
"description": "Manage Azure DevOps work items and pipelines",
|
|
"version": "1.0.0",
|
|
"packages": [
|
|
{
|
|
"registryType": "nuget",
|
|
"identifier": "Username.AzureDevOpsMcp",
|
|
"version": "1.0.0",
|
|
"transport": {
|
|
"type": "stdio"
|
|
}
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
### Ownership Verification
|
|
|
|
The MCP Registry verifies ownership of NuGet packages by checking for the existence of an `mcp-name: $SERVER_NAME` string in the package README. The string may be hidden in a comment, but the `$SERVER_NAME` portion **MUST** match the server name from `server.json`. For example:
|
|
|
|
```markdown README.md highlight={5}
|
|
# Azure DevOps MCP Server
|
|
|
|
This MCP server manages Azure DevOps work items and pipelines.
|
|
|
|
<!-- mcp-name: io.github.username/azure-devops-mcp -->
|
|
```
|
|
|
|
## Docker/OCI Images
|
|
|
|
For Docker/OCI images, the MCP Registry currently supports:
|
|
|
|
- Docker Hub (`docker.io`)
|
|
- GitHub Container Registry (`ghcr.io`)
|
|
- Google Artifact Registry (any `*.pkg.dev` domain)
|
|
- Azure Container Registry (`*.azurecr.io`)
|
|
- Microsoft Container Registry (`mcr.microsoft.com`)
|
|
|
|
Docker/OCI images use `"registryType": "oci"` in `server.json`. For example:
|
|
|
|
```json server.json highlight={9}
|
|
{
|
|
"$schema": "https://static.modelcontextprotocol.io/schemas/2025-10-17/server.schema.json",
|
|
"name": "io.github.username/kubernetes-manager-mcp",
|
|
"title": "Kubernetes Manager",
|
|
"description": "Deploy and manage Kubernetes resources",
|
|
"version": "1.0.0",
|
|
"packages": [
|
|
{
|
|
"registryType": "oci",
|
|
"identifier": "docker.io/yourusername/kubernetes-manager-mcp:1.0.0",
|
|
"transport": {
|
|
"type": "stdio"
|
|
}
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
The format of `identifier` is `registry/namespace/repository:tag`. For example, `docker.io/user/app:1.0.0` or `ghcr.io/user/app:1.0.0`. The tag can also be specified as a digest.
|
|
|
|
### Ownership Verification
|
|
|
|
The MCP Registry verifies ownership of Docker/OCI images by checking for an `io.modelcontextprotocol.server.name` annotation. The value of the `io.modelcontextprotocol.server.name` annotation **MUST** match the server name from `server.json`. For example:
|
|
|
|
```dockerfile Dockerfile
|
|
LABEL io.modelcontextprotocol.server.name="io.github.username/kubernetes-manager-mcp"
|
|
```
|
|
|
|
## MCPB Packages
|
|
|
|
For MCPB packages, the MCP Registry currently supports MCPB artifacts hosted via GitHub or GitLab releases.
|
|
|
|
MCPB packages use `"registryType": "mcpb"` in `server.json`. For example:
|
|
|
|
```json server.json highlight={9}
|
|
{
|
|
"$schema": "https://static.modelcontextprotocol.io/schemas/2025-10-17/server.schema.json",
|
|
"name": "io.github.username/image-processor-mcp",
|
|
"title": "Image Processor",
|
|
"description": "Process and transform images with various filters",
|
|
"version": "1.0.0",
|
|
"packages": [
|
|
{
|
|
"registryType": "mcpb",
|
|
"identifier": "https://github.com/username/image-processor-mcp/releases/download/v1.0.0/image-processor.mcpb",
|
|
"fileSha256": "fe333e598595000ae021bd27117db32ec69af6987f507ba7a63c90638ff633ce",
|
|
"transport": {
|
|
"type": "stdio"
|
|
}
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
### Verification
|
|
|
|
The MCPB package URL (`identifier` in `server.json`) **MUST** contain the string "mcp". That can be as part of the `.mcpb` file extension or in the name of the repository.
|
|
|
|
The package metadata in `server.json` **MUST** include a `fileSha256` property with a SHA-256 hash of the MCPB artifact, which can be computed using the `openssl` command:
|
|
|
|
```bash
|
|
openssl dgst -sha256 image-processor.mcpb
|
|
```
|
|
|
|
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.
|