Fix NuGet.org base URL default, improve API integration (#813)

<!-- Provide a brief summary of your changes -->

## Motivation and Context
<!-- Why is this change needed? What problem does it solve? -->

This resolves
#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).

Author: joelverhagen

complete.md

@@ -658,7 +658,7 @@ Only trusted public registries are supported. Private registries and alternative
 **Supported registries:**
 - **NPM**: `https://registry.npmjs.org` only
 - **PyPI**: `https://pypi.org` only
-- **NuGet**: `https://api.nuget.org` only
+- **NuGet**: `https://api.nuget.org/v3/index.json`
 - **Docker/OCI**: `https://docker.io` only
 - **MCPB**: `https://github.com` releases and `https://gitlab.com` releases only
 
@@ -1549,7 +1549,8 @@ Include your server name in your package's README using this format:
 Add a README file to your NuGet package that includes the server name. This can be in a comment if you want to hide it from display elsewhere.
 
 ### How It Works
-- Registry fetches README from `https://api.nuget.org/v3-flatcontainer/{id}/{version}/readme`
+- Registry fetches and cached service index `https://api.nuget.org/v3/index.json`
+- Registry uses `ReadmeUriTemplate/6.13.0` URL template in service index to fetch README
 - Passes if `mcp-name: server-name` is found in the README content
 
 ### Example server.json
@@ -1566,7 +1567,7 @@ Add a README file to your NuGet package that includes the server name. This can
 }
 ```
 
-The official MCP registry currently only supports the official NuGet registry (`https://api.nuget.org`).
+The official MCP registry currently only supports the official NuGet registry (`https://api.nuget.org/v3/index.json`).
 
 </details>
 
@@ -2341,7 +2342,7 @@ Suppose your MCP server application requires a `mcp start` CLI arguments to star
   "packages": [
     {
       "registry_type": "nuget",
-      "registry_base_url": "https://api.nuget.org",
+      "registry_base_url": "https://api.nuget.org/v3/index.json",
       "identifier": "Knapcode.SampleMcpServer",
       "version": "0.4.0-beta",
       "transport": {
@@ -2578,7 +2579,7 @@ The `dnx` tool ships with the .NET 10 SDK, starting with Preview 6.
   "packages": [
     {
       "registry_type": "nuget",
-      "registry_base_url": "https://api.nuget.org",
+      "registry_base_url": "https://api.nuget.org/v3/index.json",
       "identifier": "Knapcode.SampleMcpServer",
       "version": "0.5.0",
       "runtime_hint": "dnx",

docs/modelcontextprotocol-io/package-types.mdx

@@ -85,7 +85,7 @@ This MCP server executes SQL queries and manages database connections.
 
 ## NuGet Packages
 
-For NuGet packages, the MCP Registry currently supports the official NuGet registry (`https://api.nuget.org`) only.
+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:
 

docs/reference/api/openapi.yaml

@@ -414,7 +414,7 @@ components:
             - "https://registry.npmjs.org"
             - "https://pypi.org"
             - "https://docker.io"
-            - "https://api.nuget.org"
+            - "https://api.nuget.org/v3/index.json"
             - "https://github.com"
             - "https://gitlab.com"
         identifier:

docs/reference/server-json/generic-server-json.md

@@ -131,7 +131,7 @@ Suppose your MCP server application requires a `mcp start` CLI arguments to star
   "packages": [
     {
       "registryType": "nuget",
-      "registryBaseUrl": "https://api.nuget.org",
+      "registryBaseUrl": "https://api.nuget.org/v3/index.json",
       "identifier": "Knapcode.SampleMcpServer",
       "version": "0.4.0-beta",
       "transport": {
@@ -370,7 +370,7 @@ The `dnx` tool ships with the .NET 10 SDK, starting with Preview 6.
   "packages": [
     {
       "registryType": "nuget",
-      "registryBaseUrl": "https://api.nuget.org",
+      "registryBaseUrl": "https://api.nuget.org/v3/index.json",
       "identifier": "Knapcode.SampleMcpServer",
       "version": "0.5.0",
       "runtimeHint": "dnx",

docs/reference/server-json/official-registry-requirements.md

@@ -32,7 +32,7 @@ Only trusted public registries are supported. Private registries and alternative
 **Supported registries:**
 - **NPM**: `https://registry.npmjs.org` only
 - **PyPI**: `https://pypi.org` only
-- **NuGet**: `https://api.nuget.org` only
+- **NuGet**: `https://api.nuget.org/v3/index.json` only
 - **Docker/OCI**:
   - Docker Hub (`docker.io`)
   - GitHub Container Registry (`ghcr.io`)

docs/reference/server-json/server.schema.json

@@ -226,7 +226,7 @@
             "https://registry.npmjs.org",
             "https://pypi.org",
             "https://docker.io",
-            "https://api.nuget.org",
+            "https://api.nuget.org/v3/index.json",
             "https://github.com",
             "https://gitlab.com"
           ],

internal/database/migrations/012_fix_nuget_registry_base_url.sql

@@ -0,0 +1,58 @@
+-- Migration: Set NuGet package registryBaseUrl for specific server entries
+--
+-- This migration updates the packages[].registryBaseUrl to
+-- "https://api.nuget.org/v3/index.json" for NuGet packages on a small,
+-- explicitly listed set of server entries. Only packages with
+-- registryType == "nuget" are modified; other package types are left
+-- unchanged.
+--
+-- Entries to update (name, version):
+--   com.joelverhagen.mcp/Knapcode.SampleMcpServer    0.7.0-beta, 0.10.0-beta.10
+--   io.github.joelverhagen/Knapcode.SampleMcpServer  0.7.0-beta
+--   io.github.moonolgerd/game-mcp                    1.0.0
+--   io.github.timheuer/sampledotnetmcpserver         0.1.56-beta-g9538a23d37, 0.1.57-beta
+
+BEGIN;
+
+WITH affected_entries AS (
+    SELECT server_name, version FROM (VALUES
+        ('com.joelverhagen.mcp/Knapcode.SampleMcpServer',   '0.7.0-beta'),
+        ('com.joelverhagen.mcp/Knapcode.SampleMcpServer',   '0.10.0-beta.10'),
+        ('io.github.joelverhagen/Knapcode.SampleMcpServer', '0.7.0-beta'),
+        ('io.github.moonolgerd/game-mcp',                   '1.0.0'),
+        ('io.github.timheuer/sampledotnetmcpserver',        '0.1.56-beta-g9538a23d37'),
+        ('io.github.timheuer/sampledotnetmcpserver',        '0.1.57-beta')
+    ) AS t(server_name, version)
+)
+UPDATE servers s
+SET value = jsonb_set(
+    s.value,
+    '{packages}',
+    (
+        SELECT jsonb_agg(
+            CASE
+                WHEN p->>'registryType' = 'nuget' THEN
+                    jsonb_set(
+                        p,
+                        '{registryBaseUrl}',
+                        '"https://api.nuget.org/v3/index.json"'::jsonb,
+                        true
+                    )
+                ELSE p
+            END
+        )
+        FROM jsonb_array_elements(s.value#>'{packages}') AS p
+    ),
+    true
+)
+FROM affected_entries ae
+WHERE s.server_name = ae.server_name
+    AND s.version = ae.version
+    AND s.value#>'{packages}' IS NOT NULL
+    AND EXISTS (
+        SELECT 1
+        FROM jsonb_array_elements(s.value#>'{packages}') AS p
+        WHERE p->>'registryType' = 'nuget' AND p->>'registryBaseUrl' IS NOT NULL
+    );
+
+COMMIT;