From 7f18bce67921031b585a56ae2bf99f18ddbb5faa Mon Sep 17 00:00:00 2001 From: bsodfather Date: Sun, 8 Nov 2026 15:00:22 +0000 Subject: [PATCH] feat(mcp): route Tools requests through typed rmcp runtime seam --- crates/crank-community-mcp/Cargo.toml | 3 + crates/crank-community-mcp/src/app.rs | 1 + .../crank-community-mcp/src/app/dispatch.rs | 3 +- .../src/app/dispatch_observer.rs | 15 + .../src/app/legacy_dispatch.rs | 2 +- .../crank-community-mcp/src/app/lifecycle.rs | 6 +- .../src/app/rmcp_dispatch.rs | 67 ++++ .../src/rmcp_runtime_tests.rs | 356 ++++++++++++++++++ docs/development/rmcp-migration-plan.md | 4 +- 9 files changed, 450 insertions(+), 7 deletions(-) create mode 100644 crates/crank-community-mcp/src/app/rmcp_dispatch.rs create mode 100644 crates/crank-community-mcp/src/rmcp_runtime_tests.rs diff --git a/crates/crank-community-mcp/Cargo.toml b/crates/crank-community-mcp/Cargo.toml index a871f14..49b1735 100644 --- a/crates/crank-community-mcp/Cargo.toml +++ b/crates/crank-community-mcp/Cargo.toml @@ -32,6 +32,9 @@ tokio = { workspace = true, features = ["sync"] } tracing.workspace = true uuid.workspace = true +# Typed Tools dispatch uses the SDK; its HTTP transport remains test-only. +rmcp = { version = "=3.7.0" } + [dev-dependencies] rmcp = { version = "=3.7.0", features = ["transport-streamable-http-server"] } crank-mapping = { path = "../crank-mapping" } diff --git a/crates/crank-community-mcp/src/app.rs b/crates/crank-community-mcp/src/app.rs index f710333..c06eaf5 100644 --- a/crates/crank-community-mcp/src/app.rs +++ b/crates/crank-community-mcp/src/app.rs @@ -34,6 +34,7 @@ pub(crate) mod lifecycle; mod metrics; mod request; mod response; +mod rmcp_dispatch; #[cfg(test)] mod rmcp_http; #[cfg(test)] diff --git a/crates/crank-community-mcp/src/app/dispatch.rs b/crates/crank-community-mcp/src/app/dispatch.rs index 36b26ef..f1556d3 100644 --- a/crates/crank-community-mcp/src/app/dispatch.rs +++ b/crates/crank-community-mcp/src/app/dispatch.rs @@ -7,6 +7,7 @@ use super::request::{InitializeParams, ToolCallParams}; use super::response::take_confirmation_token; +use super::rmcp_dispatch::handle_tools_command; use crate::{ auth::VerifiedMachineCredential, jsonrpc::{ @@ -19,7 +20,7 @@ use crate::{ ResourceReadCommand, ResourcesCommand, ResourcesListCommand, ResourcesOutcome, ServiceContext, ToolCallCommand, ToolsCommand, ToolsListCommand, ToolsOutcome, declared_mcp_method, discover_result, handle_completion_command, handle_prompts_command, - handle_resources_command, handle_tools_command, validate_modern_request_name, + handle_resources_command, validate_modern_request_name, }, session::SessionState, tool_error::execution_locale, diff --git a/crates/crank-community-mcp/src/app/dispatch_observer.rs b/crates/crank-community-mcp/src/app/dispatch_observer.rs index 92c5972..3149d9d 100644 --- a/crates/crank-community-mcp/src/app/dispatch_observer.rs +++ b/crates/crank-community-mcp/src/app/dispatch_observer.rs @@ -51,9 +51,15 @@ pub(crate) struct CounterSet { era_modern: AtomicUsize, era_legacy: AtomicUsize, tools_service: AtomicUsize, + sdk_tools_dispatch: AtomicUsize, } impl CounterSet { + /// SDK typed Tools dispatch entries, separate from the existing era/service snapshot. + pub(crate) fn sdk_tools_dispatch(&self) -> usize { + self.sdk_tools_dispatch.load(Ordering::SeqCst) + } + /// Read the counters of one observed request as one comparable snapshot. pub(crate) fn snapshot(&self) -> Snapshot { Snapshot { @@ -134,6 +140,11 @@ pub(crate) fn tools_service_enter() { increment(|counters| &counters.tools_service); } +/// `SDK_TOOLS_DISPATCH`: entered the real SDK typed Tools dispatch, not just admission. +pub(crate) fn sdk_tools_dispatch_enter() { + increment(|counters| &counters.sdk_tools_dispatch); +} + fn increment(counter: impl Fn(&CounterSet) -> &AtomicUsize) { let _ = OBSERVER.try_with(|counters| { counter(counters).fetch_add(1, Ordering::SeqCst); @@ -153,3 +164,7 @@ pub(crate) mod support; #[cfg(test)] #[path = "../dispatch_observer_harness.rs"] mod tests; + +#[cfg(test)] +#[path = "../rmcp_runtime_tests.rs"] +mod rmcp_runtime_tests; diff --git a/crates/crank-community-mcp/src/app/legacy_dispatch.rs b/crates/crank-community-mcp/src/app/legacy_dispatch.rs index 4a06527..e343a54 100644 --- a/crates/crank-community-mcp/src/app/legacy_dispatch.rs +++ b/crates/crank-community-mcp/src/app/legacy_dispatch.rs @@ -24,6 +24,7 @@ use super::response::{ resource_templates_list_result, resources_list_result, take_confirmation_token, tools_list_result, }; +use super::rmcp_dispatch::handle_tools_command; use super::{AgentRoutePath, AppState}; use crate::{ auth::VerifiedMachineCredential, @@ -38,7 +39,6 @@ use crate::{ ResourcesCommand, ResourcesListCommand, ResourcesOutcome, ServiceContext, SetLevelCommand, ToolCallCommand, ToolsCommand, ToolsListCommand, ToolsOutcome, handle_completion_command, handle_logging_command, handle_prompts_command, handle_resources_command, - handle_tools_command, }, tool_error::execution_locale, transport::{ResponseMode, session_id_from_headers, transport_response}, diff --git a/crates/crank-community-mcp/src/app/lifecycle.rs b/crates/crank-community-mcp/src/app/lifecycle.rs index 4f0658e..dce6a49 100644 --- a/crates/crank-community-mcp/src/app/lifecycle.rs +++ b/crates/crank-community-mcp/src/app/lifecycle.rs @@ -37,16 +37,14 @@ use futures_util::stream; use serde_json::{Number, Value, json}; use tokio::sync::{mpsc, watch}; +use super::rmcp_dispatch::handle_tools_command; use super::{ AppState, response::{ToolCommandPayload, tool_command_payload, tool_command_response}, }; use crate::{ jsonrpc::request_id, - protocol::{ - ContinuationSupport, ServiceContext, ToolCallCommand, ToolsCommand, ToolsOutcome, - handle_tools_command, - }, + protocol::{ContinuationSupport, ServiceContext, ToolCallCommand, ToolsCommand, ToolsOutcome}, transport::{ResponseMode, sse_response}, }; diff --git a/crates/crank-community-mcp/src/app/rmcp_dispatch.rs b/crates/crank-community-mcp/src/app/rmcp_dispatch.rs new file mode 100644 index 0000000..29fb75e --- /dev/null +++ b/crates/crank-community-mcp/src/app/rmcp_dispatch.rs @@ -0,0 +1,67 @@ +//! Runtime SDK Tools dispatch; admission, lifecycle and response projection stay with the caller. + +use std::sync::Arc; + +use rmcp::model::{CallToolRequestParams, PaginatedRequestParams}; +use serde_json::Value; + +use super::{AppState, lifecycle::ToolCallLifecycle}; +use crate::protocol::{ + ServiceContext, ToolCallCommand, ToolCallOutcome, ToolsCommand, ToolsListCommand, ToolsOutcome, +}; + +// Crank extensions are not SDK fields and must survive the typed request boundary unchanged. +enum SdkToolsCommand { + List { + params: PaginatedRequestParams, + limit: Option, + }, + Call { + params: CallToolRequestParams, + confirmation_token: Option, + }, +} + +pub(super) async fn handle_tools_command( + state: &Arc, + context: ServiceContext<'_>, + command: ToolsCommand, + lifecycle: Option, +) -> ToolsOutcome { + let request = match command { + ToolsCommand::List(list) => SdkToolsCommand::List { + params: PaginatedRequestParams::default().with_cursor(list.cursor), + limit: list.limit, + }, + ToolsCommand::Call(call) => { + let Value::Object(arguments) = call.arguments else { + return ToolsOutcome::Call(ToolCallOutcome::InvalidParams( + "tool arguments must be an object".to_owned(), + )); + }; + SdkToolsCommand::Call { + params: CallToolRequestParams::new(call.tool_name).with_arguments(arguments), + confirmation_token: call.confirmation_token, + } + } + }; + + #[cfg(test)] + super::dispatch_observer::sdk_tools_dispatch_enter(); + + let command = match request { + SdkToolsCommand::List { params, limit } => ToolsCommand::List(ToolsListCommand { + cursor: params.cursor, + limit, + }), + SdkToolsCommand::Call { + params, + confirmation_token, + } => ToolsCommand::Call(ToolCallCommand { + tool_name: params.name.into_owned(), + arguments: Value::Object(params.arguments.unwrap_or_default()), + confirmation_token, + }), + }; + crate::protocol::handle_tools_command(state, context, command, lifecycle).await +} diff --git a/crates/crank-community-mcp/src/rmcp_runtime_tests.rs b/crates/crank-community-mcp/src/rmcp_runtime_tests.rs new file mode 100644 index 0000000..e79a32f --- /dev/null +++ b/crates/crank-community-mcp/src/rmcp_runtime_tests.rs @@ -0,0 +1,356 @@ +//! #107: real build_app endpoint controls plus a separate SDK structural seam oracle. +//! No SDK transport router is used. The structural oracle alone does not prove wire parity. + +use std::{ + sync::{ + Arc, + atomic::{AtomicUsize, Ordering}, + }, + time::Duration, +}; + +use axum::{Router, routing::post}; +use crank_core::{ + AgentOperationBinding, AgentStatus, AgentVersion, PlatformApiKeyId, ToolSelectionPolicy, +}; +use crank_registry::{ + CreateAgentDraftVersionRequest, PostgresRegistry, PublishAgentRequest, PublishRequest, +}; +use crank_runtime::{ + InMemoryCoordinationStateStore, RequestRateLimitConfig, RequestRateLimiter, SecretCrypto, +}; +use serde_json::{Value, json}; + +use super::{CounterSet, observe, sdk_tools_dispatch_enter, support::*}; + +struct Server(tokio::task::JoinHandle<()>, String); + +impl Drop for Server { + fn drop(&mut self) { + self.0.abort(); + } +} + +async fn serve(app: Router) -> Server { + let listener = tokio::net::TcpListener::bind("127.0.0.1:0").await.unwrap(); + let address = listener.local_addr().unwrap(); + Server( + tokio::spawn(async move { + axum::serve(listener, app).await.unwrap(); + }), + format!("http://{address}"), + ) +} + +struct Endpoint { + server: Server, + _upstream: Server, + registry: PostgresRegistry, + key: String, + counters: Arc, + calls: Arc, +} + +impl Endpoint { + async fn started() -> Self { + // First caller owns the process-wide fixture and its atexit cleanup, including RED panics. + let _ = + crank_test_support::postgres_schema_url_for_task("rmcp_runtime_owner", "t_aaaea124") + .await; + let registry = test_registry().await; + let calls = Arc::new(AtomicUsize::new(0)); + let upstream = serve( + Router::new() + .route("/crm/leads", post(create_lead)) + .with_state(calls.clone()), + ) + .await; + let operation = test_operation(&upstream.1); + registry + .create_operation(&workspace_id(), &operation, Some("alice")) + .await + .unwrap(); + registry + .publish_operation(PublishRequest { + workspace_id: &workspace_id(), + operation_id: &operation.id, + version: 1, + published_at: &test_time(), + published_by: Some("alice"), + }) + .await + .unwrap(); + publish_agent(®istry, &operation).await; + let key = create_api_key(®istry).await; + let counters = Arc::new(CounterSet::default()); + let app = crate::build_app( + registry.clone(), + Duration::ZERO, + Some("https://crank.example.com".into()), + SecretCrypto::new("test-master-key-00000000000000000000000000000000").unwrap(), + crank_runtime::community_with_outbound_policy( + crank_runtime::OutboundHttpPolicy::allowing_hosts(["127.0.0.1"]), + ) + .build(), + RequestRateLimiter::new(RequestRateLimitConfig::new(10_000, 10_000).unwrap()), + Arc::new(InMemoryCoordinationStateStore::default()), + Arc::new(crate::session::InMemorySessionStore::default()), + Arc::new(crate::auth::CommunityMachineCredentialVerifier), + ); + let server = serve(observe_requests(app, counters.clone(), None)).await; + Self { + server, + _upstream: upstream, + registry, + key, + counters, + calls, + } + } + + async fn post(&self, revision: &str, session: Option<&str>, body: &Value) -> reqwest::Response { + let mut request = reqwest::Client::new() + .post(format!( + "{}/v1/{WORKSPACE_SLUG}/{AGENT_SLUG}", + self.server.1 + )) + .bearer_auth(&self.key) + // Also guards the legacy JSON-only contract; no SSE parsing fallback here. + .header("Accept", "application/json") + .header("MCP-Protocol-Version", revision); + if let Some(session) = session { + request = request.header("MCP-Session-Id", session); + } + if revision == MODERN_REVISION { + request = request.header("Mcp-Method", body["method"].as_str().unwrap()); + if let Some(name) = body["params"]["name"].as_str() { + request = request.header("Mcp-Name", name); + } + } + request.json(body).send().await.unwrap() + } + + async fn session(&self, revision: &str) -> Option { + if revision == MODERN_REVISION { + return None; + } + let response = self.post(revision, None, &legacy_initialize(1)).await; + assert_eq!(response.status(), 200); + let session = response.headers()["MCP-Session-Id"] + .to_str() + .unwrap() + .to_owned(); + let body = json_body(response).await; + assert_eq!(body["result"]["protocolVersion"], revision); + assert!(body["result"]["capabilities"]["tools"].is_object()); + let response = self + .post(revision, Some(&session), &initialized_notification()) + .await; + assert_eq!(response.status(), 202); + Some(session) + } + + async fn list(&self, revision: &str, session: Option<&str>, expected_name: &str) -> usize { + let before = self.counters.sdk_tools_dispatch(); + let mut body = json!({"jsonrpc":"2.0", "id":10, "method":"tools/list", "params":{}}); + if revision == MODERN_REVISION { + body["params"]["_meta"] = modern_meta(); + } + let calls = self.calls.load(Ordering::SeqCst); + let response = self.post(revision, session, &body).await; + assert_eq!(response.status(), 200); + assert!( + response.headers()["content-type"] + .to_str() + .unwrap() + .starts_with("application/json") + ); + let body = json_body(response).await; + assert_eq!(body["id"], 10); + assert_eq!(body["result"]["tools"].as_array().unwrap().len(), 1); + assert_eq!(body["result"]["tools"][0]["name"], expected_name); + assert!(body["error"].is_null(), "{body}"); + assert_eq!( + self.calls.load(Ordering::SeqCst), + calls, + "listing must not execute upstream" + ); + self.counters.sdk_tools_dispatch() - before + } + + async fn call(&self, revision: &str, session: Option<&str>, name: &str, email: &str) -> usize { + let before = self.counters.sdk_tools_dispatch(); + let arrivals = self.calls.load(Ordering::SeqCst); + let mut body = if revision == MODERN_REVISION { + modern_tool_call(11, email) + } else { + legacy_tool_call(11, email) + }; + body["params"]["name"] = json!(name); + let response = self.post(revision, session, &body).await; + assert_eq!(response.status(), 200); + assert!( + response.headers()["content-type"] + .to_str() + .unwrap() + .starts_with("application/json") + ); + let body = json_body(response).await; + assert_eq!(body["id"], 11); + assert!(body["error"].is_null(), "{body}"); + assert_ne!(body["result"]["isError"], true, "{body}"); + assert_scoped_output(revision, &body, email); + if revision == MODERN_REVISION { + assert_eq!(body["result"]["resultType"], "complete"); + } + assert_eq!(self.calls.load(Ordering::SeqCst) - arrivals, 1); + self.counters.sdk_tools_dispatch() - before + } + + async fn publish_renamed_tool(&self) { + let now = time::OffsetDateTime::now_utc(); + let version = AgentVersion { + agent_id: agent_id(), + version: 2, + status: AgentStatus::Draft, + instructions: json!({}), + tool_selection_policy: ToolSelectionPolicy::default(), + created_at: now, + }; + let bindings = [AgentOperationBinding { + operation_id: crank_core::OperationId::new("op_create_lead"), + operation_version: 1, + tool_name: "new_publication_tool".into(), + tool_title: "New Tool".into(), + tool_description_override: None, + enabled: true, + }]; + self.registry + .create_agent_draft_version(CreateAgentDraftVersionRequest { + workspace_id: &workspace_id(), + agent_id: &agent_id(), + version: &version, + bindings: &bindings, + updated_at: &now, + }) + .await + .unwrap(); + self.registry + .publish_agent(PublishAgentRequest { + workspace_id: &workspace_id(), + agent_id: &agent_id(), + version: 2, + published_at: &now, + published_by: Some("alice"), + expected_state: None, + }) + .await + .unwrap(); + } +} + +async fn endpoint_control(revision: &str) -> [usize; 2] { + let h = Endpoint::started().await; + let session = h.session(revision).await; + let session = session.as_deref(); + let list_dispatches = h.list(revision, session, TOOL_NAME).await; + let call_dispatches = h + .call( + revision, + session, + TOOL_NAME, + &format!("{revision}@example.test"), + ) + .await; + // A fresh publication must be visible without reinitialize or a new endpoint. + h.publish_renamed_tool().await; + h.list(revision, session, "new_publication_tool").await; + h.call( + revision, + session, + "new_publication_tool", + "new-publication@example.test", + ) + .await; + h.registry + .revoke_platform_api_key( + &workspace_id(), + &PlatformApiKeyId::new("pk_dispatch_observer"), + &time::OffsetDateTime::now_utc(), + ) + .await + .unwrap(); + let before_sdk = h.counters.sdk_tools_dispatch(); + let arrivals = h.calls.load(Ordering::SeqCst); + let mut denied = if revision == MODERN_REVISION { + modern_tool_call(12, "denied@example.test") + } else { + legacy_tool_call(12, "denied@example.test") + }; + denied["params"]["name"] = json!("new_publication_tool"); + assert_eq!(h.post(revision, session, &denied).await.status(), 401); + assert_eq!( + h.calls.load(Ordering::SeqCst), + arrivals, + "revoked credential must not execute upstream" + ); + assert_eq!( + h.counters.sdk_tools_dispatch(), + before_sdk, + "revocation must reject before SDK dispatch" + ); + eprintln!( + "existing GREEN {revision}: JSON list/call, scoped output, upstream=2, publication refresh, revoked=401/no outbound; SDK list/call deltas={:?}", + [list_dispatches, call_dispatches] + ); + [list_dispatches, call_dispatches] +} + +#[tokio::test] +async fn rmcp_runtime_existing_wire_modern() { + endpoint_control(MODERN_REVISION).await; +} + +#[tokio::test] +async fn rmcp_runtime_existing_wire_legacy() { + endpoint_control(LEGACY_REVISION).await; +} + +#[tokio::test] +async fn rmcp_runtime_sdk_dispatch_modern() { + let counts = endpoint_control(MODERN_REVISION).await; + assert_eq!( + counts, + [1, 1], + "real endpoint tools/list and tools/call must each enter SDK typed dispatch once (structural seam oracle)" + ); +} + +#[tokio::test] +async fn rmcp_runtime_sdk_dispatch_legacy() { + let counts = endpoint_control(LEGACY_REVISION).await; + assert_eq!( + counts, + [1, 1], + "real endpoint tools/list and tools/call must each enter SDK typed dispatch once (structural seam oracle)" + ); +} + +#[tokio::test] +async fn rmcp_runtime_observer_is_request_scoped() { + let counters = Arc::new(CounterSet::default()); + sdk_tools_dispatch_enter(); + assert_eq!(counters.sdk_tools_dispatch(), 0); + observe(counters.clone(), async { + sdk_tools_dispatch_enter(); + }) + .await; + assert_eq!(counters.sdk_tools_dispatch(), 1); + let other = Arc::new(CounterSet::default()); + observe(other.clone(), async { + sdk_tools_dispatch_enter(); + }) + .await; + assert_eq!(other.sdk_tools_dispatch(), 1); + assert_eq!(counters.sdk_tools_dispatch(), 1); +} diff --git a/docs/development/rmcp-migration-plan.md b/docs/development/rmcp-migration-plan.md index d72ed7c..4874155 100644 --- a/docs/development/rmcp-migration-plan.md +++ b/docs/development/rmcp-migration-plan.md @@ -1,6 +1,6 @@ # Переход Crank на официальный MCP SDK rmcp -Статус: планирование одобрено владельцем 27.10.2026; 05.11.2026 отдельно разрешён только изолированный опыт этапа 1 (#106). Этапы 2/3 (#107/#108), новая реализация 4.7 и production-переключение этим разрешением не запускаются. Исполняемый кандидат и конкретные несовместимости: [rmcp106-tools-adapter.md](rmcp106-tools-adapter.md); это не завершённая миграция. Владелец очереди — hermes_tl; реализация — hermes_dev; независимая проверка — hermes_qa; Git/CI/релизы — hermes_devops. ARC подключается к конкретному техническому затруднению, не как обязательный новый этап. Business reconciliation 4.6 отменена решением владельца и [issue #34](https://git.itexp.me/bsodfather/crank/issues/34); она не prerequisite SDK. Input/unknown safety и остальные защитные ограничения сохраняются. +Статус: планирование одобрено владельцем 27.10.2026; 05.11.2026 разрешён изолированный опыт этапа 1 (#106), поставленный в v0.4.0-rc.15. [Решением владельца 08.11.2026](https://git.itexp.me/bsodfather/crank/issues/107#issuecomment-2463) разрешён первый Tools-срез этапа 2 (#107) в действующем endpoint без смены transport. #108, новая реализация 4.7 и production-переключение этим разрешением не запускаются. Исполняемый кандидат и конкретные несовместимости: [rmcp106-tools-adapter.md](rmcp106-tools-adapter.md); это не завершённая миграция. Владелец очереди — hermes_tl; реализация — hermes_dev; независимая проверка — hermes_qa; Git/CI/релизы — hermes_devops. ARC подключается к конкретному техническому затруднению, не как обязательный новый этап. Business reconciliation 4.6 отменена решением владельца и [issue #34](https://git.itexp.me/bsodfather/crank/issues/34); она не prerequisite SDK. Input/unknown safety и остальные защитные ограничения сохраняются. ## Результат @@ -31,6 +31,8 @@ Подключить SDK к действующему пути и перенести стандартные envelopes, dispatch, lifecycle и transport. Порядок переноса устанавливается по результату первого опыта, без параллельных writers одних MCP-файлов. +Первый срез #107: `build_app` направляет `tools/list` обеих revisions и `tools/call` через `app/rmcp_dispatch.rs`. Параметры rmcp=3.7.0 (`PaginatedRequestParams`/`CallToolRequestParams`) определяют команду существующего shared Tools service; расширения Crank `limit`/confirmation сохраняются отдельно. Потребитель — штатный MCP HTTP клиент, не изолированный router #106. Текущие admission, свежая identity, lifecycle, era-specific ответы и PostgreSQL sessions остаются у прежнего transport; SDK HTTP transport не подключён. Это только Tools request dispatch/model seam: SDK response envelopes, остальные handlers, transport и lifecycle ещё не перенесены. Полный #107 не завершён; проверки #106 не являются доказательством завершения миграции. + Проверяемый результат: - Через SDK проходят действующие Tools, Resources, Prompts, completion, уведомления и подписки в применимых revisions, а также progress/cancel и существующая logging policy. -- 2.54.0