diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index b90c18d6..1b1cd970 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -172,7 +172,8 @@ conventions for Markdown files: - Use the `admonition` component for notes, tips, warnings, and other annotations. This provides a consistent look and feel across the site. - Use the `:::type` syntax to define the admonition type, such as `note`, - `tip`, `info`, `warning`, or `danger`. + `tip`, `info`, `warning`, or `danger`. Use square brackets to add a title, + e.g. `:::info[Title]`. Add empty lines around the start and end directives. - Place images in `static/img` using WebP, PNG, or SVG format. - Use the `ThemedImage` component to provide both light and dark mode screenshots for apps/UIs that support both. diff --git a/CLAUDE.md b/CLAUDE.md index b90c18d6..1b1cd970 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -172,7 +172,8 @@ conventions for Markdown files: - Use the `admonition` component for notes, tips, warnings, and other annotations. This provides a consistent look and feel across the site. - Use the `:::type` syntax to define the admonition type, such as `note`, - `tip`, `info`, `warning`, or `danger`. + `tip`, `info`, `warning`, or `danger`. Use square brackets to add a title, + e.g. `:::info[Title]`. Add empty lines around the start and end directives. - Place images in `static/img` using WebP, PNG, or SVG format. - Use the `ThemedImage` component to provide both light and dark mode screenshots for apps/UIs that support both. diff --git a/docs/theme-preview.mdx b/docs/theme-preview.mdx index 41f8db65..a2c0d53d 100644 --- a/docs/theme-preview.mdx +++ b/docs/theme-preview.mdx @@ -89,6 +89,13 @@ repository: These are MDX callouts ([reference](https://docusaurus.io/docs/markdown-features/admonitions)). +To customize the title, use square brackets after the type, e.g. +`:::tip[My title]`. + +To keep Prettier from invalidating the admonition syntax, add empty lines around +the start and end of the admonition block (see +[here](https://docusaurus.io/docs/markdown-features/admonitions#usage-with-prettier)). + They can be customized in src/css/custom.css like so ([reference](https://docusaurus.community/knowledge/design/admonitions/#updating-the-css)): @@ -119,9 +126,10 @@ This is a `tip` admonition. Its CSS class is `alert--success`. ::: -:::info +:::info[Hello] -This is an `info` admonition. Its CSS class is `alert--info`. +This is an `info` admonition. Its CSS class is `alert--info` and it has a custom +title. ::: @@ -137,16 +145,16 @@ This is a `danger` admonition. Its CSS class is `alert--danger`. ::: -:::::info Parent +:::::info[Parent] Admonitions can be nested; example here so we can see how the colors look together. -::::danger Child +::::danger[Child] Child content -:::tip Inception +:::tip[Inception] This is getting silly diff --git a/docs/toolhive/guides-cli/build-containers.mdx b/docs/toolhive/guides-cli/build-containers.mdx index 58cc4929..5462d310 100644 --- a/docs/toolhive/guides-cli/build-containers.mdx +++ b/docs/toolhive/guides-cli/build-containers.mdx @@ -46,7 +46,7 @@ thv build npx://@modelcontextprotocol/server-filesystem thv build go://github.com/example/my-mcp-server@latest ``` -:::info What's happening? +:::info[What's happening?] When you run `thv build`, ToolHive: diff --git a/docs/toolhive/guides-cli/custom-permissions.mdx b/docs/toolhive/guides-cli/custom-permissions.mdx index c772e8ef..ef190e07 100644 --- a/docs/toolhive/guides-cli/custom-permissions.mdx +++ b/docs/toolhive/guides-cli/custom-permissions.mdx @@ -97,7 +97,7 @@ without creating a custom file: profile applied to MCP servers when you run a custom server without the `--permission-profile` flag. - :::important + :::info[Important] This profile is useful for development and testing but isn't recommended for production use since it doesn't restrict network destinations. Create a custom diff --git a/docs/toolhive/guides-cli/group-management.md b/docs/toolhive/guides-cli/group-management.md index 98b35be0..7a47eaa8 100644 --- a/docs/toolhive/guides-cli/group-management.md +++ b/docs/toolhive/guides-cli/group-management.md @@ -17,7 +17,7 @@ Groups let you organize MCP servers and control client access: - **Environment management**: Organize servers by development stage - **Client customization**: Configure different tool sets for different clients -:::info What's the default behavior? +:::info[What's the default behavior?] All MCP servers are automatically assigned to the `default` group unless you specify otherwise. MCP clients configured without a specific group can access @@ -49,7 +49,7 @@ thv run --group development fetch thv run --group production filesystem --volume /prod/repo:/projects:ro ``` -:::info What's happening? +:::info[What's happening?] When you specify a group: diff --git a/docs/toolhive/guides-cli/index.mdx b/docs/toolhive/guides-cli/index.mdx index e8d52f2a..7a4f69f6 100644 --- a/docs/toolhive/guides-cli/index.mdx +++ b/docs/toolhive/guides-cli/index.mdx @@ -17,7 +17,7 @@ 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? +:::tip[Did you know?] The ToolHive CLI can be used alongside the [ToolHive UI](../guides-ui/index.mdx), which provides a graphical interface. You diff --git a/docs/toolhive/guides-cli/network-isolation.mdx b/docs/toolhive/guides-cli/network-isolation.mdx index c60ebb21..8c20e13a 100644 --- a/docs/toolhive/guides-cli/network-isolation.mdx +++ b/docs/toolhive/guides-cli/network-isolation.mdx @@ -139,7 +139,7 @@ architecture-beta -:::important +:::info[Important] Network isolation supports HTTP and HTTPS protocols. If your MCP server needs to use other protocols (like direct TCP connections for database access), run it diff --git a/docs/toolhive/guides-cli/run-mcp-servers.mdx b/docs/toolhive/guides-cli/run-mcp-servers.mdx index 7c8adf3f..d3311cf6 100644 --- a/docs/toolhive/guides-cli/run-mcp-servers.mdx +++ b/docs/toolhive/guides-cli/run-mcp-servers.mdx @@ -27,7 +27,7 @@ fetches website contents: thv run fetch ``` -:::info What's happening? +:::info[What's happening?] When you run an MCP server from the registry, ToolHive: @@ -249,7 +249,7 @@ thv run --name my-mcp-server --transport streamable-http my-mcp-server-image:lat Check your MCP server's documentation for the required arguments. -:::info What's happening? +:::info[What's happening?] When you run an MCP server from a Docker image, ToolHive: @@ -289,7 +289,7 @@ You'll likely need to specify additional arguments like the transport method, volumes, and environment variables. Check your MCP server's documentation and see [`thv run --help`](../reference/cli/thv_run.md) for more options. -:::info What's happening? +:::info[What's happening?] When you use a protocol scheme, ToolHive: diff --git a/docs/toolhive/guides-cli/secrets-management.mdx b/docs/toolhive/guides-cli/secrets-management.mdx index e9f85314..0c70be68 100644 --- a/docs/toolhive/guides-cli/secrets-management.mdx +++ b/docs/toolhive/guides-cli/secrets-management.mdx @@ -121,7 +121,7 @@ Alternatively, you can set a secret using standard input: echo "MY_SECRET_VALUE" | thv secret set ``` -:::tip Example +:::tip[Example] Create a secret named `github` and set its value to your GitHub authentication token using the GitHub CLI: diff --git a/docs/toolhive/guides-cli/telemetry-and-metrics.md b/docs/toolhive/guides-cli/telemetry-and-metrics.md index 5cbac648..68defb12 100644 --- a/docs/toolhive/guides-cli/telemetry-and-metrics.md +++ b/docs/toolhive/guides-cli/telemetry-and-metrics.md @@ -54,7 +54,7 @@ By default, the service name is set to `toolhive-mcp-proxy`, and the sampling rate is `0.1` (10%). You can customize these settings with additional [configuration options](#configuration-options). -:::tip Recommendation +:::tip[Recommendation] Set the `--otel-service-name` flag to a meaningful name for each MCP server. This helps you identify the server in your observability backend. diff --git a/docs/toolhive/guides-k8s/intro.md b/docs/toolhive/guides-k8s/intro.md index d40b5e01..50e593bc 100644 --- a/docs/toolhive/guides-k8s/intro.md +++ b/docs/toolhive/guides-k8s/intro.md @@ -8,7 +8,7 @@ The ToolHive Kubernetes operator manages MCP servers in Kubernetes clusters. It lets you define MCP servers as Kubernetes resources and automates their deployment and management. -:::info Experimental +:::info[Experimental] The Kubernetes operator is still under active development and isn't recommended for production use cases yet. Specifically, the `MCPServer` Custom Resource diff --git a/docs/toolhive/guides-k8s/run-mcp-k8s.md b/docs/toolhive/guides-k8s/run-mcp-k8s.md index f6f0287a..d1f5362e 100644 --- a/docs/toolhive/guides-k8s/run-mcp-k8s.md +++ b/docs/toolhive/guides-k8s/run-mcp-k8s.md @@ -137,7 +137,7 @@ Apply the resource: kubectl apply -f my-mcpserver.yaml ``` -:::info What's happening? +:::info[What's happening?] When you apply an `MCPServer` resource, here's what happens: @@ -243,7 +243,7 @@ spec: memory: '64Mi' ``` -:::info Container name requirement +:::info[Container name requirement] When customizing containers in `podTemplateSpec`, you must use `name: mcp` for the main container. This ensures the proxy can properly manage the MCP server @@ -367,7 +367,7 @@ to learn how to connect to MCP servers using different clients. - [Custom permissions](../guides-cli/custom-permissions.mdx) - Configure permission profiles -:::important +:::info[Important] Outbound network filtering using permission profiles isn't currently implemented in the ToolHive Operator. This is a roadmap feature planned for future releases. diff --git a/docs/toolhive/guides-ui/index.mdx b/docs/toolhive/guides-ui/index.mdx index bc00b943..21d00c05 100644 --- a/docs/toolhive/guides-ui/index.mdx +++ b/docs/toolhive/guides-ui/index.mdx @@ -34,7 +34,7 @@ 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 +:::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 diff --git a/docs/toolhive/guides-ui/install.mdx b/docs/toolhive/guides-ui/install.mdx index 4c7765d3..b08f9155 100644 --- a/docs/toolhive/guides-ui/install.mdx +++ b/docs/toolhive/guides-ui/install.mdx @@ -53,7 +53,7 @@ and run the setup executable. After installation, you can find ToolHive in your Start menu or on your desktop. -:::important +:::info[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. diff --git a/docs/toolhive/guides-ui/network-isolation.mdx b/docs/toolhive/guides-ui/network-isolation.mdx index 93563153..777d1587 100644 --- a/docs/toolhive/guides-ui/network-isolation.mdx +++ b/docs/toolhive/guides-ui/network-isolation.mdx @@ -54,7 +54,7 @@ access: services or resources. For example, port 443 is the default port for HTTPS connections. -:::important +:::info[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 diff --git a/docs/toolhive/guides-ui/secrets-management.md b/docs/toolhive/guides-ui/secrets-management.md index 48625145..02561f6b 100644 --- a/docs/toolhive/guides-ui/secrets-management.md +++ b/docs/toolhive/guides-ui/secrets-management.md @@ -48,7 +48,7 @@ Your ToolHive secrets are managed on the **Secrets** page. Here you can: - Update the secret value - Delete the secret -:::important +:::warning 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 diff --git a/docs/toolhive/tutorials/quickstart-cli.mdx b/docs/toolhive/tutorials/quickstart-cli.mdx index b98fce95..bd6c6638 100644 --- a/docs/toolhive/tutorials/quickstart-cli.mdx +++ b/docs/toolhive/tutorials/quickstart-cli.mdx @@ -105,7 +105,7 @@ thv client setup Select one or more clients from the list using the spacebar to toggle selection. Press Enter to confirm your selection. -:::info What's happening? +:::info[What's happening?] When you run the setup command, ToolHive automatically finds [supported clients](../reference/client-compatibility.mdx) on your system. When @@ -152,7 +152,7 @@ notion Official Notion MCP server. Offici This shows all the MCP servers available in the ToolHive registry. -:::info What's happening? +:::info[What's happening?] ToolHive maintains a curated registry of MCP servers that have been verified to work correctly. The registry includes information about what each server does @@ -196,7 +196,7 @@ Status: Image is up to date for ghcr.io/stackloklabs/gofetch/server:latest 8:41AM INF Use 'thv stop fetch' to stop the server ``` -:::info What's happening? +:::info[What's happening?] When you run an MCP server, ToolHive: @@ -227,7 +227,7 @@ fetch ghcr.io/stackloklabs/gofetch/server:latest running http://127.0.0.1: This confirms that the fetch server is running and available on port 49226. -:::info What's happening? +:::info[What's happening?] ToolHive keeps track of all the MCP servers it's managing. The [`list`](../reference/cli/thv_list.md) command shows you which servers are @@ -248,7 +248,7 @@ 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? +:::info[What's happening?] When you ask the AI to fetch content, it detects that it needs external data. It discovers the fetch tool provided by your MCP server, calls the tool with the @@ -271,7 +271,7 @@ If you want to remove it completely: thv rm fetch ``` -:::info What's happening? +:::info[What's happening?] Stopping a server pauses it and terminates the associated proxy process but keeps the container around so you can restart it quickly later using diff --git a/docs/toolhive/tutorials/quickstart-k8s.mdx b/docs/toolhive/tutorials/quickstart-k8s.mdx index 9fd3d3a7..86304040 100644 --- a/docs/toolhive/tutorials/quickstart-k8s.mdx +++ b/docs/toolhive/tutorials/quickstart-k8s.mdx @@ -89,7 +89,7 @@ CoreDNS is running at https://127.0.0.1:xxxxx/api/v1/namespaces/kube-system/serv This confirms your cluster is running and ready for the ToolHive operator. -:::info What's happening? +:::info[What's happening?] Kind (Kubernetes in Docker) creates a local Kubernetes cluster using Docker containers. This is perfect for development and testing because it's isolated @@ -129,7 +129,7 @@ toolhive-operator-xxx 1/1 Running 0 30s If the pod shows "Running" status, your operator is ready to manage MCP servers. -:::info What's happening? +:::info[What's happening?] The ToolHive operator is a Kubernetes controller that watches for `MCPServer` resources. When you create an `MCPServer` resource, the operator automatically @@ -149,7 +149,7 @@ Apply the example `fetch` MCP server from the ToolHive repository: kubectl apply -f https://raw.githubusercontent.com/stacklok/toolhive/refs/heads/main/examples/operator/mcp-servers/mcpserver_fetch.yaml ``` -:::info What's happening? +:::info[What's happening?] When you create an `MCPServer` resource, the ToolHive operator detects it and automatically: @@ -201,7 +201,7 @@ You should see a response of `OK`. This confirms your MCP server is running and responding correctly. -:::info What's happening? +:::info[What's happening?] The ToolHive operator automatically creates a Kubernetes service for each MCP server. This service provides a stable network endpoint that other applications @@ -314,7 +314,7 @@ retrieve the content and provide a summary. className='screenshot' /> -:::info What's happening? +:::info[What's happening?] You're manually configuring VS Code to connect to your MCP server running in Kubernetes. The port-forward creates a tunnel from your local machine @@ -396,7 +396,7 @@ You should see: No resources found in toolhive-system namespace. ``` -:::info What's happening? +:::info[What's happening?] When you delete an `MCPServer` resource, the operator automatically cleans up all the associated Kubernetes resources (pods, services, etc.). This ensures no @@ -410,7 +410,7 @@ When you're completely finished, delete the kind cluster: kind delete cluster --name toolhive ``` -:::tip For Task users +:::tip[For Task users] If you followed the [TL;DR setup](#quickstart-with-task-tldr) using Task, you can also run: diff --git a/docs/toolhive/tutorials/quickstart-ui.mdx b/docs/toolhive/tutorials/quickstart-ui.mdx index 8284b9c9..cda0e73d 100644 --- a/docs/toolhive/tutorials/quickstart-ui.mdx +++ b/docs/toolhive/tutorials/quickstart-ui.mdx @@ -51,7 +51,7 @@ 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? +:::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 @@ -71,7 +71,7 @@ start the installation. Once the server is installed, it will appear on the **MCP Servers** page. -:::info What's happening? +:::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 @@ -87,7 +87,7 @@ servers you have installed. Click the toggle switch to connect the client you want to use. -:::info What's happening? +:::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 @@ -108,7 +108,7 @@ 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? +:::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 diff --git a/docusaurus.config.ts b/docusaurus.config.ts index 04b89519..087b540a 100644 --- a/docusaurus.config.ts +++ b/docusaurus.config.ts @@ -45,6 +45,11 @@ const config: Config = { markdown: { mermaid: true, + mdx1Compat: { + comments: false, + admonitions: false, + headingIds: true, + }, }, themes: ['@docusaurus/theme-mermaid', 'docusaurus-json-schema-plugin'],