diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md new file mode 100644 index 00000000..37319125 --- /dev/null +++ b/.github/pull_request_template.md @@ -0,0 +1,24 @@ +### Description + + +### Related issues/PRs + + + +### Screenshots + + +### Merge checklist + + +#### Content + +- [ ] New pages include a frontmatter section with title and description at a minimum +- [ ] Sidebar navigation (`sidebars.ts`) updated for added, deleted, reordered, or renamed files +- [ ] Redirects added to `vercel.json` for moved, renamed, or deleted pages (i.e., if the URL slug changed) + - Rationale: 404's are the enemy! You can test these in the Vercel preview build (push your branch or run `vercel`) + +#### Reviews + +- [ ] Content has been reviewed for technical accuracy +- [ ] Content has been reviewed for spelling, grammar, and [style](STYLE_GUIDE.md) diff --git a/.markdownlint-cli2.jsonc b/.markdownlint-cli2.jsonc index b2033ea4..1dcd1b13 100644 --- a/.markdownlint-cli2.jsonc +++ b/.markdownlint-cli2.jsonc @@ -1,5 +1,9 @@ { "gitignore": true, "globs": ["**/*.md"], - "ignores": ["docs/toolhive/reference/cli/", "static/api-specs/*.md"], + "ignores": [ + "docs/toolhive/reference/cli/", + "static/api-specs/*.md", + ".github/pull_request_template.md", + ], } diff --git a/.prettierignore b/.prettierignore index 47d07b06..e1c20dd2 100644 --- a/.prettierignore +++ b/.prettierignore @@ -1,3 +1,6 @@ # Ignore autogenerated files docs/toolhive/reference/cli/**/*.md static/api-specs/ + +# Ignore templates +.github/pull_request_template.md diff --git a/docs/theme-preview.mdx b/docs/theme-preview.mdx index 4a239603..41f8db65 100644 --- a/docs/theme-preview.mdx +++ b/docs/theme-preview.mdx @@ -21,7 +21,7 @@ doesn't participate in a sidebar, navigate to a different page to see them. Another element that can't be easily reproduced here is the DocCardList component, but you can see it in action on the -[ToolHive CLI guides index page](./toolhive/guides-cli). +[ToolHive CLI guides index page](./toolhive/guides-cli/index.mdx). ## Level 2 heading diff --git a/docs/toolhive/_partials/_client-config-intro.mdx b/docs/toolhive/_partials/_client-config-intro.mdx new file mode 100644 index 00000000..0d0eeefb --- /dev/null +++ b/docs/toolhive/_partials/_client-config-intro.mdx @@ -0,0 +1,17 @@ +ToolHive automatically configures supported AI clients to work with MCP servers. +This guide shows you how to set up and manage client configurations. + +## Understanding client configuration + +Before an AI application can use ToolHive MCP servers, it needs to know where to +find them. You can configure clients in two ways: + +1. **{props.term} a supported client**: {props.term} your client with ToolHive + so it automatically manages and updates the client's configuration as you + start, stop, and remove MCP servers. +2. **Manual configuration**: For clients that ToolHive doesn't directly support, + manually configure them to connect to ToolHive-managed MCP servers using the + SSE or Streamable HTTP protocol. + +For a complete list of supported clients and compatibility details, see the +[Client compatibility reference](../reference/client-compatibility.mdx). diff --git a/docs/toolhive/concepts/_category_.yaml b/docs/toolhive/concepts/_category_.yaml deleted file mode 100644 index 6fb772e2..00000000 --- a/docs/toolhive/concepts/_category_.yaml +++ /dev/null @@ -1,2 +0,0 @@ -label: 'Concepts' -position: 40 diff --git a/docs/toolhive/concepts/mcp-primer.md b/docs/toolhive/concepts/mcp-primer.md index 9be9bf23..2d914040 100644 --- a/docs/toolhive/concepts/mcp-primer.md +++ b/docs/toolhive/concepts/mcp-primer.md @@ -4,7 +4,6 @@ sidebar_label: MCP primer description: A brief introduction to the Model Context Protocol (MCP) and its benefits for developers. -sidebar_position: 5 --- **TL;DR:** MCP offers a pragmatic, language‑friendly bridge between diff --git a/docs/toolhive/concepts/registry-criteria.md b/docs/toolhive/concepts/registry-criteria.md index 071f7522..4fd09f2b 100644 --- a/docs/toolhive/concepts/registry-criteria.md +++ b/docs/toolhive/concepts/registry-criteria.md @@ -1,10 +1,9 @@ --- title: 'Registry criteria' description: Criteria for adding MCP servers to the ToolHive registry -sidebar_position: 50 --- -The ToolHive registry maintains a curated list of MCP servers that meet specific +The ToolHive registry is a curated list of MCP servers that meet specific criteria. We aim to establish a curated, community-auditable list of high-quality MCP servers through clear, observable, and objective criteria. Here are the criteria for adding an MCP server to the ToolHive registry: diff --git a/docs/toolhive/faq.md b/docs/toolhive/faq.md new file mode 100644 index 00000000..abf8963c --- /dev/null +++ b/docs/toolhive/faq.md @@ -0,0 +1,185 @@ +--- +title: Frequently asked questions +sidebar_label: FAQ +description: Common questions about ToolHive. +--- + +## General questions + +### What is ToolHive? + +ToolHive is an open source platform that simplifies the deployment and +management of Model Context Protocol (MCP) servers. It runs MCP servers in +secure, isolated containers and provides tools to manage them easily. You can +run ToolHive as a graphical desktop app, command-line tool, or Kubernetes +operator. + +### What is the Model Context Protocol (MCP)? + +MCP is a protocol that allows AI applications to connect to external data +sources and tools. It provides a standardized way for AI models to access +real-world context like APIs, source code repositories, databases, and other +systems. Think of it as a bridge between AI models and the external systems +where your data and applications live. + +### Do I need to know how to code to use ToolHive? + +No. ToolHive includes a graphical interface that doesn't require coding +knowledge. However, some MCP servers may require configuration or secrets, such +as API keys, that you'll need to set up. The ToolHive CLI is more technical but +comes with comprehensive documentation. + +### Is ToolHive free to use? + +Yes, ToolHive is open source (Apache 2.0 licensed) and free to use. You can find +the source code on GitHub and use it without any licensing fees. + +## Using MCP servers + +### How do I find available MCP servers? + +ToolHive includes a curated registry of verified MCP servers. You can browse +them from the **Registry** tab in the UI or by running `thv registry list` in +the CLI. + +### What MCP servers are available? + +The registry includes servers for common use cases, such as retrieving content +from the web using the +[GoFetch MCP server](https://github.com/StacklokLabs/gofetch), and for popular +services and platforms like: + +- **Atlassian** – Access Jira and Confluence +- **AWS Documentation** – Query AWS service documentation +- **GitHub** – Access repositories, issues, and pull requests +- **Kubernetes** – Interact with Kubernetes clusters via the + [MKP MCP server](https://github.com/StacklokLabs/mkp) +- **MongoDB**, **PostgreSQL**, **Redis** – Connect to databases +- **Notion** – Connect to Notion workspaces +- And many more + +### Can I run MCP servers that aren't in the registry? + +Yes. You can run any MCP server from a container image or source package, even +if it's not in the registry. Just provide the image name or package details when +starting the server using the CLI or UI. See the custom MCP server section in +the [UI guide](./guides-ui/run-mcp-servers.md#install-a-custom-mcp-server) and +[CLI guide](./guides-cli/run-mcp-servers.mdx#run-a-custom-mcp-server) for more +details. + +The Kubernetes operator also supports custom MCP servers that are packaged as +container images. + +:::tip + +You can use the ToolHive CLI to run a custom MCP server from a source package +once, then export the Docker image for import into your container registry or +Kubernetes cluster to use it with the operator. + +::: + +## Security and permissions + +### Is it safe to run MCP servers? + +ToolHive runs MCP servers in isolated containers with minimal default +permissions. Each server runs in its own container with restricted access to +your system and network. + +:::tip + +For extra security, review the permission profiles and network isolation options +before running new or untrusted MCP servers. + +::: + +### How does ToolHive handle secrets like API keys? + +ToolHive provides secure secrets management: + +- Secrets are encrypted and stored securely on your system +- They're passed to MCP servers as environment variables +- Secrets never appear in plaintext in configuration files +- Integration with 1Password is also supported + +### Can I control what an MCP server can access? + +Yes. ToolHive uses permission profiles to control: + +- **File system access** – Which directories the server can read or write +- **Network access** – Which hosts and ports the server can connect to + +You can use built-in profiles or create custom ones for specific security +requirements. + +### What's network isolation and when should I use it? + +Network isolation creates a secure network architecture that filters all +outbound connections from MCP servers. Use the `--isolate-network` flag when +running servers that need strict network controls, especially in enterprise +environments. + +## Enterprise and advanced usage + +### Can I use ToolHive in my company? + +Yes. ToolHive is designed for both individual developers and enterprise teams. +The Kubernetes Operator provides centralized management, security controls, and +integration with existing infrastructure for enterprise deployments. + +### How do I deploy ToolHive in Kubernetes? + +Use the ToolHive Kubernetes Operator to deploy and manage MCP servers as +Kubernetes resources. See the [Kubernetes guides](./guides-k8s/index.mdx) for +detailed instructions. The Kubernetes operator is currently experimental. + +### Can I run my own custom MCP servers? + +Yes. You can run custom MCP servers from Docker images or source packages. +ToolHive supports: + +- Docker images from public or private registries +- Source packages from package managers like npm, PyPI, or Go modules + +### How do I get my MCP server added to the ToolHive registry? + +The ToolHive registry has specific +[inclusion criteria](./concepts/registry-criteria.md), such as being open +source, following good security practices, and maintaining code quality. Review +the criteria and +[submit your server for consideration](https://github.com/stacklok/toolhive/issues/new?template=add-an-mcp-server.md). + +### Can I use ToolHive behind a corporate firewall? + +Yes. ToolHive supports corporate environments with: + +- Custom CA certificate configuration for TLS inspection +- Network isolation and permission profiles +- Integration with secret management systems like 1Password + +## Getting help + +### Where can I get help if I'm stuck? + +- **Documentation** – Check the comprehensive guides and reference documentation +- **GitHub Issues** – Report bugs or request features on the + [ToolHive GitHub repository](https://github.com/stacklok/toolhive/issues) +- **Discord Community** – Join the + [Stacklok Discord](https://discord.gg/stacklok) for community support +- **Troubleshooting sections** – Each guide includes troubleshooting tips for + common issues + +### How do I report a bug or request a feature? + +Open an issue in the appropriate GitHub repository: + +- [**ToolHive UI**](https://github.com/stacklok/toolhive-studio/issues) – For + issues specific to the graphical desktop app +- [**ToolHive CLI & Kubernetes**](https://github.com/stacklok/toolhive/issues) – + For issues related to the CLI tool or Kubernetes operator + +### Is there a community I can join? + +Yes! Join the [Stacklok Discord community](https://discord.gg/stacklok) to +connect with other ToolHive users, ask questions, and share your experiences. +There's a dedicated `#toolhive-developers` channel for technical discussions. diff --git a/docs/toolhive/guides-cli/_category_.yaml b/docs/toolhive/guides-cli/_category_.yaml deleted file mode 100644 index 80280c40..00000000 --- a/docs/toolhive/guides-cli/_category_.yaml +++ /dev/null @@ -1,5 +0,0 @@ -label: 'Using the ToolHive CLI' -position: 20 -link: - type: generated-index - slug: '/toolhive/guides-cli' diff --git a/docs/toolhive/guides-cli/api-server.md b/docs/toolhive/guides-cli/api-server.md index cf319381..a24fd1b0 100644 --- a/docs/toolhive/guides-cli/api-server.md +++ b/docs/toolhive/guides-cli/api-server.md @@ -1,7 +1,6 @@ --- title: Run the API server -description: How to run the local ToolHive API server -sidebar_position: 60 +description: How to run the local ToolHive API server. --- ToolHive includes a built-in API server that provides a RESTful interface for diff --git a/docs/toolhive/guides-cli/client-configuration.md b/docs/toolhive/guides-cli/client-configuration.mdx similarity index 84% rename from docs/toolhive/guides-cli/client-configuration.md rename to docs/toolhive/guides-cli/client-configuration.mdx index d3f10e41..bf0d546e 100644 --- a/docs/toolhive/guides-cli/client-configuration.md +++ b/docs/toolhive/guides-cli/client-configuration.mdx @@ -2,26 +2,11 @@ title: Client configuration description: How to configure AI agent clients to work with ToolHive MCP servers. -sidebar_position: 40 --- -ToolHive automatically configures supported AI clients to work with MCP servers. -This guide shows you how to set up and manage client configurations. +import ClientIntro from '../_partials/_client-config-intro.mdx'; -## Understanding client configuration - -Before an AI application can use ToolHive MCP servers, it needs to know where to -find them. You can configure clients in two ways: - -1. **Register a supported client**: Register your client with ToolHive so it - automatically manages and updates the client's configuration as you start, - stop, and remove MCP servers. -2. **Manual configuration**: For clients that ToolHive doesn't directly support, - manually configure them to connect to ToolHive-managed MCP servers using the - SSE or Streamable HTTP protocol. - -For a complete list of supported clients and compatibility details, see the -[Client compatibility reference](../reference/client-compatibility.mdx). + ## Register clients @@ -156,7 +141,7 @@ ToolHive provides. - [`thv client` command reference](../reference/cli/thv_client.md) - [`thv config` command reference](../reference/cli/thv_config.md) - [Client compatibility](../reference/client-compatibility.mdx) -- [Run MCP servers](run-mcp-servers.mdx) +- [Run MCP servers](./run-mcp-servers.mdx) ## Troubleshooting @@ -265,9 +250,14 @@ Python-based MCP servers using the Streamable HTTP transport protocol: [error] Server exited before responding to `initialize` request. ``` -This is a known interaction between VS Code and the FastMCP SDK used by -Python-based MCP servers. If you inspect the HTTP connection, you'll see a -`307 Temporary Redirect` response, which VS Code doesn't handle correctly. +This is a known interaction between VS Code and certain versions of the FastMCP +SDK used by Python-based MCP servers. If you inspect the HTTP connection, you'll +see a `307 Temporary Redirect` response, which VS Code doesn't handle correctly. + +This +[issue is resolved](https://github.com/modelcontextprotocol/python-sdk/pull/781) +in the latest versions of the SDK, but if you're using an older version of a +Python-based MCP server, you might still encounter it. There are two workarounds: @@ -278,7 +268,4 @@ There are two workarounds: 2. If the MCP server supports SSE, switch to using the SSE transport instead of Streamable HTTP. -You can track a proposed fix for this issue in the -[MCP Python SDK repository](https://github.com/modelcontextprotocol/python-sdk/pull/781). - diff --git a/docs/toolhive/guides-cli/custom-permissions.mdx b/docs/toolhive/guides-cli/custom-permissions.mdx index 4204f8a6..a8cce446 100644 --- a/docs/toolhive/guides-cli/custom-permissions.mdx +++ b/docs/toolhive/guides-cli/custom-permissions.mdx @@ -3,7 +3,6 @@ title: Custom permissions description: How to create and apply filesystem permissions and network isolation for MCP servers using permission profiles in ToolHive. -sidebar_position: 50 --- import Tabs from '@theme/Tabs'; @@ -341,7 +340,7 @@ When creating and using permission profiles: ## Related information - [`thv run` command reference](../reference/cli/thv_run.md) -- [Run MCP servers](run-mcp-servers.mdx) +- [Run MCP servers](./run-mcp-servers.mdx) ## Troubleshooting diff --git a/docs/toolhive/guides-cli/index.mdx b/docs/toolhive/guides-cli/index.mdx new file mode 100644 index 00000000..e8d52f2a --- /dev/null +++ b/docs/toolhive/guides-cli/index.mdx @@ -0,0 +1,31 @@ +--- +title: Using the ToolHive CLI +description: + How-to guides for using the ToolHive command-line interface to run and manage + MCP servers. +--- + +import DocCardList from '@theme/DocCardList'; + +## Introduction + +The ToolHive CLI (`thv`) is a command-line tool that allows you to deploy and +manage MCP servers on your local machines or in development environments. It +provides quick deployment of MCP servers and supports advanced features like +custom permissions, network access filtering, and telemetry. + +It's designed for developers who prefer working in a terminal or need to +integrate MCP server management into scripts or automation workflows. + +:::tip Did you know? + +The ToolHive CLI can be used alongside the +[ToolHive UI](../guides-ui/index.mdx), which provides a graphical interface. You +can use both tools together to get the best of both worlds: the ease of use of a +graphical interface and the flexibility of the CLI. + +::: + +## Contents + + diff --git a/docs/toolhive/guides-cli/install.mdx b/docs/toolhive/guides-cli/install.mdx index 1ad80475..d60777bb 100644 --- a/docs/toolhive/guides-cli/install.mdx +++ b/docs/toolhive/guides-cli/install.mdx @@ -1,7 +1,6 @@ --- title: Install ToolHive -description: A guide to installing, upgrading, and managing ToolHive. -sidebar_position: 10 +description: How to install, upgrade, and manage the ToolHive CLI. --- import Tabs from '@theme/Tabs'; @@ -10,6 +9,9 @@ import TabItem from '@theme/TabItem'; This guide walks you through installing, upgrading, and managing the ToolHive CLI ([`thv`](../reference/cli/thv.md)). +![Latest version](https://img.shields.io/github/v/release/stacklok/toolhive?style=for-the-badge&label=Latest%20version&color=097aff) +![Release date](https://img.shields.io/github/release-date/stacklok/toolhive?display_date=published_at&style=for-the-badge&label=Released&color=097aff) + ## Prerequisites Before installing ToolHive, make sure your system meets these requirements: @@ -21,7 +23,7 @@ Before installing ToolHive, make sure your system meets these requirements: - Rancher Desktop with the dockerd/moby runtime (experimental) ToolHive requires minimal CPU, memory, and disk space. The exact requirements -depend on how many MCP servers you run and what resources they use. +depend on how many MCP servers you run and the resources they use. ## Install ToolHive @@ -132,9 +134,9 @@ thv version You should see output showing the version number, build date, and Git commit: ```text title="ToolHive version output" -ToolHive v0.0.33 -Commit: e8efa1b1d7b0776a39339257d30bf6c4a171f2b8 -Built: 2025-05-12 14:31:06 UTC +ToolHive v0.1.1 +Commit: 18956ca1710e11c9952d13a8dde039d5d1d147d6 +Built: 2025-06-30 13:59:34 UTC Go version: go1.24.1 Platform: darwin/arm64 ``` @@ -315,13 +317,14 @@ To uninstall ToolHive: Now that you have ToolHive installed, you can start using it to run and manage MCP servers. See [Explore the registry](./registry.md) and -[Run MCP servers](run-mcp-servers.mdx) to get started. +[Run MCP servers](./run-mcp-servers.mdx) to get started. ## Related information -- Quickstart: [Getting started with ToolHive](../tutorials/quickstart.mdx) +- Quickstart: + [Getting started with the ToolHive CLI](../tutorials/quickstart-cli.mdx) - [`thv` CLI reference](../reference/cli/thv.md) -- [Client configuration](./client-configuration.md) +- [Client configuration](./client-configuration.mdx) - [Secrets management](./secrets-management.mdx) ## Troubleshooting diff --git a/docs/toolhive/guides-cli/manage-mcp-servers.md b/docs/toolhive/guides-cli/manage-mcp-servers.md index efe96362..a77d9fc3 100644 --- a/docs/toolhive/guides-cli/manage-mcp-servers.md +++ b/docs/toolhive/guides-cli/manage-mcp-servers.md @@ -2,7 +2,6 @@ title: Monitor and manage MCP servers description: How to monitor and manage the lifecycle of MCP servers using ToolHive. -sidebar_position: 25 --- ## Monitoring diff --git a/docs/toolhive/guides-cli/registry.md b/docs/toolhive/guides-cli/registry.md index 7511de78..f9bb7491 100644 --- a/docs/toolhive/guides-cli/registry.md +++ b/docs/toolhive/guides-cli/registry.md @@ -1,7 +1,6 @@ --- title: Explore the registry -description: Using the built-in registry to find MCP servers. -sidebar_position: 15 +description: How to use the built-in registry to find MCP servers. --- ToolHive includes a built-in registry of MCPs with verified configurations, diff --git a/docs/toolhive/guides-cli/run-mcp-servers.mdx b/docs/toolhive/guides-cli/run-mcp-servers.mdx index e23982b9..c54b8ded 100644 --- a/docs/toolhive/guides-cli/run-mcp-servers.mdx +++ b/docs/toolhive/guides-cli/run-mcp-servers.mdx @@ -1,7 +1,6 @@ --- title: Run MCP servers description: How to run MCP servers with the ToolHive CLI. -sidebar_position: 20 --- import Tabs from '@theme/Tabs'; @@ -94,8 +93,8 @@ For example: thv run --secret github,target=GITHUB_PERSONAL_ACCESS_TOKEN github ``` -See [Secrets management](secrets-management.mdx) to learn how to manage secrets -in ToolHive. +See [Secrets management](./secrets-management.mdx) to learn how to manage +secrets in ToolHive. ### Mount a local directory @@ -384,9 +383,9 @@ control your servers. ## Related information - [`thv run` command reference](../reference/cli/thv_run.md) -- [Client configuration](client-configuration.md) -- [Secrets management](secrets-management.mdx) -- [Custom permissions](custom-permissions.mdx) +- [Client configuration](./client-configuration.mdx) +- [Secrets management](./secrets-management.mdx) +- [Custom permissions](./custom-permissions.mdx) ## Troubleshooting @@ -416,7 +415,7 @@ If a server starts but isn't accessible: 2. Verify the port isn't blocked by a firewall 3. Make sure clients are properly configured (see - [Client configuration](client-configuration.md)) + [Client configuration](./client-configuration.mdx)) diff --git a/docs/toolhive/guides-cli/secrets-management.mdx b/docs/toolhive/guides-cli/secrets-management.mdx index 34980b0e..2ce960e0 100644 --- a/docs/toolhive/guides-cli/secrets-management.mdx +++ b/docs/toolhive/guides-cli/secrets-management.mdx @@ -2,7 +2,6 @@ title: Secrets management description: How to securely manage API tokens and other sensitive data in ToolHive. -sidebar_position: 30 --- import Tabs from '@theme/Tabs'; diff --git a/docs/toolhive/guides-k8s/_category_.yaml b/docs/toolhive/guides-k8s/_category_.yaml deleted file mode 100644 index af75b133..00000000 --- a/docs/toolhive/guides-k8s/_category_.yaml +++ /dev/null @@ -1,5 +0,0 @@ -label: 'Kubernetes deployment' -position: 30 -link: - type: generated-index - slug: '/toolhive/guides-k8s' diff --git a/docs/toolhive/guides-k8s/deploy-operator-helm.md b/docs/toolhive/guides-k8s/deploy-operator-helm.md index 61e8a366..e7258e93 100644 --- a/docs/toolhive/guides-k8s/deploy-operator-helm.md +++ b/docs/toolhive/guides-k8s/deploy-operator-helm.md @@ -2,7 +2,6 @@ title: Deploy the operator description: How to deploy the ToolHive operator in a Kubernetes cluster using Helm -sidebar_position: 10 --- Helm is the officially supported method to install the ToolHive operator in a @@ -19,6 +18,8 @@ Kubernetes cluster. ## Install the CRDs +![Latest CRD Helm chart release](https://img.shields.io/github/v/release/stacklok/toolhive?filter=toolhive-operator-crds-*&style=for-the-badge&logo=helm&label=Latest%20CRD%20chart&color=097aff) + The ToolHive operator requires Custom Resource Definitions (CRDs) to manage MCPServer resources. The CRDs define the structure and behavior of MCPServers in your cluster. @@ -27,8 +28,18 @@ your cluster. helm upgrade -i toolhive-operator-crds oci://ghcr.io/stacklok/toolhive/toolhive-operator-crds ``` +This command installs the latest version of the ToolHive operator CRDs Helm +chart. To install a specific version, append `--version ` to the +command, for example: + +```bash +helm upgrade -i toolhive-operator-crds oci://ghcr.io/stacklok/toolhive/toolhive-operator-crds --version 0.0.7 +``` + ## Install the operator +![Latest Operator Helm chart release](https://img.shields.io/github/v/release/stacklok/toolhive?filter=toolhive-operator-0*&style=for-the-badge&logo=helm&label=Latest%20Operator%20chart&color=097aff) + To install the ToolHive operator using default settings, run the following command: @@ -36,6 +47,14 @@ command: helm upgrade -i toolhive-operator oci://ghcr.io/stacklok/toolhive/toolhive-operator -n toolhive-system --create-namespace ``` +This command installs the latest version of the ToolHive operator CRDs Helm +chart. To install a specific version, append `--version ` to the +command, for example: + +```bash +helm upgrade -i toolhive-operator oci://ghcr.io/stacklok/toolhive/toolhive-operator -n toolhive-system --create-namespace --version 0.1.1 +``` + Verify the installation: ```bash @@ -241,8 +260,8 @@ configured during installation. - [Kubernetes introduction](./intro.md) - Overview of ToolHive's Kubernetes integration -- [ToolHive operator tutorial](../tutorials/toolhive-operator.mdx) - - Step-by-step tutorial for getting started using a local kind cluster +- [ToolHive operator tutorial](../tutorials/quickstart-k8s.mdx) - Step-by-step + tutorial for getting started using a local kind cluster ## Troubleshooting diff --git a/docs/toolhive/guides-k8s/index.mdx b/docs/toolhive/guides-k8s/index.mdx new file mode 100644 index 00000000..c57d81bf --- /dev/null +++ b/docs/toolhive/guides-k8s/index.mdx @@ -0,0 +1,29 @@ +--- +title: Using the ToolHive Kubernetes Operator +description: + How-to guides for using the ToolHive Kubernetes operator to run and manage MCP + servers. +--- + +import DocCardList from '@theme/DocCardList'; + +## Introduction + +The ToolHive Kubernetes operator manages MCP servers in Kubernetes clusters. It +provides a way to deploy, manage, and scale MCP servers in multi-user +environments. By defining MCP servers as Kubernetes resources, the operator +automates their deployment and management, making it easier to run MCP servers +in multi-user environments. + +:::info + +Experimental The Kubernetes operator is still under active development and isn't +recommended for production use cases yet. Specifically, the `MCPServer` Custom +Resource Definition (CRD) is still in an alpha state so breaking changes to the +spec and its capabilities are possible. + +::: + +## Contents + + diff --git a/docs/toolhive/guides-k8s/intro.md b/docs/toolhive/guides-k8s/intro.md index e4253e4b..e036dbfa 100644 --- a/docs/toolhive/guides-k8s/intro.md +++ b/docs/toolhive/guides-k8s/intro.md @@ -1,8 +1,7 @@ --- -title: ToolHive Kubernetes operator -description: Manage MCP servers in Kubernetes with the ToolHive operator -sidebar_position: 1 -sidebar_label: Introduction +title: Overview of the ToolHive Kubernetes Operator +description: How to manage MCP servers in Kubernetes with the ToolHive operator +sidebar_label: Overview --- The ToolHive Kubernetes operator manages MCP servers in Kubernetes clusters. It @@ -12,11 +11,13 @@ deployment and management. :::info Experimental The Kubernetes operator is still under active development and isn't recommended -for production use cases yet. We'd love for you to try it out and send feedback. +for production use cases yet. Specifically, the `MCPServer` Custom Resource +Definition (CRD) is still in an alpha state so breaking changes to the spec and +its capabilities are possible. -See the -[ToolHive Operator quickstart tutorial](../tutorials/toolhive-operator.mdx) to -get started quickly using a local kind cluster. +See the [ToolHive Operator quickstart tutorial](../tutorials/quickstart-k8s.mdx) +to get started quickly using a local kind cluster. We'd love for you to try +itout and send feedback! ::: diff --git a/docs/toolhive/guides-k8s/run-mcp-k8s.md b/docs/toolhive/guides-k8s/run-mcp-k8s.md index 61d87c22..8316f87a 100644 --- a/docs/toolhive/guides-k8s/run-mcp-k8s.md +++ b/docs/toolhive/guides-k8s/run-mcp-k8s.md @@ -1,7 +1,6 @@ --- title: Run MCP servers in Kubernetes description: How to deploy MCP servers in Kubernetes using the ToolHive operator -sidebar_position: 20 --- ## Prerequisites diff --git a/docs/toolhive/guides-ui/client-configuration.mdx b/docs/toolhive/guides-ui/client-configuration.mdx new file mode 100644 index 00000000..5c283eb4 --- /dev/null +++ b/docs/toolhive/guides-ui/client-configuration.mdx @@ -0,0 +1,65 @@ +--- +title: Client configuration +description: How to connect ToolHive to AI clients using the UI. +--- + +import ClientIntro from '../_partials/_client-config-intro.mdx'; + + + +## Manage client connections + +ToolHive automatically discovers supported AI clients that are installed on your +system. These are displayed on the **Clients** page. This discovery is dynamic: +if you install a new client, ToolHive automatically updates the list. + +### Connect a client + +To connect a client to ToolHive, toggle the switch under the client's name. + +When you connect a client, ToolHive automatically configures it to use your +currently running MCP servers. Any new servers you start are also added. + +When you stop or remove an MCP server, ToolHive updates the client's +configuration to remove the server. + +### Disconnect a client + +When you disconnect a client, ToolHive removes all MCP server configurations +from the client. The client will no longer be able to use any ToolHive-managed +MCP servers. + +## Why don't I see my client? + +If you don't see your client listed, ToolHive might not support it, or its +configuration file might not be in a location ToolHive recognizes. + +For a list of supported clients and how ToolHive detects them, see the +[client compatibility reference](../reference/client-compatibility.mdx). + +## Why do I still see a client I uninstalled? + +Many clients leave behind configuration files even after you uninstall them. +ToolHive detects these files and continues to show the client in the UI. If you +want to remove the client from ToolHive, delete its configuration files +manually. + +## Manual client configuration + +For clients that ToolHive doesn't support directly, you can still configure them +to connect to ToolHive-managed MCP servers using the SSE (Server-Sent Events) or +Streamable HTTP protocol. + +To do this, you need the URL of the MCP server you want to connect to. You can +get this URL from the **MCP Servers** page in ToolHive. Click the menu (︙) on +the MCP server card to copy the URL. + +You can then configure your client to use this URL. The exact steps depend on +your client or library, so refer to its documentation for details. See the +[client configuration reference](../reference/client-compatibility.mdx#manual-configuration) +for some common examples. + +## Related information + +- [Client compatibility](../reference/client-compatibility.mdx) +- [Run MCP servers](./run-mcp-servers.md) diff --git a/docs/toolhive/guides-ui/index.mdx b/docs/toolhive/guides-ui/index.mdx new file mode 100644 index 00000000..bc00b943 --- /dev/null +++ b/docs/toolhive/guides-ui/index.mdx @@ -0,0 +1,48 @@ +--- +title: Using ToolHive +description: + How-to guides for using the ToolHive UI to run and manage MCP servers. +--- + +import DocCardList from '@theme/DocCardList'; + +import useBaseUrl from '@docusaurus/useBaseUrl'; +import ThemedImage from '@theme/ThemedImage'; + +## Introduction + +The ToolHive UI is a desktop application that makes it easy to run and manage +Model Context Protocol (MCP) servers on your local machine. It provides a +user-friendly interface to discover, deploy, and manage MCP servers with +security and ease of use built in. + +It's designed for anyone who wants to run MCP servers without needing to +understand the complexities of Docker or command-line tools. Whether you're a +developer, researcher, or just curious about MCP servers, ToolHive provides a +simple way to get started. + + +
+ +We strive to make ToolHive intuitive and easy to use. If we've missed the mark +on something, [let us know](https://discord.gg/stacklok)! + +:::tip Advanced users + +If you want more control or want to experiment with more advanced features like +custom permissions and telemetry, the ToolHive UI can work side-by-side with the +[ToolHive CLI](../guides-cli/index.mdx) while still providing a graphical +interface to quickly see and control your MCP servers. + +::: + +## Contents + + diff --git a/docs/toolhive/guides-ui/install.mdx b/docs/toolhive/guides-ui/install.mdx new file mode 100644 index 00000000..414b1b86 --- /dev/null +++ b/docs/toolhive/guides-ui/install.mdx @@ -0,0 +1,234 @@ +--- +title: Install ToolHive +description: How to install the ToolHive UI application. +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +This guide walks you through installing, upgrading, and managing the ToolHive +desktop application. + +![Latest version](https://img.shields.io/github/v/release/stacklok/toolhive-studio?style=for-the-badge&label=Latest%20version&color=097aff) +![Release date](https://img.shields.io/github/release-date/stacklok/toolhive-studio?display_date=published_at&style=for-the-badge&label=Released&color=097aff) + +## Prerequisites + +Before installing ToolHive, make sure your system meets these requirements: + +- **Operating systems**: + - macOS (Apple silicon or Intel) + - Windows 10/11 (x64) + - Linux (x86_64/amd64) +- **Container runtime**: + - Docker / Docker Desktop + - Podman / Podman Desktop + - Rancher Desktop with the dockerd/moby runtime (experimental) + +ToolHive requires minimal CPU, memory, and disk space. The exact requirements +depend on how many MCP servers you run and the resources they use. + +## Install ToolHive + +Select your operating system to see the installation instructions. + + + + +Download the latest ToolHive installer for +[Apple silicon](https://github.com/stacklok/toolhive-studio/releases/latest/download/ToolHive-arm64.dmg) +or +[Intel-based](https://github.com/stacklok/toolhive-studio/releases/latest/download/ToolHive-arm64.dmg) +Macs and open the DMG file. + +Copy the ToolHive app to your Applications folder. You can then open it from +your Applications folder, Launchpad, or using Spotlight search. + + + + +Download the latest +[ToolHive installer](https://github.com/stacklok/toolhive-studio/releases/latest/download/ToolHive.Setup.exe) +and run the setup executable. + +:::note + +The Windows installer is not digitally signed yet, so you will need to accept +the warning from Windows Defender SmartScreen. We're working on getting a signed +installer published soon. + +::: + +After installation, you can find ToolHive in your Start menu or on your desktop. + +:::important + +The first time you run ToolHive, you may be prompted to allow firewall access. +If you don't allow this, ToolHive won't be able to run MCP servers. + +::: + + + + +1. Download the appropriate RPM or DEB package for your distribution from the + [ToolHive UI releases page](https://github.com/stacklok/toolhive-studio/releases/latest) + +2. Use your package manager to install the downloaded package: + - For RPM-based distributions (like Fedora or Red Hat Enterprise Linux): + + ```bash + sudo rpm -i ToolHive--1.x86_64.rpm + ``` + + - For DEB-based distributions (like Ubuntu or Debian): + + ```bash + sudo dpkg -i toolhive__amd64.deb + ``` + +For other Linux distributions, download the +[binary tarball](https://github.com/stacklok/toolhive-studio/releases/latest/download/toolhive-studio-linux-x64.tar.gz) +and extract it, then run the `ToolHive` binary directly. + + + + +## System tray icon + +When you close the ToolHive application window, it stays running in the +background so your MCP servers remain available. ToolHive installs a system tray +icon for quick access. You can use it to: + +- Enable or disable **Start on login** +- Show or hide the ToolHive application window +- Quit ToolHive, which stops all running MCP servers + +## Run ToolHive on login + +You can configure ToolHive to start automatically when you log in to your +system. This is useful if you want your MCP servers to be available without +manually starting ToolHive each time. + +To enable this feature, turn on the **Start on login** option in the system tray +icon menu or in the settings menu (⚙️) in the application. + +## Upgrade ToolHive + +ToolHive automatically checks for updates. When a new version is available, +you'll see a notification in the application. During the upgrade, ToolHive stops +all running MCP servers, updates the application, and then restarts itself and +the MCP servers. + +You can also manually install updates by downloading the latest installer for +your operating system from the +[ToolHive UI releases page](https://github.com/stacklok/toolhive-studio/releases/latest) +and running it. The installer will upgrade your existing ToolHive installation +to the latest version. See the [Install ToolHive](#install-toolhive) section for +direct download links. + +## File locations + +ToolHive stores its configuration and data files in several locations depending +on your operating system: + + + + +- The `~/Library/Application Support/ToolHive` directory contains: + - Configuration files and application data for the ToolHive UI + - MCP server logs and configurations (`logs/` and `runconfigs/` directories) + - Your encrypted secrets store (`secrets_encrypted` file) + - ToolHive CLI/API configuration file (`config.yaml`) +- The main UI application log is located at `~/Library/Logs/ToolHive/main.log` + +Since macOS is not case sensitive, the `~/Library/Application Support/ToolHive` +directory is shared by the UI and CLI if you have both installed. + + + + +- The `%LOCALAPPDATA%\ToolHive` directory contains: + - Application executables and installation logs + - MCP server logs and configurations (`logs/` and `runconfigs/` directories) + - Your encrypted secrets store (`secrets_encrypted` file) + - ToolHive CLI/API configuration file (`config.yaml`) +- The `%APPDATA%\ToolHive` directory contains: + - Configuration files and application data for the ToolHive UI +- The main UI application log is located at `%APPDATA%\ToolHive\logs\main.log` + +Since Windows is not case sensitive, the `%LOCALAPPDATA%\ToolHive` directory is +shared by the UI and CLI if you have both installed. + + + + +- The `~/.config/ToolHive` directory contains: + - Configuration files and application data for the ToolHive UI +- The `~/.config/toolhive` directory contains (note the case sensitivity): + - MCP server logs and configurations (`logs/` and `runconfigs/` directories) + - Your encrypted secrets store (`secrets_encrypted` file) + - ToolHive CLI/API configuration file (`config.yaml`) +- The main UI application log is located at `~/.config/ToolHive/logs/main.log` + +Since Linux is case sensitive, the `~/.config/ToolHive` and `~/.config/toolhive` +directories are separate. However, the ToolHive UI and CLI share the same +configuration file and secrets store to support coexistence. + + + + +## Telemetry and error reporting + +ToolHive uses [Sentry](https://sentry.io/welcome/) for error tracking and +performance monitoring to help us identify and fix issues, improve stability, +and enhance the user experience. This telemetry is enabled by default. You can +disable this by turning off the **Error reporting** option in the settings menu +(⚙️) if you prefer not to share this data. + +ToolHive collects the following information: + +- Error reports and crash logs +- Performance metrics +- Usage patterns + +This data is anonymized and does not include any personally identifiable +information. It helps us understand how ToolHive is used and identify areas for +improvement. Review the +[Stacklok privacy policy](https://www.iubenda.com/privacy-policy/29074746) and +[Terms of Service](https://stacklok.com/terms-of-service) for more details. + +## Next steps + +Now that you have ToolHive installed, you can start using it to run and manage +MCP servers. See [Run MCP servers](./run-mcp-servers.md) to get started. + +## Related information + +- Quickstart: + [Getting started with the ToolHive UI](../tutorials/quickstart-ui.mdx) +- [Client configuration](./client-configuration.mdx) +- [Secrets management](./secrets-management.md) + +## Troubleshooting + +
+Connection Refused error on startup + +If you see a "Connection Refused" error when starting ToolHive, it's likely +because your container runtime (Docker or Podman) is not installed, not running, +or not configured correctly. + +Follow the instructions on the error message to install or start your container +runtime. For example, if you're using Docker Desktop, make sure it is running +and that the Docker daemon is active. + +If the retry button doesn't work, try restarting ToolHive. + +
+ +### Other issues + +For other installation issues, check the +[GitHub issues page](https://github.com/stacklok/toolhive-studio/issues) or join +the [Discord community](https://discord.gg/stacklok). diff --git a/docs/toolhive/guides-ui/network-isolation.mdx b/docs/toolhive/guides-ui/network-isolation.mdx new file mode 100644 index 00000000..93563153 --- /dev/null +++ b/docs/toolhive/guides-ui/network-isolation.mdx @@ -0,0 +1,84 @@ +--- +title: Network isolation +description: How to configure network isolation for MCP servers in ToolHive. +--- + +import useBaseUrl from '@docusaurus/useBaseUrl'; +import ThemedImage from '@theme/ThemedImage'; + +Most MCP servers require network access to function properly—for example, to +access APIs, download data, or communicate with other services. However, +malicious or misconfigured servers can also exfiltrate sensitive data or +download unwanted content. + +When you install an MCP server in ToolHive, you can optionally enable _network +isolation_. This feature restricts the MCP server's network access to only the +resources you specify. + +:::note + +Network isolation currently supports HTTP and HTTPS connections only. Other +protocols are not supported. + +::: + +## Enabling network isolation + +Currently, network isolation is available for MCP servers installed from the +ToolHive registry. + +During the MCP server installation, select the **Network isolation** tab in the +configuration form. Click the toggle to enable it. + +When you enable network isolation, any safe default configuration defined in the +registry is pre-loaded in the form. You can accept these defaults or customize +the settings to specify which hosts and ports the MCP server is allowed to +access: + +- **Allowed hosts**:\ + A list of hostnames or IP addresses that the MCP server is allowed to access. + This can include APIs, data sources, or other services that the MCP server + needs to function properly. + + :::tip + + To allow access to all subdomains under a specific domain, add a leading + period (`.`) in front of the hostname. For example, to allow access to all + subdomains of `github.com`, enter `.github.com` in the allowed hosts list. + + ::: + +- **Allowed ports**:\ + A list of ports that the MCP server is allowed to use for outgoing + connections. This can help prevent the MCP server from accessing unauthorized + services or resources. For example, port 443 is the default port for HTTPS + connections. + +:::important + +If you do not specify any allowed hosts or ports, the MCP server will not be +able to access any external resources, including the internet. This can be +useful for MCP servers that do not require network access or for testing +purposes. + +::: + +## Example configuration + +The configuration pictured below allows the MCP server to access +`api.github.com` and all subdomains of `githubusercontent.com` on port 443 +(HTTPS): + + +
+ +## Related information + +- [Run MCP servers](./run-mcp-servers.md) diff --git a/docs/toolhive/guides-ui/run-mcp-servers.md b/docs/toolhive/guides-ui/run-mcp-servers.md new file mode 100644 index 00000000..7ec6dce5 --- /dev/null +++ b/docs/toolhive/guides-ui/run-mcp-servers.md @@ -0,0 +1,228 @@ +--- +title: Run MCP servers +description: How to install and run MCP servers in the ToolHive UI. +--- + +ToolHive makes it easy to run and manage Model Context Protocol (MCP) servers. +This guide walks you through installing MCP servers from the registry, using +Docker images, or from source packages. + +## Install from the registry + +ToolHive includes a built-in registry of MCP servers that meet a +[minimum quality standard](../concepts/registry-criteria.md), allowing you to +discover and deploy high-quality tools effortlessly. Simply select one from the +list to run it securely with just a few clicks. + +### Select an MCP server + +To install an MCP server from the registry: + +1. Open the **Registry** page from the menu bar. +2. Browse or search for the MCP server you want to install. +3. Click on the desired MCP server to open its details page. Here you can review + more information about the server like its: + - Description + - Available tools + - Tier (community or official) + - Popularity (GitHub stars) + - A link to the GitHub repository for more details and usage documentation +4. Click the **Install server** button to start the installation process. + +### Configure the server + +On the configuration form, enter the following details: + +1. **Server name**: A unique name for the MCP server.\ + This defaults to the MCP server's name in the registry. If you want to run + multiple instances of the same MCP server, give each instance a unique name. + +2. **Command arguments** (optional):\ + Enter any command-line arguments needed to run the MCP server. These might be + needed to pass application-specific parameters to the MCP server. Refer to + the MCP server's documentation for details. + + :::info + + We've made every effort to include sensible defaults in the registry for a + one-click experience, but some servers may require additional command-line + arguments to function correctly. + + ::: + +3. **Secrets** and **environment variables** expected by the server are + populated from the registry automatically. Required values are marked with an + asterisk (\*). + 1. **Secrets**: Enter a value to create a new secret or select an existing + secret to map to the environment variable. Secrets are stored securely and + can be used by the MCP server without exposing them in plaintext. + 2. **Environment variables**: Enter the value in the input field alongside + the variable name. These are typically used for configuration options that + do not require sensitive data. + +:::note + +Refer to the MCP server's documentation for the required configuration +information, required permissions, and authentication details. A link to the +GitHub repository is provided on each server's details page. + +::: + +### Network isolation + +You can optionally enable network isolation for the MCP server. This allows you +to control the MCP server's network access, restricting it to only the necessary +resources and preventing it from accessing the internet or other external +networks. + +See the [Network isolation](./network-isolation.mdx) guide for details on how to +configure network isolation for MCP servers in ToolHive. + +### Start the MCP server + +Click **Install server** to install and start the MCP server. ToolHive downloads +the Docker image, creates a container, and starts it with the specified +configuration. + +Once the server is running, you can see its status on the **MCP Servers** page. +Each server's card includes: + +- The server name +- Its status (Running or Stopped) with a toggle button to start or stop it +- A menu (︙) that includes the server's URL for AI clients that need manual + configuration, and options to: + - Open the server's GitHub repository + - View the server's logs + - Remove the server + +See [Manage MCP servers](#manage-mcp-servers) below for more details on server +states. + +## Install a custom MCP server + +You're not limited to the MCP servers in the registry. You can also run your own +custom MCP servers using Docker images or source packages. + +On the **MCP Servers** page, click **Add server**, then choose **Custom MCP +server** in the drop-down menu. Or if this is your first MCP server, click **Add +custom server** on the introductory screen. + +In the **Custom MCP server** dialog, choose [Docker image](#from-a-docker-image) +or [Package manager](#from-a-source-package). + +### From a Docker image + +Select the **Docker image** option. This allows you to run any MCP server that +is available as a Docker image in a remote registry or locally on your system. + +On the configuration form, enter: + +1. A unique **name** for the MCP server. [Required] + +2. The **transport protocol** that the MCP server uses. [Required]\ + ToolHive supports standard input/output (`stdio`), server-sent events (SSE), + and Streamable HTTP. The protocol must match what the MCP server supports. + +3. The **target port** to expose from the container (SSE or Streamable HTTP + transports only). [Optional]\ + If the MCP server uses a specific port, enter it here. If not specified, + ToolHive will use a random port that is exposed to the container with the + `MCP_PORT` and `FASTMCP_PORT` environment variables. + +4. The Docker **image name** and tag (e.g., `my-mcp-server:latest`). [Required]\ + You can use any valid Docker image, including those hosted on Docker Hub or + other registries. + +5. **Command-line arguments** needed to run the MCP server. [Optional]\ + These are specific to the MCP server and might include transport options or + application-specific parameters. Refer to the MCP server's documentation for + details. + +6. Any **secrets** or **environment variables** required by the MCP server. + [Optional]\ + These might include API tokens, configuration options, or other sensitive + data. + - Secrets are mapped to an environment variable. Enter the variable name and + select an existing secret or enter a value to create a new one. + - For non-sensitive environment variables, enter the name and value directly. + +Click **Install server** to create and start the MCP server container. + +### From a source package + +Select the **Package manager** option. This allows you to run an MCP server from +a source package. + +ToolHive downloads the MCP server's source package and builds a Docker image +on-the-fly. The following package formats are supported: + +- Node.js-based MCP servers using npm +- Python-based MCP servers available on PyPI, using the `uv` package manager +- Go-based MCP servers available on GitHub + +On the configuration form, enter: + +1. A unique **name** for the MCP server. [Required] + +2. The **transport protocol** that the MCP server uses. [Required]\ + ToolHive supports standard input/output (`stdio`), server-sent events (SSE), + and Streamable HTTP. The protocol must match what the MCP server supports. + +3. The **target port** to expose from the container (SSE or Streamable HTTP + transports only). [Optional]\ + If the MCP server uses a specific port, enter it here. If not specified, + ToolHive will use a random port that is exposed to the container with the + `MCP_PORT` and `FASTMCP_PORT` environment variables. + +4. The package **protocol** (`npx`, `uvx`, or `go`). [Required] + +5. The **name** of the package to run. [Required] + 1. For `npx`, use the [npm](https://www.npmjs.com/) package name and version, + e.g. `my-mcp-package@latest` + 2. For `uvx`, use the [PyPI](https://pypi.org/) package name and version, + e.g. `my-mcp-package@latest` + 3. For `go`, use the GitHub repository URL with full path to the `main` + package and version, e.g. + `go://github.com/orgname/my-mcp-server/cmd/server@latest` + +6. **Command-line arguments** needed to run the MCP server. [Optional]\ + These are specific to the MCP server and might include transport options or + application-specific parameters. Refer to the MCP server's documentation for + details. + +7. Any **secrets** or **environment variables** required by the MCP server. + [Optional]\ + These might include API tokens, configuration options, or other sensitive + data. + - Secrets are mapped to an environment variable. Enter the variable name and + select an existing secret or enter a value to create a new one. + - For non-sensitive environment variables, enter the name and value directly. + +Click **Install server** to create and start the MCP server container. + +## Manage MCP servers + +On the **MCP Servers** page, you can manage your installed MCP servers: + +- **Start/Stop**: Use the toggle button to start or stop the MCP server. When + you stop a server, it remains in the list but is no longer running. ToolHive + removes the server from connected AI clients while stopped. +- **Copy URL**: Click the menu (︙) on the server card and select the **Copy** + icon (⧉) to copy the MCP server's URL to your clipboard. This URL is used by + AI clients to connect to the MCP server. +- **View logs**: Click the menu (︙) on the server card and select **View logs** + to see the server's output. +- **Remove server**: Click the menu (︙) on the server card and select **Remove + server** to stop and remove the MCP server from ToolHive. This deletes the + container and any associated configuration, so use with caution. + +When you quit the application, ToolHive prompts you to stop all running MCP +servers. The running servers are recorded and ToolHive restarts them +automatically the next time you launch the application. + +## Next steps + +- Connect ToolHive to AI clients like GitHub Copilot or Cursor using the + [client configuration guide](./client-configuration.mdx). +- Learn more about [secrets management](./secrets-management.md) to securely + manage API tokens and other sensitive data. diff --git a/docs/toolhive/guides-ui/secrets-management.md b/docs/toolhive/guides-ui/secrets-management.md new file mode 100644 index 00000000..48625145 --- /dev/null +++ b/docs/toolhive/guides-ui/secrets-management.md @@ -0,0 +1,63 @@ +--- +title: Secrets management +description: + How to securely manage API tokens and other sensitive data in the ToolHive UI. +--- + +Many MCP servers need secrets like API tokens, connection strings, and other +sensitive parameters. ToolHive provides built-in secrets management so you can +manage these values securely without exposing them in plaintext configuration +files. + +ToolHive encrypts secrets using a randomly generated password that is stored in +your operating system's secure keyring. + +You can add new secrets on the **Secrets** page or during MCP server +installation. + +:::note + +The ToolHive UI does not currently support the 1Password secrets provider. If +you have configured the 1Password secrets provider using the ToolHive CLI, the +UI will automatically update your configuration to use the built-in encrypted +provider instead. + +::: + +## Enter secrets during MCP installation + +When you install an MCP server from the registry, any required secrets are +listed on the configuration form with their corresponding environment variable. + +When you add a custom MCP server, add secrets by entering the environment +variable name that the MCP server expects. + +To set the secret value, you can: + +- Select an existing secret to populate its value in the configuration form. +- Enter a value in the input box. ToolHive creates a new secret with a name + matching the environment variable. + +## Manage secrets + +Your ToolHive secrets are managed on the **Secrets** page. Here you can: + +- Click the **Add secret** button to create a new secret. Enter a friendly name + for the secret and its value. +- Expand the menu (︙) next to an existing secret to: + - Update the secret value + - Delete the secret + +:::important + +If you delete a secret that is in use by an MCP server, the server will continue +running but you will not be able to restart it if stopped. You'll need to remove +the server and reinstall it with the required secrets, or add the secret back +using the same name. + +::: + +## Related information + +- [Run MCP servers](./run-mcp-servers.md) +- [Client configuration](./client-configuration.mdx) diff --git a/docs/toolhive/index.mdx b/docs/toolhive/index.mdx index 98ea6228..f7ed58f5 100644 --- a/docs/toolhive/index.mdx +++ b/docs/toolhive/index.mdx @@ -2,7 +2,6 @@ title: Introduction hide_title: true description: ToolHive helps you run and manage MCP servers easily and securely. -sidebar_position: 1 --- import useBaseUrl from '@docusaurus/useBaseUrl'; @@ -19,11 +18,17 @@ import ThemedImage from '@theme/ThemedImage'; />
+--- + ToolHive mascot ## What is ToolHive? @@ -32,12 +37,28 @@ ToolHive simplifies the deployment and management of Model Context Protocol (MCP) servers. It ensures ease of use, consistency, and security by running containers in a locked-down environment with minimal permissions. -Follow the [getting started guide](./tutorials/quickstart.mdx) to install +Follow the [getting started guide](./tutorials/quickstart-ui.mdx) to install ToolHive and run your first MCP server. To learn more about the Model Context Protocol, see our [MCP primer](./concepts/mcp-primer.md). +ToolHive is available in three modes to suit different use cases: + +- [**ToolHive UI**](./guides-ui/index.mdx): A desktop application for individual + developers to run and manage MCP servers locally. It provides a user-friendly + interface to discover, deploy, and manage MCP servers. + +- [**ToolHive CLI**](./guides-cli/index.mdx): A command line interface to deploy + and manage MCP servers on your local machine or in development environments. + It allows quick deployment of MCP servers and supports advanced features like + custom permissions and telemetry. + +- [**ToolHive Kubernetes Operator**](./guides-k8s/index.mdx): A Kubernetes + operator for teams and enterprises to run and manage MCP servers in multi-user + environments. It provides centralized management, security controls, and + integration with existing infrastructure. + ## Why ToolHive? We want to help you get real value from MCP servers. While there are plenty of @@ -63,37 +84,29 @@ containers. The proxy communicates with MCP servers via standard input/output interacts with Docker or Podman via the Docker socket API, letting it manage containers and their configurations. -```mermaid -flowchart LR - subgraph container["**Docker/Podman**"] - direction LR - mcp1["MCP server
container"] - mcp2["MCP server
container"] - mcp3["MCP server
container"] - end - proxy1["SSE proxy"] -- stdio --> mcp1 - proxy2["SSE proxy"] -- SSE --> mcp2 - proxy3["HTTP proxy"] -- Streamable
HTTP --> mcp3 - T["ToolHive CLI"] -- Socket API --> container - C["Client"] -- HTTP/SSE --> proxy1 & proxy2 - C -- HTTP --> proxy3 - T ~~~ C -``` - -ToolHive is packaged as a [standalone CLI tool](./guides-cli/) for individual -developers and as a [Kubernetes operator](./guides-k8s/) for teams and -enterprises. The CLI provides a simple command line interface to deploy and -manage MCP servers, while the Kubernetes operator enables teams to run and -manage MCP servers centrally. + +
## Key features -ToolHive offers the following features to simplify MCP deployment: +ToolHive includes a range of features to help you run and manage MCP servers +effectively: -- **Streamlined deployment**: Deploy MCP servers instantly with a single command - using Docker containers or directly from package managers via protocol schemes - (`uvx://`, `npx://`, `go://`). Access a curated registry of verified MCP - servers that you can discover and run effortlessly. +- **Streamlined deployment**: Deploy MCP servers instantly using Docker + containers or directly from package managers via protocol schemes (`uvx://`, + `npx://`, `go://`). Access a curated registry of verified MCP servers that you + can discover and run effortlessly. + +- **Seamless integration**: Configure popular development tools automatically, + including GitHub Copilot and Cursor, to streamline your workflow with minimal + setup. - **Comprehensive security**: Run MCP servers in isolated containers with customizable, fine-grained permissions and network access filtering using JSON @@ -108,12 +121,27 @@ ToolHive offers the following features to simplify MCP deployment: - **Kubernetes deployment**: Deploy and manage MCP servers in Kubernetes clusters using the ToolHive operator. -- **Seamless integration**: Configure popular development tools automatically, - including GitHub Copilot and Cursor, to streamline your workflow with minimal - setup. - ## Additional resources -- [GitHub repository](https://github.com/stacklok/toolhive) -- [Issue tracker](https://github.com/stacklok/toolhive/issues) -- [Discord community](https://discord.gg/stacklok) +ToolHive mascot, a friendly marmot dressed as a bee + +Join the Stacklok [Discord community](https://discord.gg/stacklok) to connect +with other ToolHive users, ask questions, and share your experiences. + +Source code and issue tracking: + +- ToolHive UI + - [GitHub repository](https://github.com/stacklok/toolhive-studio) + - [Issue tracker](https://github.com/stacklok/toolhive-studio/issues) +- ToolHive CLI & K8s Operator + - [GitHub repository](https://github.com/stacklok/toolhive) + - [Issue tracker](https://github.com/stacklok/toolhive/issues) diff --git a/docs/toolhive/reference/_category_.yaml b/docs/toolhive/reference/_category_.yaml deleted file mode 100644 index 876e3363..00000000 --- a/docs/toolhive/reference/_category_.yaml +++ /dev/null @@ -1,3 +0,0 @@ -label: 'Reference' -description: 'Technical references for ToolHive' -position: 60 diff --git a/docs/toolhive/reference/api.mdx b/docs/toolhive/reference/api.mdx index 38631e3c..a06d6ee2 100644 --- a/docs/toolhive/reference/api.mdx +++ b/docs/toolhive/reference/api.mdx @@ -1,7 +1,6 @@ --- title: API reference description: Reference documentation for ToolHive's REST API -sidebar_position: 20 hide_table_of_contents: true --- diff --git a/docs/toolhive/reference/cli/_category_.yml b/docs/toolhive/reference/cli/_category_.yml deleted file mode 100644 index 0e0c892c..00000000 --- a/docs/toolhive/reference/cli/_category_.yml +++ /dev/null @@ -1,6 +0,0 @@ -label: 'CLI Reference' -description: 'ToolHive CLI reference' -position: 10 -link: - type: doc - id: thv diff --git a/docs/toolhive/reference/client-compatibility.mdx b/docs/toolhive/reference/client-compatibility.mdx index c66a457c..e3b716f5 100644 --- a/docs/toolhive/reference/client-compatibility.mdx +++ b/docs/toolhive/reference/client-compatibility.mdx @@ -2,7 +2,6 @@ title: Client compatibility description: Overview of supported AI clients and their compatibility with ToolHive. -sidebar_position: 5 --- import ClientTable from '../_partials/_client-compat-table.md'; @@ -33,9 +32,11 @@ To work with ToolHive, your client needs to: ## Automatic configuration support -ToolHive can -[automatically configure supported clients](../guides-cli/client-configuration.md) -to connect to MCP servers. +ToolHive can automatically configure supported clients to connect to MCP +servers. See the +[UI client configuration](../guides-ui/client-configuration.mdx) or +[CLI client configuration guide](../guides-cli/client-configuration.mdx) for +more details. Check the table above to see which clients support automatic configuration. @@ -259,5 +260,5 @@ Copilot for JetBrains supports SSE (`"type": "sse"`) and Streamable HTTP ## Related information -- [Client configuration](../guides-cli/client-configuration.md) +- [Client configuration](../guides-cli/client-configuration.mdx) - [Run MCP servers](../guides-cli/run-mcp-servers.mdx) diff --git a/docs/toolhive/reference/crd-spec.mdx b/docs/toolhive/reference/crd-spec.mdx index 82922d44..fbf2efe2 100644 --- a/docs/toolhive/reference/crd-spec.mdx +++ b/docs/toolhive/reference/crd-spec.mdx @@ -1,8 +1,8 @@ --- title: Kubernetes CRD reference +sidebar_label: CRD Reference description: ToolHive Kubernetes Operator Custom Resource Definitions (CRDs) reference. -sidebar_position: 30 toc_max_heading_level: 4 --- diff --git a/docs/toolhive/tutorials/_category_.yaml b/docs/toolhive/tutorials/_category_.yaml deleted file mode 100644 index 2f3974fe..00000000 --- a/docs/toolhive/tutorials/_category_.yaml +++ /dev/null @@ -1,3 +0,0 @@ -label: 'Tutorials' -position: 10 -collapsed: false diff --git a/docs/toolhive/tutorials/quickstart.mdx b/docs/toolhive/tutorials/quickstart-cli.mdx similarity index 94% rename from docs/toolhive/tutorials/quickstart.mdx rename to docs/toolhive/tutorials/quickstart-cli.mdx index 31be4a40..d009c086 100644 --- a/docs/toolhive/tutorials/quickstart.mdx +++ b/docs/toolhive/tutorials/quickstart-cli.mdx @@ -1,17 +1,17 @@ --- -title: Quickstart - run your first MCP server +title: 'Quickstart: ToolHive CLI' description: - A step-by-step guide to installing ToolHive and running your first MCP server. -sidebar_position: 10 -slug: /toolhive/quickstart + A step-by-step guide to installing the ToolHive CLI and running your first MCP + server. --- import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; -In this tutorial, you'll install ToolHive and run your first MCP server. By the -end, you'll have a working MCP server that can fetch content from websites and -be used by AI applications like GitHub Copilot or Cursor. +In this tutorial, you'll install the ToolHive command-line application and run +your first MCP server. By the end, you'll have a working MCP server that can +fetch content from websites and be used by AI applications like GitHub Copilot +or Cursor. ## What you'll learn @@ -85,9 +85,9 @@ thv version You should see output similar to this: ```text -ToolHive v0.0.38 -Commit: c321ba873f5dcb1d33035d4f8496eb3e22f8b37e -Built: 2025-05-29 12:03:02 UTC +ToolHive v0.1.1 +Commit: 18956ca1710e11c9952d13a8dde039d5d1d147d6 +Built: 2025-06-30 13:59:34 UTC Go version: go1.24.1 Platform: darwin/arm64 ``` @@ -242,7 +242,7 @@ application. Open your supported client (VS Code, Cursor, etc.) and ask the AI to fetch content from a website. Note that you might need to restart your client for the changes to take effect. -For example, try asking: "Can you fetch the content from https://stacklok.com +For example, try asking: "Can you fetch the content from https://toolhive.dev and summarize it for me?" The AI should be able to use the Fetch MCP server to retrieve the content and @@ -328,3 +328,6 @@ If your AI client application can't use the server: - Verify the server is running with [`thv list`](../reference/cli/thv_list.md) + +If you encounter any problems, please join our +[Discord community](https://discord.gg/stacklok) for help. diff --git a/docs/toolhive/tutorials/toolhive-operator.mdx b/docs/toolhive/tutorials/quickstart-k8s.mdx similarity index 99% rename from docs/toolhive/tutorials/toolhive-operator.mdx rename to docs/toolhive/tutorials/quickstart-k8s.mdx index 00a58b49..9fd3d3a7 100644 --- a/docs/toolhive/tutorials/toolhive-operator.mdx +++ b/docs/toolhive/tutorials/quickstart-k8s.mdx @@ -1,9 +1,8 @@ --- -title: Deploy and use the ToolHive Kubernetes operator +title: 'Quickstart: ToolHive Kubernetes Operator' description: Learn how to deploy the ToolHive Kubernetes operator and use it to manage MCP servers in a Kubernetes cluster. -sidebar_position: 20 --- import useBaseUrl from '@docusaurus/useBaseUrl'; diff --git a/docs/toolhive/tutorials/quickstart-ui.mdx b/docs/toolhive/tutorials/quickstart-ui.mdx new file mode 100644 index 00000000..b8c836b5 --- /dev/null +++ b/docs/toolhive/tutorials/quickstart-ui.mdx @@ -0,0 +1,168 @@ +--- +title: 'Quickstart: ToolHive UI' +description: + A step-by-step guide to installing the ToolHive desktop application and + running your first MCP server. +--- + +In this tutorial, you'll install the ToolHive desktop application and run your +first MCP server. By the end, you'll have a working MCP server that can fetch +content from websites and be used by AI applications like GitHub Copilot or +Cursor. + +## What you'll learn + +- How to install ToolHive on your system +- How to find available MCP servers +- How to run an MCP server +- How to use the server with an AI client application + +## Prerequisites + +Before starting this tutorial, make sure you have: + +- [Docker](https://docs.docker.com/get-docker/) or + [Podman](https://podman-desktop.io/downloads) installed and running +- A [supported MCP client](../reference/client-compatibility.mdx) like GitHub + Copilot in VS Code, Cursor, Claude Code, and more + +## Step 1: Install the ToolHive UI + +First, download and run the ToolHive installer for your system. + +- **macOS**: download the DMG installer for + [Apple silicon](https://github.com/stacklok/toolhive-studio/releases/latest/download/ToolHive-arm64.dmg) + or + [Intel-based](https://github.com/stacklok/toolhive-studio/releases/latest/download/ToolHive-x64.dmg) + Macs and copy the ToolHive application to your Applications folder +- **Windows**: download and run the + [installer](https://github.com/stacklok/toolhive-studio/releases/latest/download/ToolHive.Setup.exe) + + :::note + + The Windows installer is not digitally signed yet, so you will need to accept + the warning from Windows Defender SmartScreen. We're working on getting a + signed installer published soon. + + ::: + +- **Linux**: download the RPM or DEB package from the + [releases page](https://github.com/stacklok/toolhive-studio/releases/latest) + and install it using your package manager. + +For more detailed installation instructions, see the +[installing ToolHive](../guides-ui/install.mdx) guide. + +## Step 2: Find an MCP server to run + +On the initial splash screen, click **Browse registry**, or open the +**Registry** page from the top menu bar. This page lists the MCP servers in +ToolHive's built-in registry. + +:::info What is this? + +ToolHive maintains a curated registry of MCP servers that have been verified to +work correctly. The registry includes information about what each server does +and how to use it. + +::: + +For this tutorial, you'll use the "fetch" server, which is a simple MCP server +that lets AI agents get the contents of a website. Click on the "fetch" server +to start the installation process. + +## Step 3: Install the Fetch MCP server + +The Fetch MCP server doesn't require any special configuration, so you can +install it with the default settings. Click the **Install server** button to +start the installation. + +Once the server is installed, it will appear on the **MCP Servers** page. + +:::info What's happening? + +ToolHive downloads the container image for the fetch server, creates a container +with the appropriate security settings, and starts the server. It also sets up a +proxy process that lets your AI agent communicate with the server. + +::: + +## Step 4: Connect an AI client + +On the **Clients** page, you'll see the supported AI clients that ToolHive can +manage for you. When you connect a client, ToolHive configures it to use the MCP +servers you have installed. + +Click the toggle switch to connect the client you want to use. + +:::info What's happening? + +When you connect a supported client, ToolHive automatically configures it to use +MCP servers that you install. This means you don't have to manually configure +the client each time you run an MCP server. + +::: + +## Step 5: Use the MCP server with your client + +Now that your MCP server is running and your client is connected to ToolHive, +you can use the MCP server's tools. Open your client and ask the AI to fetch +content from a website. Note that you might need to restart your client for the +changes to take effect. + +For example, try asking: "Can you fetch the content from https://toolhive.dev +and summarize it for me?" + +The AI should be able to use the Fetch MCP server to retrieve the content and +provide a summary. + +:::info What's happening? + +When you ask the AI agent to fetch content, the large language model (LLM) +determines that it needs external data. It discovers the fetch tool provided by +your MCP server, instructs the agent to execute the tool with the URL you +specified, then receives and processes the webpage content to create a summary. + +::: + +## What's next? + +Congratulations! You've successfully installed ToolHive and run your first MCP +server. Here are some next steps to explore: + +- Learn more about MCP concepts in the + [MCP primer guide](../concepts/mcp-primer.md) +- Try [running more MCP servers](../guides-ui/run-mcp-servers.md) from the + registry or from custom sources +- Learn about [secrets management](../guides-ui/secrets-management.md) for MCP + servers that require authentication +- Learn how to + [manually configure clients](../reference/client-compatibility.mdx#manual-configuration) + that ToolHive doesn't automatically configure + +## Troubleshooting + +
+Server fails to start + +If the server fails to start, check: + +- Is Docker or Podman running? +- Do you have internet access to pull the container image? + +
+ +
+Client can't use the server + +If your AI client application can't use the server: + +- Make sure your client is connected to ToolHive (see Step 4) +- Restart your client to pick up the new configuration +- Verify the server is running on the **MCP Servers** page +- Disconnect and reconnect the client in ToolHive to refresh the configuration + +
+ +If you encounter any problems, please join our +[Discord community](https://discord.gg/stacklok) for help. diff --git a/docusaurus.config.ts b/docusaurus.config.ts index 13865797..0ee4f7db 100644 --- a/docusaurus.config.ts +++ b/docusaurus.config.ts @@ -97,6 +97,12 @@ const config: Config = { }, // Replace with your project's social card // image: 'img/docusaurus-social-card.jpg', + docs: { + sidebar: { + hideable: false, + autoCollapseCategories: false, + }, + }, navbar: { // title: 'Stacklok Docs', logo: { @@ -107,11 +113,31 @@ const config: Config = { }, items: [ { - type: 'docSidebar', - sidebarId: 'toolhiveSidebar', - position: 'left', + type: 'dropdown', label: 'ToolHive Docs', - className: 'navbar__product-link--custom', + position: 'left', + items: [ + { + label: 'Home', + href: '/toolhive', + }, + { + label: 'Tutorials', + to: 'toolhive/tutorials', + }, + { + label: 'ToolHive UI', + to: 'toolhive/guides-ui', + }, + { + label: 'ToolHive CLI', + to: 'toolhive/guides-cli', + }, + { + label: 'Kubernetes Operator', + to: 'toolhive/guides-k8s', + }, + ], }, { href: 'https://github.com/stacklok', diff --git a/eslint.config.mjs b/eslint.config.mjs index 5f29c27b..4b3cc385 100644 --- a/eslint.config.mjs +++ b/eslint.config.mjs @@ -39,6 +39,16 @@ export default [ }, }, + // Config for _partials with JSX props + { + files: ['docs/**/_partials/*.mdx'], + rules: { + 'no-unused-expressions': 'off', + '@typescript-eslint/no-unused-expressions': 'off', + 'no-undef': 'off', + }, + }, + { settings: { react: { diff --git a/scripts/update-toolhive-reference.sh b/scripts/update-toolhive-reference.sh index 9097da58..b3baac16 100755 --- a/scripts/update-toolhive-reference.sh +++ b/scripts/update-toolhive-reference.sh @@ -1,4 +1,6 @@ #!/bin/bash +# SPDX-FileCopyrightText: Copyright 2025 Stacklok, Inc. +# SPDX-License-Identifier: Apache-2.0 set -euo pipefail diff --git a/sidebars.ts b/sidebars.ts index 3d2feccc..c7797400 100644 --- a/sidebars.ts +++ b/sidebars.ts @@ -1,4 +1,5 @@ import type { SidebarsConfig } from '@docusaurus/plugin-content-docs'; +import { buildCliReferenceSidebar } from './src/utils/buildHierarchicalSidebar'; // This runs in Node.js - Don't use client-side code here (browser APIs, JSX...) @@ -13,8 +14,116 @@ import type { SidebarsConfig } from '@docusaurus/plugin-content-docs'; Create as many sidebars as you want. */ const sidebars: SidebarsConfig = { - // Auto-generated sidebars for each project - toolhiveSidebar: [{ type: 'autogenerated', dirName: 'toolhive' }], + toolhiveSidebar: [ + 'toolhive/index', + + { + type: 'category', + label: 'Tutorials', + description: 'Step-by-step guides to get started with ToolHive', + link: { + type: 'generated-index', + slug: 'toolhive/tutorials', + description: + 'Learn how to use ToolHive with these step-by-step tutorials', + }, + collapsed: false, + items: [ + 'toolhive/tutorials/quickstart-ui', + 'toolhive/tutorials/quickstart-cli', + 'toolhive/tutorials/quickstart-k8s', + ], + }, + + 'toolhive/reference/client-compatibility', + + { + type: 'category', + label: 'Guides: ToolHive UI', + description: 'How to use the ToolHive desktop application', + link: { + type: 'doc', + id: 'toolhive/guides-ui/index', + }, + items: [ + 'toolhive/guides-ui/install', + 'toolhive/guides-ui/run-mcp-servers', + 'toolhive/guides-ui/network-isolation', + 'toolhive/guides-ui/secrets-management', + 'toolhive/guides-ui/client-configuration', + ], + }, + + { + type: 'category', + label: 'Guides: ToolHive CLI', + description: 'How to use the ToolHive CLI for managing MCP servers', + link: { + type: 'doc', + id: 'toolhive/guides-cli/index', + }, + items: [ + 'toolhive/guides-cli/install', + 'toolhive/guides-cli/registry', + 'toolhive/guides-cli/run-mcp-servers', + 'toolhive/guides-cli/manage-mcp-servers', + 'toolhive/guides-cli/secrets-management', + 'toolhive/guides-cli/client-configuration', + 'toolhive/guides-cli/custom-permissions', + { + type: 'category', + label: 'Command reference', + description: 'Detailed reference for ToolHive CLI commands', + collapsed: true, + items: buildCliReferenceSidebar(), + }, + { + type: 'category', + label: 'API server', + description: 'How to set up and use the ToolHive API server', + link: { + type: 'doc', + id: 'toolhive/guides-cli/api-server', + }, + items: ['toolhive/reference/api'], + }, + ], + }, + + { + type: 'category', + label: 'Guides: Kubernetes Operator', + description: 'How to deploy and manage ToolHive on Kubernetes', + link: { + type: 'doc', + id: 'toolhive/guides-k8s/index', + }, + items: [ + 'toolhive/guides-k8s/intro', + 'toolhive/guides-k8s/deploy-operator-helm', + 'toolhive/guides-k8s/run-mcp-k8s', + 'toolhive/reference/crd-spec', + ], + }, + + { + type: 'category', + label: 'Concepts', + description: 'Core concepts and architecture of ToolHive and MCP', + link: { + type: 'generated-index', + slug: 'toolhive/concepts', + description: + 'Learn about the key concepts behind ToolHive and the Model Context Protocol (MCP)', + }, + items: [ + 'toolhive/concepts/mcp-primer', + 'toolhive/concepts/registry-criteria', + ], + }, + + 'toolhive/faq', + ], }; export default sidebars; diff --git a/src/components/ProductCard/index.tsx b/src/components/ProductCard/index.tsx index ef44d0cb..0066120a 100644 --- a/src/components/ProductCard/index.tsx +++ b/src/components/ProductCard/index.tsx @@ -1,3 +1,6 @@ +// SPDX-FileCopyrightText: Copyright 2025 Stacklok, Inc. +// SPDX-License-Identifier: Apache-2.0 + import React from 'react'; import clsx from 'clsx'; import useBaseUrl from '@docusaurus/useBaseUrl'; diff --git a/src/components/ProductCard/styles.module.css b/src/components/ProductCard/styles.module.css index f2e0494a..5101f816 100644 --- a/src/components/ProductCard/styles.module.css +++ b/src/components/ProductCard/styles.module.css @@ -1,3 +1,8 @@ +/* + SPDX-FileCopyrightText: Copyright 2025 Stacklok, Inc. + SPDX-License-Identifier: Apache-2.0 +*/ + /* CSS Custom Properties for theming */ .card { --card-background: var(--product-card-background-color, #ededed); diff --git a/src/components/ProductGrid/index.tsx b/src/components/ProductGrid/index.tsx index 7428aa9c..99d67fbb 100644 --- a/src/components/ProductGrid/index.tsx +++ b/src/components/ProductGrid/index.tsx @@ -1,3 +1,6 @@ +// SPDX-FileCopyrightText: Copyright 2025 Stacklok, Inc. +// SPDX-License-Identifier: Apache-2.0 + import React from 'react'; import clsx from 'clsx'; import styles from './styles.module.css'; diff --git a/src/components/ProductGrid/styles.module.css b/src/components/ProductGrid/styles.module.css index b25778f9..5bd18db6 100644 --- a/src/components/ProductGrid/styles.module.css +++ b/src/components/ProductGrid/styles.module.css @@ -1,3 +1,8 @@ +/* + SPDX-FileCopyrightText: Copyright 2025 Stacklok, Inc. + SPDX-License-Identifier: Apache-2.0 +*/ + /* Base grid styles */ .grid { margin-top: 3rem; diff --git a/src/css/custom.css b/src/css/custom.css index 9a224d4f..0ecd7ae2 100644 --- a/src/css/custom.css +++ b/src/css/custom.css @@ -1,3 +1,8 @@ +/* + SPDX-FileCopyrightText: Copyright 2025 Stacklok, Inc. + SPDX-License-Identifier: Apache-2.0 +*/ + /** * Any CSS included here will be global. The classic template * bundles Infima by default. Infima is a CSS framework designed to diff --git a/src/css/footer.css b/src/css/footer.css index c4ade7d7..ce41bbc8 100644 --- a/src/css/footer.css +++ b/src/css/footer.css @@ -1,3 +1,8 @@ +/* + SPDX-FileCopyrightText: Copyright 2025 Stacklok, Inc. + SPDX-License-Identifier: Apache-2.0 +*/ + /* Footer classes to match the style of stacklok.com */ [data-theme='dark'] .footer__logo--invert { diff --git a/src/pages/index.module.css b/src/pages/index.module.css index c7073cc9..e52619f5 100644 --- a/src/pages/index.module.css +++ b/src/pages/index.module.css @@ -1,3 +1,8 @@ +/* + SPDX-FileCopyrightText: Copyright 2025 Stacklok, Inc. + SPDX-License-Identifier: Apache-2.0 +*/ + /** * CSS files with the .module.css suffix will be treated as CSS modules * and scoped locally. diff --git a/src/pages/index.tsx b/src/pages/index.tsx index c0d76c94..250a65a1 100644 --- a/src/pages/index.tsx +++ b/src/pages/index.tsx @@ -1,3 +1,6 @@ +// SPDX-FileCopyrightText: Copyright 2025 Stacklok, Inc. +// SPDX-License-Identifier: Apache-2.0 + import React from 'react'; import type { ReactNode } from 'react'; import clsx from 'clsx'; @@ -43,7 +46,7 @@ export default function Home(): ReactNode { linkText='Read documentation' > ToolHive mascot ToolHive simplifies the deployment and management of Model Context diff --git a/src/redocly/redocly-codegate.yaml b/src/redocly/redocly-codegate.yaml deleted file mode 100644 index 84ccd17c..00000000 --- a/src/redocly/redocly-codegate.yaml +++ /dev/null @@ -1,13 +0,0 @@ -# Redocly config for the ToolHive API -# NOTE: Only supports options marked as "Supported in Redoc CE" -# See https://redocly.com/docs/cli/configuration/ for more information. - -extends: - - recommended - -plugins: - - plugins/replace-servers-url.js - -decorators: - servers/replace-servers-url: - serverUrl: 'http://localhost:8989' diff --git a/src/theme/NotFound/Content/index.tsx b/src/theme/NotFound/Content/index.tsx index c5797963..3dbce347 100644 --- a/src/theme/NotFound/Content/index.tsx +++ b/src/theme/NotFound/Content/index.tsx @@ -1,3 +1,6 @@ +// SPDX-FileCopyrightText: Copyright 2025 Stacklok, Inc. +// SPDX-License-Identifier: Apache-2.0 + import React, { type ReactNode } from 'react'; import clsx from 'clsx'; import Translate from '@docusaurus/Translate'; diff --git a/src/theme/NotFound/index.tsx b/src/theme/NotFound/index.tsx index 079e5d9c..96fdfb47 100644 --- a/src/theme/NotFound/index.tsx +++ b/src/theme/NotFound/index.tsx @@ -1,3 +1,6 @@ +// SPDX-FileCopyrightText: Copyright 2025 Stacklok, Inc. +// SPDX-License-Identifier: Apache-2.0 + import React, { type ReactNode } from 'react'; import { translate } from '@docusaurus/Translate'; import { PageMetadata } from '@docusaurus/theme-common'; diff --git a/src/utils/buildHierarchicalSidebar.ts b/src/utils/buildHierarchicalSidebar.ts new file mode 100644 index 00000000..19867470 --- /dev/null +++ b/src/utils/buildHierarchicalSidebar.ts @@ -0,0 +1,186 @@ +// SPDX-FileCopyrightText: Copyright 2025 Stacklok, Inc. +// SPDX-License-Identifier: Apache-2.0 + +import fs from 'fs'; +import path from 'path'; + +// TypeScript interfaces for better type safety +interface CommandTreeNode { + id: string; + label: string; + children: Map; + hasFile: boolean; +} + +interface SidebarItemDoc { + type: 'doc'; + id: string; + label?: string; +} + +interface SidebarItemCategory { + type: 'category'; + label: string; + collapsed: boolean; + items: SidebarItem[]; + link?: { type: 'doc'; id: string }; +} + +interface SidebarItemAutogenerated { + type: 'autogenerated'; + dirName: string; +} + +type SidebarItem = + | SidebarItemDoc + | SidebarItemCategory + | SidebarItemAutogenerated; + +interface HierarchicalSidebarOptions { + /** Relative path to the directory containing markdown files */ + dirPath: string; + /** ID prefix for generated sidebar items (e.g., 'toolhive/reference/cli') */ + idPrefix: string; + /** Separator used in filenames to denote hierarchy (default: '_') */ + separator?: string; + /** Whether categories should be collapsed by default (default: true) */ + collapsed?: boolean; +} + +/** + * Builds a hierarchical sidebar from flat markdown files with separator-delimited naming. + * + * Parses files with naming patterns like: + * - tool.md -> "tool" + * - tool_command.md -> "tool" > "command" + * - tool_command_subcommand_action.md -> "tool" > "command" > "subcommand" > "action" + * + * Each level shows only the command name (not the full path), creating clean navigation. + * + * @param options Configuration options for building the sidebar + * @returns Array of sidebar items with hierarchical structure + * + * @example + * ```typescript + * // For CLI reference docs + * const cliSidebar = buildHierarchicalSidebar({ + * dirPath: 'docs/toolhive/reference/cli', + * idPrefix: 'toolhive/reference/cli' + * }); + * + * // For API reference docs with different separator + * const apiSidebar = buildHierarchicalSidebar({ + * dirPath: 'docs/api/endpoints', + * idPrefix: 'api/endpoints', + * separator: '-' + * }); + * ``` + */ +export function buildHierarchicalSidebar( + options: HierarchicalSidebarOptions +): SidebarItem[] { + const { dirPath, idPrefix, separator = '_', collapsed = true } = options; + + const fullDirPath = path.join(process.cwd(), dirPath); + + try { + const files = fs + .readdirSync(fullDirPath) + .filter((file) => file.endsWith('.md')) + .map((file) => file.replace('.md', '')); + + // Build command tree + const tree = new Map(); + + for (const filename of files) { + const parts = filename.split(separator); + let current = tree; + + for (let i = 0; i < parts.length; i++) { + const part = parts[i]; + const isLeaf = i === parts.length - 1; + + if (!current.has(part)) { + current.set(part, { + id: `${idPrefix}/${parts.slice(0, i + 1).join(separator)}`, + label: part, + children: new Map(), + hasFile: false, + }); + } + + const node = current.get(part)!; + if (isLeaf) { + node.hasFile = true; + } + current = node.children; + } + } + + // Convert tree to sidebar items + function treeToItems(nodeMap: Map): SidebarItem[] { + const items: SidebarItem[] = []; + + for (const [, node] of nodeMap) { + if (node.children.size === 0) { + // Leaf node + items.push({ + type: 'doc', + id: node.id, + label: node.label, + }); + } else { + // Category with children + const categoryItem: SidebarItemCategory = { + type: 'category', + label: node.label, + collapsed, + items: treeToItems(node.children), + }; + + // Link to main command page if it exists + if (node.hasFile) { + categoryItem.link = { + type: 'doc', + id: node.id, + }; + } + + items.push(categoryItem); + } + } + + return items; + } + + return treeToItems(tree); + } catch (error) { + console.warn(`Could not build hierarchical sidebar for ${dirPath}:`, error); + // Fallback to autogenerated + return [ + { + type: 'autogenerated', + dirName: dirPath, + }, + ]; + } +} + +/** + * Convenience function for building CLI reference sidebars. + * + * @param dirPath Relative path to CLI documentation directory + * @param idPrefix ID prefix for generated sidebar items + * @returns Array of sidebar items with hierarchical structure + */ +export function buildCliReferenceSidebar( + dirPath: string = 'docs/toolhive/reference/cli', + idPrefix: string = 'toolhive/reference/cli' +): SidebarItem[] { + return buildHierarchicalSidebar({ + dirPath, + idPrefix, + separator: '_', + collapsed: true, + }); +} diff --git a/static/img/toolhive-icon-honey.svg b/static/img/toolhive-icon-honey.svg new file mode 100644 index 00000000..8b916fe6 --- /dev/null +++ b/static/img/toolhive-icon-honey.svg @@ -0,0 +1,60 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/static/img/toolhive/network-isolation-dark.webp b/static/img/toolhive/network-isolation-dark.webp new file mode 100644 index 00000000..63ecc951 Binary files /dev/null and b/static/img/toolhive/network-isolation-dark.webp differ diff --git a/static/img/toolhive/network-isolation-light.webp b/static/img/toolhive/network-isolation-light.webp new file mode 100644 index 00000000..692d2155 Binary files /dev/null and b/static/img/toolhive/network-isolation-light.webp differ diff --git a/static/img/toolhive/toolhive-diagram-dark.svg b/static/img/toolhive/toolhive-diagram-dark.svg new file mode 100644 index 00000000..01b4d945 --- /dev/null +++ b/static/img/toolhive/toolhive-diagram-dark.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/static/img/toolhive/toolhive-diagram-light.svg b/static/img/toolhive/toolhive-diagram-light.svg new file mode 100644 index 00000000..914cbbb8 --- /dev/null +++ b/static/img/toolhive/toolhive-diagram-light.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/static/img/toolhive/toolhive-ui-screenshot-dark.webp b/static/img/toolhive/toolhive-ui-screenshot-dark.webp new file mode 100644 index 00000000..bda58424 Binary files /dev/null and b/static/img/toolhive/toolhive-ui-screenshot-dark.webp differ diff --git a/static/img/toolhive/toolhive-ui-screenshot-light.webp b/static/img/toolhive/toolhive-ui-screenshot-light.webp new file mode 100644 index 00000000..3cd8c110 Binary files /dev/null and b/static/img/toolhive/toolhive-ui-screenshot-light.webp differ diff --git a/vercel.json b/vercel.json index 3c884c1d..ffcbeb67 100644 --- a/vercel.json +++ b/vercel.json @@ -1,3 +1,14 @@ { - "redirects": [] + "redirects": [ + { + "source": "/toolhive/quickstart", + "destination": "/toolhive/tutorials/quickstart-cli", + "permanent": false + }, + { + "source": "/toolhive/tutorials/toolhive-operator", + "destination": "/toolhive/tutorials/quickstart-k8s", + "permanent": true + } + ] }