Skip to content

Commit d2c5fa3

Browse files
committed
docs(readme): cut 2025-only / deprecated walkthroughs; simplify
Remove material that isn't 2026-specific: - MCP Session Management Compliance Testing walkthrough → one-line pointer to the 2025-11-25 opt-in packages (sessions/DELETE/TTL are 2025-only) - 'What the Compliance Test Verifies' + 'Expected Output' (session-ID / persistence / expiry / reinitialize / DELETE / isolation) — 2025 sessions - Storage Backend Configuration + Customizing TTL Configuration — 2025 session-TTL framing - Server-Sent Events (SSE) Verification + Manual GET-SSE verification — GET SSE is deprecated (SEP-2596); replaced with a short 'Notifications & Streaming' note: 2026 rides POST SSE (request-scoped notifications + subscriptions/listen), with a live demo and the wire-test command - Running Tests: swap the 2025 concurrent_session example for ci-gates.sh and a 2026 wire-acceptance suite README 1343 → 1211 lines (-132); brief 2025-opt-in pointers retained so readers know the lane exists. Docs-only; not a doctest target.
1 parent 55ce87d commit d2c5fa3

1 file changed

Lines changed: 20 additions & 152 deletions

File tree

README.md

Lines changed: 20 additions & 152 deletions
Original file line numberDiff line numberDiff line change
@@ -1075,29 +1075,10 @@ curl -X POST http://127.0.0.1:8080/mcp \
10751075
}'
10761076
```
10771077

1078-
> On the `2025-11-25` opt-in build, `tools/call` instead requires the stateful handshake
1079-
> and the `Mcp-Session-Id` header, and GET SSE notifications are available on that stream.
1080-
1081-
### MCP Session Management Compliance Testing
1082-
1083-
Sessions (and the `Mcp-Session-Id` header) belong to the stateful **2025-11-25** spec;
1084-
the example packages below are pinned to the `protocol-2025-11-25` opt-in in their own
1085-
manifests, so the commands work unchanged on this branch. The default 2026-07-28 build
1086-
is stateless and has no session management to test.
1087-
1088-
#### Running the Session Management Compliance Test
1089-
1090-
```bash
1091-
# 1. Start a server with session storage (choose backend: sqlite, postgres, dynamodb, or inmemory)
1092-
cargo run -p client-initialise-server -- --port 52950 --storage-backend dynamodb --create-tables
1093-
1094-
# 2. In another terminal, run the comprehensive compliance test (IMPORTANT: include RUST_LOG=info)
1095-
RUST_LOG=info cargo run -p session-management-compliance-test -- http://127.0.0.1:52950/mcp
1096-
1097-
# 3. Alternative: Use different storage backends
1098-
cargo run -p client-initialise-server -- --port 52951 --storage-backend sqlite --create-tables
1099-
RUST_LOG=info cargo run -p session-management-compliance-test -- http://127.0.0.1:52951/mcp
1100-
```
1078+
> The 2026 core is stateless. Sessions, the `Mcp-Session-Id` header, and the session
1079+
> lifecycle (DELETE termination, TTL/expiry) are part of the **2025-11-25 opt-in** lane;
1080+
> the `client-initialise-server` + `session-management-compliance-test` packages exercise
1081+
> them under that pin.
11011082
11021083
## 🛠️ Development & Testing
11031084

@@ -1119,14 +1100,14 @@ The framework includes a **comprehensive test suite** covering all functionality
11191100
# Run all tests (recommended - includes E2E integration tests)
11201101
cargo test --workspace
11211102

1122-
# Run specific test suite
1123-
cargo test --package mcp-e2e-shared --test all -- concurrent_session
1103+
# Run the full lane-by-lane gate suite (2026 default + 2025 opt-in matrix)
1104+
./scripts/ci-gates.sh all
1105+
1106+
# Run a 2026 wire-acceptance suite directly
1107+
cargo test -p turul-mcp-server --no-default-features --features http,sse,protocol-2026-07-28 --test discover_stateless_2026
11241108

11251109
# Run with logging output
11261110
RUST_LOG=info cargo test --workspace
1127-
1128-
# Clean build and test (verifies auto-build works)
1129-
cargo clean && cargo test --workspace
11301111
```
11311112

11321113
**Key Features:**
@@ -1136,132 +1117,19 @@ cargo clean && cargo test --workspace
11361117

11371118
The test infrastructure automatically builds required test server binaries (`resource-test-server`, `prompts-test-server`, `tools-test-server`, etc.) when running integration tests. This ensures a seamless developer experience.
11381119

1139-
#### What the Compliance Test Verifies
1140-
1141-
The comprehensive test validates all MCP session management requirements:
1142-
1143-
- **✅ Session ID Generation**: UUID v7 with cryptographic security and ASCII compliance
1144-
- **✅ Session Persistence**: Proper session validation and storage backend integration
1145-
- **✅ Session Expiry**: TTL-based cleanup and 404 responses for expired sessions
1146-
- **✅ Client Reinitialize**: Graceful session recovery on expiry
1147-
- **✅ DELETE Termination**: Explicit session termination support
1148-
- **✅ Session Isolation**: Multi-session security and data separation
1149-
1150-
#### Expected Output
1151-
1152-
```
1153-
🧪 MCP Session Management Compliance Test
1154-
═══════════════════════════════════════════
1155-
✅ Session ID generation compliance verified
1156-
✅ Session persistence compliance verified
1157-
✅ Session expiry compliance verified
1158-
✅ Client reinitialize compliance verified
1159-
✅ DELETE session termination compliance verified
1160-
✅ Session isolation compliance verified
1161-
1162-
🎉 MCP SESSION MANAGEMENT COMPLIANCE: COMPLETE
1163-
═══════════════════════════════════════════════
1164-
```
1165-
1166-
#### Storage Backend Configuration
1167-
1168-
**DynamoDB** (Development):
1169-
- 5-minute TTL with automatic cleanup
1170-
- GSI indexes for efficient queries
1171-
- AWS credentials required
1172-
1173-
**SQLite** (Development):
1174-
- File-based persistence
1175-
- 5-minute TTL with background cleanup
1176-
- No external dependencies
1177-
1178-
**PostgreSQL** (Enterprise):
1179-
- Full SQL features with indexing
1180-
- 5-minute TTL with efficient cleanup
1181-
- Connection string required
1182-
1183-
**InMemory** (Testing):
1184-
- Fast, no persistence
1185-
- 5-minute TTL with memory cleanup
1186-
- Zero configuration
1187-
1188-
#### Customizing TTL Configuration
1120+
### Notifications & Streaming
11891121

1190-
```rust
1191-
// Custom TTL configuration (default: 5 minutes)
1192-
let config = DynamoDbConfig {
1193-
session_ttl_minutes: 30, // 30-minute session TTL
1194-
event_ttl_minutes: 15, // 15-minute event TTL
1195-
..Default::default()
1196-
};
1197-
```
1198-
1199-
### Server-Sent Events (SSE) Verification
1200-
1201-
The framework includes comprehensive SSE testing to verify real-time notification streaming:
1202-
1203-
#### Running SSE Tests
1204-
1205-
```bash
1206-
# Test SSE functionality in prompts package
1207-
cargo test --package mcp-prompts-tests --test all -- sse
1208-
1209-
# Test specific SSE scenarios
1210-
cargo test --package mcp-prompts-tests test_sse_prompts_connection_establishment -- --nocapture
1211-
cargo test --package mcp-prompts-tests test_sse_prompts_list_changed_notification -- --nocapture
1212-
cargo test --package mcp-prompts-tests test_sse_prompts_session_isolation -- --nocapture
1213-
1214-
# Test SSE functionality in resources package
1215-
cargo test --package mcp-resources-tests --test all -- sse
1216-
1217-
# Test specific resource SSE scenarios
1218-
cargo test --package mcp-resources-tests test_sse_connection_establishment -- --nocapture
1219-
cargo test --package mcp-resources-tests test_sse_resource_list_changed_notification -- --nocapture
1220-
cargo test --package mcp-resources-tests test_sse_session_isolation -- --nocapture
1221-
```
1122+
On the 2026 default, notifications ride **POST** SSE — request-scoped notifications
1123+
(`notifications/progress`, `notifications/message`) flow on the originating request's
1124+
own response stream, and server-push subscriptions use the long-lived
1125+
`subscriptions/listen` POST stream. The 2025-era GET-SSE endpoint and
1126+
`Mcp-Session-Id`-keyed streams are part of the 2025-11-25 opt-in lane (the HTTP+SSE
1127+
transport is deprecated upstream, SEP-2596).
12221128

1223-
#### Expected SSE Test Output
1224-
1225-
```
1226-
🚀 Starting MCP Resource Test Server on port 18994
1227-
✅ Session 01997404-d8f4-7b20-b76d-ac1f4be628a3 created and immediately initialized
1228-
✅ SSE connection: session=01997404-d908-7e62-ae74-af87f1523836, connection=01997404-d909-7001-8b95-296e806aa1e1
1229-
✅ Total notifications detected: 1
1230-
✅ Session ID correlation verified
1231-
✅ Valid SSE format compliance verified
1232-
1233-
test result: ok. 8 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out
1234-
```
1235-
1236-
#### Manual SSE Verification (2025-11-25 opt-in)
1237-
1238-
GET SSE with a session ID is part of the stateful 2025-11-25 core, which is the opt-in
1239-
build (`--no-default-features --features protocol-2025-11-25`). The default 2026-07-28
1240-
build is stateless and does not hold a session-keyed GET SSE stream.
1241-
1242-
```bash
1243-
# 1. Start a 2025-11-25-pinned server (the pin lives in the example's own manifest)
1244-
cargo run -p prompts-test-server -- --port 8080
1245-
1246-
# 2. Get session ID via initialization
1247-
curl -X POST http://127.0.0.1:8080/mcp \
1248-
-H "Content-Type: application/json" \
1249-
-d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}'
1250-
1251-
# 3. Connect to SSE stream (replace SESSION_ID with actual ID)
1252-
curl -N -H "Accept: text/event-stream" \
1253-
-H "Mcp-Session-Id: SESSION_ID" \
1254-
http://127.0.0.1:8080/mcp
1255-
1256-
# Expected SSE output:
1257-
# id: 0
1258-
# event: ping
1259-
# data: {"type":"keepalive"}
1260-
#
1261-
# id: 1
1262-
# event: notification
1263-
# data: {"type":"resource_update","resource":"prompts/list"}
1264-
```
1129+
- **Live demo**: `cargo run -p notification-server`, then drive it with
1130+
`cargo run -p streamable-http-client http://127.0.0.1:8005/mcp` (opens a
1131+
`subscriptions/listen` stream and triggers list-changed + resource-update deliveries).
1132+
- **Wire tests**: `cargo test -p turul-mcp-server --no-default-features --features http,sse,protocol-2026-07-28 --test subscriptions_listen_2026`
12651133

12661134
## 📊 Business Value Examples
12671135

0 commit comments

Comments
 (0)