Skip to content

Commit e0f30f1

Browse files
domdomeggclaude[bot]
domdomegg
and
claude[bot]
authored
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 <[email protected]>
1 parent c130c50 commit e0f30f1

File tree

2 files changed

+120
-138
lines changed

2 files changed

+120
-138
lines changed

‎docs/reference/api/openapi.yaml‎

Lines changed: 51 additions & 57 deletions
Original file line numberDiff line numberDiff line change
@@ -267,33 +267,6 @@ components:
267267
description: "Optional relative path from repository root to the server location within a monorepo structure"
268268
example: "src/everything"
269269

270-
Server:
271-
type: object
272-
required:
273-
- name
274-
- description
275-
- version
276-
properties:
277-
name:
278-
type: string
279-
description: "Reverse DNS name of the MCP server"
280-
example: "io.github.modelcontextprotocol/filesystem"
281-
description:
282-
type: string
283-
description: "Human-readable description of the server's functionality"
284-
example: "Node.js server implementing Model Context Protocol (MCP) for filesystem operations."
285-
repository:
286-
$ref: '#/components/schemas/Repository'
287-
version:
288-
type: string
289-
example: "1.0.2"
290-
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."
291-
websiteUrl:
292-
type: string
293-
format: uri
294-
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."
295-
example: "https://modelcontextprotocol.io/examples"
296-
297270

298271
ServerList:
299272
type: object
@@ -515,38 +488,59 @@ components:
515488

516489
ServerDetail:
517490
description: Schema for a static representation of an MCP server. Used in various contexts related to discovery, installation, and configuration.
518-
allOf:
519-
- $ref: '#/components/schemas/Server'
520-
- type: object
491+
type: object
492+
required:
493+
- name
494+
- description
495+
- version
496+
properties:
497+
name:
498+
type: string
499+
description: "Reverse DNS name of the MCP server"
500+
example: "io.github.modelcontextprotocol/filesystem"
501+
description:
502+
type: string
503+
description: "Human-readable description of the server's functionality"
504+
example: "Node.js server implementing Model Context Protocol (MCP) for filesystem operations."
505+
repository:
506+
$ref: '#/components/schemas/Repository'
507+
version:
508+
type: string
509+
example: "1.0.2"
510+
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."
511+
websiteUrl:
512+
type: string
513+
format: uri
514+
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."
515+
example: "https://modelcontextprotocol.io/examples"
516+
$schema:
517+
type: string
518+
format: uri
519+
description: JSON Schema URI for this server.json format
520+
example: "https://static.modelcontextprotocol.io/schemas/2025-09-29/server.schema.json"
521+
packages:
522+
type: array
523+
items:
524+
$ref: '#/components/schemas/Package'
525+
remotes:
526+
type: array
527+
items:
528+
$ref: '#/components/schemas/Remote'
529+
_meta:
530+
type: object
531+
description: Extension metadata using reverse DNS namespacing
521532
properties:
522-
$schema:
523-
type: string
524-
format: uri
525-
description: JSON Schema URI for this server.json format
526-
example: "https://static.modelcontextprotocol.io/schemas/2025-09-29/server.schema.json"
527-
packages:
528-
type: array
529-
items:
530-
$ref: '#/components/schemas/Package'
531-
remotes:
532-
type: array
533-
items:
534-
$ref: '#/components/schemas/Remote'
535-
_meta:
533+
io.modelcontextprotocol.registry/publisher-provided:
536534
type: object
537-
description: Extension metadata using reverse DNS namespacing
538-
properties:
539-
io.modelcontextprotocol.registry/publisher-provided:
540-
type: object
541-
description: Publisher-specific metadata and build information
542-
additionalProperties: true
543-
example:
544-
tool: "publisher-cli"
545-
version: "1.2.3"
546-
buildInfo:
547-
commit: "abc123def456"
548-
timestamp: "2023-12-01T10:30:00Z"
549-
pipelineId: "build-789"
535+
description: Publisher-specific metadata and build information
536+
additionalProperties: true
537+
example:
538+
tool: "publisher-cli"
539+
version: "1.2.3"
540+
buildInfo:
541+
commit: "abc123def456"
542+
timestamp: "2023-12-01T10:30:00Z"
543+
pipelineId: "build-789"
550544

551545
ServerResponse:
552546
description: API response format with separated server data and registry metadata

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

Lines changed: 69 additions & 81 deletions
Original file line numberDiff line numberDiff line change
@@ -35,47 +35,6 @@
3535
}
3636
}
3737
},
38-
"Server": {
39-
"type": "object",
40-
"required": [
41-
"name",
42-
"description",
43-
"version"
44-
],
45-
"properties": {
46-
"name": {
47-
"type": "string",
48-
"description": "Server name in reverse-DNS format. Must contain exactly one forward slash separating namespace from server name.",
49-
"example": "io.github.user/weather",
50-
"pattern": "^[a-zA-Z0-9.-]+/[a-zA-Z0-9._-]+$",
51-
"minLength": 3,
52-
"maxLength": 200
53-
},
54-
"description": {
55-
"type": "string",
56-
"description": "Clear human-readable explanation of server functionality. Should focus on capabilities, not implementation details.",
57-
"example": "MCP server providing weather data and forecasts via OpenWeatherMap API",
58-
"minLength": 1,
59-
"maxLength": 100
60-
},
61-
"repository": {
62-
"$ref": "#/definitions/Repository",
63-
"description": "Optional repository metadata for the MCP server source code. Recommended for transparency and security inspection."
64-
},
65-
"version": {
66-
"type": "string",
67-
"maxLength": 255,
68-
"example": "1.0.2",
69-
"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.*')."
70-
},
71-
"websiteUrl": {
72-
"type": "string",
73-
"format": "uri",
74-
"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.",
75-
"example": "https://modelcontextprotocol.io/examples"
76-
}
77-
}
78-
},
7938
"Package": {
8039
"type": "object",
8140
"additionalProperties": false,
@@ -415,53 +374,82 @@
415374
},
416375
"ServerDetail": {
417376
"description": "Schema for a static representation of an MCP server. Used in various contexts related to discovery, installation, and configuration.",
418-
"allOf": [
419-
{
420-
"$ref": "#/definitions/Server"
377+
"type": "object",
378+
"required": [
379+
"name",
380+
"description",
381+
"version"
382+
],
383+
"properties": {
384+
"name": {
385+
"type": "string",
386+
"description": "Server name in reverse-DNS format. Must contain exactly one forward slash separating namespace from server name.",
387+
"example": "io.github.user/weather",
388+
"pattern": "^[a-zA-Z0-9.-]+/[a-zA-Z0-9._-]+$",
389+
"minLength": 3,
390+
"maxLength": 200
421391
},
422-
{
392+
"description": {
393+
"type": "string",
394+
"description": "Clear human-readable explanation of server functionality. Should focus on capabilities, not implementation details.",
395+
"example": "MCP server providing weather data and forecasts via OpenWeatherMap API",
396+
"minLength": 1,
397+
"maxLength": 100
398+
},
399+
"repository": {
400+
"$ref": "#/definitions/Repository",
401+
"description": "Optional repository metadata for the MCP server source code. Recommended for transparency and security inspection."
402+
},
403+
"version": {
404+
"type": "string",
405+
"maxLength": 255,
406+
"example": "1.0.2",
407+
"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.*')."
408+
},
409+
"websiteUrl": {
410+
"type": "string",
411+
"format": "uri",
412+
"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.",
413+
"example": "https://modelcontextprotocol.io/examples"
414+
},
415+
"$schema": {
416+
"type": "string",
417+
"format": "uri",
418+
"description": "JSON Schema URI for this server.json format",
419+
"example": "https://static.modelcontextprotocol.io/schemas/2025-09-29/server.schema.json"
420+
},
421+
"packages": {
422+
"type": "array",
423+
"items": {
424+
"$ref": "#/definitions/Package"
425+
}
426+
},
427+
"remotes": {
428+
"type": "array",
429+
"items": {
430+
"anyOf": [
431+
{
432+
"$ref": "#/definitions/StreamableHttpTransport"
433+
},
434+
{
435+
"$ref": "#/definitions/SseTransport"
436+
}
437+
]
438+
}
439+
},
440+
"_meta": {
423441
"type": "object",
442+
"description": "Extension metadata using reverse DNS namespacing for vendor-specific data",
443+
"additionalProperties": true,
424444
"properties": {
425-
"$schema": {
426-
"type": "string",
427-
"format": "uri",
428-
"description": "JSON Schema URI for this server.json format",
429-
"example": "https://static.modelcontextprotocol.io/schemas/2025-09-29/server.schema.json"
430-
},
431-
"packages": {
432-
"type": "array",
433-
"items": {
434-
"$ref": "#/definitions/Package"
435-
}
436-
},
437-
"remotes": {
438-
"type": "array",
439-
"items": {
440-
"anyOf": [
441-
{
442-
"$ref": "#/definitions/StreamableHttpTransport"
443-
},
444-
{
445-
"$ref": "#/definitions/SseTransport"
446-
}
447-
]
448-
}
449-
},
450-
"_meta": {
445+
"io.modelcontextprotocol.registry/publisher-provided": {
451446
"type": "object",
452-
"description": "Extension metadata using reverse DNS namespacing for vendor-specific data",
453-
"additionalProperties": true,
454-
"properties": {
455-
"io.modelcontextprotocol.registry/publisher-provided": {
456-
"type": "object",
457-
"description": "Publisher-provided metadata for downstream registries",
458-
"additionalProperties": true
459-
}
460-
}
447+
"description": "Publisher-provided metadata for downstream registries",
448+
"additionalProperties": true
461449
}
462450
}
463451
}
464-
]
452+
}
465453
}
466454
}
467455
}

0 commit comments

Comments
 (0)