Skip to content

Polish Registry Server docs: requirements, upgrade, auth#744

Merged
rdimitrov merged 5 commits intomainfrom
registry-docs-polish
Apr 21, 2026
Merged

Polish Registry Server docs: requirements, upgrade, auth#744
rdimitrov merged 5 commits intomainfrom
registry-docs-polish

Conversation

@rdimitrov
Copy link
Copy Markdown
Member

@rdimitrov rdimitrov commented Apr 21, 2026

Summary

Final polish pass for the remaining secondary items from #364:

  • authentication.mdx: Wrap the four provider-specific examples (Keycloak, Auth0, Azure AD, Okta) in collapsible `
    Details` blocks so readers can focus on their provider without scrolling through the others. Matches the progressive-disclosure pattern used in `guides-k8s/auth-k8s.mdx`.
  • intro.mdx:
    • Rephrase the Kubernetes-source "knowledge workers" bullet that Dan flagged as jargon without context. New wording talks about surfacing running servers to end users and the dev/consumer split in larger orgs.
    • Add a new "Registry Server and the rest of ToolHive" section that explicitly clarifies how the Registry Server relates to the CLI's built-in catalog (`thv search`, `thv registry`, and `thv config set-registry`) and the ToolHive operator's Kubernetes source integration.
  • deployment.mdx: Add an explicit "System requirements" section (Kubernetes version support, PostgreSQL 14+, migration privileges, persistent storage recommendation for Git sources, network-access notes). Group the deployment-method table under a "Deployment methods" heading.
  • deploy-operator.mdx: New "Upgrade and migration" section covering the operator-and-CRD upgrade order, image-tag rollout through the `MCPRegistry` CR, automatic database migrations, and a pointer to the release notes.
  • deploy-manual.mdx: New "Upgrade and migration" section for the manifest path (image tag change, rolling update, config-change considerations, release-notes pointer).

Stacked on #743

This PR is stacked on #743 (Add Publish MCP servers guide), which is stacked on #742. Merge the stack in order (#742 → #743 → this) for a clean fast-forward.

With this round, every issue listed in #364 is either closed or has a concrete follow-up already deployed.

Closes #364

Test plan

  • `npm run build` - site builds cleanly (only the pre-existing broken anchor on an unrelated page under /guides-ui/mcp-optimizer)
  • `npm run start` spot-check: `
    Details` blocks expand/collapse correctly on authentication page; new sections render; cross-links resolve; sidebar unchanged

🤖 Generated with Claude Code

@vercel
Copy link
Copy Markdown

vercel Bot commented Apr 21, 2026 •
edited
Loading

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated (UTC)
docs-website Ready Ready Preview, Comment Apr 21, 2026 4:13pm

Request Review

@rdimitrov rdimitrov force-pushed the registry-publishing-guide branch from e9f62fe to 08b1ec8 Compare April 21, 2026 08:20
@rdimitrov rdimitrov force-pushed the registry-docs-polish branch from 267375c to fce4228 Compare April 21, 2026 08:21
@rdimitrov rdimitrov force-pushed the registry-publishing-guide branch from 08b1ec8 to c7231ee Compare April 21, 2026 09:06
rdimitrov added a commit that referenced this pull request Apr 21, 2026
@rdimitrov @claude
Address review feedback on PR #744
f87cad5 
- intro.mdx: fix the example client URL in the Key concepts list.
  Registry Server v0.1 routes are mounted under /registry, so the
  correct example is /registry/{registryName}/v0.1/servers.
- skills.mdx: fix the six curl examples and the "Browse endpoints"
  path prefix. Pre-existing drift in the skills docs missed the
  /registry path prefix, so readers copying these commands would
  receive 404s. Verified against toolhive-registry-server@main
  internal/api/server.go and docs/thv-registry-api/swagger.yaml.
- deployment.mdx: restructure Next steps to first point readers at
  the deployment how-to that matches their method (Operator vs.
  manual), then at the configuration tasks that apply to both.
  Previously the chooser page never surfaced the two how-tos in
  Next steps even though it's the natural progression.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@rdimitrov rdimitrov force-pushed the registry-docs-polish branch from fce4228 to f87cad5 Compare April 21, 2026 09:08
@rdimitrov rdimitrov mentioned this pull request Apr 21, 2026
Merged
2 tasks
@rdimitrov rdimitrov force-pushed the registry-docs-polish branch from f87cad5 to 8970c9b Compare April 21, 2026 10:08
rdimitrov added a commit that referenced this pull request Apr 21, 2026
@rdimitrov @claude
Address review feedback on PR #744
8970c9b 
- intro.mdx: fix the example client URL in the Key concepts list.
  Registry Server v0.1 routes are mounted under /registry, so the
  correct example is /registry/{registryName}/v0.1/servers.
- skills.mdx: fix the six curl examples and the "Browse endpoints"
  path prefix. Pre-existing drift in the skills docs missed the
  /registry path prefix, so readers copying these commands would
  receive 404s. Verified against toolhive-registry-server@main
  internal/api/server.go and docs/thv-registry-api/swagger.yaml.
- deployment.mdx: restructure Next steps to first point readers at
  the deployment how-to that matches their method (Operator vs.
  manual), then at the configuration tasks that apply to both.
  Previously the chooser page never surfaced the two how-tos in
  Next steps even though it's the natural progression.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@rdimitrov rdimitrov force-pushed the registry-publishing-guide branch from e5f9381 to d5a0ce0 Compare April 21, 2026 11:39
rdimitrov added a commit that referenced this pull request Apr 21, 2026
@rdimitrov @claude
Address review feedback on PR #744
6e3e166 
- intro.mdx: fix the example client URL in the Key concepts list.
  Registry Server v0.1 routes are mounted under /registry, so the
  correct example is /registry/{registryName}/v0.1/servers.
- skills.mdx: fix the six curl examples and the "Browse endpoints"
  path prefix. Pre-existing drift in the skills docs missed the
  /registry path prefix, so readers copying these commands would
  receive 404s. Verified against toolhive-registry-server@main
  internal/api/server.go and docs/thv-registry-api/swagger.yaml.
- deployment.mdx: restructure Next steps to first point readers at
  the deployment how-to that matches their method (Operator vs.
  manual), then at the configuration tasks that apply to both.
  Previously the chooser page never surfaced the two how-tos in
  Next steps even though it's the natural progression.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@rdimitrov rdimitrov force-pushed the registry-docs-polish branch from 8970c9b to 6e3e166 Compare April 21, 2026 11:40
@rdimitrov rdimitrov force-pushed the registry-publishing-guide branch from d5a0ce0 to 3af560f Compare April 21, 2026 15:06
danbarr
danbarr reviewed Apr 21, 2026
View reviewed changes
Copy link
Copy Markdown
Collaborator

@danbarr danbarr left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This one looks good too, just a few non-blocking questions/comments to think about?

Comment thread docs/toolhive/guides-registry/deployment.mdx
Comment thread docs/toolhive/guides-registry/intro.mdx Outdated
Comment thread docs/toolhive/guides-registry/authentication.mdx Outdated
rdimitrov added a commit that referenced this pull request Apr 21, 2026
@rdimitrov @claude
Address review feedback on PR #744
f2a3db0 
- intro.mdx: fix the example client URL in the Key concepts list.
  Registry Server v0.1 routes are mounted under /registry, so the
  correct example is /registry/{registryName}/v0.1/servers.
- skills.mdx: fix the six curl examples and the "Browse endpoints"
  path prefix. Pre-existing drift in the skills docs missed the
  /registry path prefix, so readers copying these commands would
  receive 404s. Verified against toolhive-registry-server@main
  internal/api/server.go and docs/thv-registry-api/swagger.yaml.
- deployment.mdx: restructure Next steps to first point readers at
  the deployment how-to that matches their method (Operator vs.
  manual), then at the configuration tasks that apply to both.
  Previously the chooser page never surfaced the two how-tos in
  Next steps even though it's the natural progression.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@rdimitrov rdimitrov force-pushed the registry-docs-polish branch from 6e3e166 to 5f9469e Compare April 21, 2026 15:09
rdimitrov added a commit that referenced this pull request Apr 21, 2026
@rdimitrov @claude
Address danbarr review on PR #744
6e73766 
- Mention PostgreSQL 14+ requirement in database.mdx too, so a reader
  who jumps straight into the database guide learns the version floor
  and is directed at the migration-user-privileges section.
- Point intro.mdx readers at the concrete CLI hook (thv config
  set-registry) instead of the vague "can also point at" phrasing.
- Replace the <details> provider blocks on authentication.mdx with
  <Tabs queryString='provider'> so every provider is visible at a
  glance and individual providers get durable deep-links (for example
  ?provider=okta) without relying on lost section anchors.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@rdimitrov rdimitrov force-pushed the registry-publishing-guide branch from 3af560f to 4887f10 Compare April 21, 2026 15:22
rdimitrov added a commit that referenced this pull request Apr 21, 2026
@rdimitrov @claude
Address review feedback on PR #744
f722986 
- intro.mdx: fix the example client URL in the Key concepts list.
  Registry Server v0.1 routes are mounted under /registry, so the
  correct example is /registry/{registryName}/v0.1/servers.
- skills.mdx: fix the six curl examples and the "Browse endpoints"
  path prefix. Pre-existing drift in the skills docs missed the
  /registry path prefix, so readers copying these commands would
  receive 404s. Verified against toolhive-registry-server@main
  internal/api/server.go and docs/thv-registry-api/swagger.yaml.
- deployment.mdx: restructure Next steps to first point readers at
  the deployment how-to that matches their method (Operator vs.
  manual), then at the configuration tasks that apply to both.
  Previously the chooser page never surfaced the two how-tos in
  Next steps even though it's the natural progression.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
rdimitrov added a commit that referenced this pull request Apr 21, 2026
@rdimitrov @claude
Address danbarr review on PR #744
ec0e627 
- Mention PostgreSQL 14+ requirement in database.mdx too, so a reader
  who jumps straight into the database guide learns the version floor
  and is directed at the migration-user-privileges section.
- Point intro.mdx readers at the concrete CLI hook (thv config
  set-registry) instead of the vague "can also point at" phrasing.
- Replace the <details> provider blocks on authentication.mdx with
  <Tabs queryString='provider'> so every provider is visible at a
  glance and individual providers get durable deep-links (for example
  ?provider=okta) without relying on lost section anchors.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@rdimitrov rdimitrov force-pushed the registry-docs-polish branch from 6e73766 to 36fb89f Compare April 21, 2026 15:24
rdimitrov added a commit that referenced this pull request Apr 21, 2026
@rdimitrov @claude
Apply docs-review findings to PR #744
36fb89f 
- Link deployment.mdx's PostgreSQL bullet directly to the
  migration-user-privileges anchor in database.mdx instead of the top
  of the page.
- Replace "A PostgreSQL database" with "PostgreSQL 14 or later" in
  deploy-operator.mdx and deploy-manual.mdx prose so readers landing
  on a specific deploy method see the version floor consistent with
  deployment.mdx and database.mdx.
- Point deploy-manual.mdx's top info admonition at both the operator
  and Helm alternatives, keeping the three deploy-* pages parallel.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
danbarr
danbarr previously approved these changes Apr 21, 2026
View reviewed changes
rdimitrov added a commit that referenced this pull request Apr 21, 2026
@rdimitrov @claude
Address review feedback on PR #744
8bc659c 
- intro.mdx: fix the example client URL in the Key concepts list.
  Registry Server v0.1 routes are mounted under /registry, so the
  correct example is /registry/{registryName}/v0.1/servers.
- skills.mdx: fix the six curl examples and the "Browse endpoints"
  path prefix. Pre-existing drift in the skills docs missed the
  /registry path prefix, so readers copying these commands would
  receive 404s. Verified against toolhive-registry-server@main
  internal/api/server.go and docs/thv-registry-api/swagger.yaml.
- deployment.mdx: restructure Next steps to first point readers at
  the deployment how-to that matches their method (Operator vs.
  manual), then at the configuration tasks that apply to both.
  Previously the chooser page never surfaced the two how-tos in
  Next steps even though it's the natural progression.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
rdimitrov added a commit that referenced this pull request Apr 21, 2026
@rdimitrov @claude
Address danbarr review on PR #744
69a8e88 
- Mention PostgreSQL 14+ requirement in database.mdx too, so a reader
  who jumps straight into the database guide learns the version floor
  and is directed at the migration-user-privileges section.
- Point intro.mdx readers at the concrete CLI hook (thv config
  set-registry) instead of the vague "can also point at" phrasing.
- Replace the <details> provider blocks on authentication.mdx with
  <Tabs queryString='provider'> so every provider is visible at a
  glance and individual providers get durable deep-links (for example
  ?provider=okta) without relying on lost section anchors.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
rdimitrov added a commit that referenced this pull request Apr 21, 2026
@rdimitrov @claude
Apply docs-review findings to PR #744
0547654 
- Link deployment.mdx's PostgreSQL bullet directly to the
  migration-user-privileges anchor in database.mdx instead of the top
  of the page.
- Replace "A PostgreSQL database" with "PostgreSQL 14 or later" in
  deploy-operator.mdx and deploy-manual.mdx prose so readers landing
  on a specific deploy method see the version floor consistent with
  deployment.mdx and database.mdx.
- Point deploy-manual.mdx's top info admonition at both the operator
  and Helm alternatives, keeping the three deploy-* pages parallel.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@rdimitrov rdimitrov force-pushed the registry-docs-polish branch from 36fb89f to 0547654 Compare April 21, 2026 15:53
Base automatically changed from registry-publishing-guide to main April 21, 2026 16:09
@rdimitrov rdimitrov dismissed danbarr’s stale review April 21, 2026 16:09

The base branch was changed.

rdimitrov and others added 5 commits April 21, 2026 19:11
@rdimitrov @claude
Polish Registry Server docs: requirements, upgrade, auth
73e3d93 
Addresses the remaining secondary items from #364:

- authentication.mdx: wrap the four provider-specific examples (Keycloak,
  Auth0, Azure AD, Okta) in collapsible <details> blocks. Shorter visual
  footprint and matches the progressive-disclosure pattern used in
  guides-k8s/auth-k8s.mdx.
- intro.mdx: rephrase the "knowledge workers" bullet in the Kubernetes
  source description to use clearer, less jargon-y wording. Add a new
  "Registry Server and the rest of ToolHive" section clarifying how the
  Registry Server relates to the CLI's built-in catalog and the ToolHive
  operator.
- deployment.mdx: add an explicit System requirements section covering
  Kubernetes versions, PostgreSQL version and migration privileges,
  persistent storage, and network access. Group the method-choice table
  under a Deployment methods heading.
- deploy-operator.mdx and deploy-manual.mdx: add Upgrade and migration
  sections covering the operator-chart-then-image flow and the
  manifest-image-tag flow respectively, with pointers to the release
  notes and the migration-user privilege model.

Relates to #364

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@rdimitrov @claude
Address review feedback on PR #744
c567942 
- intro.mdx: fix the example client URL in the Key concepts list.
  Registry Server v0.1 routes are mounted under /registry, so the
  correct example is /registry/{registryName}/v0.1/servers.
- skills.mdx: fix the six curl examples and the "Browse endpoints"
  path prefix. Pre-existing drift in the skills docs missed the
  /registry path prefix, so readers copying these commands would
  receive 404s. Verified against toolhive-registry-server@main
  internal/api/server.go and docs/thv-registry-api/swagger.yaml.
- deployment.mdx: restructure Next steps to first point readers at
  the deployment how-to that matches their method (Operator vs.
  manual), then at the configuration tasks that apply to both.
  Previously the chooser page never surfaced the two how-tos in
  Next steps even though it's the natural progression.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@rdimitrov @claude
Group deployment pages under a sidebar category
04d2b63 
Wrap deploy-operator, deploy-helm, and deploy-manual inside a
non-collapsible "Deploy the Registry Server" sidebar category that links
to the deployment overview page, per danbarr's suggestion on #742. Add
the Helm entry to the deployment page's Next steps now that all three
deployment methods coexist here.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@rdimitrov @claude
Address danbarr review on PR #744
dbc81eb 
- Mention PostgreSQL 14+ requirement in database.mdx too, so a reader
  who jumps straight into the database guide learns the version floor
  and is directed at the migration-user-privileges section.
- Point intro.mdx readers at the concrete CLI hook (thv config
  set-registry) instead of the vague "can also point at" phrasing.
- Replace the <details> provider blocks on authentication.mdx with
  <Tabs queryString='provider'> so every provider is visible at a
  glance and individual providers get durable deep-links (for example
  ?provider=okta) without relying on lost section anchors.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@rdimitrov @claude
Apply docs-review findings to PR #744
b11e56d 
- Link deployment.mdx's PostgreSQL bullet directly to the
  migration-user-privileges anchor in database.mdx instead of the top
  of the page.
- Replace "A PostgreSQL database" with "PostgreSQL 14 or later" in
  deploy-operator.mdx and deploy-manual.mdx prose so readers landing
  on a specific deploy method see the version floor consistent with
  deployment.mdx and database.mdx.
- Point deploy-manual.mdx's top info admonition at both the operator
  and Helm alternatives, keeping the three deploy-* pages parallel.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@rdimitrov rdimitrov force-pushed the registry-docs-polish branch from 0547654 to b11e56d Compare April 21, 2026 16:12
@rdimitrov rdimitrov merged commit af346b8 into main Apr 21, 2026
4 checks passed
@rdimitrov rdimitrov deleted the registry-docs-polish branch April 21, 2026 16:13
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@danbarr danbarr danbarr approved these changes

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

2 participants

@rdimitrov @danbarr