Skip to content

Commit 09de8fb

Browse files
hortovanyihortovanyi
committed
docs(readme): release-ready rewrite — 2026-07-28 as current spec
Drop the WIP/release-candidate banner and branch-scoped language; present MCP 2026-07-28 as the current specification (2025-11-25 stays the documented opt-in). Rewrite the opening for first-time readers and reorder: intro -> highlights -> Quick Start (code first) -> spec deep-dive; move the turul-rpc layering note down beside Architecture. Fix stale error-code list (-32001/-32003/-32004 -> -32020/-32021/-32022, matching the implemented 2026-07-02 re-pin).
1 parent f913dc3 commit 09de8fb

1 file changed

Lines changed: 75 additions & 88 deletions

File tree

‎README.md‎

Lines changed: 75 additions & 88 deletions
Original file line numberDiff line numberDiff line change
@@ -1,25 +1,12 @@
1-
> # 🚧 Work In Progress — MCP 2026-07-28 adoption
2-
>
3-
> **This branch (`feat/turul-mcp-protocol-2026-07-28`) is migrating the framework to the
4-
> [MCP 2026-07-28 release candidate](https://blog.modelcontextprotocol.io/posts/2026-07-28-release-candidate/)
5-
> (stateless core: `server/discover` instead of `initialize`, per-request `_meta`, no
6-
> `Mcp-Session-Id`; tasks moved to an extension; Roots/Sampling/Logging deprecated).**
7-
> It is **not** merged to `main`, which continues to track the stable 2025-11-25 line.
8-
>
9-
> - **`cargo build` / `cargo test` default to the 2026-07-28 spec.**
10-
> - **2025-11-25 is still supported** as an opt-in:
11-
> `--no-default-features --features protocol-2025-11-25`.
12-
> - Servers are single-spec per build; the client (`turul-mcp-client`) is bilingual.
13-
> - Expect churn: examples, docs, and E2E tests are still being migrated to 2026 semantics.
14-
151
# Turul MCP Framework
162

17-
A comprehensive Rust framework for building Model Context Protocol (MCP) servers and clients with modern patterns, extensive tooling, and enterprise-grade features. On this branch the default build targets the **MCP 2026-07-28 specification** (stateless core: `server/discover`, per-request `_meta`, no `Mcp-Session-Id`); **MCP 2025-11-25 remains available** as an opt-in (`--no-default-features --features protocol-2025-11-25`).
3+
Build [Model Context Protocol (MCP)](https://modelcontextprotocol.io) servers and clients in Rust — from a five-line tool server to serverless AWS Lambda deployments.
4+
5+
Turul gives you the full MCP surface (tools, resources, prompts, completion, notifications, extensions) behind a zero-configuration builder API: annotate a function or derive on a struct, add it to the builder, run. The framework generates the schemas, wires the transport, and keeps you spec-compliant.
186

19-
**Pre-1.0 (0.4.x).** The framework is production-shaped — comprehensive test coverage, zero-warning gates — but public APIs may still change before 1.0.0. The default build is MCP 2026-07-28 (stateless); 2025-11-25 is opt-in.
7+
The default build targets **MCP 2026-07-28**, the current specification. The previous spec, **2025-11-25**, stays fully supported as an opt-in build (`--no-default-features --features protocol-2025-11-25`). Servers are single-spec per build; the client speaks both and negotiates per connection.
208

21-
## 🧪 Comprehensive Test Coverage
22-
**Broad test coverage across the workspace** • **Complete async SessionContext integration** • **Framework-native testing patterns**
9+
> **Pre-1.0 (0.4.x):** production-shaped — comprehensive test coverage, zero-warning gates — but public APIs may still change before 1.0.0.
2310
2411
## ✨ Key Highlights
2512

@@ -31,75 +18,6 @@ A comprehensive Rust framework for building Model Context Protocol (MCP) servers
3118
- **☁️ Serverless Support**: AWS Lambda integration with streaming responses and SQS event processing
3219
- **🔧 Development Features**: Session management, real-time notifications, performance monitoring, and UUID v7 support
3320

34-
## 🆕 MCP 2026-07-28
35-
36-
The default build targets the 2026-07-28 release candidate. This is a **stateless
37-
rewrite** of the protocol with several core methods removed — if you're coming from
38-
2025-11-25, read this section first.
39-
40-
### What's new (and implemented here)
41-
42-
- **Stateless core** — `server/discover` advertises versions/capabilities/identity;
43-
every request carries `protocolVersion` + `clientInfo` + `clientCapabilities` in
44-
`_meta` under `io.modelcontextprotocol/*`. Any server instance serves any request.
45-
- **MRTR (Multi-Round-Trip Requests, SEP-2322)** — a tool/resource/prompt returns an
46-
`InputRequiredResult` to ask for elicitation/sampling/roots input; the client
47-
answers and retries the original call. This replaces all server-initiated requests.
48-
→ `examples/mrtr-elicitation-server`
49-
- **`subscriptions/listen`** — the ack-first, filtered, long-lived POST SSE stream that
50-
replaces 2025's GET-SSE resumability and the `resources/subscribe` RPC.
51-
- **Tasks extension** (`io.modelcontextprotocol/tasks`, SEP-2663) — durable poll handles
52-
via `turul-mcp-ext-tasks` (opt-in `ext-tasks` feature): `.with_ext_tasks()` +
53-
`.ext_task_tool()` server-side, `call_tool_or_task` / `task_*` client-side.
54-
→ `examples/ext-tasks-server`
55-
- **MCP Apps extension** (`io.modelcontextprotocol/ui`, SEP-1865) — MCP-side bindings
56-
(`turul-mcp-ext-apps`).
57-
- **SEP-2243 request-metadata headers** — `Mcp-Method` / `Mcp-Name` / `Mcp-Param-*` let
58-
infrastructure route on method/tool/arguments without parsing JSON bodies.
59-
→ `examples/header-bound-tools-server`
60-
- **Origin validation / DNS-rebinding protection** — on by default (ADR-031).
61-
→ `examples/origin-policy-server`
62-
- **JSON Schema 2020-12**, **caching headers** (`ttlMs` / `cacheScope` on list/read
63-
results), and OAuth 2.1 Resource Server hardening (RFC 9207/9728).
64-
65-
### What changed from 2025-11-25
66-
67-
- **No handshake** — `initialize` → `notifications/initialized` → `Mcp-Session-Id` is
68-
gone; capabilities ride per-request `_meta` instead.
69-
- **Error codes** — resource-not-found moved from `-32002` to `-32602`; new
70-
`-32001` (header mismatch), `-32003` (missing required client capability),
71-
`-32004` (unsupported protocol version).
72-
- **Per-request logging** — log level is set per-request via `io.modelcontextprotocol/logLevel`
73-
in `_meta`; servers must not emit `notifications/message` for requests that didn't opt in.
74-
- **Deprecations (SEP-2577)** — Roots, Sampling, and Logging are deprecated (earliest
75-
removal 2027-07-28). Still implemented; on 2026 the server-initiated forms ride MRTR.
76-
77-
### What's removed from the core (2026 default → these 404 / 405)
78-
79-
| Removed | SEP | Replacement on 2026 |
80-
|---|---|---|
81-
| `initialize` / `notifications/initialized` | 2575 | `server/discover` + per-request `_meta` |
82-
| Protocol sessions / `Mcp-Session-Id` | 2567 | stateless; server-minted handles as tool args |
83-
| `ping` | 2575 | — (use `server/discover` for liveness) |
84-
| `logging/setLevel` | 2575 | per-request `_meta.logLevel` |
85-
| `notifications/roots/list_changed` | 2575 | — |
86-
| GET SSE endpoint / `resources/subscribe` | 2575 | `subscriptions/listen` |
87-
| Core `tasks/*` (incl. `tasks/list`, blocking `tasks/result`) | 2663 | the Tasks **extension** (`tasks/get` polling + `tasks/update`) |
88-
89-
**2025-11-25 stays fully supported** as the opt-in stateful lane
90-
(`--no-default-features --features protocol-2025-11-25`) — the handshake, sessions,
91-
GET SSE, and core tasks all work there. Per-requirement compliance status:
92-
[`docs/plans/2026-07-28-spec-compliance.md`](docs/plans/2026-07-28-spec-compliance.md).
93-
94-
## Turul MCP vs Turul RPC
95-
96-
This project ships two layered surfaces. Most users only need the MCP layer.
97-
98-
- **`turul-mcp`** (this framework) — the Model Context Protocol implementation. Tools, resources, prompts, sampling, elicitation, tasks, sessions, Streamable HTTP/SSE transport, the macro suite, storage backends.
99-
- **[`turul-rpc`](https://github.com/aussierobots/turul-rpc)** — generic, transport-agnostic typed JSON-RPC 2.0 framework: dispatch, domain/protocol error separation, optional session context, async handler trait, batch processing, notifications. No MCP knowledge. Useful as a foundation for any non-MCP request/response service that wants the same handler-returns-domain-error contract Turul uses internally.
100-
101-
Turul MCP is built on top of Turul RPC. The `turul-mcp-json-rpc-server` crate, which historically carried the JSON-RPC implementation, is a thin re-export shim over `turul-rpc` since v0.3.39. **Existing 0.3.x users do not need to change anything** — `turul_mcp_json_rpc_server::*` imports continue to compile and behave identically. New code (and new tools/agents reading this README) should depend on `turul-rpc` directly. See [ADR-025](docs/adr/025-extract-turul-rpc.md).
102-
10321
## 🚀 Quick Start
10422

10523
### 1. Function Macros (Simplest - Recommended)
@@ -249,6 +167,66 @@ The framework automatically:
249167
- Maps them to function parameters
250168
- Registers appropriate resource handlers
251169

170+
## The MCP 2026-07-28 specification
171+
172+
The default build targets MCP 2026-07-28, the current specification — a **stateless
173+
rewrite** of the protocol with several core methods removed. New to MCP? You can skim
174+
this section and come back later. Migrating from 2025-11-25? Read it first.
175+
176+
### What's new (and implemented here)
177+
178+
- **Stateless core** — `server/discover` advertises versions/capabilities/identity;
179+
every request carries `protocolVersion` + `clientInfo` + `clientCapabilities` in
180+
`_meta` under `io.modelcontextprotocol/*`. Any server instance serves any request.
181+
- **MRTR (Multi-Round-Trip Requests, SEP-2322)** — a tool/resource/prompt returns an
182+
`InputRequiredResult` to ask for elicitation/sampling/roots input; the client
183+
answers and retries the original call. This replaces all server-initiated requests.
184+
→ `examples/mrtr-elicitation-server`
185+
- **`subscriptions/listen`** — the ack-first, filtered, long-lived POST SSE stream that
186+
replaces 2025's GET-SSE resumability and the `resources/subscribe` RPC.
187+
- **Tasks extension** (`io.modelcontextprotocol/tasks`, SEP-2663) — durable poll handles
188+
via `turul-mcp-ext-tasks` (opt-in `ext-tasks` feature): `.with_ext_tasks()` +
189+
`.ext_task_tool()` server-side, `call_tool_or_task` / `task_*` client-side.
190+
→ `examples/ext-tasks-server`
191+
- **MCP Apps extension** (`io.modelcontextprotocol/ui`, SEP-1865) — MCP-side bindings
192+
(`turul-mcp-ext-apps`).
193+
- **SEP-2243 request-metadata headers** — `Mcp-Method` / `Mcp-Name` / `Mcp-Param-*` let
194+
infrastructure route on method/tool/arguments without parsing JSON bodies.
195+
→ `examples/header-bound-tools-server`
196+
- **Origin validation / DNS-rebinding protection** — on by default (ADR-031).
197+
→ `examples/origin-policy-server`
198+
- **JSON Schema 2020-12**, **caching headers** (`ttlMs` / `cacheScope` on list/read
199+
results), and OAuth 2.1 Resource Server hardening (RFC 9207/9728).
200+
201+
### What changed from 2025-11-25
202+
203+
- **No handshake** — `initialize` → `notifications/initialized` → `Mcp-Session-Id` is
204+
gone; capabilities ride per-request `_meta` instead.
205+
- **Error codes** — resource-not-found moved from `-32002` to `-32602`; new
206+
`-32020` (header mismatch), `-32021` (missing required client capability),
207+
`-32022` (unsupported protocol version).
208+
- **Per-request logging** — log level is set per-request via `io.modelcontextprotocol/logLevel`
209+
in `_meta`; servers must not emit `notifications/message` for requests that didn't opt in.
210+
- **Deprecations (SEP-2577)** — Roots, Sampling, and Logging are deprecated (earliest
211+
removal 2027-07-28). Still implemented; on 2026 the server-initiated forms ride MRTR.
212+
213+
### What's removed from the core (2026 default → these 404 / 405)
214+
215+
| Removed | SEP | Replacement on 2026 |
216+
|---|---|---|
217+
| `initialize` / `notifications/initialized` | 2575 | `server/discover` + per-request `_meta` |
218+
| Protocol sessions / `Mcp-Session-Id` | 2567 | stateless; server-minted handles as tool args |
219+
| `ping` | 2575 | — (use `server/discover` for liveness) |
220+
| `logging/setLevel` | 2575 | per-request `_meta.logLevel` |
221+
| `notifications/roots/list_changed` | 2575 | — |
222+
| GET SSE endpoint / `resources/subscribe` | 2575 | `subscriptions/listen` |
223+
| Core `tasks/*` (incl. `tasks/list`, blocking `tasks/result`) | 2663 | the Tasks **extension** (`tasks/get` polling + `tasks/update`) |
224+
225+
**2025-11-25 stays fully supported** as the opt-in stateful lane
226+
(`--no-default-features --features protocol-2025-11-25`) — the handshake, sessions,
227+
GET SSE, and core tasks all work there. Per-requirement compliance status:
228+
[`docs/plans/2026-07-28-spec-compliance.md`](docs/plans/2026-07-28-spec-compliance.md).
229+
252230
## 🚀 Running & Testing the Framework
253231

254232
### Quick Start - Verify Everything Works
@@ -400,6 +378,15 @@ cargo run -p minimal-server &
400378
./quick_check.sh 8641
401379
```
402380

381+
## Turul MCP vs Turul RPC
382+
383+
This project ships two layered surfaces. Most users only need the MCP layer.
384+
385+
- **`turul-mcp`** (this framework) — the Model Context Protocol implementation. Tools, resources, prompts, sampling, elicitation, tasks, sessions, Streamable HTTP/SSE transport, the macro suite, storage backends.
386+
- **[`turul-rpc`](https://github.com/aussierobots/turul-rpc)** — generic, transport-agnostic typed JSON-RPC 2.0 framework: dispatch, domain/protocol error separation, optional session context, async handler trait, batch processing, notifications. No MCP knowledge. Useful as a foundation for any non-MCP request/response service that wants the same handler-returns-domain-error contract Turul uses internally.
387+
388+
Turul MCP is built on top of Turul RPC. The `turul-mcp-json-rpc-server` crate, which historically carried the JSON-RPC implementation, is a thin re-export shim over `turul-rpc` since v0.3.39. **Existing 0.3.x users do not need to change anything** — `turul_mcp_json_rpc_server::*` imports continue to compile and behave identically. New code (and new tools/agents reading this README) should depend on `turul-rpc` directly. See [ADR-025](docs/adr/025-extract-turul-rpc.md).
389+
403390
## 🏛️ Architecture Overview
404391

405392
### Middleware System
@@ -1180,7 +1167,7 @@ This project is licensed under the MIT OR Apache-2.0 License - see the LICENSE f
11801167
## 📋 Development Status & Current Limitations
11811168

11821169
### 🎯 Current Framework State
1183-
- **MCP 2026-07-28 adoption (this branch)**: default build targets the 2026-07-28 stateless core; 2025-11-25 remains fully supported as the opt-in stateful line
1170+
- **MCP 2026-07-28**: default build targets the current stateless spec; 2025-11-25 remains fully supported as the opt-in stateful line
11841171
- **Examples Validated**: 54 active examples compile under their lane's CI gates (2026-07-28 default lane plus the pinned 2025-11-25 regression set — see EXAMPLES.md)
11851172
- **SSE Streaming Verified**: Real-time notifications and session-aware logging working correctly
11861173
- **Pre-1.0 (0.4.x)**: production-shaped with comprehensive test coverage; public APIs may still change before 1.0.0

0 commit comments

Comments
 (0)