Align the server.json schema with the YAML (#168)

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

## Motivation and Context

This is in support of
https://github.com/modelcontextprotocol/registry/issues/159, to make it
easier, I hope. My team noticed some differences in the JSON schema,
most notably the "choices" property was missing. I tried to write a tool
to do this but slowed down since I am not experienced with Go. This is a
first pass, maybe someone else can finish the tooling.

I restructured the JSON schema to break out child objects like the YAML
file, and brought the descriptions and example into sync. The only
differences are two extra properties in the YAML which are computed by
the server:

- `VersionDetail.is_latest` is not present in the JSON schema, computed
by the registry based on
https://github.com/modelcontextprotocol/registry/issues/158
- `Server.id` is not present in the JSON schema, generated by the
registry

The idea is the a tool could look at ServerDetail in the YAML and then
generate the schema.json with minimal fix-ups (add a root title, remove
`VersionDetail.is_latest` and `Server.id`.

~Question for @tadasant - should `VersionDetail.release_date` be in the
JSON schema? I think _no_ (and let it be computed) but it's there right
now.~ - aligned with
https://github.com/modelcontextprotocol/registry/pull/167 and removed

## How Has This Been Tested?

I have tested the JSON schema against the sample server.json in the repo
(files and markdown blocks).

## Breaking Changes

None.

## Types of changes
<!-- What types of changes does your code introduce? Put an `x` in all
the boxes that apply: -->
- [x] Bug fix (non-breaking change which fixes an issue)
- [ ] New feature (non-breaking change which adds functionality)
- [ ] 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
- [ ] New and existing tests pass locally
- [ ] 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
-->

docs/openapi.yaml

@@ -1,4 +1,5 @@
 openapi: 3.1.0
+jsonSchemaDialect: "https://json-schema.org/draft/2020-12/schema"
 info:
   title: MCP Server Registry API
   summary: API for discovering and accessing MCP servers metadata
@@ -82,7 +83,6 @@ paths:
                     example: "Server not found"
 components:
   schemas:
-    jsonSchemaDialect: "https://json-schema.org/draft/2020-12/schema"
     Repository:
       type: object
       required:
@@ -116,33 +116,36 @@ components:
           example: "a5e8a7f0-d4e4-4a1d-b12f-2896a23fd4f1"
         name:
           type: string
-          example: "@modelcontextprotocol/servers/src/filesystem"
+          description: Human-readable description of the server's functionality
+          example: "io.modelcontextprotocol/filesystem"
         description:
           type: string
           example: "Node.js server implementing Model Context Protocol (MCP) for filesystem operations."
         repository:
           $ref: '#/components/schemas/Repository'
         version_detail:
-          type: object
-          required:
-            - version
-            - release_date
-            - is_latest
-          properties:
-            version:
-              type: string
-              example: "1.0.2"
-              description: Equivalent of Implementation.version in MCP specification.
-            release_date:
-              type: string
-              format: date-time
-              example: "2023-06-15T10:30:00Z"
-              description: Datetime that the MCP server version was published to the registry.
-            is_latest:
-              type: boolean
-              example: true
-              description: Whether the MCP server version is the latest version available in the registry.
-      $schema: "https://json-schema.org/draft/2020-12/schema"
+          $ref: '#/components/schemas/VersionDetail'
+
+    VersionDetail:
+      type: object
+      required:
+        - version
+        - release_date
+        - is_latest
+      properties:
+        version:
+          type: string
+          example: "1.0.2"
+          description: Equivalent of Implementation.version in MCP specification.
+        release_date:
+          type: string
+          format: date-time
+          example: "2023-06-15T10:30:00Z"
+          description: Datetime that the MCP server version was published to the registry.
+        is_latest:
+          type: boolean
+          example: true
+          description: Whether the MCP server version is the latest version available in the registry.
 
     ServerList:
       type: object
@@ -172,12 +175,15 @@ components:
         registry_name:
           type: string
           enum: [npm, docker, pypi, homebrew, nuget]
+          description: Package registry type
           example: "npm"
         name:
           type: string
+          description: Package name in the registry
           example: "io.modelcontextprotocol/filesystem"
         version:
           type: string
+          description: Package version
           example: "1.0.2"
         runtime_hint:
           type: string
@@ -317,17 +323,21 @@ components:
         transport_type:
           type: string
           enum: [streamable, sse]
+          description: Transport protocol type
           example: "sse"
         url:
           type: string
           format: uri
+          description: Remote server URL
           example: "https://mcp-fs.example.com/sse"
         headers:
           type: array
+          description: HTTP headers to include
           items:
             $ref: '#/components/schemas/KeyValueInput'
 
     ServerDetail:
+      description: Schema for a static representation of an MCP server. Used in various contexts related to discovery, installation, and configuration.
       allOf:
         - $ref: '#/components/schemas/Server'
         - type: object