From 163561085bbd64e4162ea988ee7f17e465195c0d Mon Sep 17 00:00:00 2001 From: benjdlambert Date: Tue, 21 Apr 2026 10:55:27 +0200 Subject: [PATCH] feat(catalog-model): add API v1beta2 default and mcp-server schemas Signed-off-by: benjdlambert --- .../kinds/API.v1beta2.mcp-server.schema.json | 93 +++++++++++++++++++ .../src/schema/kinds/API.v1beta2.schema.json | 79 ++++++++++++++++ 2 files changed, 172 insertions(+) create mode 100644 packages/catalog-model/src/schema/kinds/API.v1beta2.mcp-server.schema.json create mode 100644 packages/catalog-model/src/schema/kinds/API.v1beta2.schema.json diff --git a/packages/catalog-model/src/schema/kinds/API.v1beta2.mcp-server.schema.json b/packages/catalog-model/src/schema/kinds/API.v1beta2.mcp-server.schema.json new file mode 100644 index 0000000000..0567a9d0c5 --- /dev/null +++ b/packages/catalog-model/src/schema/kinds/API.v1beta2.mcp-server.schema.json @@ -0,0 +1,93 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema", + "$id": "ApiV1beta2McpServer", + "description": "An MCP (Model Context Protocol) server exposed as an API entity. See RFC backstage/backstage#32062.", + "examples": [ + { + "apiVersion": "backstage.io/v1beta2", + "kind": "API", + "metadata": { + "name": "backstage-mcp-actions", + "title": "Backstage MCP Server", + "description": "Exposes tools related to the Backstage Ecosystem" + }, + "spec": { + "type": "mcp-server", + "lifecycle": "experimental", + "owner": "backstage", + "remotes": [ + { + "type": "streamable-http", + "url": "http://internal.backstage.company:7007/api/mcp-actions/v1" + } + ] + } + } + ], + "allOf": [ + { + "$ref": "Entity" + }, + { + "type": "object", + "required": ["spec"], + "properties": { + "apiVersion": { + "enum": ["backstage.io/v1beta2"] + }, + "kind": { + "enum": ["API"] + }, + "spec": { + "type": "object", + "required": ["type", "lifecycle", "owner", "remotes"], + "properties": { + "type": { + "const": "mcp-server", + "description": "Discriminant for the MCP server specType." + }, + "lifecycle": { + "type": "string", + "description": "The lifecycle state of the MCP server.", + "examples": ["experimental", "production", "deprecated"], + "minLength": 1 + }, + "owner": { + "type": "string", + "description": "An entity reference to the owner of the MCP server.", + "examples": ["ai-platform-team", "user:john.johnson"], + "minLength": 1 + }, + "system": { + "type": "string", + "description": "An entity reference to the system that the MCP server belongs to.", + "minLength": 1 + }, + "remotes": { + "type": "array", + "minItems": 1, + "description": "Transport endpoints for the MCP server.", + "items": { + "type": "object", + "required": ["type", "url"], + "properties": { + "type": { + "type": "string", + "description": "Transport type, e.g. streamable-http, stdio, sse.", + "examples": ["streamable-http", "stdio", "sse"], + "minLength": 1 + }, + "url": { + "type": "string", + "description": "Endpoint URL for the remote. For stdio transports this may be a command string.", + "minLength": 1 + } + } + } + } + } + } + } + } + ] +} diff --git a/packages/catalog-model/src/schema/kinds/API.v1beta2.schema.json b/packages/catalog-model/src/schema/kinds/API.v1beta2.schema.json new file mode 100644 index 0000000000..2ce7b5bc0e --- /dev/null +++ b/packages/catalog-model/src/schema/kinds/API.v1beta2.schema.json @@ -0,0 +1,79 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema", + "$id": "ApiV1beta2", + "description": "An API describes an interface that can be exposed by a component. The API can be defined in different formats, like OpenAPI, AsyncAPI, GraphQL, gRPC, or other formats.", + "examples": [ + { + "apiVersion": "backstage.io/v1beta2", + "kind": "API", + "metadata": { + "name": "artist-api", + "description": "Retrieve artist details", + "labels": { + "product_name": "Random value Generator" + }, + "annotations": { + "docs": "https://github.com/..../tree/develop/doc" + } + }, + "spec": { + "type": "openapi", + "lifecycle": "production", + "owner": "artist-relations-team", + "system": "artist-engagement-portal", + "definition": "openapi: \"3.0.0\"\ninfo:..." + } + } + ], + "allOf": [ + { + "$ref": "Entity" + }, + { + "type": "object", + "required": ["spec"], + "properties": { + "apiVersion": { + "enum": ["backstage.io/v1beta2"] + }, + "kind": { + "enum": ["API"] + }, + "spec": { + "type": "object", + "required": ["type", "lifecycle", "owner", "definition"], + "properties": { + "type": { + "type": "string", + "description": "The type of the API definition.", + "examples": ["openapi", "asyncapi", "graphql", "grpc", "trpc"], + "minLength": 1 + }, + "lifecycle": { + "type": "string", + "description": "The lifecycle state of the API.", + "examples": ["experimental", "production", "deprecated"], + "minLength": 1 + }, + "owner": { + "type": "string", + "description": "An entity reference to the owner of the API.", + "examples": ["artist-relations-team", "user:john.johnson"], + "minLength": 1 + }, + "system": { + "type": "string", + "description": "An entity reference to the system that the API belongs to.", + "minLength": 1 + }, + "definition": { + "type": "string", + "description": "The definition of the API, based on the format defined by the type.", + "minLength": 1 + } + } + } + } + } + ] +}