[Docs][Examples][CI] Document and gate the 2026-07-28 lifecycle (#457)

docs/stateless-lifecycle.md walks the revision end to end - per-request
_meta, server/discover, multi round-trip requests, caching and subscriptions
- and a runnable example on each side shows what that looks like in code.

CI matrixes both conformance roles over both revisions. --spec-version is
cumulative across the dated revisions, so 2025-11-25 covers the two before
it; 2026-07-28 is not cumulative with them and needs its own run against its
own baseline. The runner is pinned so a PR only goes red for reasons in the
PR, and conformance-weekly tracks the moving target instead - on both
revisions, since the draft scenarios ship only on the alpha dist-tag.

The Inspector cannot reach a modern-lifecycle server (it opens with
initialize), so the example is covered by integration tests instead: one
drives it with hand-built HTTP the way a conforming client would, one drives
it with this SDK's client, and one drives the single endpoint from both eras.

Author: chr-hertel

.github/workflows/conformance-weekly.yaml

@@ -26,7 +26,7 @@ jobs:
             baseline: conformance-baseline-2025-11-25.yml
           - spec-version: '2026-07-28'
             dist-tag: alpha
-            path: '/stateless'
+            path: '/'
             baseline: conformance-baseline-2026-07-28.yml
     steps:
       - uses: actions/checkout@v7

.github/workflows/pipeline.yaml

@@ -109,7 +109,7 @@ jobs:
             path: '/'
             baseline: conformance-baseline-2025-11-25.yml
           - spec-version: '2026-07-28'
-            path: '/stateless'
+            path: '/'
             baseline: conformance-baseline-2026-07-28.yml
 
     steps:

.gitignore

@@ -8,7 +8,7 @@ examples/**/cache
 examples/**/sessions
 tests/Conformance/client-conformance.json
 tests/Conformance/server-conformance.json
-tests/Conformance/results
+tests/Conformance/results*
 tests/Conformance/sessions
 tests/Conformance/logs/*.log
 

Makefile

@@ -55,7 +55,7 @@ conformance-draft-server:
 	@echo "Waiting for server to start..."
 	@sleep 5
 	rm -rf tests/Conformance/results-2026-07-28
-	cd tests/Conformance && $(CONFORMANCE) server --url http://localhost:8000/stateless --suite all --spec-version 2026-07-28 --expected-failures conformance-baseline-2026-07-28.yml --output-dir results-2026-07-28 || true
+	cd tests/Conformance && $(CONFORMANCE) server --url http://localhost:8000/ --suite all --spec-version 2026-07-28 --expected-failures conformance-baseline-2026-07-28.yml --output-dir results-2026-07-28 || true
 	php tests/Conformance/score.php server 2026-07-28 results-2026-07-28
 	docker compose -f tests/Conformance/Fixtures/docker-compose.yml down
 

docs/index.md

@@ -3,6 +3,7 @@
 - [MCP Elements](mcp-elements.md) — Core capabilities (Tools, Resources, Resource Templates, and Prompts) with registration methods.
 - [Server Builder](server-builder.md) — Fluent builder class for creating and configuring MCP server instances.
 - [Client](client.md) — Client SDK for connecting to and communicating with MCP servers.
+- [The 2026-07-28 Lifecycle](stateless-lifecycle.md) — The stateless protocol revision: per-request metadata, `server/discover`, multi round-trip requests, caching and subscriptions.
 - [Transports](transports.md) — STDIO and HTTP transport implementations with guidance on choosing between them.
 - [Server-Client Communication](server-client-communication.md) — Methods for servers to communicate back to clients: sampling, logging, progress, and notifications.
 - [Protocol Extensions](extensions.md) — Opt-in protocol extensions announced during capability negotiation, including MCP Apps (HTML UI resources).

docs/server-client-communication.md

@@ -1,6 +1,13 @@
 # Client Communication
 
-MCP supports various ways a server can communicate back to a server on top of the main request-response flow.
+MCP supports various ways a server can communicate back to a client on top of the main request-response flow.
+
+> **Protocol revision `2026-07-28`.** This page describes the handshake era, where a server sends its own
+> JSON-RPC requests to the client. The modern lifecycle removed that: sampling, elicitation and roots are
+> carried back inside the *result* instead, and `ClientGateway::sample()`, `elicit()` and `listRoots()`
+> raise a `LogicException` there. Logging and progress still work as described below — they simply travel
+> on the request's own response stream, and the client opts into each. See
+> [The 2026-07-28 Lifecycle](stateless-lifecycle.md).
 
 ## Table of Contents