Skip to content

πŸš€ The fast, Pythonic way to build MCP servers and clients.

docs: preserve docs routing metadata and release guidance (#6320)

nate nowack6884153bfe5b
diff --git a/.agents/skills/docs/SKILL.md b/.agents/skills/docs/SKILL.md
index d6cfa15b8..ac7a226e1 100644
--- a/.agents/skills/docs/SKILL.md
+++ b/.agents/skills/docs/SKILL.md
@@ -5,7 +5,7 @@ description: Write or revise a page under docs/ for gofastmcp.com. Use when addi
# FastMCP docs
-The docs are a Mintlify site built from `docs/`. A page exists only when `docs/docs.json` lists it, and a feature exists only when a page documents it. `docs/python-sdk/**` is generated from docstrings by a bot; edit the docstring, not the page.
+The docs are a Mintlify site built from `docs/` on `published-docs`, served at `https://gofastmcp.com/docs`. The separate `PrefectHQ/gofastmcp-website` repository deploys its `main` branch to Vercel, serves the root landing page, and proxies these docs under `/docs`. Author docs here on `main`; website changes belong in that repository. A page exists only when `docs/docs.json` lists it, and a feature exists only when a page documents it. `docs/python-sdk/**` is generated from docstrings by a bot; edit the docstring, not the page.
## Procedure
diff --git a/.agents/skills/release/SKILL.md b/.agents/skills/release/SKILL.md
index 562a4456d..64d9b45d7 100644
--- a/.agents/skills/release/SKILL.md
+++ b/.agents/skills/release/SKILL.md
@@ -10,8 +10,12 @@ the current major and `release/3.x` for 3.x maintenance. Every step runs against
branch, including the docs PR, so a maintenance entry lands in the maintenance
branch's own changelog above its newest 3.x entry. The tag triggers `Publish fastmcp-slim to PyPI`;
its success fans out to `fastmcp-tasks`, `fastmcp-remote`, and `fastmcp`, and the
-`fastmcp` publish job opens the `published-docs` PR that makes gofastmcp.com reflect
-the release. Two hand-maintained docs files mirror every release and must be on the
+`fastmcp` publish job opens the `published-docs` PR for stable release-triggered
+publication when the release SHA is an ancestor of the default branch. Prereleases
+and manual package-workflow dispatch do not open that PR. Mintlify builds `docs/`
+from `published-docs` at `https://gofastmcp.com/docs`; the separate
+`PrefectHQ/gofastmcp-website` repository deploys its `main` to Vercel for the landing
+page and `/docs` proxy. Two hand-maintained docs files mirror every release and must be on the
tagged commit, so the docs PR always lands first. PyPI releases are immutable; a bad
one gets a follow-up patch, never a re-tag.
@@ -142,8 +146,9 @@ one gets a follow-up patch, never a re-tag.
Confirm each package with `curl -fsS https://pypi.org/pypi/<pkg>/<new>/json | jq .info.version`;
the unversioned endpoint lags a few minutes.
-7. **Publish docs** (`main` releases only; maintenance releases skip this step and
- leave gofastmcp.com on the current major). When the `fastmcp` run finishes, its last job has opened
+7. **Publish docs** (eligible stable releases from the default-branch lineage only;
+ maintenance releases leave gofastmcp.com/docs on the current major). After a
+ successful eligible `fastmcp` run, its last job has opened
`Publish FastMCP v<new> docs` against `published-docs`:
```bash
@@ -151,6 +156,8 @@ one gets a follow-up patch, never a re-tag.
gh pr merge <n> --merge --admin
```
+ Before merging, apply the publication checks below to the PR's exact release
+ tree; a later fix on `main` does not change an existing release candidate.
Merging pushes `published-docs`, which runs the `Deploy docs` workflow: it asks
Mintlify's admin API for a deployment of the tip and waits for the verdict.
That run is the signal that the site changed; the merge alone proves nothing.
@@ -165,7 +172,7 @@ one gets a follow-up patch, never a re-tag.
`gh workflow run deploy-docs.yml --ref published-docs` once their incident clears.
Verify through the markdown endpoints, which bypass the HTML edge cache:
- `curl -fsS https://gofastmcp.com/changelog.md | grep -c "<pun>"`, and the same
+ `curl -fsS https://gofastmcp.com/docs/changelog.md | grep -c "<pun>"`, and the same
for `updates.md` and any page the release touched.
## Publishing docs by hand
@@ -173,6 +180,9 @@ one gets a follow-up patch, never a re-tag.
Used when a deploy failed and was fixed on `main`, or for a docs change outside a
release. The publication commit must match `main`'s tree exactly.
+Before preparing the PR, apply the publication checks below to the selected main
+tree. This publishes the entire tree, not just the changed page.
+
```bash
git fetch origin main published-docs
git checkout -b publish-docs-<topic> origin/published-docs
@@ -185,6 +195,30 @@ gh pr merge <n> --merge --admin
Then watch the `Deploy docs` run and verify the endpoints as in step 7.
+## Publication checks
+
+Invoking this skill or requesting documentation alone does not authorize a merge,
+package release, docs publication, or infrastructure change. Use the maintainer's
+explicit scope. Follow repository review policy unless the maintainer explicitly
+authorizes an available admin merge; example flags alone do not grant permission.
+An agent review is not an independent human GitHub approval.
+
+Compare `docs/docs.json` in the actual publication candidate (the release SHA for
+an automatic PR, selected main SHA for a manual PR) with `published-docs`. Preserve
+`logo.href = https://gofastmcp.com`,
+`seo.metatags.canonical = https://gofastmcp.com/docs`, and
+`seo.organization.logo = https://gofastmcp.com/docs/assets/brand/wordmark.png`.
+If missing, hold publication and reconcile the source and candidate through review.
+A main-only fix does not repair an already generated release tree.
+
+After Deploy docs succeeds, verify changed pages and their `.md` forms under
+`/docs`, search, assets, and version switching. For routing changes also verify
+old links redirect to one `/docs` prefix with queries and browser anchors intact,
+production canonicals, and root `/mcp` initialization, tools/list, and read-only
+search. Ordinary publication leaves domains and Mintlify's `/docs` base path alone.
+Manual dispatch or rerunning an old Deploy docs run deploys the configured tip;
+it does not restore that run's historical tree.
+
## Template: notes file for a patch
```
@@ -212,5 +246,5 @@ connections instead of raising.
Each of these prints a count above zero:
`curl -fsS https://pypi.org/pypi/fastmcp/<new>/json | grep -c '"version"'`,
-`curl -fsS https://gofastmcp.com/changelog.md | grep -c "<pun>"`,
-`curl -fsS https://gofastmcp.com/updates.md | grep -c "<pun>"`.
+`curl -fsS https://gofastmcp.com/docs/changelog.md | grep -c "<pun>"`,
+`curl -fsS https://gofastmcp.com/docs/updates.md | grep -c "<pun>"`.
diff --git a/AGENTS.md b/AGENTS.md
index ddf9d8033..846abf50f 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -129,7 +129,7 @@ Load the `release` skill to cut one; it holds the procedure. The policy it imple
- The handwritten notes need the maintainer's sign-off: one or two sentences for a patch, narrative prose for a point release.
- Generate the changelog from the last stable tag (`previous_tag_name` in the notes API, or `--notes-start-tag` when using CLI generation) so a prerelease tag never truncates it. Complete contributor attribution before publication and publish those completed notes with `--notes-file`.
- Merge the docs changelog PR on the release branch immediately *before* tagging, so the entry is in the tagged commit.
-- gofastmcp.com serves the `published-docs` branch, which accepts changes only through PRs.
+- gofastmcp.com/docs serves Mintlify docs from `published-docs`, which accepts changes only through PRs. `main` is the docs authoring source. The root website is maintained separately in `PrefectHQ/gofastmcp-website` and deployed by Vercel from its `main` branch.
### Commit Messages and Agent Attribution
diff --git a/docs/development/releases.mdx b/docs/development/releases.mdx
index 541b256be..11b4dca70 100644
--- a/docs/development/releases.mdx
+++ b/docs/development/releases.mdx
@@ -45,8 +45,8 @@ Publishing a release triggers the package workflows. On the current line, `fastm
## Publishing documentation
-The live site serves the `published-docs` branch, not `main`. A stable release from `main` opens a PR that copies the release tree to `published-docs` after package publishing succeeds. A maintainer merges that PR, then verifies the `Deploy docs` workflow completed successfully.
+The documentation at `https://gofastmcp.com/docs` is built by Mintlify from `docs/` on `published-docs`; `main` is the authoring source. The separate `PrefectHQ/gofastmcp-website` repository deploys its `main` branch to Vercel for the root landing page and `/docs` proxy. A stable release from the default-branch lineage opens a PR that copies the exact release tree to `published-docs` after package publishing succeeds. A maintainer merges that PR, then verifies the `Deploy docs` workflow completed successfully and checks the changed public docs.
-Prereleases do not open that publication PR automatically. Docs-only changes between releases can be published through a PR that synchronizes `main` to `published-docs`; follow the release skill's manual publication procedure. Do not push directly to the publication branch.
+Prereleases and manual package-workflow dispatch do not open that publication PR automatically. Docs-only changes between releases can be published through a PR that synchronizes `main` to `published-docs`; follow the release skill's manual publication procedure and publication checks, including preservation of `/docs` metadata in the candidate tree. Do not push directly to the publication branch. Ordinary publication does not change domains or Mintlify's `/docs` base path.
Maintenance releases update their own changelog and packages without repointing the current documentation site. The `docs/v2/` and `docs/v3/` trees preserve historical documentation; outside their release changelogs, they are frozen snapshots.
diff --git a/docs/docs.json b/docs/docs.json
index 97fc92616..cdd120904 100644
--- a/docs/docs.json
+++ b/docs/docs.json
@@ -59,6 +59,7 @@
"drilldown": false
},
"logo": {
+ "href": "https://gofastmcp.com",
"dark": "/assets/brand/wordmark-white.png",
"light": "/assets/brand/wordmark.png"
},
@@ -564,11 +565,14 @@
"prompt": "Search the docs..."
},
"seo": {
+ "metatags": {
+ "canonical": "https://gofastmcp.com/docs"
+ },
"organization": {
"name": "FastMCP",
"legalName": "Prefect Technologies, Inc.",
"url": "https://gofastmcp.com",
- "logo": "https://gofastmcp.com/assets/brand/wordmark.png",
+ "logo": "https://gofastmcp.com/docs/assets/brand/wordmark.png",
"sameAs": [
"https://github.com/PrefectHQ/fastmcp",
"https://x.com/fastmcp",