Simplify OpenAPI schema by merging Server into ServerDetail (#612)

This PR simplifies the OpenAPI schema by merging the `Server` component
into `ServerDetail`, addressing the issue where the `Server` component
was never used independently.

## Changes
- Merged all Server properties directly into ServerDetail in both
OpenAPI spec and JSON schema
- Removed allOf construct for clearer, standalone definitions
- Deleted unused Server components

## Benefits
- Clearer schema structure
- Easier to understand without inheritance tracing
- Reduced maintenance complexity
- No functionality loss

## Validation
All schemas and documentation examples continue to validate
successfully.

Resolves #609

Generated with [Claude Code](https://claude.ai/code)

Co-authored-by: claude[bot] <209825114+claude[bot]@users.noreply.github.com>
Co-authored-by: adam jones <domdomegg@users.noreply.github.com>
This commit is contained in:
adam jones 2025-10-04 00:57:52 +01:00 • committed by GitHub
commit e0f30f1a29
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
2 changed files with 120 additions and 138 deletions

View file

@ -267,33 +267,6 @@ components:
description: "Optional relative path from repository root to the server location within a monorepo structure"
example: "src/everything"
Server:
type: object
required:
- name
- description
- version
properties:
name:
type: string
description: "Reverse DNS name of the MCP server"
example: "io.github.modelcontextprotocol/filesystem"
description:
type: string
description: "Human-readable description of the server's functionality"
example: "Node.js server implementing Model Context Protocol (MCP) for filesystem operations."
repository:
$ref: '#/components/schemas/Repository'
version:
type: string
example: "1.0.2"
description: "Version string for this server. SHOULD follow semantic versioning (e.g., '1.0.2', '2.1.0-alpha'). Equivalent of Implementation.version in MCP specification."
websiteUrl:
type: string
format: uri
description: "Optional URL to the server's homepage, documentation, or project website. This provides a central link for users to learn more about the server. Particularly useful when the server has custom installation instructions or setup requirements."
example: "https://modelcontextprotocol.io/examples"
ServerList:
type: object
@ -515,10 +488,31 @@ components:
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
type: object
required:
- name
- description
- version
properties:
name:
type: string
description: "Reverse DNS name of the MCP server"
example: "io.github.modelcontextprotocol/filesystem"
description:
type: string
description: "Human-readable description of the server's functionality"
example: "Node.js server implementing Model Context Protocol (MCP) for filesystem operations."
repository:
$ref: '#/components/schemas/Repository'
version:
type: string
example: "1.0.2"
description: "Version string for this server. SHOULD follow semantic versioning (e.g., '1.0.2', '2.1.0-alpha'). Equivalent of Implementation.version in MCP specification."
websiteUrl:
type: string
format: uri
description: "Optional URL to the server's homepage, documentation, or project website. This provides a central link for users to learn more about the server. Particularly useful when the server has custom installation instructions or setup requirements."
example: "https://modelcontextprotocol.io/examples"
$schema:
type: string
format: uri

View file

@ -35,47 +35,6 @@
}
}
},
"Server": {
"type": "object",
"required": [
"name",
"description",
"version"
],
"properties": {
"name": {
"type": "string",
"description": "Server name in reverse-DNS format. Must contain exactly one forward slash separating namespace from server name.",
"example": "io.github.user/weather",
"pattern": "^[a-zA-Z0-9.-]+/[a-zA-Z0-9._-]+$",
"minLength": 3,
"maxLength": 200
},
"description": {
"type": "string",
"description": "Clear human-readable explanation of server functionality. Should focus on capabilities, not implementation details.",
"example": "MCP server providing weather data and forecasts via OpenWeatherMap API",
"minLength": 1,
"maxLength": 100
},
"repository": {
"$ref": "#/definitions/Repository",
"description": "Optional repository metadata for the MCP server source code. Recommended for transparency and security inspection."
},
"version": {
"type": "string",
"maxLength": 255,
"example": "1.0.2",
"description": "Version string for this server. SHOULD follow semantic versioning (e.g., '1.0.2', '2.1.0-alpha'). Equivalent of Implementation.version in MCP specification. Non-semantic versions are allowed but may not sort predictably. Version ranges are rejected (e.g., '^1.2.3', '~1.2.3', '>=1.2.3', '1.x', '1.*')."
},
"websiteUrl": {
"type": "string",
"format": "uri",
"description": "Optional URL to the server's homepage, documentation, or project website. This provides a central link for users to learn more about the server. Particularly useful when the server has custom installation instructions or setup requirements.",
"example": "https://modelcontextprotocol.io/examples"
}
}
},
"Package": {
"type": "object",
"additionalProperties": false,
@ -415,13 +374,44 @@
},
"ServerDetail": {
"description": "Schema for a static representation of an MCP server. Used in various contexts related to discovery, installation, and configuration.",
"allOf": [
{
"$ref": "#/definitions/Server"
},
{
"type": "object",
"required": [
"name",
"description",
"version"
],
"properties": {
"name": {
"type": "string",
"description": "Server name in reverse-DNS format. Must contain exactly one forward slash separating namespace from server name.",
"example": "io.github.user/weather",
"pattern": "^[a-zA-Z0-9.-]+/[a-zA-Z0-9._-]+$",
"minLength": 3,
"maxLength": 200
},
"description": {
"type": "string",
"description": "Clear human-readable explanation of server functionality. Should focus on capabilities, not implementation details.",
"example": "MCP server providing weather data and forecasts via OpenWeatherMap API",
"minLength": 1,
"maxLength": 100
},
"repository": {
"$ref": "#/definitions/Repository",
"description": "Optional repository metadata for the MCP server source code. Recommended for transparency and security inspection."
},
"version": {
"type": "string",
"maxLength": 255,
"example": "1.0.2",
"description": "Version string for this server. SHOULD follow semantic versioning (e.g., '1.0.2', '2.1.0-alpha'). Equivalent of Implementation.version in MCP specification. Non-semantic versions are allowed but may not sort predictably. Version ranges are rejected (e.g., '^1.2.3', '~1.2.3', '>=1.2.3', '1.x', '1.*')."
},
"websiteUrl": {
"type": "string",
"format": "uri",
"description": "Optional URL to the server's homepage, documentation, or project website. This provides a central link for users to learn more about the server. Particularly useful when the server has custom installation instructions or setup requirements.",
"example": "https://modelcontextprotocol.io/examples"
},
"$schema": {
"type": "string",
"format": "uri",
@ -461,7 +451,5 @@
}
}
}
]
}
}
}