use std::{collections::BTreeMap, error::Error, fmt, future::Future, pin::Pin};
use rmcp::{
ErrorData, RoleServer,
handler::server::{
router::tool::{IntoToolRoute, ToolRouter},
tool::ToolCallContext,
},
model::{
CacheScope, CallToolRequestParams, CallToolResponse, ListResourcesResult, ListToolsResult,
MetaObject, PaginatedRequestParams, ReadResourceRequestParams, ReadResourceResponse,
ReadResourceResult, ServerCapabilities, Tool,
},
service::RequestContext,
};
use crate::{
MetadataError, ResourceUi, StaticUiResource, ToolUi, UiResource, UiResourceUri, UiUriError,
declare_ui_extension,
};
pub type HtmlFuture<'a> = Pin<Box<dyn Future<Output = Result<String, ErrorData>> + Send + 'a>>;
type HtmlHandler<S> =
dyn for<'a> Fn(&'a S, RequestContext<RoleServer>) -> HtmlFuture<'a> + Send + Sync;
enum HtmlSource<S> {
Static(String),
Callback(Box<HtmlHandler<S>>),
}
pub struct UiResourceRoute<S> {
resource: UiResource,
source: HtmlSource<S>,
meta: MetaObject,
}
impl<S> UiResourceRoute<S> {
fn from_static<R: StaticUiResource>() -> Result<Self, RegistrationError> {
Ok(Self::static_html(R::resource()?, R::html())
.with_meta(R::meta()?)?
.with_ui(&R::ui())?)
}
pub fn new(
resource: UiResource,
callback: impl for<'a> Fn(&'a S, RequestContext<RoleServer>) -> HtmlFuture<'a>
+ Send
+ Sync
+ 'static,
) -> Self {
Self {
resource,
source: HtmlSource::Callback(Box::new(callback)),
meta: MetaObject::default(),
}
}
pub fn static_html(resource: UiResource, html: impl Into<String>) -> Self {
Self {
resource,
source: HtmlSource::Static(html.into()),
meta: MetaObject::default(),
}
}
pub fn with_meta(mut self, mut meta: MetaObject) -> Result<Self, MetadataError> {
ResourceUi::default().merge_into(&mut meta)?;
self.meta = meta;
Ok(self)
}
pub fn with_ui(mut self, ui: &ResourceUi) -> Result<Self, MetadataError> {
ui.merge_into(&mut self.meta)?;
Ok(self)
}
}
#[derive(Debug)]
#[non_exhaustive]
pub enum RegistrationError {
DuplicateTool {
name: String,
},
ToolNameMismatch {
registered_name: String,
declared_name: String,
},
DuplicateResource {
uri: String,
},
ConflictingResource {
uri: String,
},
UnknownTool {
name: String,
},
MissingResourceUri {
tool: String,
},
UnregisteredResource {
uri: String,
},
InvalidToolAssociation {
tool: String,
path: String,
},
Uri(UiUriError),
Metadata(MetadataError),
}
impl fmt::Display for RegistrationError {
fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
match self {
Self::DuplicateTool { name } => {
write!(formatter, "tool {name:?} is already registered")
}
Self::ToolNameMismatch {
registered_name,
declared_name,
} => write!(
formatter,
"registered tool name {registered_name:?} differs from declaration {declared_name:?}"
),
Self::DuplicateResource { uri } => {
write!(formatter, "resource {uri:?} is already registered")
}
Self::ConflictingResource { uri } => {
write!(
formatter,
"resource {uri:?} has a conflicting static declaration"
)
}
Self::UnknownTool { name } => write!(formatter, "tool {name:?} is not registered"),
Self::MissingResourceUri { tool } => {
write!(
formatter,
"association for tool {tool:?} requires a resource URI"
)
}
Self::UnregisteredResource { uri } => {
write!(formatter, "associated resource {uri:?} is not registered")
}
Self::InvalidToolAssociation { tool, path } => {
write!(formatter, "tool {tool:?} requires a string at {path}")
}
Self::Uri(error) => write!(formatter, "invalid registered UI URI: {error}"),
Self::Metadata(error) => write!(formatter, "invalid registration metadata: {error}"),
}
}
}
impl Error for RegistrationError {
fn source(&self) -> Option<&(dyn Error + 'static)> {
match self {
Self::Uri(error) => Some(error),
Self::Metadata(error) => Some(error),
_ => None,
}
}
}
impl From<UiUriError> for RegistrationError {
fn from(error: UiUriError) -> Self {
Self::Uri(error)
}
}
impl From<MetadataError> for RegistrationError {
fn from(error: MetadataError) -> Self {
Self::Metadata(error)
}
}
pub struct AppRouter<S> {
tools: ToolRouter<S>,
resources: BTreeMap<String, UiResourceRoute<S>>,
}
impl<S> Default for AppRouter<S> {
fn default() -> Self {
Self {
tools: ToolRouter::default(),
resources: BTreeMap::new(),
}
}
}
impl<S: Send + Sync + 'static> AppRouter<S> {
pub fn new() -> Self {
Self::default()
}
pub fn from_tool_router(tools: ToolRouter<S>) -> Self {
Self {
tools,
resources: BTreeMap::new(),
}
}
pub fn register_resource(
&mut self,
route: UiResourceRoute<S>,
) -> Result<(), RegistrationError> {
let uri = route.resource.uri().to_string();
if self.resources.contains_key(&uri) {
return Err(RegistrationError::DuplicateResource { uri });
}
self.resources.insert(uri, route);
Ok(())
}
pub fn register_static<R: StaticUiResource>(&mut self) -> Result<(), RegistrationError> {
let route = UiResourceRoute::from_static::<R>()?;
self.register_resource(route)
}
pub fn ensure_static<R: StaticUiResource>(
&mut self,
) -> Result<UiResourceUri, RegistrationError> {
let route = UiResourceRoute::from_static::<R>()?;
let uri = route.resource.uri().clone();
if let Some(existing) = self.resources.get(uri.as_str()) {
let same_html = match (&existing.source, &route.source) {
(HtmlSource::Static(left), HtmlSource::Static(right)) => left == right,
_ => false,
};
if !same_html
|| existing.resource.descriptor() != route.resource.descriptor()
|| existing.meta != route.meta
{
return Err(RegistrationError::ConflictingResource {
uri: uri.to_string(),
});
}
} else {
self.resources.insert(uri.to_string(), route);
}
Ok(uri)
}
pub fn register_tool<R, A>(&mut self, route: R) -> Result<(), RegistrationError>
where
R: IntoToolRoute<S, A>,
{
let route = route.into_tool_route();
if self.tools.map.contains_key(&route.attr.name) {
return Err(RegistrationError::DuplicateTool {
name: route.attr.name.to_string(),
});
}
self.validate_tool(&route.attr)?;
self.tools.add_route(route);
Ok(())
}
pub fn associate_tool(&mut self, name: &str, ui: &ToolUi) -> Result<(), RegistrationError> {
if !self.tools.map.contains_key(name) {
return Err(RegistrationError::UnknownTool { name: name.into() });
}
let uri = ui
.resource_uri
.as_ref()
.ok_or_else(|| RegistrationError::MissingResourceUri { tool: name.into() })?;
if !self.contains_resource(uri.as_str()) {
return Err(RegistrationError::UnregisteredResource {
uri: uri.to_string(),
});
}
let route = self
.tools
.map
.get_mut(name)
.ok_or_else(|| RegistrationError::UnknownTool { name: name.into() })?;
ui.apply_to(&mut route.attr)?;
Ok(())
}
pub fn associate_static_tool<R: StaticUiResource>(
&mut self,
name: &str,
) -> Result<(), RegistrationError> {
self.associate_tool(name, &ToolUi::new(R::resource()?.uri().clone()))
}
pub fn merge(&mut self, mut other: Self) -> Result<(), RegistrationError> {
self.validate_tool_names()?;
other.validate_tool_names()?;
for name in other.tools.map.keys() {
if self.tools.map.contains_key(name) {
return Err(RegistrationError::DuplicateTool {
name: name.to_string(),
});
}
}
for name in self.tools.map.keys() {
if other.tools.enable_route(name) {
return Err(RegistrationError::DuplicateTool {
name: name.to_string(),
});
}
}
for uri in other.resources.keys() {
if self.resources.contains_key(uri) {
return Err(RegistrationError::DuplicateResource { uri: uri.clone() });
}
}
self.tools.merge(other.tools);
self.resources.extend(other.resources);
Ok(())
}
pub fn validate(&self) -> Result<(), RegistrationError> {
self.validate_tool_names()?;
for route in self.tools.map.values() {
self.validate_tool(&route.attr)?;
}
Ok(())
}
pub fn get_tool(&self, name: &str) -> Option<Tool> {
self.tools.get(name).cloned()
}
pub fn list_tools(
&self,
request: Option<PaginatedRequestParams>,
) -> Result<ListToolsResult, ErrorData> {
reject_cursor(request)?;
Ok(ListToolsResult::with_all_items(self.tools.list_all())
.with_ttl_ms(0)
.with_cache_scope(CacheScope::Private))
}
pub fn list_resources(
&self,
request: Option<PaginatedRequestParams>,
) -> Result<ListResourcesResult, ErrorData> {
reject_cursor(request)?;
Ok(ListResourcesResult::with_all_items(
self.resources
.values()
.map(|route| route.resource.descriptor())
.collect(),
)
.with_ttl_ms(0)
.with_cache_scope(CacheScope::Private))
}
pub async fn call_tool(
&self,
state: &S,
request: CallToolRequestParams,
context: RequestContext<RoleServer>,
) -> Result<CallToolResponse, ErrorData> {
self.tools
.call(ToolCallContext::new(state, request, context))
.await
}
pub async fn read_resource(
&self,
state: &S,
request: ReadResourceRequestParams,
context: RequestContext<RoleServer>,
) -> Result<ReadResourceResponse, ErrorData> {
let route = self
.resources
.get(&request.uri)
.ok_or_else(|| ErrorData::resource_not_found("UI resource is not registered", None))?;
let html = match &route.source {
HtmlSource::Static(html) => html.clone(),
HtmlSource::Callback(callback) => callback(state, context).await?,
};
let content = route
.resource
.html_contents(html)
.with_meta(route.meta.clone());
Ok(ReadResourceResult::new(vec![content])
.with_ttl_ms(0)
.with_cache_scope(CacheScope::Private)
.into())
}
pub fn contains_resource(&self, uri: &str) -> bool {
self.resources.contains_key(uri)
}
pub fn declare_capabilities(&self, capabilities: &mut ServerCapabilities) {
if !self.tools.map.is_empty() {
capabilities.tools.get_or_insert_default();
}
if !self.resources.is_empty() {
capabilities.resources.get_or_insert_default();
declare_ui_extension(capabilities);
}
}
fn validate_tool_names(&self) -> Result<(), RegistrationError> {
for (name, route) in &self.tools.map {
if name != &route.attr.name {
return Err(RegistrationError::ToolNameMismatch {
registered_name: name.to_string(),
declared_name: route.attr.name.to_string(),
});
}
}
Ok(())
}
fn validate_tool(&self, tool: &Tool) -> Result<(), RegistrationError> {
let Some(meta) = &tool.meta else {
return Ok(());
};
let mut candidate = meta.clone();
ToolUi::default().merge_into(&mut candidate)?;
let nested = meta
.0
.get("ui")
.and_then(|value| value.as_object())
.and_then(|ui| ui.get("resourceUri"));
let legacy = meta.0.get("ui/resourceUri");
let mut association = None;
for (value, path) in [
(nested, "_meta.ui.resourceUri"),
(legacy, "_meta.ui/resourceUri"),
] {
if let Some(value) = value {
let raw =
value
.as_str()
.ok_or_else(|| RegistrationError::InvalidToolAssociation {
tool: tool.name.to_string(),
path: path.into(),
})?;
let uri = UiResourceUri::new(raw)?;
ToolUi::new(uri.clone()).merge_into(&mut candidate)?;
association = Some(uri);
}
}
if let Some(uri) = association
&& !self.contains_resource(uri.as_str())
{
return Err(RegistrationError::UnregisteredResource {
uri: uri.to_string(),
});
}
Ok(())
}
}
fn reject_cursor(request: Option<PaginatedRequestParams>) -> Result<(), ErrorData> {
if request.is_some_and(|request| request.cursor.is_some()) {
return Err(ErrorData::invalid_params(
"AppRouter lists all entries and does not accept a pagination cursor",
None,
));
}
Ok(())
}