[Docs] Render the guides with Zensical instead of phpDocumentor

.gitattributes

@@ -5,6 +5,8 @@
 /tests export-ignore
 /.php-cs-fixer.dist.php export-ignore
 /Makefile export-ignore
+/mkdocs.yml export-ignore
+/requirements-docs.txt export-ignore
 /phpdoc.dist.xml
 /phpstan* export-ignore
 /phpunit.xml.dist export-ignore

.github/workflows/docs.yml

@@ -1,15 +1,25 @@
-name: Deploy Documentation
+name: Documentation
+
+# The site is built by `make docs`: Zensical renders the guides under docs/
+# (see mkdocs.yml) and phpDocumentor renders the API reference into /api/.
+# Pull requests build only — the build is strict, so a broken internal link
+# fails CI instead of shipping a dead link to the site.
 
 on:
-  release:
-    types: [published]
+  push:
+    branches: [main]
+  pull_request:
   workflow_dispatch:
 
 permissions:
-  contents: write
+  contents: read
+
+concurrency:
+  group: docs-${{ github.ref }}
+  cancel-in-progress: true
 
 jobs:
-  deploy:
+  build:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
@@ -21,16 +31,33 @@ jobs:
           php-version: '8.4'
           coverage: "none"
 
-      - name: Install Composer
+      - name: Install Composer dependencies
         uses: "ramsey/composer-install@v4"
 
-      - name: Generate Documentation
+      - name: Install uv
+        uses: astral-sh/setup-uv@v9.0.0
+        with:
+          enable-cache: true
+
+      - name: Build documentation
         run: make docs
 
-      - name: Deploy to gh-pages branch
-        uses: peaceiris/actions-gh-pages@v4
+      - name: Upload Pages artifact
+        uses: actions/upload-pages-artifact@v5
         with:
-          github_token: ${{ secrets.GITHUB_TOKEN }}
-          publish_dir: ./.phpdoc/build
-          enable_jekyll: false
-          cname: php.sdk.modelcontextprotocol.io
+          path: ./site
+
+  deploy:
+    needs: build
+    if: github.event_name != 'pull_request'
+    runs-on: ubuntu-latest
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v5

.github/workflows/pipeline.yaml

@@ -244,5 +244,7 @@ jobs:
       - name: PHPStan
         run: vendor/bin/phpstan analyse
 
+      # Only the phpDocumentor half: this job is PHP-only, and the Zensical
+      # guides are built (strictly) by the Documentation workflow.
       - name: Documentation
-        run: make docs
+        run: make docs-api

.gitignore

@@ -15,3 +15,7 @@ tests/Conformance/logs/*.log
 # phpDocumentor
 .phpdoc/build/
 .phpdoc/cache/
+
+# Documentation site (make docs)
+/site/
+/.cache/

.phpdoc/template/base.html.twig

@@ -2,7 +2,7 @@
 
 {% set topMenu = {
     "menu": [
-        { "name": "Guides", "url": "docs/index.html"},
+        { "name": "Guides", "url": "/"},
         { "name": "Specification", "url": "https://modelcontextprotocol.io/" }
     ],
     "social": [

.phpdoc/template/components/header-title.html.twig

@@ -1,5 +1,5 @@
 <h1 class="phpdocumentor-title">
-    <a href="{{ path('/docs/index.html') }}" class="phpdocumentor-title__link">
+    <a href="/" class="phpdocumentor-title__link">
         <svg xmlns="http://www.w3.org/2000/svg" width="40" height="40" viewBox="0 0 195 195" fill="none">
             <path d="M25 97.8528L92.8823 29.9706C102.255 20.598 117.451 20.598 126.823 29.9706V29.9706C136.196 39.3431 136.196 54.5391 126.823 63.9117L75.5581 115.177" stroke="black" stroke-width="12" stroke-linecap="round"/>
             <path d="M76.2653 114.47L126.823 63.9117C136.196 54.5391 151.392 54.5391 160.765 63.9117L161.118 64.2652C170.491 73.6378 170.491 88.8338 161.118 98.2063L99.7248 159.6C96.6006 162.724 96.6006 167.789 99.7248 170.913L112.331 183.52" stroke="black" stroke-width="12" stroke-linecap="round"/>

CHANGELOG.md

@@ -14,7 +14,7 @@ All notable changes to `mcp/sdk` will be documented in this file.
 * Answer a request over a response stream under the 2026-07-28 lifecycle: `StatelessProtocol` runs handlers in a fiber, so `$gateway->progress()` and `$gateway->log()` work there as they do in the handshake era. The stream opens only if the handler actually emits something *and* the client's `Accept` admits `text/event-stream`, and the choice is made after the handler's first suspension, so a request that turns out to need `-32021` or `-32602` is still answered with the status the spec fixes for it.
 * Honour `io.modelcontextprotocol/logLevel` (SEP-2575), which replaced the `logging/setLevel` RPC: a request naming no level receives no `notifications/message` at all, one naming a level receives the messages at or above it. Adds `LoggingLevel::severity()` and `LoggingLevel::isAtLeast()`.
 * [BC Break] Answer a not-found subject with `-32602` (Invalid params) instead of `-32002`, which the 2026-07-28 revision reserves and forbids emitting (SEP-2164). `resources/read` picks the code from the revision serving the request — `-32602` with the uri in `error.data` from `2026-07-28` on, `-32002` below. `prompts/get` for an unknown prompt, `completion/complete` for an unknown reference and `tools/call` for an unknown tool switch to `-32602` in *every* revision: `-32002` was never the code for those. Adds `ProtocolVersion::usesInvalidParamsForResourceNotFound()`.
-* Add the multi round-trip requests pattern for the 2026-07-28 lifecycle (SEP-2322): a `tools/call` or `prompts/get` handler returning `Mcp\Schema\Result\InputRequiredResult` comes back as `resultType: "input_required"` carrying the `inputRequests` it needs answered and an opaque `requestState`; the client retries the same request with `inputResponses`, which the handler reads through `RequestContext::getInputContext()`. `Mcp\Server\Stateless\RequestStateCodec` signs and time-bounds the state — set the key with `Builder::setRequestStateKey()`.
+* Add the multi round-trip requests pattern for the 2026-07-28 lifecycle (SEP-2322): a `tools/call` or `prompts/get` handler returning `Mcp\Schema\Result\InputRequiredResult` comes back as `resultType: "input_required"` carrying the `inputRequests` it needs answered and an opaque `requestState`; the client retries the same request with `inputResponses`, which the handler reads through `RequestContext::getInputContext()`. `Mcp\Server\Stateless\RequestStateCodec` signs and time-bounds the state — set the key with `Builder::setRequestState()`.
 * Validate the standard MCP request headers under the 2026-07-28 lifecycle (SEP-2243): `Mcp\Server\Stateless\StandardHeaderValidator`, set with `Builder::setHeaderValidator()`, checks that `Mcp-Method` and `Mcp-Name` agree with the body they travel with and that a `Mcp-Param-*` mirrors the argument its tool marked `x-mcp-header`, answering `-32020` when they disagree. Intermediaries route on these headers, so a value contradicting the body has to be refused rather than ignored.
 * [BC Break] `Mcp\Schema\JsonRpc\Error` accepts `null` as its `$id`, and `getId()` may return it. An error response whose id could not be read now omits the member instead of sending `"id": ""` — which claimed the peer had issued a request with an empty-string id. All the `for*()` factories default to `null`, `fromArray()` accepts a missing or explicitly-null id, and `MessageFactory` decodes both as an id-less error rather than rejecting them.
 * Preserve the original request `id` on an invalid-but-parseable message (`-32600`) instead of answering it id-less: `InvalidInputMessageException` now carries the recoverable id via `getRequestId()`/`setRequestId()`, threaded from `MessageFactory` through to the error response.

Makefile

@@ -1,11 +1,16 @@
-.PHONY: deps-stable deps-low cs phpstan tests unit-tests integration-tests inspector-tests coverage ci ci-stable ci-lowest conformance-tests conformance-server conformance-client conformance-draft conformance-draft-server conformance-draft-client docs
+.PHONY: deps-stable deps-low cs phpstan tests unit-tests integration-tests inspector-tests coverage ci ci-stable ci-lowest conformance-tests conformance-server conformance-client conformance-draft conformance-draft-server conformance-draft-client docs docs-guides docs-api docs-serve
 
 # The 2026-07-28 scenarios ship on the `alpha` dist-tag; `latest` (0.1.x) has
 # none of them. Pinned to the same version CI runs (see
 # .github/workflows/pipeline.yaml), so a local pass means a green pipeline.
 CONFORMANCE_VERSION ?= 0.2.0-alpha.11
 CONFORMANCE = npx --yes @modelcontextprotocol/conformance@$(CONFORMANCE_VERSION)
 
+# The documentation toolchain is Python (Zensical, see requirements-docs.txt),
+# run through uv so no virtualenv has to be managed by hand:
+# https://docs.astral.sh/uv/getting-started/installation/
+DOCS_RUN = uv run --no-project --with-requirements requirements-docs.txt --
+
 deps-stable:
 	composer update --prefer-stable
 
@@ -73,7 +78,19 @@ ci-stable: deps-stable cs phpstan tests
 
 ci-lowest: deps-low cs phpstan tests
 
-docs:
-	vendor/bin/phpdoc
-	@grep -q 'No errors have been found' .phpdoc/build/reports/errors.html || \
-		(echo "Documentation errors found. See build/docs/reports/errors.html" && exit 1)
+# The published site is the guides (Zensical) with the phpDocumentor API
+# reference mounted at /api/. `zensical build` wipes site/, so it runs first.
+docs: docs-guides docs-api
+	rm -rf site/api
+	cp -a .phpdoc/build/api site/api
+
+docs-guides:
+	$(DOCS_RUN) zensical build --strict
+
+docs-api:
+	vendor/bin/phpdoc --no-interaction
+	@grep -q 'No errors have been found' .phpdoc/build/api/reports/errors.html || \
+		(echo "Documentation errors found. See .phpdoc/build/api/reports/errors.html" && exit 1)
+
+docs-serve:
+	$(DOCS_RUN) zensical serve