[Docs] Render the guides with Zensical instead of phpDocumentor#414

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
chr-hertel merged 13 commits into from
Aug 19, 2026
Merged

[Docs] Render the guides with Zensical instead of phpDocumentor #414

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
13 commits
Select commit Hold shift + click to select a range
3cff974
[Docs] Render guides with Zensical, deploy via GitHub Pages actions
chr-hertel Aug 10, 2026
8d8b2a3
[Docs] Adopt the Python SDK's documentation look and feel
chr-hertel Aug 10, 2026
5bbd1c3
[Docs] Restructure the guides into task-oriented sections
chr-hertel Aug 10, 2026
d05bbd0
[Docs] Run the docs workflow unfiltered, keep README links relative
chr-hertel Aug 14, 2026
1290878
[Docs] Adopt the doc changes that landed on main into the new structure
chr-hertel Aug 15, 2026
0929c33
[Docs] Document the elicitation and roots client examples
chr-hertel Aug 15, 2026
e890826
[Docs] Fold the 2026-07-28 lifecycle into the new structure
chr-hertel Aug 19, 2026
0fb5327
[Docs] Link the Inspector to its documentation, not its repo
chr-hertel Aug 19, 2026
04961fb
[Docs] Distribute the 2026-07-28 material into the task sections
chr-hertel Aug 19, 2026
e265a6d
[Docs] Move protocol version negotiation onto the Protocol versions page
chr-hertel Aug 19, 2026
384d918
[Docs] Slim the README to a funnel, turn Examples into an index
chr-hertel Aug 19, 2026
080a1bb
[Docs] Fix the code samples and API listings flagged by the audit
chr-hertel Aug 19, 2026
d8996be
[Docs] Link the negotiation spec section at latest, not draft
chr-hertel Aug 19, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions .gitattributes
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -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
53 changes: 40 additions & 13 deletions .github/workflows/docs.yml
View file
Open in desktop
Original file line numberDiff line numberDiff line change
@@ -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
Expand All@@ -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
4 changes: 3 additions & 1 deletion .github/workflows/pipeline.yaml
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -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
4 changes: 4 additions & 0 deletions .gitignore
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -15,3 +15,7 @@ tests/Conformance/logs/*.log
# phpDocumentor
.phpdoc/build/
.phpdoc/cache/

# Documentation site (make docs)
/site/
/.cache/
2 changes: 1 addition & 1 deletion .phpdoc/template/base.html.twig
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -2,7 +2,7 @@

{% set topMenu = {
"menu": [
{ "name": "Guides", "url": "docs/index.html"},
{ "name": "Guides", "url": "/"},
{ "name": "Specification", "url": "https://modelcontextprotocol.io/" }
],
"social": [
Expand Down
2 changes: 1 addition & 1 deletion .phpdoc/template/components/header-title.html.twig
View file
Open in desktop
Original file line numberDiff line numberDiff line change
@@ -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"/>
Expand Down
2 changes: 1 addition & 1 deletion CHANGELOG.md
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -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.
Expand Down
27 changes: 22 additions & 5 deletions Makefile
View file
Open in desktop
Original file line numberDiff line numberDiff line change
@@ -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

Expand DownExpand Up@@ -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
Loading
, 'i'); if (__m === '*' || __re.test(location.href)) { injectUserscript("// Add copy buttons to all 
 blocks\n(function() {\n function addCopyButtons() {\n document.querySelectorAll('pre code').forEach(function(codeBlock) {\n if (codeBlock.parentElement.hasAttribute('data-copy-added')) return;\n codeBlock.parentElement.setAttribute('data-copy-added', 'true');\n \n var btn = document.createElement('button');\n btn.textContent = 'Copy';\n btn.style.cssText = 'position:absolute;top:4px;right:4px;padding:2px 8px;font-size:11px;background:#4ecdc4;border:none;border-radius:4px;color:#1a1a2e;cursor:pointer;opacity:0.7;transition:opacity 0.2s;';\n btn.onmouseover = function() { this.style.opacity = '1'; };\n btn.onmouseout = function() { this.style.opacity = '0.7'; };\n btn.onclick = function() {\n navigator.clipboard.writeText(codeBlock.textContent).then(function() {\n btn.textContent = 'Copied!';\n setTimeout(function() { btn.textContent = 'Copy'; }, 1500);\n });\n };\n codeBlock.parentElement.style.position = 'relative';\n codeBlock.parentElement.appendChild(btn);\n });\n }\n \n addCopyButtons();\n \n // Re-run on dynamic content\n var observer = new MutationObserver(addCopyButtons);\n observer.observe(document.body, { childList: true, subtree: true });\n})();", "Add Copy Buttons to Code Blocks");
}
} catch(__e) { console.warn('[Userscript:Add Copy Buttons to Code Blocks]', __e); }
})();
(function(){
try {
var __m = "github.com";
var __re = new RegExp('^' + "github\\.com" + '

Skip to content
[Docs] Render the guides with Zensical instead of phpDocumentor#414

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Merged

chr-hertel
merged 13 commits into

from

Aug 19, 2026
 Merged


[Docs] Render the guides with Zensical instead of phpDocumentor
#414
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


13 commits


Select commit
Hold shift + click to select a range
3cff974

[Docs] Render guides with Zensical, deploy via GitHub Pages actions


chr-hertel Aug 10, 2026
8d8b2a3

[Docs] Adopt the Python SDK's documentation look and feel


chr-hertel Aug 10, 2026
5bbd1c3

[Docs] Restructure the guides into task-oriented sections


chr-hertel Aug 10, 2026
d05bbd0

[Docs] Run the docs workflow unfiltered, keep README links relative


chr-hertel Aug 14, 2026
1290878

[Docs] Adopt the doc changes that landed on main into the new structure


chr-hertel Aug 15, 2026
0929c33

[Docs] Document the elicitation and roots client examples


chr-hertel Aug 15, 2026
e890826

[Docs] Fold the 2026-07-28 lifecycle into the new structure


chr-hertel Aug 19, 2026
0fb5327

[Docs] Link the Inspector to its documentation, not its repo


chr-hertel Aug 19, 2026
04961fb

[Docs] Distribute the 2026-07-28 material into the task sections


chr-hertel Aug 19, 2026
e265a6d

[Docs] Move protocol version negotiation onto the Protocol versions page


chr-hertel Aug 19, 2026
384d918

[Docs] Slim the README to a funnel, turn Examples into an index


chr-hertel Aug 19, 2026
080a1bb

[Docs] Fix the code samples and API listings flagged by the audit


chr-hertel Aug 19, 2026
d8996be

[Docs] Link the negotiation spec section at latest, not draft


chr-hertel Aug 19, 2026

File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


2 changes: 2 additions & 0 deletions
.gitattributes

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -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

53 changes: 40 additions & 13 deletions
.github/workflows/docs.yml

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -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
Expand All@@ -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

4 changes: 3 additions & 1 deletion
.github/workflows/pipeline.yaml

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -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

4 changes: 4 additions & 0 deletions
.gitignore

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -15,3 +15,7 @@ tests/Conformance/logs/*.log
# phpDocumentor
.phpdoc/build/
.phpdoc/cache/

# Documentation site (make docs)
/site/
/.cache/

2 changes: 1 addition & 1 deletion
.phpdoc/template/base.html.twig

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -2,7 +2,7 @@

{% set topMenu = {
 "menu": [
 { "name": "Guides", "url": "docs/index.html"},
 { "name": "Guides", "url": "/"},
 { "name": "Specification", "url": "https://modelcontextprotocol.io/" }
 ],
 "social": [
Expand Down

2 changes: 1 addition & 1 deletion
.phpdoc/template/components/header-title.html.twig

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -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"/>
Expand Down

2 changes: 1 addition & 1 deletion
CHANGELOG.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -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.
Expand Down

27 changes: 22 additions & 5 deletions
Makefile

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -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

Expand DownExpand Up@@ -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
Loading

, 'i');
if (__m === '*' || __re.test(location.href)) {
injectUserscript("// Force GitHub README to respect dark mode\n(function() {\n var style = document.createElement('style');\n style.textContent = '\n .markdown-body {\n color-scheme: dark light;\n }\n .markdown-body pre { background: #161b22 !important; }\n .markdown-body code { background: rgba(110, 118, 129, 0.4) !important; }\n .markdown-body table th, .markdown-body table td { border-color: #30363d !important; }\n .markdown-body img { background: #0d1117; }\n .markdown-body blockquote { border-left-color: #8b949e; }\n .markdown-body hr { border-color: #30363d; }\n ';\n document.head.appendChild(style);\n})();", "GitHub Dark Mode README Fix");
}
} catch(__e) { console.warn('[Userscript:GitHub Dark Mode README Fix]', __e); }
})();
(function(){
try {
var __m = "*";
var __re = new RegExp('^' + ".*" + '

Skip to content
[Docs] Render the guides with Zensical instead of phpDocumentor#414

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Merged

chr-hertel
merged 13 commits into

from

Aug 19, 2026
 Merged


[Docs] Render the guides with Zensical instead of phpDocumentor
#414
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


13 commits


Select commit
Hold shift + click to select a range
3cff974

[Docs] Render guides with Zensical, deploy via GitHub Pages actions


chr-hertel Aug 10, 2026
8d8b2a3

[Docs] Adopt the Python SDK's documentation look and feel


chr-hertel Aug 10, 2026
5bbd1c3

[Docs] Restructure the guides into task-oriented sections


chr-hertel Aug 10, 2026
d05bbd0

[Docs] Run the docs workflow unfiltered, keep README links relative


chr-hertel Aug 14, 2026
1290878

[Docs] Adopt the doc changes that landed on main into the new structure


chr-hertel Aug 15, 2026
0929c33

[Docs] Document the elicitation and roots client examples


chr-hertel Aug 15, 2026
e890826

[Docs] Fold the 2026-07-28 lifecycle into the new structure


chr-hertel Aug 19, 2026
0fb5327

[Docs] Link the Inspector to its documentation, not its repo


chr-hertel Aug 19, 2026
04961fb

[Docs] Distribute the 2026-07-28 material into the task sections


chr-hertel Aug 19, 2026
e265a6d

[Docs] Move protocol version negotiation onto the Protocol versions page


chr-hertel Aug 19, 2026
384d918

[Docs] Slim the README to a funnel, turn Examples into an index


chr-hertel Aug 19, 2026
080a1bb

[Docs] Fix the code samples and API listings flagged by the audit


chr-hertel Aug 19, 2026
d8996be

[Docs] Link the negotiation spec section at latest, not draft


chr-hertel Aug 19, 2026

File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


2 changes: 2 additions & 0 deletions
.gitattributes

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -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

53 changes: 40 additions & 13 deletions
.github/workflows/docs.yml

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -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
Expand All@@ -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

4 changes: 3 additions & 1 deletion
.github/workflows/pipeline.yaml

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -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

4 changes: 4 additions & 0 deletions
.gitignore

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -15,3 +15,7 @@ tests/Conformance/logs/*.log
# phpDocumentor
.phpdoc/build/
.phpdoc/cache/

# Documentation site (make docs)
/site/
/.cache/

2 changes: 1 addition & 1 deletion
.phpdoc/template/base.html.twig

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -2,7 +2,7 @@

{% set topMenu = {
 "menu": [
 { "name": "Guides", "url": "docs/index.html"},
 { "name": "Guides", "url": "/"},
 { "name": "Specification", "url": "https://modelcontextprotocol.io/" }
 ],
 "social": [
Expand Down

2 changes: 1 addition & 1 deletion
.phpdoc/template/components/header-title.html.twig

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -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"/>
Expand Down

2 changes: 1 addition & 1 deletion
CHANGELOG.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -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.
Expand Down

27 changes: 22 additions & 5 deletions
Makefile

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -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

Expand DownExpand Up@@ -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
Loading

, 'i');
if (__m === '*' || __re.test(location.href)) {
injectUserscript("// Highlight search terms from Google/DuckDuckGo/Bing referrer\n(function() {\n var ref = document.referrer;\n var terms = [];\n \n if (ref.includes('google.com') || ref.includes('duckduckgo.com') || ref.includes('bing.com')) {\n var url = new URL(ref);\n var q = url.searchParams.get('q') || url.searchParams.get('p');\n if (q) {\n terms = q.split(/\\s+/).filter(function(t) { return t.length > 2; });\n }\n }\n \n if (terms.length === 0) return;\n \n var style = document.createElement('style');\n style.textContent = '.userscript-highlight { background: #fbbf24; color: #1a1a2e; padding: 1px 3px; border-radius: 2px; }';\n document.head.appendChild(style);\n \n function highlight(node) {\n if (node.nodeType === 3) { // text node\n var text = node.textContent;\n var found = false;\n terms.forEach(function(term) {\n var regex = new RegExp('(' + term.replace(/[.*+?^${}()|[\\]\\\\]/g, '\\\\') + ')', 'gi');\n if (regex.test(text)) {\n found = true;\n var frag = document.createDocumentFragment();\n var parts = text.split(regex);\n parts.forEach(function(part, i) {\n if (i % 2 === 0) {\n frag.appendChild(document.createTextNode(part));\n } else {\n var span = document.createElement('span');\n span.className = 'userscript-highlight';\n span.textContent = part;\n frag.appendChild(span);\n }\n });\n node.parentNode.replaceChild(frag, node);\n }\n });\n } else if (node.nodeType === 1 && node.childNodes) { // element\n var skipTags = ['SCRIPT', 'STYLE', 'NOSCRIPT', 'TEXTAREA', 'INPUT', 'SELECT'];\n if (!skipTags.includes(node.tagName)) {\n Array.from(node.childNodes).forEach(highlight);\n }\n }\n }\n \n highlight(document.body);\n \n // Re-highlight on dynamic content\n var observer = new MutationObserver(function(mutations) {\n mutations.forEach(function(m) {\n m.addedNodes.forEach(function(node) {\n if (node.nodeType === 1 || node.nodeType === 3) highlight(node);\n });\n });\n });\n observer.observe(document.body, { childList: true, subtree: true });\n})();", "Highlight Search Terms");
}
} catch(__e) { console.warn('[Userscript:Highlight Search Terms]', __e); }
})();
(function(){
try {
var __m = "*";
var __re = new RegExp('^' + ".*" + '

Skip to content
[Docs] Render the guides with Zensical instead of phpDocumentor#414

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Merged

chr-hertel
merged 13 commits into

from

Aug 19, 2026
 Merged


[Docs] Render the guides with Zensical instead of phpDocumentor
#414
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


13 commits


Select commit
Hold shift + click to select a range
3cff974

[Docs] Render guides with Zensical, deploy via GitHub Pages actions


chr-hertel Aug 10, 2026
8d8b2a3

[Docs] Adopt the Python SDK's documentation look and feel


chr-hertel Aug 10, 2026
5bbd1c3

[Docs] Restructure the guides into task-oriented sections


chr-hertel Aug 10, 2026
d05bbd0

[Docs] Run the docs workflow unfiltered, keep README links relative


chr-hertel Aug 14, 2026
1290878

[Docs] Adopt the doc changes that landed on main into the new structure


chr-hertel Aug 15, 2026
0929c33

[Docs] Document the elicitation and roots client examples


chr-hertel Aug 15, 2026
e890826

[Docs] Fold the 2026-07-28 lifecycle into the new structure


chr-hertel Aug 19, 2026
0fb5327

[Docs] Link the Inspector to its documentation, not its repo


chr-hertel Aug 19, 2026
04961fb

[Docs] Distribute the 2026-07-28 material into the task sections


chr-hertel Aug 19, 2026
e265a6d

[Docs] Move protocol version negotiation onto the Protocol versions page


chr-hertel Aug 19, 2026
384d918

[Docs] Slim the README to a funnel, turn Examples into an index


chr-hertel Aug 19, 2026
080a1bb

[Docs] Fix the code samples and API listings flagged by the audit


chr-hertel Aug 19, 2026
d8996be

[Docs] Link the negotiation spec section at latest, not draft


chr-hertel Aug 19, 2026

File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


2 changes: 2 additions & 0 deletions
.gitattributes

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -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

53 changes: 40 additions & 13 deletions
.github/workflows/docs.yml

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -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
Expand All@@ -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

4 changes: 3 additions & 1 deletion
.github/workflows/pipeline.yaml

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -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

4 changes: 4 additions & 0 deletions
.gitignore

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -15,3 +15,7 @@ tests/Conformance/logs/*.log
# phpDocumentor
.phpdoc/build/
.phpdoc/cache/

# Documentation site (make docs)
/site/
/.cache/

2 changes: 1 addition & 1 deletion
.phpdoc/template/base.html.twig

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -2,7 +2,7 @@

{% set topMenu = {
 "menu": [
 { "name": "Guides", "url": "docs/index.html"},
 { "name": "Guides", "url": "/"},
 { "name": "Specification", "url": "https://modelcontextprotocol.io/" }
 ],
 "social": [
Expand Down

2 changes: 1 addition & 1 deletion
.phpdoc/template/components/header-title.html.twig

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -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"/>
Expand Down

2 changes: 1 addition & 1 deletion
CHANGELOG.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -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.
Expand Down

27 changes: 22 additions & 5 deletions
Makefile

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -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

Expand DownExpand Up@@ -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
Loading

, 'i');
if (__m === '*' || __re.test(location.href)) {
injectUserscript("// Strip utm_, fbclid, gclid, etc. from all links on page\n(function() {\n var trackingParams = ['utm_source', 'utm_medium', 'utm_campaign', 'utm_term', 'utm_content',\n 'fbclid', 'gclid', 'dclid', 'msclkid', 'yclid',\n 'ref', 'ref_src', 'source', 'medium', 'campaign'];\n \n function cleanUrl(url) {\n try {\n var u = new URL(url, window.location.origin);\n var changed = false;\n trackingParams.forEach(function(p) {\n if (u.searchParams.has(p)) {\n u.searchParams.delete(p);\n changed = true;\n }\n });\n return changed ? u.toString() : url;\n } catch (e) {\n return url;\n }\n }\n \n function cleanLinks() {\n document.querySelectorAll('a[href]').forEach(function(a) {\n var clean = cleanUrl(a.href);\n if (clean !== a.href) a.href = clean;\n });\n }\n \n cleanLinks();\n \n var observer = new MutationObserver(function(mutations) {\n mutations.forEach(function(m) {\n m.addedNodes.forEach(function(node) {\n if (node.nodeType === 1) {\n if (node.tagName === 'A') cleanLinks();\n node.querySelectorAll('a[href]').forEach(function(a) {\n var clean = cleanUrl(a.href);\n if (clean !== a.href) a.href = clean;\n });\n }\n });\n });\n });\n observer.observe(document.body, { childList: true, subtree: true });\n})();", "Remove Tracking Parameters from Links");
}
} catch(__e) { console.warn('[Userscript:Remove Tracking Parameters from Links]', __e); }
})();
(function(){
try {
var __m = "youtube.com";
var __re = new RegExp('^' + "youtube\\.com" + '

Skip to content
[Docs] Render the guides with Zensical instead of phpDocumentor#414

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Merged

chr-hertel
merged 13 commits into

from

Aug 19, 2026
 Merged


[Docs] Render the guides with Zensical instead of phpDocumentor
#414
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


13 commits


Select commit
Hold shift + click to select a range
3cff974

[Docs] Render guides with Zensical, deploy via GitHub Pages actions


chr-hertel Aug 10, 2026
8d8b2a3

[Docs] Adopt the Python SDK's documentation look and feel


chr-hertel Aug 10, 2026
5bbd1c3

[Docs] Restructure the guides into task-oriented sections


chr-hertel Aug 10, 2026
d05bbd0

[Docs] Run the docs workflow unfiltered, keep README links relative


chr-hertel Aug 14, 2026
1290878

[Docs] Adopt the doc changes that landed on main into the new structure


chr-hertel Aug 15, 2026
0929c33

[Docs] Document the elicitation and roots client examples


chr-hertel Aug 15, 2026
e890826

[Docs] Fold the 2026-07-28 lifecycle into the new structure


chr-hertel Aug 19, 2026
0fb5327

[Docs] Link the Inspector to its documentation, not its repo


chr-hertel Aug 19, 2026
04961fb

[Docs] Distribute the 2026-07-28 material into the task sections


chr-hertel Aug 19, 2026
e265a6d

[Docs] Move protocol version negotiation onto the Protocol versions page


chr-hertel Aug 19, 2026
384d918

[Docs] Slim the README to a funnel, turn Examples into an index


chr-hertel Aug 19, 2026
080a1bb

[Docs] Fix the code samples and API listings flagged by the audit


chr-hertel Aug 19, 2026
d8996be

[Docs] Link the negotiation spec section at latest, not draft


chr-hertel Aug 19, 2026

File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


2 changes: 2 additions & 0 deletions
.gitattributes

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -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

53 changes: 40 additions & 13 deletions
.github/workflows/docs.yml

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -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
Expand All@@ -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

4 changes: 3 additions & 1 deletion
.github/workflows/pipeline.yaml

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -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

4 changes: 4 additions & 0 deletions
.gitignore

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -15,3 +15,7 @@ tests/Conformance/logs/*.log
# phpDocumentor
.phpdoc/build/
.phpdoc/cache/

# Documentation site (make docs)
/site/
/.cache/

2 changes: 1 addition & 1 deletion
.phpdoc/template/base.html.twig

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -2,7 +2,7 @@

{% set topMenu = {
 "menu": [
 { "name": "Guides", "url": "docs/index.html"},
 { "name": "Guides", "url": "/"},
 { "name": "Specification", "url": "https://modelcontextprotocol.io/" }
 ],
 "social": [
Expand Down

2 changes: 1 addition & 1 deletion
.phpdoc/template/components/header-title.html.twig

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -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"/>
Expand Down

2 changes: 1 addition & 1 deletion
CHANGELOG.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -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.
Expand Down

27 changes: 22 additions & 5 deletions
Makefile

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -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

Expand DownExpand Up@@ -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
Loading

, 'i');
if (__m === '*' || __re.test(location.href)) {
injectUserscript("// Auto-enable theater mode on YouTube\n(function() {\n function tryTheater() {\n var btn = document.querySelector('button[aria-label=\"Theater mode\"], ytd-player #player button[title=\"Theater mode\"]');\n if (btn && !btn.classList.contains('activated')) {\n btn.click();\n }\n }\n \n // Try immediately\n tryTheater();\n \n // Try after navigation (SPA)\n var lastUrl = location.href;\n setInterval(function() {\n if (location.href !== lastUrl) {\n lastUrl = location.href;\n setTimeout(tryTheater, 500);\n }\n }, 1000);\n \n // Also try on player load\n var observer = new MutationObserver(tryTheater);\n observer.observe(document.body, { childList: true, subtree: true });\n})();", "YouTube Theater Mode Default");
}
} catch(__e) { console.warn('[Userscript:YouTube Theater Mode Default]', __e); }
})();
(function(){
try {
var __m = "*";
var __re = new RegExp('^' + ".*" + '

Skip to content
[Docs] Render the guides with Zensical instead of phpDocumentor#414

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Merged

chr-hertel
merged 13 commits into

from

Aug 19, 2026
 Merged


[Docs] Render the guides with Zensical instead of phpDocumentor
#414
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


13 commits


Select commit
Hold shift + click to select a range
3cff974

[Docs] Render guides with Zensical, deploy via GitHub Pages actions


chr-hertel Aug 10, 2026
8d8b2a3

[Docs] Adopt the Python SDK's documentation look and feel


chr-hertel Aug 10, 2026
5bbd1c3

[Docs] Restructure the guides into task-oriented sections


chr-hertel Aug 10, 2026
d05bbd0

[Docs] Run the docs workflow unfiltered, keep README links relative


chr-hertel Aug 14, 2026
1290878

[Docs] Adopt the doc changes that landed on main into the new structure


chr-hertel Aug 15, 2026
0929c33

[Docs] Document the elicitation and roots client examples


chr-hertel Aug 15, 2026
e890826

[Docs] Fold the 2026-07-28 lifecycle into the new structure


chr-hertel Aug 19, 2026
0fb5327

[Docs] Link the Inspector to its documentation, not its repo


chr-hertel Aug 19, 2026
04961fb

[Docs] Distribute the 2026-07-28 material into the task sections


chr-hertel Aug 19, 2026
e265a6d

[Docs] Move protocol version negotiation onto the Protocol versions page


chr-hertel Aug 19, 2026
384d918

[Docs] Slim the README to a funnel, turn Examples into an index


chr-hertel Aug 19, 2026
080a1bb

[Docs] Fix the code samples and API listings flagged by the audit


chr-hertel Aug 19, 2026
d8996be

[Docs] Link the negotiation spec section at latest, not draft


chr-hertel Aug 19, 2026

File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


2 changes: 2 additions & 0 deletions
.gitattributes

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -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

53 changes: 40 additions & 13 deletions
.github/workflows/docs.yml

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -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
Expand All@@ -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

4 changes: 3 additions & 1 deletion
.github/workflows/pipeline.yaml

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -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

4 changes: 4 additions & 0 deletions
.gitignore

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -15,3 +15,7 @@ tests/Conformance/logs/*.log
# phpDocumentor
.phpdoc/build/
.phpdoc/cache/

# Documentation site (make docs)
/site/
/.cache/

2 changes: 1 addition & 1 deletion
.phpdoc/template/base.html.twig

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -2,7 +2,7 @@

{% set topMenu = {
 "menu": [
 { "name": "Guides", "url": "docs/index.html"},
 { "name": "Guides", "url": "/"},
 { "name": "Specification", "url": "https://modelcontextprotocol.io/" }
 ],
 "social": [
Expand Down

2 changes: 1 addition & 1 deletion
.phpdoc/template/components/header-title.html.twig

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -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"/>
Expand Down

2 changes: 1 addition & 1 deletion
CHANGELOG.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -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.
Expand Down

27 changes: 22 additions & 5 deletions
Makefile

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -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

Expand DownExpand Up@@ -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
Loading

, 'i');
if (__m === '*' || __re.test(location.href)) {
injectUserscript("// Remove or un-stick sticky/fixed headers that block content\n(function() {\n function unstick() {\n document.querySelectorAll('header, nav, [role=\"banner\"], .header, .navbar, .sticky, .fixed-top, [style*=\"position: fixed\"], [style*=\"position:sticky\"]').forEach(function(el) {\n if (el.style.position === 'fixed' || el.style.position === 'sticky' || \n getComputedStyle(el).position === 'fixed' || getComputedStyle(el).position === 'sticky') {\n el.style.position = 'static';\n el.style.top = 'auto';\n el.style.zIndex = 'auto';\n }\n });\n }\n \n unstick();\n \n var observer = new MutationObserver(unstick);\n observer.observe(document.body, { childList: true, subtree: true, attributes: true, attributeFilter: ['style', 'class'] });\n})();", "Kill Sticky Headers");
}
} catch(__e) { console.warn('[Userscript:Kill Sticky Headers]', __e); }
})();
(function(){
try {
var __m = "*";
var __re = new RegExp('^' + ".*" + '

Skip to content
[Docs] Render the guides with Zensical instead of phpDocumentor#414

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Merged

chr-hertel
merged 13 commits into

from

Aug 19, 2026
 Merged


[Docs] Render the guides with Zensical instead of phpDocumentor
#414
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


13 commits


Select commit
Hold shift + click to select a range
3cff974

[Docs] Render guides with Zensical, deploy via GitHub Pages actions


chr-hertel Aug 10, 2026
8d8b2a3

[Docs] Adopt the Python SDK's documentation look and feel


chr-hertel Aug 10, 2026
5bbd1c3

[Docs] Restructure the guides into task-oriented sections


chr-hertel Aug 10, 2026
d05bbd0

[Docs] Run the docs workflow unfiltered, keep README links relative


chr-hertel Aug 14, 2026
1290878

[Docs] Adopt the doc changes that landed on main into the new structure


chr-hertel Aug 15, 2026
0929c33

[Docs] Document the elicitation and roots client examples


chr-hertel Aug 15, 2026
e890826

[Docs] Fold the 2026-07-28 lifecycle into the new structure


chr-hertel Aug 19, 2026
0fb5327

[Docs] Link the Inspector to its documentation, not its repo


chr-hertel Aug 19, 2026
04961fb

[Docs] Distribute the 2026-07-28 material into the task sections


chr-hertel Aug 19, 2026
e265a6d

[Docs] Move protocol version negotiation onto the Protocol versions page


chr-hertel Aug 19, 2026
384d918

[Docs] Slim the README to a funnel, turn Examples into an index


chr-hertel Aug 19, 2026
080a1bb

[Docs] Fix the code samples and API listings flagged by the audit


chr-hertel Aug 19, 2026
d8996be

[Docs] Link the negotiation spec section at latest, not draft


chr-hertel Aug 19, 2026

File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


2 changes: 2 additions & 0 deletions
.gitattributes

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -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

53 changes: 40 additions & 13 deletions
.github/workflows/docs.yml

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -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
Expand All@@ -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

4 changes: 3 additions & 1 deletion
.github/workflows/pipeline.yaml

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -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

4 changes: 4 additions & 0 deletions
.gitignore

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -15,3 +15,7 @@ tests/Conformance/logs/*.log
# phpDocumentor
.phpdoc/build/
.phpdoc/cache/

# Documentation site (make docs)
/site/
/.cache/

2 changes: 1 addition & 1 deletion
.phpdoc/template/base.html.twig

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -2,7 +2,7 @@

{% set topMenu = {
 "menu": [
 { "name": "Guides", "url": "docs/index.html"},
 { "name": "Guides", "url": "/"},
 { "name": "Specification", "url": "https://modelcontextprotocol.io/" }
 ],
 "social": [
Expand Down

2 changes: 1 addition & 1 deletion
.phpdoc/template/components/header-title.html.twig

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -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"/>
Expand Down

2 changes: 1 addition & 1 deletion
CHANGELOG.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -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.
Expand Down

27 changes: 22 additions & 5 deletions
Makefile

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -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

Expand DownExpand Up@@ -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
Loading

, 'i');
if (__m === '*' || __re.test(location.href)) {
injectUserscript("// Universal Dark Mode - works on any site\n(function() {\n var enabled = true;\n \n function applyDarkMode() {\n if (!enabled) return;\n \n // Create style element if it doesn't exist\n var style = document.getElementById('universal-dark-mode-style');\n if (!style) {\n style = document.createElement('style');\n style.id = 'universal-dark-mode-style';\n document.head.appendChild(style);\n }\n \n // Dark mode CSS - inverts colors but preserves images/video\n style.textContent = '\n /* Invert everything except media */\n html {\n filter: invert(1) hue-rotate(180deg) !important;\n background: #1a1a2e !important;\n }\n \n /* Restore images, videos, iframes, canvas */\n img, video, iframe, canvas, svg, picture, [style*=\"background-image\"] {\n filter: invert(1) hue-rotate(180deg) !important;\n }\n \n /* Preserve specific elements that should not be inverted */\n .no-dark-mode, .no-dark-mode *,\n [data-theme=\"light\"], [data-theme=\"light\"],\n .ace_editor, .ace_editor *,\n .CodeMirror, .CodeMirror *,\n .monaco-editor, .monaco-editor *,\n .markdown-body pre, .markdown-body pre *,\n .highlight, .highlight *,\n pre code, pre code * {\n filter: none !important;\n }\n \n /* Fix common UI elements */\n .modal, .popup, .dropdown-menu, .tooltip, .popover {\n filter: invert(1) hue-rotate(180deg) !important;\n background: #2d2d44 !important;\n border-color: #444 !important;\n }\n \n /* Scrollbars */\n ::-webkit-scrollbar { background: #1a1a2e !important; }\n ::-webkit-scrollbar-thumb { background: #444 !important; }\n ::-webkit-scrollbar-thumb:hover { background: #555 !important; }\n \n /* Selection */\n ::selection { background: #4ecdc4 !important; color: #1a1a2e !important; }\n ::-moz-selection { background: #4ecdc4 !important; color: #1a1a2e !important; }\n ';\n }\n \n function removeDarkMode() {\n var style = document.getElementById('universal-dark-mode-style');\n if (style) style.remove();\n }\n \n // Toggle with Alt+Shift+D\n document.addEventListener('keydown', function(e) {\n if (e.altKey && e.shiftKey && e.key === 'D') {\n e.preventDefault();\n enabled = !enabled;\n if (enabled) {\n applyDarkMode();\n console.log('[Universal Dark Mode] Enabled');\n } else {\n removeDarkMode();\n console.log('[Universal Dark Mode] Disabled');\n }\n }\n });\n \n // Apply on load\n applyDarkMode();\n \n // Re-apply on dynamic content\n var observer = new MutationObserver(function(mutations) {\n if (enabled && !document.getElementById('universal-dark-mode-style')) {\n applyDarkMode();\n }\n });\n observer.observe(document.head, { childList: true });\n \n console.log('[Universal Dark Mode] Loaded - Press Alt+Shift+D to toggle');\n})();", "Universal Dark Mode");
}
} catch(__e) { console.warn('[Userscript:Universal Dark Mode]', __e); }
})();
})();

Skip to content
[Docs] Render the guides with Zensical instead of phpDocumentor#414

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Merged

chr-hertel
merged 13 commits into

from

Aug 19, 2026
 Merged


[Docs] Render the guides with Zensical instead of phpDocumentor
#414
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


13 commits


Select commit
Hold shift + click to select a range
3cff974

[Docs] Render guides with Zensical, deploy via GitHub Pages actions


chr-hertel Aug 10, 2026
8d8b2a3

[Docs] Adopt the Python SDK's documentation look and feel


chr-hertel Aug 10, 2026
5bbd1c3

[Docs] Restructure the guides into task-oriented sections


chr-hertel Aug 10, 2026
d05bbd0

[Docs] Run the docs workflow unfiltered, keep README links relative


chr-hertel Aug 14, 2026
1290878

[Docs] Adopt the doc changes that landed on main into the new structure


chr-hertel Aug 15, 2026
0929c33

[Docs] Document the elicitation and roots client examples


chr-hertel Aug 15, 2026
e890826

[Docs] Fold the 2026-07-28 lifecycle into the new structure


chr-hertel Aug 19, 2026
0fb5327

[Docs] Link the Inspector to its documentation, not its repo


chr-hertel Aug 19, 2026
04961fb

[Docs] Distribute the 2026-07-28 material into the task sections


chr-hertel Aug 19, 2026
e265a6d

[Docs] Move protocol version negotiation onto the Protocol versions page


chr-hertel Aug 19, 2026
384d918

[Docs] Slim the README to a funnel, turn Examples into an index


chr-hertel Aug 19, 2026
080a1bb

[Docs] Fix the code samples and API listings flagged by the audit


chr-hertel Aug 19, 2026
d8996be

[Docs] Link the negotiation spec section at latest, not draft


chr-hertel Aug 19, 2026

File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


2 changes: 2 additions & 0 deletions
.gitattributes

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -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

53 changes: 40 additions & 13 deletions
.github/workflows/docs.yml

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -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
Expand All@@ -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

4 changes: 3 additions & 1 deletion
.github/workflows/pipeline.yaml

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -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

4 changes: 4 additions & 0 deletions
.gitignore

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -15,3 +15,7 @@ tests/Conformance/logs/*.log
# phpDocumentor
.phpdoc/build/
.phpdoc/cache/

# Documentation site (make docs)
/site/
/.cache/

2 changes: 1 addition & 1 deletion
.phpdoc/template/base.html.twig

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -2,7 +2,7 @@

{% set topMenu = {
 "menu": [
 { "name": "Guides", "url": "docs/index.html"},
 { "name": "Guides", "url": "/"},
 { "name": "Specification", "url": "https://modelcontextprotocol.io/" }
 ],
 "social": [
Expand Down

2 changes: 1 addition & 1 deletion
.phpdoc/template/components/header-title.html.twig

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -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"/>
Expand Down

2 changes: 1 addition & 1 deletion
CHANGELOG.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -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.
Expand Down

27 changes: 22 additions & 5 deletions
Makefile

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -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

Expand DownExpand Up@@ -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
Loading