From 2f9c4cb56827a03ef6217346ae267eadb10fcfbf Mon Sep 17 00:00:00 2001 From: bsodfather Date: Thu, 12 Nov 2026 10:48:24 +0000 Subject: [PATCH] refactor(mcp): serialize negotiation results through rmcp SDK --- .../crank-community-mcp/src/app/dispatch.rs | 9 +- .../src/app/dispatch_observer.rs | 21 ++ .../src/protocol/lifecycle_sdk.rs | 88 ++++++ .../crank-community-mcp/src/protocol/mod.rs | 19 +- .../src/rmcp_envelopes_runtime_tests.rs | 21 +- ...mcp_lifecycle_negotiation_runtime_tests.rs | 270 ++++++++++++++++++ .../src/rmcp_progress_cancel_http_support.rs | 2 +- .../src/rmcp_progress_cancel_runtime_tests.rs | 2 +- docs/development/rmcp-migration-plan.md | 2 + 9 files changed, 388 insertions(+), 46 deletions(-) create mode 100644 crates/crank-community-mcp/src/protocol/lifecycle_sdk.rs create mode 100644 crates/crank-community-mcp/src/rmcp_lifecycle_negotiation_runtime_tests.rs diff --git a/crates/crank-community-mcp/src/app/dispatch.rs b/crates/crank-community-mcp/src/app/dispatch.rs index 5d64ca1..9c77c89 100644 --- a/crates/crank-community-mcp/src/app/dispatch.rs +++ b/crates/crank-community-mcp/src/app/dispatch.rs @@ -835,14 +835,7 @@ pub(super) async fn handle_initialize( StatusCode::OK, jsonrpc_result( request_id(message), - json!( { - "protocolVersion": protocol_version, - "capabilities": crate::protocol::advertised_server_capabilities(protocol_version), - "serverInfo": { - "name": SERVER_NAME, - "version": SERVER_VERSION - } - }), + crate::protocol::initialize_result(protocol_version, SERVER_NAME, SERVER_VERSION), ), response_mode, Some(&session_id), diff --git a/crates/crank-community-mcp/src/app/dispatch_observer.rs b/crates/crank-community-mcp/src/app/dispatch_observer.rs index d8cb90c..fc4465e 100644 --- a/crates/crank-community-mcp/src/app/dispatch_observer.rs +++ b/crates/crank-community-mcp/src/app/dispatch_observer.rs @@ -73,9 +73,17 @@ pub(crate) struct CounterSet { sdk_signal_notification: AtomicUsize, sdk_jsonrpc_response: AtomicUsize, sdk_jsonrpc_error: AtomicUsize, + sdk_initialize_result: AtomicUsize, + sdk_discover_result: AtomicUsize, } impl CounterSet { + pub(crate) fn sdk_initialize_result(&self) -> usize { + self.sdk_initialize_result.load(Ordering::SeqCst) + } + pub(crate) fn sdk_discover_result(&self) -> usize { + self.sdk_discover_result.load(Ordering::SeqCst) + } pub(crate) fn sdk_jsonrpc_response(&self) -> usize { self.sdk_jsonrpc_response.load(Ordering::SeqCst) } @@ -377,6 +385,19 @@ pub(crate) fn sdk_jsonrpc_error_serialized() { #[path = "../rmcp_envelopes_runtime_tests.rs"] mod rmcp_envelopes_runtime_tests; +/// Mark only after successfully serializing a real rmcp InitializeResult. +pub(crate) fn sdk_initialize_result_serialized() { + increment(|counters| &counters.sdk_initialize_result); +} + +/// Mark only after successfully serializing a real rmcp DiscoverResult. +pub(crate) fn sdk_discover_result_serialized() { + increment(|counters| &counters.sdk_discover_result); +} + +#[path = "../rmcp_lifecycle_negotiation_runtime_tests.rs"] +mod rmcp_lifecycle_negotiation_runtime_tests; + fn increment(counter: impl Fn(&CounterSet) -> &AtomicUsize) { let _ = OBSERVER.try_with(|counters| { counter(counters).fetch_add(1, Ordering::SeqCst); diff --git a/crates/crank-community-mcp/src/protocol/lifecycle_sdk.rs b/crates/crank-community-mcp/src/protocol/lifecycle_sdk.rs new file mode 100644 index 0000000..2a58418 --- /dev/null +++ b/crates/crank-community-mcp/src/protocol/lifecycle_sdk.rs @@ -0,0 +1,88 @@ +//! Typed negotiation results; admission and session lifecycle remain in the HTTP adapter. + +use rmcp::model::{ + CacheScope, DiscoverResult, Implementation, InitializeResult, ProtocolVersion, + ServerCapabilities, +}; +use serde_json::Value; + +use super::advertised_server_capabilities; +use crate::jsonrpc::SUPPORTED_PROTOCOL_VERSIONS; + +fn protocol_version(revision: &str) -> ProtocolVersion { + serde_json::from_value(Value::String(revision.to_owned())) + .expect("served protocol revisions are strings") +} + +fn capabilities(advertised: &Value) -> ServerCapabilities { + serde_json::from_value(advertised.clone()) + .expect("registry capability fragments match SDK capability shapes") +} + +fn restore_registry_extensions(result: &mut Value, advertised: Value) { + let capabilities = result["capabilities"] + .as_object_mut() + .expect("SDK server capabilities serialize as an object"); + // SDK ServerCapabilities has no flattened map for extra registry capability names. + for (name, settings) in advertised + .as_object() + .expect("registry capabilities are an object") + { + capabilities + .entry(name.clone()) + .or_insert_with(|| settings.clone()); + } +} + +pub(crate) fn initialize_result(revision: &str, name: &str, version: &str) -> Value { + let advertised = advertised_server_capabilities(revision); + let result = InitializeResult::new(capabilities(&advertised)) + .with_protocol_version(protocol_version(revision)) + .with_server_info(Implementation::new(name, version)); + let mut result = serde_json::to_value(result) + .expect("SDK initialize result with registry capabilities is serializable"); + #[cfg(test)] + crate::app::dispatch_observer::sdk_initialize_result_serialized(); + restore_registry_extensions(&mut result, advertised); + result +} + +pub(crate) fn discover_result(revision: &str, name: &str, version: &str) -> Value { + let advertised = advertised_server_capabilities(revision); + let result = DiscoverResult::new( + SUPPORTED_PROTOCOL_VERSIONS + .iter() + .map(|revision| protocol_version(revision)) + .collect(), + capabilities(&advertised), + ) + .with_server_info(Implementation::new(name, version)) + .with_ttl_ms(0) + .with_cache_scope(CacheScope::Private); + let mut result = serde_json::to_value(result) + .expect("SDK discovery result with registry capabilities is serializable"); + #[cfg(test)] + crate::app::dispatch_observer::sdk_discover_result_serialized(); + restore_registry_extensions(&mut result, advertised); + result +} + +#[cfg(test)] +mod tests { + use super::*; + use serde_json::json; + + #[test] + fn lifecycle_sdk_retains_extra_registry_capabilities_without_replacing_sdk_fields() { + let advertised = + json!({"tools":{"listChanged":false}, "inert_test_capability":{"enabled":true}}); + let mut result = serde_json::to_value(InitializeResult::new(capabilities(&advertised))) + .expect("typed result serializes"); + assert_eq!( + result["capabilities"], + json!({"tools":{"listChanged":false}}) + ); + restore_registry_extensions(&mut result, advertised.clone()); + assert_eq!(result["capabilities"], advertised); + } +} diff --git a/crates/crank-community-mcp/src/protocol/mod.rs b/crates/crank-community-mcp/src/protocol/mod.rs index c8e322c..0b6c469 100644 --- a/crates/crank-community-mcp/src/protocol/mod.rs +++ b/crates/crank-community-mcp/src/protocol/mod.rs @@ -26,6 +26,7 @@ use crate::transport::{json_response, protocol_version_from_headers, singleton_h mod command; mod completion; +mod lifecycle_sdk; mod logging; mod prompts; mod registry; @@ -40,6 +41,7 @@ pub(crate) use completion::{ CompletionArgument, CompletionCommand, CompletionOutcome, CompletionReference, handle_completion_command, }; +pub(crate) use lifecycle_sdk::{discover_result, initialize_result}; pub(crate) use logging::{ CarriedScope, EVENT_FAILED, EVENT_LEVEL_APPLIED, EVENT_REJECTED, EVENT_SERVED, INVALID_LEVEL, LogLevel, LogLevelStore, LoggingOutcome, SetLevelCommand, carry_scope, handle_logging_command, @@ -844,20 +846,3 @@ pub(crate) fn resolve_request_identity( } } } - -/// The pinned `DiscoverResult` for `server/discover` of the revision the caller serves. -pub(crate) fn discover_result(revision: &str, server_name: &str, server_version: &str) -> Value { - json!({ - "resultType": "complete", - "supportedVersions": SUPPORTED_PROTOCOL_VERSIONS, - "capabilities": advertised_server_capabilities(revision), - "_meta": { - crate::jsonrpc::META_SERVER_INFO_KEY: { - "name": server_name, - "version": server_version, - } - }, - "ttlMs": 0, - "cacheScope": "private" - }) -} diff --git a/crates/crank-community-mcp/src/rmcp_envelopes_runtime_tests.rs b/crates/crank-community-mcp/src/rmcp_envelopes_runtime_tests.rs index 17c7df8..c3f7d36 100644 --- a/crates/crank-community-mcp/src/rmcp_envelopes_runtime_tests.rs +++ b/crates/crank-community-mcp/src/rmcp_envelopes_runtime_tests.rs @@ -1,28 +1,11 @@ //! #107 envelope migration: independent real HTTP wire and SDK participation controls. use super::{CounterSet, observe, support::*}; -use axum::{body::Body, response::Response}; -use futures_util::{StreamExt, stream}; + use serde_json::{Value, json}; use std::{sync::Arc, time::Duration}; // Reuse the existing real build_app, published catalog, auth and loopback execution fixture. -#[path = "rmcp_progress_cancel_http_support.rs"] -#[allow(dead_code)] -mod fixtures; -use fixtures::Endpoint; - -fn observe_body(response: Response, counters: Arc) -> Response { - let (parts, body) = response.into_parts(); - let body = stream::unfold( - (body.into_data_stream(), counters), - |(mut body, counters)| async move { - observe(counters.clone(), body.next()) - .await - .map(|chunk| (chunk, (body, counters))) - }, - ); - Response::from_parts(parts, Body::from_stream(body)) -} +use super::rmcp_progress_cancel_runtime_tests::fixtures::Endpoint; fn counts(c: &CounterSet) -> [usize; 2] { [c.sdk_jsonrpc_response(), c.sdk_jsonrpc_error()] diff --git a/crates/crank-community-mcp/src/rmcp_lifecycle_negotiation_runtime_tests.rs b/crates/crank-community-mcp/src/rmcp_lifecycle_negotiation_runtime_tests.rs new file mode 100644 index 0000000..403a3c2 --- /dev/null +++ b/crates/crank-community-mcp/src/rmcp_lifecycle_negotiation_runtime_tests.rs @@ -0,0 +1,270 @@ +//! #107 negotiation results: existing HTTP wire GREEN, independent SDK execution oracle RED. +use super::{CounterSet, observe, support::*}; + +use serde_json::{Value, json}; +use std::{sync::Arc, time::Duration}; + +use super::rmcp_progress_cancel_runtime_tests::fixtures::Endpoint; + +fn sdk_counts(c: &CounterSet) -> [usize; 2] { + [c.sdk_initialize_result(), c.sdk_discover_result()] +} + +fn capabilities() -> Value { + // Pin the reviewed advertisement, not a call to the builder under test or SDK defaults. + json!({"completions":{},"logging":{},"prompts":{"listChanged":true}, + "resources":{"listChanged":true,"subscribe":false},"tools":{"listChanged":true}}) +} + +fn expected_result(revision: &str) -> Value { + let server = json!({"name":"crank-mcp-server","version":env!("CARGO_PKG_VERSION")}); + if revision == LEGACY_REVISION { + json!({"protocolVersion":LEGACY_REVISION,"capabilities":capabilities(),"serverInfo":server}) + } else { + json!({"resultType":"complete","supportedVersions":["2026-07-28","2025-11-25"], + "capabilities":capabilities(),"_meta":{"io.modelcontextprotocol/serverInfo":server}, + "ttlMs":0,"cacheScope":"private"}) + } +} + +async fn wire(response: reqwest::Response, revision: &str, id: &Value, sse: bool) -> Value { + assert_eq!(response.status(), 200); + assert_eq!(response.headers()["MCP-Protocol-Version"], revision); + assert_eq!(response.headers()["x-request-id"], "negotiation-request"); + assert_eq!( + response.headers()["x-trace-id"], + "11111111111111111111111111111111" + ); + let content_type = response.headers()["content-type"].to_str().unwrap(); + assert!(content_type.starts_with(if sse { + "text/event-stream" + } else { + "application/json" + })); + let raw = tokio::time::timeout(Duration::from_secs(6), response.text()) + .await + .unwrap() + .unwrap(); + let body: Value = if sse { + let frames: Vec = raw + .lines() + .filter_map(|line| line.strip_prefix("data:")) + .map(|data| serde_json::from_str(data.trim()).unwrap()) + .collect(); + assert_eq!( + frames.len(), + 1, + "one terminal, no unsolicited notifications: {raw}" + ); + frames.into_iter().next().unwrap() + } else { + serde_json::from_str(&raw).unwrap() + }; + assert_eq!( + body, + json!({"jsonrpc":"2.0","id":id,"result":expected_result(revision)}), + "exact result/envelope fields and omissions (including title/icons/instructions/defaults)" + ); + body +} + +async fn control(revision: &str) -> Vec<[usize; 2]> { + crank_test_support::postgres_schema_url_for_task("negotiation_owner", "t_99aa603c").await; + let h = Endpoint::started().await; + let mut deltas = vec![]; + // Accept order selects JSON or a single terminal SSE frame on the real transport. + for accept in ["application/json", "text/event-stream, application/json"] { + let id = json!("negotiation/Ю"); + let payload = if revision == LEGACY_REVISION { + let mut initialize = legacy_initialize(1); + initialize["id"] = id.clone(); + initialize + } else { + json!({"jsonrpc":"2.0","id":id,"method":"server/discover","params":{"_meta":modern_meta()}}) + }; + let before = sdk_counts(&h.counters); + let admission_before = h.counters.snapshot(); + let response = h + .request(revision, None, &h.key, accept, payload) + .header("x-request-id", "negotiation-request") + .header( + "traceparent", + "00-11111111111111111111111111111111-2222222222222222-01", + ) + .send() + .await + .unwrap(); + let session = response + .headers() + .get("MCP-Session-Id") + .map(|v| v.to_str().unwrap().to_owned()); + if revision == LEGACY_REVISION { + assert!( + !session + .as_deref() + .expect("initialize creates a session") + .is_empty() + ); + } else { + assert_eq!( + session, None, + "stateless discovery never creates a session carrier" + ); + } + wire( + response, + revision, + &id, + accept.starts_with("text/event-stream"), + ) + .await; + assert_deltas( + "negotiation admission positive control", + admission_before, + h.counters.snapshot(), + if revision == LEGACY_REVISION { + super::Snapshot::new(1, 0, 1, 0) + } else { + super::Snapshot::new(1, 1, 0, 0) + }, + ); + let after = sdk_counts(&h.counters); + deltas.push([after[0] - before[0], after[1] - before[1]]); + if let Some(session) = session { + let response = h + .request( + revision, + Some(&session), + &h.key, + accept, + initialized_notification(), + ) + .send() + .await + .unwrap(); + assert_eq!(response.status(), 202); + assert!(response.bytes().await.unwrap().is_empty()); + // Prove the minted session can authorize the next protected request. + let response = h + .request( + revision, + Some(&session), + &h.key, + "application/json", + json!({"jsonrpc":"2.0","id":2,"method":"ping"}), + ) + .send() + .await + .unwrap(); + assert_eq!(response.status(), 200); + assert_eq!( + json_body(response).await, + json!({"jsonrpc":"2.0","id":2,"result":{"protocolVersion":LEGACY_REVISION}}) + ); + } + } + eprintln!("existing GREEN lifecycle negotiation wire {revision}; SDK deltas={deltas:?}"); + deltas +} + +#[tokio::test] +async fn rmcp_lifecycle_negotiation_wire_legacy() { + control(LEGACY_REVISION).await; +} +#[tokio::test] +async fn rmcp_lifecycle_negotiation_wire_modern() { + control(MODERN_REVISION).await; +} +#[tokio::test] +async fn rmcp_lifecycle_negotiation_sdk_legacy() { + assert_eq!( + control(LEGACY_REVISION).await, + vec![[1, 0]; 2], + "real HTTP initialize must serialize SDK InitializeResult (not admission/envelope only)" + ); +} +#[tokio::test] +async fn rmcp_lifecycle_negotiation_sdk_modern() { + assert_eq!( + control(MODERN_REVISION).await, + vec![[0, 1]; 2], + "real HTTP discovery must serialize SDK DiscoverResult (not admission/envelope only)" + ); +} + +#[tokio::test] +async fn rmcp_lifecycle_negotiation_observer_positive_control() { + let c = Arc::new(CounterSet::default()); + observe(c.clone(), async { + super::admission_enter(); + super::sdk_initialize_result_serialized(); + assert_eq!( + sdk_counts(&c), + [1, 0], + "initialize and discovery are separate markers" + ); + super::sdk_discover_result_serialized(); + }) + .await; + assert_eq!(sdk_counts(&c), [1, 1]); + assert_eq!(c.snapshot(), super::Snapshot::new(1, 0, 0, 0)); + super::sdk_initialize_result_serialized(); + super::sdk_discover_result_serialized(); + assert_eq!(sdk_counts(&c), [1, 1], "out-of-scope markers are no-ops"); +} + +#[tokio::test] +async fn rmcp_lifecycle_negotiation_wire_session_operations() { + crank_test_support::postgres_schema_url_for_task("negotiation_sessions_owner", "t_99aa603c") + .await; + let h = Harness::started().await; + // Existing counted-session fixture supplies independent get/create/initialized oracles. + run_valid_legacy_initialize(&h, 10, "legacy create exactly once").await; + let session = h.initialize_legacy_session().await; + run_valid_legacy_call( + &h, + &session, + 11, + "negotiation@example.test", + "initialized session works", + ) + .await; + for accept in ["application/json", "text/event-stream, application/json"] { + let before = h.session_ops(); + let admission_before = h.snapshot(); + let response = h + .post( + &[ + ("MCP-Protocol-Version", MODERN_REVISION), + ("Mcp-Method", "server/discover"), + ("Accept", accept), + ("x-request-id", "negotiation-request"), + ( + "traceparent", + "00-11111111111111111111111111111111-2222222222222222-01", + ), + ], + &json!({"jsonrpc":"2.0","id":"discovery","method":"server/discover", + "params":{"_meta":modern_meta()}}), + ) + .await; + assert!(response.headers().get("MCP-Session-Id").is_none()); + wire(response, MODERN_REVISION, &json!("discovery"), false).await; + assert_deltas( + "modern discovery", + admission_before, + h.snapshot(), + super::Snapshot::new(1, 1, 0, 0), + ); + assert_session_ops( + "stateless discovery", + before, + h.session_ops(), + SessionOps { + get: 0, + create: 0, + mark_initialized: 0, + }, + ); + } +} diff --git a/crates/crank-community-mcp/src/rmcp_progress_cancel_http_support.rs b/crates/crank-community-mcp/src/rmcp_progress_cancel_http_support.rs index 57fbd2a..4acb591 100644 --- a/crates/crank-community-mcp/src/rmcp_progress_cancel_http_support.rs +++ b/crates/crank-community-mcp/src/rmcp_progress_cancel_http_support.rs @@ -6,7 +6,7 @@ use crank_runtime::{ use std::sync::atomic::{AtomicUsize, Ordering}; use tokio::sync::Semaphore; -pub(super) struct Endpoint { +pub(in crate::app::dispatch_observer) struct Endpoint { pub registry: crank_registry::PostgresRegistry, pub counters: Arc, pub key: String, diff --git a/crates/crank-community-mcp/src/rmcp_progress_cancel_runtime_tests.rs b/crates/crank-community-mcp/src/rmcp_progress_cancel_runtime_tests.rs index 7208445..625ff83 100644 --- a/crates/crank-community-mcp/src/rmcp_progress_cancel_runtime_tests.rs +++ b/crates/crank-community-mcp/src/rmcp_progress_cancel_runtime_tests.rs @@ -5,7 +5,7 @@ use futures_util::{StreamExt, stream}; use serde_json::{Value, json}; use std::{sync::Arc, time::Duration}; #[path = "rmcp_progress_cancel_http_support.rs"] -mod fixtures; +pub(super) mod fixtures; use fixtures::Endpoint; fn observe_body(response: Response, counters: Arc) -> Response { diff --git a/docs/development/rmcp-migration-plan.md b/docs/development/rmcp-migration-plan.md index edfe756..a35110b 100644 --- a/docs/development/rmcp-migration-plan.md +++ b/docs/development/rmcp-migration-plan.md @@ -47,6 +47,8 @@ Catalog-change signals/subscriptions-срез #107 на базе rc.24/rmcp3.9.0 Envelopes-срез #107 на базе rc.25/rmcp3.9.0 заменяет handwritten `jsonrpc_result`/`jsonrpc_error` в `jsonrpc.rs` сериализацией настоящих `JsonRpcResponse` и `JsonRpcError`/`ErrorData`. Уже подключённые consumers — общий `build_app` HTTP JSON и lifecycle SSE terminal обеих revisions; новые dispatch/transport пути не добавляются. Локальная projection+restore сразу возвращает исходные JSON id (включая null, u64 и точную floating-point форму) и i64 error code, которые SDK-типы не представляют полностью; произвольный result и omission error.data сохраняются. Прежний guard correlation не меняется: JSON protocol errors содержат correlation data, lifecycle SSE terminal errors по-прежнему её опускают. Runtime wire controls и отдельный SDK oracle проверяют success/protocol error, а affected regressions — admission, revoked credentials, tool isError и cancellation. Входная валидация, safe response id, auth, статусы/headers, очереди/сессии и transport остаются прежними; это не завершение #107, feature qualification или production deployment. +Negotiation-results-срез #107 на базе rc.26/rmcp3.9.0 заменяет handwritten ответы legacy `initialize` и modern `server/discover` на настоящие `InitializeResult`/`DiscoverResult` в `protocol/lifecycle_sdk.rs`. Уже подключённый потребитель — штатный `build_app` HTTP JSON/SSE. Версии и их порядок заданы прежним allowlist, capabilities поступают только из registry; server identity, omissions и discovery ttlMs=0/cacheScope=private сохранены. SDK `ServerCapabilities` не представляет дополнительные top-level имена registry: после typed serialization восстанавливаются только отсутствующие ключи, без замены SDK-known полей. HTTP ATDD отдельно проверяет прежний wire и SDK execution, legacy initialize→initialized→защищённый вызов и отсутствие session operations у modern discovery; affected regression сохраняет frozen advertisement, unsupported revision rejection, auth/revocation/Agent scope и legacy transport lifecycle. Входной InitializeParams parser с прежней tolerance, generic dispatch/ping, session storage/TTL/reconnect, admission/auth и transport не переносились. Существующий SSE error.data omission не исправляется; полный #107, feature qualification и production deployment не завершены. + Проверяемый результат: - Через SDK проходят действующие Tools, Resources, Prompts, completion, уведомления и подписки в применимых revisions, а также progress/cancel и существующая logging policy.