modelcontextprotocol/php-sdk
Watch
1
0
Fork
You've already forked php-sdk
 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

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

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

phpDocumentor's guide renderer copies the markdown through mostly verbatim:
relative links between pages keep pointing at `*.md` targets that do not exist
in the built site, and nothing validates them, so the published guides are full
of dead links.

Zensical (the Material for MkDocs team's successor to MkDocs) resolves internal
links against the page tree and fails the build on a broken one. `zensical
build --strict` already found four dead links on the first run — three
repo-relative links escaping docs/ (fixed to point at GitHub) and one wrong
in-page anchor.

phpDocumentor stays on for the class-level API reference only; `make docs`
builds the guides into site/ and mounts the reference at site/api/, so its two
header links back to the guides now target the site root.

Deployment moves from pushing a gh-pages branch to the official GitHub Pages
actions, and from release-only to every push on main, with pull requests
building (but not deploying) so a broken link fails review instead of the site.

NOTE: this needs the repository's Pages source switched to "GitHub Actions"
(Settings -> Pages) once.

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

The docs site now uses the same theme configuration as
https://py.sdk.modelcontextprotocol.io/ so the language SDKs read as one set
of docs: the MCP mark as logo and favicon, Inter/JetBrains Mono, the
black/slate palette with a three-way (system/light/dark) toggle, instant
navigation, code copy/annotate, and a right-hand table of contents.

The markdown extension set is widened to the same list (tabbed blocks,
task lists, footnotes, emoji/icons, mermaid fences), which the content
restructure builds on.

Styling is otherwise stock: no custom stylesheet, and Zensical's own
`modern` theme variant, pinned explicitly rather than left to the default.

The one departure is code highlighting, which is broken out of the box here:
Pygments only highlights PHP after a `<?php` tag, so the guides — whose code
blocks are almost all fragments — rendered as flat plain text. The `php`
lexer is extended with `startinline`, and complete-file blocks use a
`php-file` lexer that keeps the literal open tag highlighted.

* [Docs] Restructure the guides into task-oriented sections

The guides were ten flat pages, each opening with a hand-maintained table of
contents and each mixing several audiences: `mcp-elements.md` covered tools,
prompts, schema generation and handler-side logging, `transports.md` covered
both transports plus framework integration, and `server-builder.md` covered
configuration, sessions and custom message handlers.

They are now split along the same lines as the Python SDK's documentation
(https://py.sdk.modelcontextprotocol.io/), one topic per page:

  Get started        installation, first server, the Inspector
  Servers            tools, resources, resource templates, prompts,
                     completions, schema generation, registration
  Inside your handler  the ClientGateway, logging
  Running your server  builder, STDIO, HTTP, framework integration,
                     sessions, authorization
  Clients            connecting, transports, capabilities, server-initiated
                     requests, error handling
  Advanced           events, protocol extensions, custom message handlers

Prose is carried over as-is apart from the seams; what is new is the landing
page and one index page per section, which say what the section is for and
where to go next, so no page is a dead end.

The per-page "Table of Contents" lists are gone — the theme renders one from
the headings — and GitHub's `> [!IMPORTANT]` blockquotes became admonitions,
which Zensical renders as callouts rather than plain quotes.

Every code sample and factual claim was then checked against src/ and the
runnable examples, which turned up long-standing errors in the carried-over
prose. Samples that could not run: a prompt using a `system` role (MCP has
only user/assistant), `Mcp\Schema\PromptMessage` (it is under `Schema\Content`)
constructed with an array instead of a single content object,
`Mcp\Capability\Prompt\Completion\ProviderInterface` (it is
`Mcp\Capability\Completion\ProviderInterface`), `new EmbeddedResource(type:,
resource: [...])` (neither parameter exists), a `: resource` return type
(not a PHP type), `#[McpResource]` with a `{path}` variable (that is a
template), a stray quote in the builder example, a `middlewares:` argument
(it is `middleware:`), and `getRequest()->getAttribute()` in the OAuth guide
(no such method — the values arrive on the request meta). Claims corrected:
sampling's `system_prompt` option (it is `systemPrompt`), `SampleMessage`
(it is `SamplingMessage`), `Notification` called an interface (abstract
class), "parameter order matters" for URI templates (bound by name), full
RFC 6570 support (only simple `{var}`), the tool description fallback chain,
`void` returning empty content, a non-zero STDIO exit code, `ErrorEvent`
being null for parse errors, handlers being "prepended", `Psr16StoreSession`,
and PSR-3 log context being sent to the client (it is dropped). Sixteen
`examples/` paths were missing their `server/` segment.

README, the OAuth ADR and one source comment now point at the published site
instead of at markdown files that moved.

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

The `paths:` filters were mostly noise: `src/**` had to be in the list for
the phpDocumentor build, which meant the workflow ran on nearly every PR
anyway. They also missed two real inputs — `.phpdoc/template/**` and
`composer.lock` — so a template tweak or a phpDocumentor bump could change
the rendered site without triggering a build.

README links go back to relative repo paths. The README is not part of the
Zensical site (`docs_dir` is `docs/`), so those links are only ever resolved
by GitHub and Packagist, where absolute URLs break in-repo navigation for no
gain. The site pointer and the generated API reference stay absolute.

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

Twelve commits landed while the restructure was open, seven of them touching
the flat guides this branch replaces. Renames merged on their own; the three
files that were split apart needed their new sections placed by hand:

- Connection retries, protocol version negotiation, sampling with tools and
  roots from `client.md` into `client/connecting.md` and
  `client/server-requests.md`
- `ResourceLink` and structured output from `mcp-elements.md` into
  `servers/tools.md`
- Protocol version negotiation from `server-builder.md` into
  `run/server-builder.md`

The `setMaxRetries()` note claiming the value is never acted on is gone —
#413 implemented it. Callouts became admonitions and cross-links were
repointed at the new paths, as everywhere else in this branch.

* [Docs] Document the elicitation and roots client examples

Both were missing from the examples guide: the elicitation client predates
this branch, the roots client arrived with #395.

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

Main's stateless-lifecycle.md becomes a docs/lifecycle/ section, and the pages
main touched — deprecations, the middleware split, the client's modern era —
land where the restructure moved them.

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

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

The Python and TypeScript SDKs file each feature where the task lives and keep
only an era comparison on its own page. Follow them: input-required moves next
to the other handler concerns, caching, subscriptions and era routing to
"Running your server", and one Protocol versions page carries the rest.

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

The builder page keeps the setProtocolVersion() knob and links out; how a
revision is agreed now sits beside the era it belongs to.

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

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

* [Docs] Link the negotiation spec section at latest, not draft
This commit is contained in:
Christopher Hertel 2026-08-20 00:03:54 +02:00 • committed by GitHub
commit 0cd5d56164
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
1 changed files with 4245 additions and 4069 deletions
Download patch file Download diff file Expand all files Collapse all files

178
docs/protocol-versions.md Normal file
View file

@ -0,0 +1,178 @@
# Protocol versions
MCP has two eras. Everything up to `2025-11-25` opens with an `initialize` handshake and
keeps the negotiated revision on a session. Protocol revision `2026-07-28` removed both:
everything a server needs to answer a request travels *in* that request, so any process can
answer any request and none of them need to share state.
The SDK serves both, and a server built the ordinary way answers either. This page is the
map; the mechanics live with the task they belong to.
## The two eras
| | Handshake era (`2025-11-25` and earlier) | Modern era (`2026-07-28`) |
| --- | --- | --- |
| Opening | `initialize` / `notifications/initialized` | none |
| Version | negotiated once, kept on the session | declared on every request |
| Capabilities | exchanged once | declared on every request |
| Discovery | `initialize` result | `server/discover` |
| Sessions | `Mcp-Session-Id` | removed |
| Server → client requests | sent as JSON-RPC requests | returned in the result (MRTR) |
| Change notifications | HTTP `GET` stream, `resources/subscribe` | `subscriptions/listen` |
| Dispatcher | `Protocol` | `StatelessProtocol` |
| HTTP entry | `StreamableHttpTransport` — the same one, for both |
`ProtocolVersion::isModern()` tells the two apart, and
`Mcp\Schema\Enum\ProtocolVersion::FIRST_MODERN_VERSION` is where the boundary sits.
## Negotiating in the handshake era
Revisions up to `2025-11-25` agree on one during `initialize`. The client names the revision it wants to speak, and
the server answers with the revision the connection will actually use. Both sides disconnect if they cannot agree.
This follows the
[protocol version negotiation](https://modelcontextprotocol.io/specification/latest/basic/versioning#protocol-version-negotiation)
section of the specification. The modern era negotiates nothing — each request names its own revision.
The SDK's known revisions live in `Mcp\Schema\Enum\ProtocolVersion`, declared oldest to newest:
```php
use Mcp\Schema\Enum\ProtocolVersion;
ProtocolVersion::latestHandshake(); // newest revision reachable via `initialize`
ProtocolVersion::handshakeVersions(); // every revision the server will negotiate, oldest first
ProtocolVersion::modernVersions(); // every revision served without a handshake
ProtocolVersion::V2025_11_25->isAtLeast(ProtocolVersion::V2025_06_18); // true
```
Comparisons go through declaration order rather than string collation. The identifiers happen to be ISO dates today,
but they are an enumerated set rather than an ordered scalar, so nothing should assume they sort chronologically.
### How the server answers
| Client requests | Server responds with |
| --- | --- |
| A revision the server supports | That same revision |
| An unknown or malformed revision | `ProtocolVersion::latestHandshake()` as a counter-offer |
| A modern revision such as `2026-07-28` | `ProtocolVersion::latestHandshake()` as a counter-offer |
A counter-offer is not an error: the client decides whether it can continue on the offered revision or must close the
connection. The negotiated revision is stored on the session under `protocol_version`.
The last row is not a rejection of an unknown revision — the SDK knows `2026-07-28`, it just cannot be reached through
this handshake. The modern era replaced `initialize` with per-request metadata, so answering with one of its revisions
would leave a connection neither side could use. A client speaking it never gets here: it sends the envelope instead
of an `initialize` request, and the transport routes it to the modern dispatcher before any negotiation is attempted.
See [Serving both eras](run/protocol-eras.md).
### Pinning a revision
`Builder::setProtocolVersion()` pins the handshake to exactly one revision instead of negotiating across the supported
set. The pin wins over the client's request, so a client asking for anything else receives the pinned revision as a
counter-offer and has to decide whether to continue. Leave it unset unless you have a reason to refuse other
revisions.
It pins the handshake era only. `setModernVersions()` narrows what the modern leg answers for, and
`withoutModernEra()` removes that leg altogether — see
[Serving one era only](run/protocol-eras.md#serving-one-era-only).
!!! note
On the Streamable HTTP transport, every handshake-era request after the handshake also carries an
`MCP-Protocol-Version` header, which is validated separately by `ProtocolVersionMiddleware`. The pin does not reach
that check: the transport builds the middleware without access to the server configuration, so the header keeps
being accepted for every revision in `ProtocolVersion::handshakeVersions()`. To narrow it too, construct the
middleware yourself with the same revision — see
[Protocol Version Validation](run/http.md#protocol-version-validation).
## What changes, and where it is written down
Tools, resources, prompts and their handlers are unaffected — the same registrations serve
either lifecycle. What changes:
* **[Asking for input](handlers/input-required.md)** — a handler that needs elicitation,
sampling or roots *returns* the ask instead of calling out. Write handlers this way and
they serve both eras.
* **[Serving both eras](run/protocol-eras.md)** — what a modern request carries, how one
endpoint classifies and routes each request, and how to serve one era only.
* **[Caching](run/caching.md)** — the `ttlMs` / `cacheScope` hints a cacheable result must
carry.
* **[Subscriptions](run/subscriptions.md)** — `subscriptions/listen` and the notification bus
behind it.
* **[Sessions](run/sessions.md)** — handshake-era only; the modern era has none.
* Progress and logging become per-request opt-ins — see
[Talking back to the client](handlers/client-communication.md#progress) and
[Logging](handlers/logging.md).
## Speaking it from a client
One line selects the lifecycle; nothing else about the [client API](client/index.md) changes.
```php
$client = Client::builder()
->setClientInfo('my-client', '1.0.0')
->setProtocolVersion(ProtocolVersion::V2026_07_28)
->setCapabilities(new ClientCapabilities(elicitation: true))
->addRequestHandler($myElicitationHandler)
->build();
$client->connect(new HttpTransport('https://example.com/mcp'));
$client->callTool('greet', []);
```
What that changes underneath:
- **No handshake.** `connect()` sends no `initialize`. It asks `server/discover` only for the
server's identity, and a server that does not answer it still yields a usable connection —
the method is optional. If discovery *does* report `supportedVersions` and the configured
revision is not among them, the client moves to a modern revision the server lists, or
refuses the connection outright rather than talking past it.
- **An envelope on every request**, carrying the revision, the declared capabilities and the
client identity. The capabilities are what let a server decide, per request, whether it may
ask for input.
- **Headers on every POST** — `MCP-Protocol-Version`, `Mcp-Method`, and `Mcp-Name` where the
method addresses a subject. Arguments annotated with `x-mcp-header` are mirrored into
`Mcp-Param-*`, which requires the client to have listed the tool first; `tools/list` is what
populates that knowledge. A tool whose annotations are malformed is dropped from the listing
and refused if called, since the client cannot produce the headers it demands.
- **[Multi round-trip calls](handlers/input-required.md) are answered by the client.** A result
of `resultType: "input_required"` is resolved through the same
[request handlers](client/server-requests.md) that served server-initiated requests in the
handshake era, and the call is re-sent with `inputResponses` and the server's `requestState`
echoed back byte for byte, under a new JSON-RPC id. The caller sees one call and one result.
Headers are an HTTP concern, so a transport opts into them by implementing
`HeaderAwareTransportInterface`; `HttpTransport` does, `StdioTransport` has nothing to carry
them on. Everything else — the envelope, the skipped handshake, the round-trip loop — applies
to both.
See
[`examples/client/stateless_lifecycle_client.php`](https://github.com/modelcontextprotocol/php-sdk/blob/main/examples/client/stateless_lifecycle_client.php)
for a runnable version, described in [Examples](examples.md#modern-era-client).
## What was removed
Answered with `404` and `-32601` by a modern server:
- `initialize`, `notifications/initialized`
- `ping`
- `logging/setLevel` — replaced by `_meta["io.modelcontextprotocol/logLevel"]`
- `resources/subscribe`, `resources/unsubscribe` — replaced by the `resourceSubscriptions`
filter of `subscriptions/listen`
- `notifications/roots/list_changed`
Also gone: `Mcp-Session-Id`, the HTTP `GET` stream, and SSE resumability (`Last-Event-ID`).
A broken response stream loses the request; the client re-issues it with a new id.
Error code `-32002` (resource not found) is retired in favour of `-32602`, and must not be
emitted by a server of this revision. The SDK picks the code from the revision serving the
request, so a handshake-era client still gets `-32002`.
## Deprecations
Roots, sampling and logging are all **deprecated** as of this revision
([SEP-2577](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2577)), earliest
removal `2027-07-28`. They remain functional until then; new servers should pass directories
through tool arguments or resource URIs instead of roots, integrate with an LLM provider
directly instead of sampling, and log to `stderr` or OpenTelemetry instead of
`notifications/message`.