Split OpenAPI specs into base and official registry versions (modelcontextprotocol#171)

Closes modelcontextprotocol#149

As noted in the FAQ update here, this is a helpful starting point in
thinking about this:

```
### What is the difference between "Official MCP Registry", "MCP Registry", "MCP registry", "MCP Registry API", etc?

There are four underlying concepts:
- "MCP Server Registry API" (or "MCP Registry API"): The OpenAPI specification defined in [openapi.yaml](./server-registry-api/openapi.yaml). This is a reusable API specification that anyone building any sort of "MCP server registry" should consider adopting / aligning with.
- "Official MCP Registry" (or "MCP Registry"): The application that lives at `https://registry.modelcontextprotocol.io`. This registry currently only catalogs MCP servers, but may be extended in the future to also catalog MCP client/host apps and frameworks.
- "Official MCP Registry API": The REST API that lives at `https://registry.modelcontextprotocol.io/api`, with an OpenAPI specification defined at [official-registry-openapi.yaml](./server-registry-api/official-registry-openapi.yaml)
- "MCP server registry" (or "MCP registry"): A third party, likely commercial, implementation of the MCP Server Registry API or derivative specification.
```

Prior to this PR, we were just treating "MCP Server Registry API" and
"Official MCP Registry API" to be the same thing. They are not the same:
the latter is inherently a more constrained version of the former. A
private deployment of a similar registry need not have constraints like
"the only valid source code repositories are `github` and `gitlab`".

This PR separates out the definitions to match that path forward.

## Notable Changes

### Base OpenAPI spec (`openapi.yaml`)
- Removed official-registry-specific constraints:
  - No maximum limit on `/servers` endpoint
  - No enum constraint on `Repository.source`
  - No enum constraint on `Package.registry_name`
- Removed `/v0` prefix from paths (it's now just baked into the
`official` one's URL prefix)
- Added `$id` for proper schema identification

### Official Registry OpenAPI spec (`official-registry-openapi.yaml`)
- Created as a derivative of the base spec using `$ref`
- Re-adds official-registry-specific constraints:
  - `Repository.source` enum: `[github]`
  - `Package.registry_name` enum: `[npm, docker, pypi, nuget]`

### Documentation updates
- Added `server-registry-api/README.md` explaining the relationship
between specs
- Updated FAQ to clarify terminology
- Reorganized docs structure

Author: tadasant

docs/faq.md

@@ -13,6 +13,14 @@ The MCP Registry is the official centralized metadata repository for publicly-ac
 - Standardized installation and configuration information
 - Namespace management through DNS verification
 
+### What is the difference between "Official MCP Registry", "MCP Registry", "MCP registry", "MCP Registry API", etc?
+
+There are four underlying concepts:
+- "MCP Server Registry API" (or "MCP Registry API"): The OpenAPI specification defined in [openapi.yaml](./server-registry-api/openapi.yaml). This is a reusable API specification that anyone building any sort of "MCP server registry" should consider adopting / aligning with.
+- "Official MCP Registry" (or "MCP Registry"): The application that lives at `https://registry.modelcontextprotocol.io`. This registry currently only catalogs MCP servers, but may be extended in the future to also catalog MCP client/host apps and frameworks.
+- "Official MCP Registry API": The REST API that lives at `https://registry.modelcontextprotocol.io/api`, with an OpenAPI specification defined at [official-registry-openapi.yaml](./server-registry-api/official-registry-openapi.yaml)
+- "MCP server registry" (or "MCP registry"): A third party, likely commercial, implementation of the MCP Server Registry API or derivative specification.
+
 ### 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, NuGet, Docker Hub, etc.), but does not host the actual source code or packages.

docs/server-registry-api/README.md

@@ -0,0 +1,14 @@
+# Registry API
+
+There are a variety of use cases where an MCP Server Registry API is useful to the MCP ecosystem. At least the following:
+- Implementation of a centralized, publicly available catalog of all publicly accessible MCP server implementations
+- Implementation of a private catalog of MCP server implementations exclusively accessible by a specific group of people (e.g. a single enterprise)
+
+These scenarios would benefit from a standard "MCP server registry API" specification that they could potentially compose, as well as share resources (like SDK implementations).
+
+The centralized, publicly available catalog ("Official MCP Registry") needs additional constraints that need not apply to the broader "MCP server registry API"
+
+References:
+- [openapi.yaml](./openapi.yaml) - A reusable API specification (MCP Server Registry API) that anyone building any sort of "MCP server registry" should consider adopting / aligning with.
+- [examples.md](./api_examples.md) - Example manifestations of the OpenAPI specification
+- [official-registry-openapi.ayml](./official-registry-openapi.yaml) - The specification backing the Official MCP Registry; a derivative of the MCP Server Registry API specification.

docs/api_examples.md renamed to docs/server-registry-api/examples.md

@@ -0,0 +1,42 @@
+openapi: 3.1.0
+jsonSchemaDialect: "https://json-schema.org/draft/2020-12/schema"
+info:
+  title: Official MCP Registry API
+  summary: Official API for discovering and accessing MCP servers metadata with registry constraints
+  description: |
+    Extends the base MCP Server Registry API with additional constraints for the official registry and adding additional functionality.
+    The Official Registry allows server creators to publish and maintain metadata about their servers in a standardized format.
+    The read side of the API enables MCP client applications and "server aggregator" type consumers to discover and install MCP servers.
+  version: 0.0.1
+  contact:
+    name: MCP Community Working Group
+  license:
+    name: MIT
+    identifier: MIT
+servers:
+  - url: https://registry.modelcontextprotocol.io/api/v0
+    description: Official MCP Registry
+
+paths:
+  /servers:
+    $ref: 'https://modelcontextprotocol.io/schemas/draft/2025-07-09/server-registry-openapi#/paths/~1servers'
+  /servers/{id}:
+    $ref: 'https://modelcontextprotocol.io/schemas/draft/2025-07-09/server-registry-openapi#/paths/~1servers~1{id}'
+
+components:
+  schemas:
+    Repository:
+      allOf:
+        - $ref: 'https://modelcontextprotocol.io/schemas/draft/2025-07-09/server-registry-openapi#/components/schemas/Repository'
+        - type: object
+          properties:
+            source:
+              enum: [github]
+    
+    Package:
+      allOf:
+        - $ref: 'https://modelcontextprotocol.io/schemas/draft/2025-07-09/server-registry-openapi#/components/schemas/Package'
+        - type: object
+          properties:
+            registry_name:
+              enum: [npm, docker, pypi, nuget]

docs/server-registry-api/official-registry-openapi.yaml

@@ -1,37 +1,26 @@
 openapi: 3.1.0
 jsonSchemaDialect: "https://json-schema.org/draft/2020-12/schema"
+$id: https://modelcontextprotocol.io/schemas/draft/2025-07-09/server-registry-openapi
 info:
   title: MCP Server Registry API
-  summary: API for discovering and accessing MCP servers metadata
+  summary: API for discovering and accessing MCP server metadata
   description: |
-    REST API that centralizes metadata about publicly available MCP servers by allowing server creators to submit
-    and maintain metadata about their servers in a standardized format. This API enables MCP client
-    applications and "server aggregator" type consumers to discover and install MCP servers.
-  version: 0.0.1
-  contact:
-    name: MCP Community Working Group
+    Specification for a theoretical REST API that serves up metadata about MCP servers.
   license:
     name: MIT
     identifier: MIT
-servers:
-  # TODO: Still think a unique name would be better; maybe we open a public discussion on the topic and let people submit ideas?
-  - url: https://registry.modelcontextprotocol.io
-    description: MCP Server Registry
-# TODO: Webhooks here would be interesting, but out of scope for MVP
 
 paths:
-  /v0/servers:
+  /servers:
     get:
       summary: List MCP servers
       description: Returns a list of all registered MCP servers
       parameters:
         - name: limit
           in: query
-          description: Number of results per page (maximum 5000)
+          description: Number of results per page
           schema:
             type: integer
-            default: 5000
-            maximum: 5000
             minimum: 1
         - name: offset
           in: query
@@ -47,7 +36,7 @@ paths:
             application/json:
               schema:
                 $ref: '#/components/schemas/ServerList'
-  /v0/servers/{id}:
+  /servers/{id}:
     get:
       summary: Get MCP server details
       description: Returns detailed information about a specific MCP server
@@ -96,7 +85,6 @@ components:
           example: "https://github.com/modelcontextprotocol/servers"
         source:
           type: string
-          enum: [github, gitlab] # TODO: Add all supported sources as a whitelist
           example: "github"
         id:
           type: string
@@ -174,7 +162,6 @@ components:
       properties:
         registry_name:
           type: string
-          enum: [npm, docker, pypi, homebrew, nuget]
           description: Package registry type
           example: "npm"
         name: