From 1d06511c0f5a9b954d121e845f2f6fa30faadb77 Mon Sep 17 00:00:00 2001 From: Radoslav Dimitrov Date: Thu, 14 May 2026 14:09:21 +0300 Subject: [PATCH 1/3] Drop "Upstream" qualifier from registry schema docs Now that the legacy ToolHive-native registry schema reference has been removed, there is only one registry schema. Rename the page title, navbar entry, and reference index card to "Registry schema" and clean up inline prose accordingly. Kept "Upstream API" as a source type name (federation/aggregation from external registries is a distinct concept). Artifact/file renames are deferred. Co-Authored-By: Claude Opus 4.7 (1M context) --- docs/toolhive/guides-cli/registry.mdx | 17 +++++++------ .../guides-registry/configuration.mdx | 4 ++-- docs/toolhive/guides-registry/intro.mdx | 6 ++--- .../guides-registry/publish-servers.mdx | 24 +++++++++---------- docs/toolhive/reference/index.mdx | 4 ++-- .../reference/registry-schema-upstream.mdx | 15 ++++++------ docs/toolhive/tutorials/custom-registry.mdx | 4 ++-- docusaurus.config.ts | 2 +- 8 files changed, 37 insertions(+), 39 deletions(-) diff --git a/docs/toolhive/guides-cli/registry.mdx b/docs/toolhive/guides-cli/registry.mdx index bf959bae..dd2b8984 100644 --- a/docs/toolhive/guides-cli/registry.mdx +++ b/docs/toolhive/guides-cli/registry.mdx @@ -137,10 +137,10 @@ organizations that want to maintain their own private registry of MCP servers. ToolHive supports two types of custom registries: - **File-based registries**: JSON files that follow the - [upstream registry schema](../reference/registry-schema-upstream.mdx) + [ToolHive registry schema](../reference/registry-schema-upstream.mdx) - **API-based registries**: REST API endpoints that implement the [MCP Registry API specification](../guides-registry/index.mdx), which use the - [upstream registry schema](../reference/registry-schema-upstream.mdx) + [ToolHive registry schema](../reference/registry-schema-upstream.mdx) :::warning[Legacy format no longer accepted] @@ -154,7 +154,7 @@ thv registry convert --in registry.json --in-place ``` The conversion is lossless: every ToolHive-specific field is mapped to a -publisher-provided extension on the corresponding upstream server entry. +publisher-provided extension on the corresponding MCP server entry. ::: @@ -273,8 +273,8 @@ name, description, and an array of servers: } ``` -See the [upstream registry schema](../reference/registry-schema-upstream.mdx) -for the full server object structure. +See the [registry schema](../reference/registry-schema-upstream.mdx) for the +full server object structure. ### Key characteristics @@ -289,10 +289,9 @@ for the full server object structure. ### Full example -For a complete custom registry file with both top-level servers and groups in -the upstream format, see the -[Full example](../reference/registry-schema-upstream.mdx#full-example) in the -upstream registry schema reference. +For a complete custom registry file with both top-level servers and groups, see +the [Full example](../reference/registry-schema-upstream.mdx#full-example) in +the registry schema reference. ### Use registry servers with groups diff --git a/docs/toolhive/guides-registry/configuration.mdx b/docs/toolhive/guides-registry/configuration.mdx index 24127dc5..8530236e 100644 --- a/docs/toolhive/guides-registry/configuration.mdx +++ b/docs/toolhive/guides-registry/configuration.mdx @@ -97,8 +97,8 @@ Kubernetes lease name suffixes for leader election. ## Registry data format -The Registry Server reads registry data in the official -[upstream MCP registry format](../reference/registry-schema-upstream.mdx). All +The Registry Server reads registry data in the +[ToolHive registry format](../reference/registry-schema-upstream.mdx). All synced sources (Git, API, and File) must provide data in this format. For a walkthrough of what the file looks like and how to land changes in a Git repository, see [Publish MCP servers](./publish-servers.mdx). diff --git a/docs/toolhive/guides-registry/intro.mdx b/docs/toolhive/guides-registry/intro.mdx index d9d815fa..433c84f2 100644 --- a/docs/toolhive/guides-registry/intro.mdx +++ b/docs/toolhive/guides-registry/intro.mdx @@ -118,7 +118,7 @@ The server supports five source types: 1. **Managed** - A fully-managed MCP source - Ideal for hosting private MCP server catalogs - - Automatically exposes entries following upstream MCP Registry format + - Automatically exposes entries following the MCP Registry format - Supports publishing MCP servers and skills via the `/v1/entries` admin API 2. **Upstream API** - Sync from upstream MCP Registry APIs @@ -135,12 +135,12 @@ The server supports five source types: 4. **Git** - Clone and sync from Git repositories - Supports branch, tag, or commit pinning - - Syncs both MCP servers and skills (upstream format) + - Syncs both MCP servers and skills - Does not support publishing 5. **File** - Read from filesystem - Ideal for local development and testing - - Syncs both MCP servers and skills (upstream format) + - Syncs both MCP servers and skills - Does not support publishing ## Registry Server and the rest of ToolHive diff --git a/docs/toolhive/guides-registry/publish-servers.mdx b/docs/toolhive/guides-registry/publish-servers.mdx index b2d5a181..bdfc9062 100644 --- a/docs/toolhive/guides-registry/publish-servers.mdx +++ b/docs/toolhive/guides-registry/publish-servers.mdx @@ -28,8 +28,8 @@ a `skill` payload instead of a `server` payload. ## Registry file format Git and file sources both read a single JSON file in the -[upstream MCP registry format](../reference/registry-schema-upstream.mdx). The -file has top-level `version` and `meta` fields, plus a `data` object that holds +[ToolHive registry format](../reference/registry-schema-upstream.mdx). The file +has top-level `version` and `meta` fields, plus a `data` object that holds `servers` and optionally `skills` arrays. A single file can carry servers, skills, or both: @@ -99,13 +99,13 @@ skills, or both: ### Required fields Each entry in the `data.servers` array needs the following keys, per the -upstream schema: +registry schema: - `name`: reverse-DNS identifier (for example, `io.github.acme/deploy-helper`). This is the unique key for the entry. - `description`: short text displayed in listings. - `version`: the version this entry represents. Must follow the rules in the - upstream schema. + registry schema. - Either `packages` (for servers distributed as container images or other package types) or `remotes` (for remote MCP servers accessed by URL). @@ -114,9 +114,9 @@ at least one `packages` entry referencing the skill's Git repository or OCI artifact. See [Manage skills](./skills.mdx) for the full skill-specific field reference and the managed-source admin API for skills. -See the [upstream registry schema](../reference/registry-schema-upstream.mdx) -for the full field catalog, including optional metadata, tool definitions, and -the ToolHive extensions under +See the [registry schema](../reference/registry-schema-upstream.mdx) for the +full field catalog, including optional metadata, tool definitions, and the +ToolHive extensions under `_meta["io.modelcontextprotocol.registry/publisher-provided"]`. ### Add the `$schema` property @@ -189,7 +189,7 @@ source (see ### Validate before committing -Validate the file against the upstream schema locally before opening a PR. Any +Validate the file against the registry schema locally before opening a PR. Any JSON Schema validator works. For a quick check with [`check-jsonschema`](https://github.com/python-jsonschema/check-jsonschema): @@ -276,8 +276,8 @@ curl -X POST \ Required fields in the `server` object: `name`, `description`, `version`, and either `packages` or `remotes`. See the -[upstream registry schema](../reference/registry-schema-upstream.mdx) for the -full structure and the optional ToolHive extensions. +[registry schema](../reference/registry-schema-upstream.mdx) for the full +structure and the optional ToolHive extensions. A successful response returns `201 Created` with the published server. If the version already exists, the server returns `409 Conflict`. @@ -364,8 +364,8 @@ for the authorization rules. ## Related information -- [Upstream registry JSON schema](../reference/registry-schema-upstream.mdx) - - the full structure and validation rules for server and skill entries +- [Registry JSON schema](../reference/registry-schema-upstream.mdx) - the full + structure and validation rules for server and skill entries - [Registry Server API reference](../reference/registry-api.mdx) - request and response schemas for every endpoint - [Configure sources and registries](./configuration.mdx) - source types, sync diff --git a/docs/toolhive/reference/index.mdx b/docs/toolhive/reference/index.mdx index 0180f207..29ccba22 100644 --- a/docs/toolhive/reference/index.mdx +++ b/docs/toolhive/reference/index.mdx @@ -72,8 +72,8 @@ tutorials, see the individual product sections. item={{ type: 'link', href: '/toolhive/reference/registry-schema-upstream', - label: 'Upstream registry JSON schema', - description: 'JSON schema for the upstream MCP registry format.', + label: 'Registry JSON schema', + description: 'JSON schema for the ToolHive registry format.', }} /> diff --git a/docs/toolhive/reference/registry-schema-upstream.mdx b/docs/toolhive/reference/registry-schema-upstream.mdx index 1df8c8b3..02476421 100644 --- a/docs/toolhive/reference/registry-schema-upstream.mdx +++ b/docs/toolhive/reference/registry-schema-upstream.mdx @@ -1,5 +1,5 @@ --- -title: Upstream registry JSON schema +title: Registry JSON schema description: JSON schema reference for the ToolHive registry format, which builds on the official MCP server schema and adds skills, groups, and publisher-provided @@ -27,10 +27,9 @@ needs `"servers": []`. :::info The CLI, UI, and [Registry Server](/toolhive/guides-registry/intro) all consume -this upstream format. The legacy ToolHive-native registry format is no longer -accepted by `thv config set-registry` or by remote registries; migrate any -existing custom registry file with -[`thv registry convert`](./cli/thv_registry_convert.md). +this format. The legacy ToolHive-native registry format is no longer accepted by +`thv config set-registry` or by remote registries; migrate any existing custom +registry file with [`thv registry convert`](./cli/thv_registry_convert.md). ::: @@ -57,9 +56,9 @@ official MCP server schema: ## ToolHive extensions schema -ToolHive extends the upstream MCP server schema with additional metadata to -support features like container configuration, authentication, and -categorization. These extensions are stored in the +ToolHive extends the MCP server schema with additional metadata to support +features like container configuration, authentication, and categorization. These +extensions are stored in the `_meta['io.modelcontextprotocol.registry/publisher-provided']` property of each server definition. diff --git a/docs/toolhive/tutorials/custom-registry.mdx b/docs/toolhive/tutorials/custom-registry.mdx index 03b0a868..2a91fa49 100644 --- a/docs/toolhive/tutorials/custom-registry.mdx +++ b/docs/toolhive/tutorials/custom-registry.mdx @@ -395,8 +395,8 @@ registries (public or private) as well as remote servers hosted at a URL. registry with authentication, multiple data sources, and automatic synchronization - Explore the full - [upstream registry schema reference](../reference/registry-schema-upstream.mdx) - to understand all available configuration options + [registry schema reference](../reference/registry-schema-upstream.mdx) to + understand all available configuration options - Learn about [custom permissions](../guides-cli/custom-permissions.mdx) for fine-grained security control - Set up [secrets management](../guides-cli/secrets-management.mdx) for servers diff --git a/docusaurus.config.ts b/docusaurus.config.ts index ecd53184..62d7ddc7 100644 --- a/docusaurus.config.ts +++ b/docusaurus.config.ts @@ -304,7 +304,7 @@ const config: Config = { to: 'toolhive/reference/registry-api', }, { - label: 'Upstream registry schema', + label: 'Registry schema', to: 'toolhive/reference/registry-schema-upstream', }, ], From 3fc6ad3120f222ce77e0f3a065143bb3b464dca1 Mon Sep 17 00:00:00 2001 From: Radoslav Dimitrov Date: Thu, 14 May 2026 14:16:20 +0300 Subject: [PATCH 2/3] Clean up Upstream schema refs in registry guides Address Copilot review feedback on #873 by cleaning up missed schema-qualifier references in the registry quickstart, operator deployment guide, and skills guide. Co-Authored-By: Claude Opus 4.7 (1M context) --- docs/toolhive/guides-registry/deploy-operator.mdx | 2 +- docs/toolhive/guides-registry/quickstart.mdx | 4 ++-- docs/toolhive/guides-registry/skills.mdx | 2 +- 3 files changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/toolhive/guides-registry/deploy-operator.mdx b/docs/toolhive/guides-registry/deploy-operator.mdx index 44d753bb..62b14226 100644 --- a/docs/toolhive/guides-registry/deploy-operator.mdx +++ b/docs/toolhive/guides-registry/deploy-operator.mdx @@ -827,7 +827,7 @@ Common causes include: - **Source unavailable**: Git repository, API endpoint, or file is inaccessible - **Invalid JSON format**: Registry file contains invalid JSON - **Schema mismatch**: The data does not conform to the - [upstream MCP registry schema](../reference/registry-schema-upstream.mdx) + [ToolHive registry schema](../reference/registry-schema-upstream.mdx) - **Filter too restrictive**: Filters may be excluding all servers diff --git a/docs/toolhive/guides-registry/quickstart.mdx b/docs/toolhive/guides-registry/quickstart.mdx index 2e30884b..5c9f5878 100644 --- a/docs/toolhive/guides-registry/quickstart.mdx +++ b/docs/toolhive/guides-registry/quickstart.mdx @@ -21,7 +21,7 @@ ToolHive CLI and UI, see the [Introduction](./intro.mdx) for a comparison. - How to install the ToolHive Operator, which bundles the `MCPRegistry` CRD - How to deploy a minimal PostgreSQL database for the Registry Server - How to define registry data in a ConfigMap using the - [upstream MCP registry format](../reference/registry-schema-upstream.mdx) + [ToolHive registry format](../reference/registry-schema-upstream.mdx) - How to create an `MCPRegistry` resource that reads from that ConfigMap - How to query the Registry API @@ -184,7 +184,7 @@ the Registry Server pod and points the server at it automatically when you set Define registry data in a ConfigMap. The Registry Server reads it through a file-based source. The ConfigMap uses the -[upstream MCP registry format](../reference/registry-schema-upstream.mdx) with a +[ToolHive registry format](../reference/registry-schema-upstream.mdx) with a single example server entry: ```yaml title="registry-data.yaml" diff --git a/docs/toolhive/guides-registry/skills.mdx b/docs/toolhive/guides-registry/skills.mdx index 4769ce29..9603a1fd 100644 --- a/docs/toolhive/guides-registry/skills.mdx +++ b/docs/toolhive/guides-registry/skills.mdx @@ -15,7 +15,7 @@ Skills can come from two paths: - **Publish to a managed source via the admin API** (covered in depth below). Good for programmatic or UI-driven publishing with per-version control. - **Sync from external sources** (Git, upstream API, or file) that contain - skills in the upstream registry format. Good for catalogs that live in a + skills in the ToolHive registry format. Good for catalogs that live in a repository with code review and CI. For the file-based path, the registry JSON format is identical to the one used From b01054f6b5d71478e72ce5c7d8bc0233794d237d Mon Sep 17 00:00:00 2001 From: Radoslav Dimitrov Date: Thu, 14 May 2026 10:18:43 -0400 Subject: [PATCH 3/3] Update docs/toolhive/guides-registry/intro.mdx Co-authored-by: Dan Barr --- docs/toolhive/guides-registry/intro.mdx | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/toolhive/guides-registry/intro.mdx b/docs/toolhive/guides-registry/intro.mdx index 433c84f2..d9ed32f7 100644 --- a/docs/toolhive/guides-registry/intro.mdx +++ b/docs/toolhive/guides-registry/intro.mdx @@ -118,7 +118,8 @@ The server supports five source types: 1. **Managed** - A fully-managed MCP source - Ideal for hosting private MCP server catalogs - - Automatically exposes entries following the MCP Registry format + - Automatically exposes entries following the MCP Registry format with + ToolHive-specific extensions - Supports publishing MCP servers and skills via the `/v1/entries` admin API 2. **Upstream API** - Sync from upstream MCP Registry APIs