Add the CRD reference and automation

.github/workflows/update-toolhive-reference.yml

@@ -2,13 +2,22 @@ name: Update ToolHive Reference Docs
 
 on:
   workflow_dispatch:
+    inputs:
+      version:
+        description: 'ToolHive version to update reference docs for'
+        required: true
+        default: 'latest'
   repository_dispatch:
     types: [published-release]
 
 permissions:
   contents: write
   pull-requests: write
 
+concurrency:
+  group: update-toolhive-reference
+  cancel-in-progress: false
+
 jobs:
   update-reference:
     runs-on: ubuntu-latest
@@ -23,11 +32,23 @@ jobs:
           git config --global user.name "github-actions[bot]"
           git config --global user.email "github-actions[bot]@users.noreply.github.com"
 
-      - name: Run update-toolhive-reference.sh and capture version
+      - name: Determine version
+        id: get-version
+        run: |
+          if [[ "${{ github.event_name }}" == "repository_dispatch" ]]; then
+            echo "version=${{ github.event.client_payload.version }}" >> $GITHUB_OUTPUT
+          else
+            echo "version=${{ github.event.inputs.version }}" >> $GITHUB_OUTPUT
+          fi
+
+      - name: Run update script
         id: imports
         run: |
           chmod +x scripts/update-toolhive-reference.sh
-          scripts/update-toolhive-reference.sh
+          if ! scripts/update-toolhive-reference.sh ${{ steps.get-version.outputs.version }}; then
+            echo "::error::Failed to update ToolHive reference docs"
+            exit 1
+          fi
 
       - name: Check for changes
         id: git-diff

.markdownlint-cli2.jsonc

@@ -1,5 +1,5 @@
 {
   "gitignore": true,
   "globs": ["**/*.md"],
-  "ignores": ["docs/toolhive/reference/cli/"],
+  "ignores": ["docs/toolhive/reference/cli/", "static/api-specs/*.md"],
 }

.vscode/settings.json

@@ -9,20 +9,7 @@
   "prettier.requireConfig": true,
   "yaml.format.proseWrap": "always",
   "css.lint.emptyRules": "ignore",
-
-  "[markdown]": {
-    "editor.defaultFormatter": "esbenp.prettier-vscode"
-  },
-  "[mdx]": {
-    "editor.defaultFormatter": "esbenp.prettier-vscode"
-  },
-  "[css]": {
-    "editor.defaultFormatter": "esbenp.prettier-vscode"
-  },
-  "[json]": {
-    "editor.defaultFormatter": "esbenp.prettier-vscode"
-  },
-  "[yaml]": {
+  "[markdown][mdx][css][json][jsonc][yaml]": {
     "editor.defaultFormatter": "esbenp.prettier-vscode"
   }
 }

docs/toolhive/guides-k8s/run-mcp-k8s.md

@@ -163,6 +163,10 @@ When you apply an `MCPServer` resource, here's what happens:
 
 :::
 
+For more examples of `MCPServer` resources, see the
+[example MCP server manifests](https://github.com/stacklok/toolhive/tree/main/examples/operator/mcp-servers)
+in the ToolHive repo.
+
 ## Automatic RBAC management
 
 The ToolHive operator automatically handles RBAC (Role-Based Access Control) for
@@ -185,14 +189,13 @@ This approach provides:
 - Better security isolation between different MCPServer instances
 - Support for multi-tenant deployments across different namespaces
 
-For more examples of `MCPServer` resources, see the
-[example MCP server manifests](https://github.com/stacklok/toolhive/tree/main/examples/operator/mcp-servers)
-in the ToolHive repo.
-
 ## Customize server settings
 
 You can customize the MCP server by adding additional fields to the `MCPServer`
-resource. Here are some common configurations.
+resource. The full specification is available in the
+[Kubernetes CRD reference](../reference/crd-spec.mdx).
+
+Below are some common configurations.
 
 ### Customize the MCP server pod
 
@@ -363,56 +366,19 @@ For more details about a specific MCP server:
 kubectl -n <NAMESPACE> describe mcpserver <NAME>
 ```
 
-## Configuration reference
-
-### MCPServer spec
-
-| Field               | Description                                     | Required | Default |
-| ------------------- | ----------------------------------------------- | -------- | ------- |
-| `image`             | Container image for the MCP server              | Yes      | -       |
-| `transport`         | Transport method (stdio or sse)                 | No       | stdio   |
-| `port`              | Port to expose the MCP server on                | No       | 8080    |
-| `targetPort`        | Port to use for the MCP server (for SSE)        | No       |         |
-| `args`              | Additional arguments to pass to the MCP server  | No       | -       |
-| `env`               | Environment variables to set in the container   | No       | -       |
-| `resources`         | Resource requirements for the container         | No       | -       |
-| `secrets`           | References to secrets to mount in the container | No       | -       |
-| `permissionProfile` | Permission profile configuration                | No       | -       |
-| `podTemplateSpec`   | Custom pod specification for the MCP server     | No       | -       |
-
-### Secrets
-
-The `secrets` field has the following parameters:
-
-- `name`: The name of the Kubernetes secret (required)
-- `key`: The key in the secret (required)
-- `targetEnvName`: The environment variable to be used when setting up the
-  secret in the MCP server (optional). If left unspecified, it defaults to the
-  key.
-
-### Permission Profiles
-
-Permission profiles can be configured in two ways:
-
-1. Using a built-in profile:
-
-   ```yaml
-   permissionProfile:
-     type: builtin
-     name: network # or "none"
-   ```
+## Next steps
 
-2. Using a ConfigMap:
+See the [Client compatibility](../reference/client-compatibility.mdx) reference
+to learn how to connect to MCP servers using different clients.
 
-   ```yaml
-   permissionProfile:
-     type: configmap
-     name: my-permission-profile
-     key: profile.json
-   ```
+## Related information
 
-The ConfigMap should contain a JSON
-[permission profile](../guides-cli/custom-permissions.mdx#create-a-custom-permission-profile).
+- [Kubernetes CRD reference](../reference/crd-spec.mdx) - Reference for the
+  `MCPServer` Custom Resource Definition (CRD)
+- [Deploy the operator using Helm](./deploy-operator-helm.md) - Install the
+  ToolHive operator
+- [Custom permissions](../guides-cli/custom-permissions.mdx) - Configure
+  permission profiles
 
 :::important
 
@@ -425,18 +391,6 @@ visiting our [GitHub repository](https://github.com/stacklok/toolhive).
 
 :::
 
-## Next steps
-
-See the [Client compatibility](../reference/client-compatibility.mdx) reference
-to learn how to connect to MCP servers using different clients.
-
-## Related information
-
-- [Deploy the operator using Helm](./deploy-operator-helm.md) - Install the
-  ToolHive operator
-- [Custom permissions](../guides-cli/custom-permissions.mdx) - Configure
-  permission profiles
-
 ## Troubleshooting
 
 ### MCPServer resource not creating pods

docs/toolhive/reference/crd-spec.mdx

@@ -0,0 +1,11 @@
+---
+title: Kubernetes CRD reference
+description:
+  ToolHive Kubernetes Operator Custom Resource Definitions (CRDs) reference.
+sidebar_position: 30
+toc_max_heading_level: 4
+---
+
+import CRDRef from '@site/static/api-specs/crd-api.md';
+
+<CRDRef />

scripts/update-toolhive-reference.sh

@@ -1,7 +1,9 @@
 #!/bin/bash
 
+set -euo pipefail
+
 REPO_ROOT=$(git rev-parse --show-toplevel)
-cd $REPO_ROOT
+cd "$REPO_ROOT"
 
 IMPORT_DIR="./imports"
 DOCS_DIR="./docs"
@@ -20,39 +22,108 @@ if [ ! -d "$STATIC_DIR" ]; then
     exit 1
 fi
 
-RELEASE_JSON=$(curl -s https://api.github.com/repos/stacklok/toolhive/releases/latest)
-LATEST_RELEASE_TARBALL=$(echo "$RELEASE_JSON" | grep "tarball_url" | cut -d '"' -f 4)
-LATEST_RELEASE_VERSION=$(echo "$RELEASE_JSON" | grep '"tag_name"' | cut -d '"' -f 4)
+# Check if jq is installed
+if ! command -v jq >/dev/null 2>&1; then
+    echo "Error: 'jq' is required but not installed. Please install jq and try again."
+    exit 1
+fi
+
+VERSION=$(echo "${1:-}" | tr -cd '[:alnum:].-')
+
+# Handle tag name parameter - default to "latest" if not provided
+if [ -z "$VERSION" ] || [ "$VERSION" = "latest" ]; then
+    API_ENDPOINT="https://api.github.com/repos/stacklok/toolhive/releases/latest"
+    echo "No tag specified or 'latest' specified, using latest release"
+else
+    TAG_NAME="$VERSION"
+    API_ENDPOINT="https://api.github.com/repos/stacklok/toolhive/releases/tags/$TAG_NAME"
+    echo "Using specified tag: $TAG_NAME"
+fi
+
+# Fetch release information
+RELEASE_JSON=$(curl -sf "$API_ENDPOINT" || {
+    echo "Failed to fetch release information from GitHub API"
+    exit 1
+})
+RELEASE_TARBALL=$(echo "$RELEASE_JSON" | jq -r '.tarball_url // empty')
+RELEASE_VERSION=$(echo "$RELEASE_JSON" | jq -r '.tag_name // empty')
 
-if [ -z "$LATEST_RELEASE_TARBALL" ]; then
-    echo "Failed to get the latest release tarball URL for ${LATEST_RELEASE_VERSION}"
+if [ -z "$RELEASE_TARBALL" ]; then
+    echo "Failed to get release tarball URL for release: ${RELEASE_VERSION}"
+    echo "Please check if the tag exists in the repository"
     exit 1
 fi
 
-# Output the latest release version for use in CI workflows
-if [ ! -z "$GITHUB_OUTPUT" ]; then
-    echo "version=$LATEST_RELEASE_VERSION" >> "$GITHUB_OUTPUT"
+# Output the release version for use in CI workflows (if running in GitHub Actions)
+if [ -n "${GITHUB_OUTPUT:-}" ]; then
+    echo "version=$RELEASE_VERSION" >> "$GITHUB_OUTPUT"
 fi
 
+# Clean up and prepare import directory
 rm -rf ${IMPORT_DIR}/toolhive
 mkdir -p ${IMPORT_DIR}/toolhive
 
-echo "Fetching the latest ToolHive release (${LATEST_RELEASE_VERSION}) from: $LATEST_RELEASE_TARBALL"
+echo "Fetching ToolHive release (${RELEASE_VERSION}) from: $RELEASE_TARBALL"
 echo "Importing to: $IMPORT_DIR"
 
-curl -sL "$LATEST_RELEASE_TARBALL" | tar xz --strip-components=1  -C ./imports/toolhive
-
-## CLI reference
-
-echo "Updating ToolHive CLI reference documentation in ${DOCS_DIR}/toolhive/reference/cli"
-
-# Remove existing CLI reference documentation files in case we remove any commands
-rm -f ${DOCS_DIR}/toolhive/reference/cli/thv_*.md
-
-cp -r ${IMPORT_DIR}/toolhive/docs/cli/* ${DOCS_DIR}/toolhive/reference/cli
-
-## API reference
-
-echo "Updating ToolHive API reference in ${STATIC_DIR}/api-specs"
+# Download and extract the release tarball
+curl -sfL "$RELEASE_TARBALL" | tar xz --strip-components=1 -C ./imports/toolhive
+
+# Determine release type and process accordingly
+if [[ "$RELEASE_VERSION" =~ ^v.* ]]; then
+    echo "Processing main CLI release: $RELEASE_VERSION"
+
+    ## CLI reference
+    echo "Updating ToolHive CLI reference documentation in ${DOCS_DIR}/toolhive/reference/cli"
+
+    # Remove existing CLI reference documentation files in case we remove any commands
+    rm -f ${DOCS_DIR}/toolhive/reference/cli/thv_*.md
+
+    # Copy CLI documentation
+    if [ -d "${IMPORT_DIR}/toolhive/docs/cli" ]; then
+        cp -r ${IMPORT_DIR}/toolhive/docs/cli/* ${DOCS_DIR}/toolhive/reference/cli
+        echo "CLI reference documentation updated successfully"
+    else
+        echo "Warning: CLI documentation not found in ${IMPORT_DIR}/toolhive/docs/cli"
+    fi
+
+    ## API reference
+    echo "Updating ToolHive API reference in ${STATIC_DIR}/api-specs"
+
+    # Copy API specification
+    if [ -f "${IMPORT_DIR}/toolhive/docs/server/swagger.yaml" ]; then
+        cp ${IMPORT_DIR}/toolhive/docs/server/swagger.yaml ${STATIC_DIR}/api-specs/toolhive-api.yaml
+        echo "API reference updated successfully"
+    else
+        echo "Warning: API specification not found in ${IMPORT_DIR}/toolhive/docs/server/swagger.yaml"
+    fi
+
+    elif [[ "$RELEASE_VERSION" =~ ^toolhive-operator-crds-.* ]]; then
+    echo "Processing operator CRD release: $RELEASE_VERSION"
+
+    ## CRD API reference
+    echo "Updating ToolHive CRD API reference in ${STATIC_DIR}/api-specs"
+
+    # Copy CRD API documentation
+    if [ -f "${IMPORT_DIR}/toolhive/docs/operator/crd-api.md" ]; then
+        # Remove h1 title from the CRD API documentation, Docusaurus will use the title from the front matter
+        sed '1{/^# /d;}' ${IMPORT_DIR}/toolhive/docs/operator/crd-api.md > ${STATIC_DIR}/api-specs/crd-api.md
+        echo "CRD API reference updated successfully"
+    else
+        echo "Warning: CRD API documentation not found in ${IMPORT_DIR}/toolhive/docs/operator/crd-api.md"
+    fi
+
+    elif [[ "$RELEASE_VERSION" =~ ^toolhive-operator- ]]; then
+    echo "Processing main operator release: $RELEASE_VERSION"
+    echo "Placeholder: No specific processing implemented for this release type yet"
+
+else
+    echo "Unknown release type for tag: $RELEASE_VERSION"
+    echo "Supported release types:"
+    echo "  - v* (main CLI releases)"
+    echo "  - toolhive-operator-crds-* (CRD releases)"
+    echo "  - toolhive-operator-* (other operator releases)"
+    exit 1
+fi
 
-cp -r ${IMPORT_DIR}/toolhive/docs/server/swagger.yaml ${STATIC_DIR}/api-specs/toolhive-api.yaml
+echo "Release processing completed for: $RELEASE_VERSION"