neva 0.5.0

MCP SDK for Rust
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172

//! Stateless HTTP transport (MCP 2026-07-28) end-to-end checks.
//!
//! Exercises the stateless POST-only path: `server/discover` without a
//! session, a stateless `tools/call` carrying the required
//! `MCP-Protocol-Version` header, rejection of a header-less POST, and the
//! absence of the GET (SSE) / DELETE routes.
#![cfg(all(
    not(feature = "legacy-spec"),
    feature = "http-server-volga",
    feature = "http-client"
))]

use neva::App;

#[tokio::test(flavor = "multi_thread")]
async fn stateless_discover_and_call() {
    let port = pick_free_port();
    let addr = format!("127.0.0.1:{port}");
    let mut app =
        App::new().with_options(|opt| opt.with_http(|http| http.bind(&addr).with_endpoint("/mcp")));
    app.map_tool("ping", || async move { "pong".to_string() });
    let handle = tokio::spawn(async move { app.run().await });
    tokio::time::sleep(std::time::Duration::from_millis(300)).await;

    let client = reqwest::Client::builder()
        .no_proxy()
        .build()
        .expect("test client");
    let url = format!("http://{addr}/mcp");

    // (a) discover, no session header.
    let discover = serde_json::json!({
        "jsonrpc": "2.0", "id": 1, "method": "server/discover",
        "params": { "_meta": meta() }
    });
    let resp = routed(client.post(&url), &discover)
        .json(&discover)
        .send()
        .await
        .expect("discover failed");
    assert!(resp.status().is_success());
    // (b) no session id on the wire.
    assert!(
        resp.headers().get("Mcp-Session-Id").is_none(),
        "stateless server must not emit Mcp-Session-Id"
    );
    let body: serde_json::Value = resp.json().await.unwrap();
    assert_eq!(
        body["result"]["supportedVersions"],
        serde_json::json!(["2026-07-28"])
    );
    // `serverInfo` left the discovery result; the server identifies itself in
    // every result's `_meta` instead.
    assert!(body["result"].get("serverInfo").is_none(), "got: {body}");
    assert_eq!(
        body["result"]["_meta"]["io.modelcontextprotocol/serverInfo"]["name"],
        "neva"
    );
    // Every result carries the mandatory `resultType` discriminator, including
    // the discovery result.
    assert_eq!(body["result"]["resultType"], serde_json::json!("complete"));

    // (c) stateless tool call with the protocol-version header, no session.
    let call = serde_json::json!({
        "jsonrpc": "2.0", "id": 2, "method": "tools/call",
        "params": { "name": "ping", "arguments": {}, "_meta": meta() }
    });
    let resp = routed(client.post(&url), &call)
        .json(&call)
        .send()
        .await
        .expect("call failed");
    assert!(resp.status().is_success());
    let body: serde_json::Value = resp.json().await.unwrap();
    assert_eq!(
        body.pointer("/result/content/0/text")
            .and_then(|v| v.as_str()),
        Some("pong")
    );
    assert_eq!(body["result"]["resultType"], serde_json::json!("complete"));

    // (d) missing protocol-version header -> `HeaderMismatch`, HTTP 400.
    let resp = client
        .post(&url)
        .json(&call)
        .send()
        .await
        .expect("send failed");
    assert_eq!(resp.status(), reqwest::StatusCode::BAD_REQUEST);
    let body: serde_json::Value = resp.json().await.unwrap();
    assert_eq!(body["error"]["code"], -32020, "got: {body}");

    // (d2) a version we do not speak -> `UnsupportedProtocolVersion`, and the
    //      client is told what is on offer.
    let resp = client
        .post(&url)
        .header("MCP-Protocol-Version", "1999-01-01")
        .json(&call)
        .send()
        .await
        .expect("send failed");
    assert_eq!(resp.status(), reqwest::StatusCode::BAD_REQUEST);
    let body: serde_json::Value = resp.json().await.unwrap();
    assert_eq!(body["error"]["code"], -32022, "got: {body}");
    assert_eq!(body["error"]["data"]["requested"], "1999-01-01");
    assert_eq!(
        body["error"]["data"]["supported"],
        serde_json::json!(["2026-07-28"])
    );

    // (d3) `ping` is gone in MCP 2026-07-28.
    let ping = serde_json::json!({
        "jsonrpc": "2.0", "id": 5, "method": "ping",
        "params": { "_meta": meta() }
    });
    let body: serde_json::Value = routed(client.post(&url), &ping)
        .json(&ping)
        .send()
        .await
        .expect("send failed")
        .json()
        .await
        .unwrap();
    assert_eq!(body["error"]["code"], -32601, "ping must be gone: {body}");

    // (e) GET and DELETE are not routed under the flag.
    let get = client.get(&url).send().await.expect("get failed");
    assert!(
        get.status() == reqwest::StatusCode::NOT_FOUND
            || get.status() == reqwest::StatusCode::METHOD_NOT_ALLOWED,
        "GET should not be routed, got {}",
        get.status()
    );

    handle.abort();
}

/// The `_meta` MCP 2026-07-28 requires on every request: the protocol version,
/// and the capabilities this request is made under -- empty being the valid
/// declaration of "no optional capabilities".
fn meta() -> serde_json::Value {
    serde_json::json!({
        "io.modelcontextprotocol/protocolVersion": "2026-07-28",
        "io.modelcontextprotocol/clientCapabilities": {}
    })
}

fn pick_free_port() -> u16 {
    let listener = std::net::TcpListener::bind("127.0.0.1:0").unwrap();
    let port = listener.local_addr().unwrap().port();
    drop(listener);
    port
}

/// Attaches the routing headers MCP 2026-07-28 requires on every request, the
/// way a conforming client derives them: from the body it is about to send.
fn routed(req: reqwest::RequestBuilder, body: &serde_json::Value) -> reqwest::RequestBuilder {
    let method = body["method"].as_str().unwrap_or_default();
    let req = req
        .header("MCP-Protocol-Version", "2026-07-28")
        .header("Mcp-Method", method);
    let name = match method {
        "tools/call" | "prompts/get" => body.pointer("/params/name"),
        "resources/read" => body.pointer("/params/uri"),
        "tasks/get" | "tasks/update" | "tasks/cancel" => body.pointer("/params/taskId"),
        _ => None,
    };
    match name.and_then(|v| v.as_str()) {
        Some(name) => req.header("Mcp-Name", name),
        None => req,
    }
}