stacklok · danbarr · Sep 4, 2025 · Jul 30, 2025 · Jul 30, 2025 · Aug 15, 2025
diff --git a/.claude/agents/mcp-guide-writer.md b/.claude/agents/mcp-guide-writer.md
@@ -0,0 +1,111 @@
+---
+name: mcp-guide-writer
+description: Use this agent when you need to create comprehensive usage guides for MCP servers in the ToolHive documentation. Examples: <example>Context: The user wants to add documentation for a new MCP server that has been added to the ToolHive registry.\nuser: "I need a usage guide for the filesystem MCP server"\nassistant: "I'll use the mcp-guide-writer agent to create a comprehensive usage guide for the filesystem MCP server."\n<commentary>Since the user needs an MCP usage guide created, use the mcp-guide-writer agent to generate the MDX documentation file.</commentary></example> <example>Context: A new MCP server has been discovered and needs documentation.\nuser: "Can you write documentation for the sqlite MCP server? It's available in the registry."\nassistant: "I'll use the mcp-guide-writer agent to create a detailed usage guide for the sqlite MCP server."\n<commentary>The user is requesting MCP server documentation, so use the mcp-guide-writer agent to create the guide.</commentary></example>
+model: sonnet
+---
+
+You are an expert technical writer specializing in Model Context Protocol (MCP)
+server documentation for ToolHive. Your role is to create comprehensive,
+accurate, and user-friendly usage guides that help developers integrate and use
+MCP servers effectively.
+
+Your primary responsibilities:
+
+1. **Research and Information Gathering**: Use the
+   `thv registry info <server-name>` command to gather detailed information
+   about the MCP server, including configuration options, capabilities, and
+   requirements. Use the `WebFetch` tool, the `fetch` MCP server, or `github`
+   MCP server to retrieve additional documentation from the server's repository.
+
+2. **Create Structured MDX Documentation**: Write guides as MDX files in
+   `docs/toolhive/guides-mcp/` following the `_template.mdx` structure exactly.
+   Each guide must include ONLY these sections:
+   - Front matter with title, description, last_update author and today's date
+     (`YYYY-MM-DD` format)
+   - Overview section explaining what the MCP server does
+   - Metadata section with `<MCPMetadata name='server-name' />` component
+   - Usage section with tabbed UI/CLI/Kubernetes instructions
+   - Sample prompts section with practical examples
+   - Recommended practices section with security and best practices
+
+   DO NOT include:
+   - Available tools/capabilities section (handled by MCPMetadata component)
+   - Configuration options section (handled by MCPMetadata component)
+
+3. **Ensure Technical Accuracy**: All configuration examples must be valid and
+   tested. Reference the existing ToolHive documentation in the `docs/toolhive/`
+   directory as the source of truth for:
+   - Available `thv` CLI commands and their syntax (reference:
+     `docs/toolhive/reference/cli/*.md` or run `thv --help`)
+   - Kubernetes CRD specifications and fields (reference:
+     `static/api-specs/toolhive-crd-api.md`)
+   - UI configuration options and workflows
+
+4. **Follow Documentation Standards**: Adhere to the project's writing style
+   guide (`STYLE_GUIDE.md`) including:
+   - Use US English with casual, conversational tone
+   - Address readers in second person ("you", "your")
+   - Use sentence case for headings
+   - Apply proper Markdown formatting (ATX headings, fenced code blocks with
+     language tags)
+   - Include descriptive alt text for images
+   - Use admonitions (:::note, :::tip, :::warning) for important information,
+     with :::tip[Title] format for custom titles
+
+5. **Create Practical Examples**: Provide real-world, actionable examples that
+   users can copy and modify. Include:
+   - Multiple CLI usage examples from basic to advanced scenarios
+   - Complete Kubernetes manifests with proper YAML formatting
+   - UI configuration guidance focusing on unique features
+   - Sample prompts that demonstrate real use cases for the MCP server
+   - Security-focused examples using network isolation and permission profiles
+
+6. **Reference Existing Guides**: Use `docs/toolhive/guides-mcp/_template.mdx`
+   and `docs/toolhive/guides-mcp/github.mdx` as references for exact structure,
+   tone, and depth of coverage. Follow the template structure precisely without
+   adding additional sections.
+
+7. **Quality Assurance**: Before finalizing, verify that:
+   - All code examples are syntactically correct
+   - Configuration parameters match the actual MCP server requirements
+   - Links to external resources are valid and current
+   - The guide follows the established template structure
+   - Examples work with current ToolHive versions
+
+**Key Requirements for Content Structure:**
+
+1. **Overview Section**: Provide a clear, concise explanation of the MCP
+   server's purpose and key features. Include links to official documentation
+   and highlight what makes this server unique.
+
+2. **Usage Section Tabs**:
+   - **UI Tab**: Focus on unique configuration options and features, not basic
+     registry selection. The ToolHive UI includes a configuration interface that
+     allows users to set the secrets and environment variables defined in the
+     server metadata, customize command-line arguments, and add volume mounts.
+     Provide step-by-step instructions for these configurations if needed for
+     the MCP server.
+   - **CLI Tab**: Provide multiple progressive examples from basic to advanced
+     usage, including security configurations.
+   - **Kubernetes Tab**: Include complete, working YAML manifests with proper
+     formatting and comments.
+
+3. **Sample Prompts**: Create 3-6 realistic prompts that demonstrate the
+   server's capabilities. Make them specific and actionable, not generic.
+
+4. **Recommended Practices**: Focus on security, performance, and reliability
+   best practices specific to the MCP server.
+
+**Critical Guidelines:**
+
+- Never add tools/capabilities sections (MCPMetadata handles this)
+- Always include the MCPMetadata component exactly as shown:
+  `<MCPMetadata name='server-name' />`
+- Ensure all examples are copy-pasteable and functional
+- Use proper YAML formatting with `title=` attributes for code blocks
+- Include security considerations like network isolation where relevant
+
+When creating a guide, start by gathering comprehensive information about the
+MCP server, then structure the content to progressively guide users from basic
+setup to advanced usage scenarios. Focus on practical value and ensure every
+example is something users can actually implement.
diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json
@@ -1,9 +1,14 @@
 {
   "name": "Docusaurus",
   "image": "mcr.microsoft.com/devcontainers/typescript-node:22-bookworm",
-  "features": {},
+  "features": {
+    "ghcr.io/devcontainers/features/docker-outside-of-docker:1": {}
+  },
   "forwardPorts": [3000],
-  "postCreateCommand": "npm install",
+  "containerEnv": {
+    "CI": "true"
+  },
+  "postStartCommand": "bash scripts/install-thv.sh && npm install",
   "customizations": {
     "vscode": {
       "extensions": [

diff --git a/.markdownlint-cli2.jsonc b/.markdownlint-cli2.jsonc
@@ -6,5 +6,6 @@
     "static/api-specs/*.md",
     ".github/pull_request_template.md",
     ".github/prompts/*.md",
+    ".claude/**/*.md",
   ],
 }
diff --git a/docs/theme-preview.mdx b/docs/theme-preview.mdx
@@ -182,9 +182,6 @@ A standard Markdown table:
 MDX Tabs component, default theme
 ([reference](https://docusaurus.io/docs/markdown-features/tabs))
 
-import Tabs from '@theme/Tabs';
-import TabItem from '@theme/TabItem';
-
 <Tabs>
   <TabItem value='apple' label='Apple' default>
     This is an apple 🍎

diff --git a/docs/toolhive/guides-cli/build-containers.mdx b/docs/toolhive/guides-cli/build-containers.mdx
@@ -5,9 +5,6 @@ description:
   CLI.
 ---
 
-import Tabs from '@theme/Tabs';
-import TabItem from '@theme/TabItem';
-
 This guide explains how to use the [`thv build`](../reference/cli/thv_build.md)
 command to build MCP server containers from protocol schemes without running
 them. This is useful for pre-building containers for Kubernetes deployments,

diff --git a/docs/toolhive/guides-cli/install.mdx b/docs/toolhive/guides-cli/install.mdx
@@ -3,9 +3,6 @@ title: Install ToolHive
 description: How to install, upgrade, and manage the ToolHive CLI.
 ---
 
-import Tabs from '@theme/Tabs';
-import TabItem from '@theme/TabItem';
-
 This guide walks you through installing, upgrading, and managing the ToolHive
 CLI ([`thv`](../reference/cli/thv.md)).
 

diff --git a/docs/toolhive/guides-cli/network-isolation.mdx b/docs/toolhive/guides-cli/network-isolation.mdx
@@ -3,9 +3,6 @@ title: Network isolation
 description: How to configure network isolation for MCP servers in ToolHive
 ---
 
-import Tabs from '@theme/Tabs';
-import TabItem from '@theme/TabItem';
-
 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

diff --git a/docs/toolhive/guides-cli/run-mcp-servers.mdx b/docs/toolhive/guides-cli/run-mcp-servers.mdx
@@ -3,9 +3,6 @@ title: Run MCP servers
 description: How to run MCP servers with the ToolHive CLI.
 ---
 
-import Tabs from '@theme/Tabs';
-import TabItem from '@theme/TabItem';
-
 This guide explains how to run Model Context Protocol (MCP) servers using
 ToolHive. It covers how to run servers from the ToolHive registry, customize
 server settings, and run custom servers using Docker images or protocol schemes.

diff --git a/docs/toolhive/guides-cli/secrets-management.mdx b/docs/toolhive/guides-cli/secrets-management.mdx
@@ -4,9 +4,6 @@ description:
   How to securely manage API tokens and other sensitive data in ToolHive.
 ---
 
-import Tabs from '@theme/Tabs';
-import TabItem from '@theme/TabItem';
-
 MCP servers often need secrets like API tokens, connection strings, and other
 sensitive parameters. ToolHive provides built-in secrets management features,
 letting you manage these values securely without exposing them in plaintext

diff --git a/docs/toolhive/guides-mcp/_template.mdx b/docs/toolhive/guides-mcp/_template.mdx
@@ -0,0 +1,60 @@
+---
+title: SERVER_NAME MCP server guide
+sidebar_label: SERVER_NAME
+description: Using the SERVER_NAME MCP server with ToolHive for PURPOSE.
+last_update:
+  author: YOUR_GITHUB_USERNAME
+  date: YYYY-MM-DD
+---
+
+## Overview
+
+A brief overview of the MCP server, its purpose, and key features. Link to the
+official documentation.
+
+## Metadata
+
+<MCPMetadata name='SERVER_NAME' />
+
+## Usage
+
+<Tabs groupId='mode' queryString='mode'>
+<TabItem value='ui' label='UI' default>
+
+UI instructions go here. Only include a screenshot if it adds value, such as
+showing a unique configuration option or feature.
+
+</TabItem>
+<TabItem value='cli' label='CLI'>
+
+CLI instructions go here, with multiple usage examples specific to the MCP
+server.
+
+```bash
+thv run ...
+```
+
+If appropriate, include guidance for using network isolation and/or a custom
+permission profile.
+
+</TabItem>
+<TabItem value='k8s' label='Kubernetes'>
+
+Kubernetes manifest and instructions go here
+
+```yaml title="SERVER_NAME.yaml"
+apiVersion: toolhive.stacklok.dev/v1alpha1
+kind: MCPServer
+```
+
+</TabItem>
+</Tabs>
+
+## Sample prompts
+
+Provide sample prompts that users can use to interact with the MCP server.
+
+## Recommended practices
+
+- Include some recommended practices for using the MCP server safely and
+  effectively