Merge pull request 'Route existing MCP Tools requests through typed rmcp runtime seam (partial #107)' (#119) from feat/rmcp107-tools-runtime into main
CI / Rust Checks (push) Successful in 24m5s
CI / Rust Feature Validation (push) Skipped
CI / UI Checks (push) Successful in 7s
CI / Frontend E2E (push) Skipped
CI / Community Image Smoke (push) Skipped
CI / Required Checks (push) Successful in 1s
CI / Deploy (push) Skipped
Community Release / release (push) Failing after 45m55s

This commit was merged in pull request #119.
This commit is contained in:
bsodfather committed 2026-11-08 15:30:17 +00:00
commit 74a98d9362
9 files changed
+450 -7

No files matched your search

+3
View File
@@ -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" }
+1
View File
@@ -34,6 +34,7 @@ pub(crate) mod lifecycle;
mod metrics;
mod request;
mod response;
mod rmcp_dispatch;
#[cfg(test)]
mod rmcp_http;
#[cfg(test)]
@@ -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,
@@ -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;
@@ -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},
@@ -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},
};
@@ -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<usize>,
},
Call {
params: CallToolRequestParams,
confirmation_token: Option<String>,
},
}
pub(super) async fn handle_tools_command(
state: &Arc<AppState>,
context: ServiceContext<'_>,
command: ToolsCommand,
lifecycle: Option<ToolCallLifecycle>,
) -> 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
}
@@ -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<CounterSet>,
calls: Arc<AtomicUsize>,
}
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(&registry, &operation).await;
let key = create_api_key(&registry).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<String> {
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);
}
+3 -1
View File
@@ -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.