diff --git a/.github/workflows/cloudflare_sync.yaml b/.github/workflows/cloudflare_sync.yaml new file mode 100644 index 000000000000..3fac901d070e --- /dev/null +++ b/.github/workflows/cloudflare_sync.yaml @@ -0,0 +1,42 @@ +# Copyright 2026 Google LLC +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +name: "Sync v1 docsite to Cloudflare" + +concurrency: + group: cloudflare-sync + cancel-in-progress: true + +on: + workflow_run: + workflows: ["CF: Deploy Dev Docs", "CF: Deploy Versioned Docs", "CF: Deploy Previous Version Docs"] + types: [completed] + +jobs: + deploy: + runs-on: ubuntu-latest + if: ${{ github.event.workflow_run.conclusion == 'success' }} + steps: + - uses: actions/checkout@v4 + with: + ref: 'cloudflare-pages' + - name: Cleanup + run: | + rm -rf .git + - name: Cloudflare Deploy + uses: cloudflare/wrangler-action@v3 + with: + apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }} + accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }} + command: pages deploy . --project-name=toolbox-docs --branch=main \ No newline at end of file diff --git a/.github/workflows/deploy_dev_docs_to_cf.yaml b/.github/workflows/deploy_dev_docs_to_cf.yaml new file mode 100644 index 000000000000..ecd989516ecf --- /dev/null +++ b/.github/workflows/deploy_dev_docs_to_cf.yaml @@ -0,0 +1,87 @@ +# Copyright 2026 Google LLC +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +name: "CF: Deploy Dev Docs" + +permissions: + contents: write + +on: + push: + branches: + - main + paths: + - 'docs/**' + - '.github/workflows/docs*_cf.yaml' + - '.github/workflows/deploy*_cf.yaml' + - '.hugo/**' + + # Allow triggering manually. + workflow_dispatch: + +jobs: + deploy: + runs-on: ubuntu-24.04 + defaults: + run: + working-directory: .hugo + # This shared concurrency group ensures only one docs deployment runs at a time. + concurrency: + group: cf-docs-update + cancel-in-progress: false + steps: + - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6 + with: + fetch-depth: 0 + submodules: recursive + + - name: Setup Hugo + uses: peaceiris/actions-hugo@75d2e84710de30f6ff7268e08f310b60ef14033f # v3 + with: + hugo-version: "0.145.0" + extended: true + + - name: Setup Node + uses: actions/setup-node@6044e13b5dc448c55e2357c09f80417699197238 # v6 + with: + node-version: "22" + + - name: Cache dependencies + uses: actions/cache@cdf6c1fa76f9f475f3d7449005a359c84ca0f306 # v5 + with: + path: ~/.npm + key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }} + restore-keys: | + ${{ runner.os }}-node- + + - run: npm ci + - run: hugo --minify --config hugo.cloudflare.toml + env: + HUGO_BASEURL: https://mcp-toolbox.dev/dev/ + HUGO_RELATIVEURLS: false + + - name: Create Staging Directory + run: | + mkdir staging + mv public staging/dev + mv staging/dev/releases.releases staging/releases.releases + + - name: Push to Cloudflare Branch + uses: peaceiris/actions-gh-pages@4f9cc6602d3f66b9c108549d475ec49e8ef4d45e # v4 + with: + github_token: ${{ secrets.GITHUB_TOKEN }} + publish_dir: ./.hugo/staging + publish_branch: cloudflare-pages + keep_files: true + commit_message: "deploy: ${{ github.event.head_commit.message }}" diff --git a/.github/workflows/deploy_previous_version_docs_to_cf.yaml b/.github/workflows/deploy_previous_version_docs_to_cf.yaml new file mode 100644 index 000000000000..f5c6f5b3cca9 --- /dev/null +++ b/.github/workflows/deploy_previous_version_docs_to_cf.yaml @@ -0,0 +1,104 @@ +# Copyright 2026 Google LLC +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +name: "CF: Deploy Previous Version Docs" + +on: + workflow_dispatch: + inputs: + version_tag: + description: 'The old version tag to build docs for (e.g., v0.15.0)' + required: true + type: string + +jobs: + build_and_deploy: + runs-on: ubuntu-latest + permissions: + contents: write + + steps: + - name: Checkout main branch (for latest templates and theme) + uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6 + with: + ref: 'main' + submodules: 'recursive' + fetch-depth: 0 + + - name: Checkout old content from tag into a temporary directory + uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6 + with: + ref: ${{ github.event.inputs.version_tag }} + path: 'old_version_source' # Checkout into a temp subdir + # Sparse checkout to only get the content directory + sparse-checkout: | + docs + + - name: Replace content with old version + run: | + # Remove the current content directory from the main branch checkout + rm -rf docs/ + # Move the old content directory into place + mv ./old_version_source/docs docs + + - name: Setup Hugo and Node + uses: peaceiris/actions-hugo@75d2e84710de30f6ff7268e08f310b60ef14033f # v3 + with: + hugo-version: "0.145.0" + extended: true + - uses: actions/setup-node@6044e13b5dc448c55e2357c09f80417699197238 # v6 + with: + node-version: "22" + + - name: Install Dependencies + run: npm ci + working-directory: .hugo + + - name: Build Hugo Site for Archived Version + run: hugo --minify --config hugo.cloudflare.toml + working-directory: .hugo + env: + HUGO_BASEURL: https://mcp-toolbox.dev/${{ github.event.inputs.version_tag }}/ + HUGO_RELATIVEURLS: false + + - name: Deploy to cloudflare-pages + uses: peaceiris/actions-gh-pages@v4 + with: + github_token: ${{ secrets.GITHUB_TOKEN }} + publish_dir: .hugo/public + publish_branch: cloudflare-pages + destination_dir: ./${{ github.event.inputs.version_tag }} + keep_files: true + allow_empty_commit: true + commit_message: "docs(backport): deploy docs for ${{ github.event.inputs.version_tag }}" + + - name: Clean Build Directory + run: rm -rf .hugo/public + + - name: Build Hugo Site + run: hugo --minify --config hugo.cloudflare.toml + working-directory: .hugo + env: + HUGO_BASEURL: https://mcp-toolbox.dev/ + HUGO_RELATIVEURLS: false + + - name: Deploy to root + uses: peaceiris/actions-gh-pages@4f9cc6602d3f66b9c108549d475ec49e8ef4d45e # v4 + with: + github_token: ${{ secrets.GITHUB_TOKEN }} + publish_dir: .hugo/public + publish_branch: cloudflare-pages + keep_files: true + allow_empty_commit: true + commit_message: "deploy: docs to root for ${{ github.event.inputs.version_tag }}" diff --git a/.github/workflows/deploy_versioned_docs_to_cf.yaml b/.github/workflows/deploy_versioned_docs_to_cf.yaml new file mode 100644 index 000000000000..8cb2e719a362 --- /dev/null +++ b/.github/workflows/deploy_versioned_docs_to_cf.yaml @@ -0,0 +1,93 @@ +# Copyright 2026 Google LLC +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +name: "CF: Deploy Versioned Docs" + +permissions: + contents: write + +on: + release: + types: [published] + +jobs: + deploy: + runs-on: ubuntu-24.04 + # This shared concurrency group ensures only one docs deployment runs at a time. + concurrency: + group: cf-docs-update + cancel-in-progress: false + steps: + - name: Checkout Code at Tag + uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6 + with: + ref: ${{ github.event.release.tag_name }} + + - name: Get Version from Release Tag + id: get_version + env: + RELEASE_TAG: ${{ github.event.release.tag_name }} + run: echo "VERSION=${RELEASE_TAG}" >> "$GITHUB_OUTPUT" + + - name: Setup Hugo + uses: peaceiris/actions-hugo@75d2e84710de30f6ff7268e08f310b60ef14033f # v3 + with: + hugo-version: "0.145.0" + extended: true + + - name: Setup Node + uses: actions/setup-node@6044e13b5dc448c55e2357c09f80417699197238 # v6 + with: + node-version: "22" + + - name: Install Dependencies + run: npm ci + working-directory: .hugo + + - name: Build Hugo Site + run: hugo --minify --config hugo.cloudflare.toml + working-directory: .hugo + env: + HUGO_BASEURL: https://mcp-toolbox.dev/${{ steps.get_version.outputs.VERSION }}/ + HUGO_RELATIVEURLS: false + + - name: Deploy + uses: peaceiris/actions-gh-pages@4f9cc6602d3f66b9c108549d475ec49e8ef4d45e # v4 + with: + github_token: ${{ secrets.GITHUB_TOKEN }} + publish_dir: .hugo/public + publish_branch: cloudflare-pages + destination_dir: ./${{ steps.get_version.outputs.VERSION }} + keep_files: true + commit_message: "deploy: docs for ${{ steps.get_version.outputs.VERSION }}" + + - name: Clean Build Directory + run: rm -rf .hugo/public + + - name: Build Hugo Site + run: hugo --minify --config hugo.cloudflare.toml + working-directory: .hugo + env: + HUGO_BASEURL: https://mcp-toolbox.dev/ + HUGO_RELATIVEURLS: false + + - name: Deploy to root + uses: peaceiris/actions-gh-pages@4f9cc6602d3f66b9c108549d475ec49e8ef4d45e # v4 + with: + github_token: ${{ secrets.GITHUB_TOKEN }} + publish_dir: .hugo/public + publish_branch: cloudflare-pages + keep_files: true + allow_empty_commit: true + commit_message: "deploy: docs to root for ${{ steps.get_version.outputs.VERSION }}" diff --git a/.github/workflows/docs_preview_clean_cf.yaml b/.github/workflows/docs_preview_clean_cf.yaml new file mode 100644 index 000000000000..b7f6361124b5 --- /dev/null +++ b/.github/workflows/docs_preview_clean_cf.yaml @@ -0,0 +1,73 @@ +# Copyright 2026 Google LLC +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +name: "CF: Cleanup PR Preview" + +permissions: + pull-requests: write + +# This Workflow depends on 'github.event.number', +# not compatible with branch or manual triggers. +on: + pull_request: + types: + - closed + +jobs: + clean: + # Only run for PRs from the same repository to ensure secret access + if: "${{ github.event.pull_request.head.repo.full_name == github.event.pull_request.base.repo.full_name }}" + runs-on: ubuntu-24.04 + concurrency: + # Shared concurrency group with preview staging. + group: "cf-preview-${{ github.event.number }}" + cancel-in-progress: true + steps: + - name: Delete Cloudflare Pages Deployments via API + env: + ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }} + API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }} + PROJECT_NAME: toolbox-docs + BRANCH_NAME: pr-${{ github.event.number }} + run: | + echo "Fetching deployments for preview branch: $BRANCH_NAME" + + # Fetch the most recent deployments from your Cloudflare project + RESPONSE=$(curl -s -X GET "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/pages/projects/$PROJECT_NAME/deployments" \ + -H "Authorization: Bearer $API_TOKEN") + + # Use 'jq' to extract all deployment IDs that match this specific PR branch alias + IDS=$(echo "$RESPONSE" | jq -r --arg branch "$BRANCH_NAME" '.result[] | select(.deployment_trigger.metadata.branch? == $branch) | .id') + + if [ -z "$IDS" ]; then + echo "No preview deployments found to clean up." + else + for id in $IDS; do + echo "Deleting Cloudflare deployment ID: $id" + curl -s -X DELETE "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/pages/projects/$PROJECT_NAME/deployments/$id?force=true" \ + -H "Authorization: Bearer $API_TOKEN" + done + echo "Successfully removed preview environment." + fi + + - name: Comment + uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8 + with: + script: | + github.rest.issues.createComment({ + issue_number: context.payload.number, + owner: context.repo.owner, + repo: context.repo.repo, + body: "๐Ÿงจ **Preview deployments removed.**\n\nCloudflare Pages environments for `pr-${{ github.event.number }}` have been deleted." + }) diff --git a/.github/workflows/docs_preview_deploy_cf.yaml b/.github/workflows/docs_preview_deploy_cf.yaml new file mode 100644 index 000000000000..71a6f7c65c34 --- /dev/null +++ b/.github/workflows/docs_preview_deploy_cf.yaml @@ -0,0 +1,92 @@ +# Copyright 2026 Google LLC +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +name: "CF: Deploy PR Preview" + +permissions: + contents: read + pull-requests: write + +# This Workflow depends on 'github.event.number', +# not compatible with branch or manual triggers. +on: + pull_request: + paths: + - 'docs/**' + - '.github/workflows/docs*_cf.yaml' + - '.github/workflows/deploy*_cf.yaml' + - '.hugo/**' + +jobs: + preview: + # Only run for PRs from the same repository to ensure secret access + if: "${{ github.event.pull_request.head.repo.full_name == github.event.pull_request.base.repo.full_name }}" + runs-on: ubuntu-24.04 + defaults: + run: + working-directory: .hugo + concurrency: + # Shared concurrency group with preview cleanup. + group: "cf-preview-${{ github.event.number }}" + cancel-in-progress: true + steps: + - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6 + with: + ref: ${{ github.event.pull_request.head.sha }} + fetch-depth: 0 # Fetch all history for .GitInfo and .Lastmod + + - name: Setup Hugo + uses: peaceiris/actions-hugo@75d2e84710de30f6ff7268e08f310b60ef14033f # v3 + with: + hugo-version: "0.145.0" + extended: true + + - name: Setup Node + uses: actions/setup-node@6044e13b5dc448c55e2357c09f80417699197238 # v6 + with: + node-version: "22" + + - name: Cache dependencies + uses: actions/cache@cdf6c1fa76f9f475f3d7449005a359c84ca0f306 # v5 + with: + path: ~/.npm + key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }} + restore-keys: | + ${{ runner.os }}-node- + + - run: npm ci + - run: hugo --minify --config hugo.cloudflare.toml + env: + HUGO_BASEURL: "/" + HUGO_ENVIRONMENT: preview + HUGO_RELATIVEURLS: false + + - name: Deploy to Cloudflare Pages via Wrangler + id: cf_deploy + uses: cloudflare/wrangler-action@v3 + with: + apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }} + accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }} + command: pages deploy .hugo/public --project-name toolbox-docs --branch pr-${{ github.event.number }} + + - name: Comment + uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8 + with: + script: | + github.rest.issues.createComment({ + issue_number: context.payload.number, + owner: context.repo.owner, + repo: context.repo.repo, + body: "๐Ÿš€ **Cloudflare Preview is building!**\n\n๐Ÿ”Ž View Preview: ${{ steps.cf_deploy.outputs.pages-deployment-alias-url }}\n\n*(Note: It may take a minute or two for Cloudflare to finish deploying the branch)*" + }) diff --git a/.hugo/hugo.cloudflare.toml b/.hugo/hugo.cloudflare.toml new file mode 100644 index 000000000000..1be869e7f330 --- /dev/null +++ b/.hugo/hugo.cloudflare.toml @@ -0,0 +1,152 @@ +# Copyright 2026 Google LLC +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +title = 'MCP Toolbox for Databases' +relativeURLs = false + +languageCode = 'en-us' +defaultContentLanguage = "en" +defaultContentLanguageInSubdir = false + +enableGitInfo = true +enableRobotsTXT = true + +ignoreFiles = ["quickstart/shared", "quickstart/python", "quickstart/js", "quickstart/go"] + +[languages] + [languages.en] + languageName ="English" + weight = 1 + +[module] + proxy = "direct" + [module.hugoVersion] + extended = true + min = "0.146.0" + [[module.mounts]] + source = "../docs/en" + target = 'content' + [[module.imports]] + path = "github.com/google/docsy" + disable = false + [[module.imports]] + path = "github.com/martignoni/hugo-notice" + +[params] + description = "MCP Toolbox for Databases is an open source MCP server for databases. It enables you to develop tools easier, faster, and more securely by handling the complexities such as connection pooling, authentication, and more." + copyright = "Google LLC" + github_repo = "https://github.com/googleapis/genai-toolbox" + github_project_repo = "https://github.com/googleapis/genai-toolbox" + github_subdir = "docs" + offlineSearch = true + version_menu = "Releases" + disableMigrationBanner = true + releases_url = "/releases.releases" + global_logo_url = "/" + [params.ui] + ul_show = 100 + showLightDarkModeMenu = true + breadcrumb_disable = true + sidebar_menu_foldable = true + sidebar_menu_compact = false + +[[params.versions]] + version = "Dev" + url = "https://mcp-toolbox.dev/dev/" + +# Add a new version block here before every release +# The order of versions in this file is mirrored into the dropdown + +[[params.versions]] + version = "v0.28.0" + url = "https://mcp-toolbox.dev/v0.28.0/" + +[[params.versions]] + version = "v0.27.0" + url = "https://mcp-toolbox.dev/v0.27.0/" + +[[params.versions]] + version = "v0.26.0" + url = "https://mcp-toolbox.dev/v0.26.0/" + +[[params.versions]] + version = "v0.25.0" + url = "https://mcp-toolbox.dev/v0.25.0/" + +[[params.versions]] + version = "v0.24.0" + url = "https://mcp-toolbox.dev/v0.24.0/" + +[[params.versions]] + version = "v0.23.0" + url = "https://mcp-toolbox.dev/v0.23.0/" + +[[params.versions]] + version = "v0.22.0" + url = "https://mcp-toolbox.dev/v0.22.0/" + +[[params.versions]] + version = "v0.21.0" + url = "https://mcp-toolbox.dev/v0.21.0/" + +[[params.versions]] + version = "v0.20.0" + url = "https://mcp-toolbox.dev/v0.20.0/" + +[[params.versions]] + version = "v0.19.1" + url = "https://mcp-toolbox.dev/v0.19.1/" + +[[params.versions]] + version = "v0.18.0" + url = "https://mcp-toolbox.dev/v0.18.0/" + +[[params.versions]] + version = "v0.17.0" + url = "https://mcp-toolbox.dev/v0.17.0/" + +[[menu.main]] + name = "GitHub" + weight = 50 + url = "https://github.com/googleapis/genai-toolbox" + pre = "" + +[markup.goldmark.renderer] + unsafe= true + +[markup.highlight] + noClasses = false + style = "tango" + +[outputFormats] + [outputFormats.LLMS] + mediaType = "text/plain" + baseName = "llms" + isPlainText = true + root = true + [outputFormats.LLMS-FULL] + mediaType = "text/plain" + baseName = "llms-full" + isPlainText = true + root = true + [outputFormats.releases] + baseName = 'releases' + isPlainText = true + mediaType = 'text/releases' + +[mediaTypes."text/releases"] + suffixes = ["releases"] + +[outputs] + home = ["HTML", "RSS", "LLMS", "LLMS-FULL", "releases"] diff --git a/docs/en/user-guide/configuration/toolbox-ui/edit-headers.gif b/docs/en/user-guide/configuration/toolbox-ui/edit-headers.gif index b63860dca005..f8fcc66e1d87 100644 Binary files a/docs/en/user-guide/configuration/toolbox-ui/edit-headers.gif and b/docs/en/user-guide/configuration/toolbox-ui/edit-headers.gif differ diff --git a/docs/en/user-guide/introduction/_index.md b/docs/en/user-guide/introduction/_index.md index d817a420a67b..ed421e09813e 100644 --- a/docs/en/user-guide/introduction/_index.md +++ b/docs/en/user-guide/introduction/_index.md @@ -77,7 +77,7 @@ redeploying your application. ## Getting Started -### Quickstart: Running Toolbox using npx +### Quickstart: Running Toolbox using NPX You can run Toolbox directly with a [configuration file](../configuration/_index.md):