Skip to main content

Crate mcp_apps_server

Crate mcp_apps_server 

Source
Expand description

Typed MCP Apps registration and resources for rmcp servers.

Start with StaticUiResource for embedded HTML. With the server feature, AppRouter groups rmcp tools and resources and checks their associations; AppServer provides the common server handling. With macros, the optional derive declares fixed views and app_router associates each UI tool with its view in one place. Manual declarations and routing remain directly usable. Consumers choose their runtime and transport and own business logic/access checks.

§Simple application (server and macros)

The consumer enables rmcp’s server and macros features. The HTML below is this project’s bundled example; use a path relative to your own declaring file. rmcp generates both schemas from the Rust models; no input schema JSON is needed.

use mcp_apps_server::{AppServer, StaticUiResource, app_router};
use rmcp::{tool, schemars::JsonSchema, ServerHandler,
    handler::server::wrapper::{Json, Parameters}};
use serde::{Deserialize, Serialize};

#[derive(StaticUiResource)]
#[ui_resource(id = "inventory/dashboard", name = "dashboard",
              html_file = "../examples/dashboard.html")]
struct Dashboard;

#[derive(Deserialize, JsonSchema)]
#[schemars(crate = "rmcp::schemars")]
#[serde(deny_unknown_fields)]
struct Input { sku: String }
#[derive(Serialize, JsonSchema)]
#[schemars(crate = "rmcp::schemars")]
struct Snapshot { sku: String, available: u32 }
struct Inventory;
#[app_router]
impl Inventory {
    #[tool(description = "Read inventory")]
    #[ui(resource = Dashboard)]
    fn snapshot(&self, Parameters(input): Parameters<Input>) -> Json<Snapshot> {
        Json(Snapshot { sku: input.sku, available: 12 })
    }
}
let server = AppServer::new(Inventory, Inventory::app_router()?)?;
assert!(server.get_info().capabilities.resources.is_some());
assert!(server.get_tool("snapshot").is_some());

Construction performs no request or transport activity. Call rmcp’s ServiceExt::serve with the transport you choose when ready to serve. The repository’s examples/server.rs supplies the complete stdio lifecycle.

§Custom integration

Keep your own ServerHandler when you need authorization middleware, prompts, unrelated resources or custom lifecycle behavior. Prepare the same router, call its validation before serving, then delegate with the original request and context. Its lists are unpaginated; your handler owns filtering, pagination and selecting other resource owners. Callback errors are not fallback signals. See AppRouter for executable tool and dynamic-resource examples and AppServer for the supported ready-server methods. The repository’s examples/custom_server.rs implements the complete manual equivalent.

Implement your own handler over the same prepared router

This handler replaces the ready adapter. With macros, obtain the same router from Inventory::app_router(); with manual declarations, register resources and associate rmcp tools explicitly. Validate the router and store it with your application state. These methods let you insert access checks and retain other MCP methods. A fully manual resource declaration is demonstrated on StaticUiResource.

use mcp_apps_server::{AppRouter, UiResource, UiResourceRoute, UiResourceUri};
use rmcp::{ErrorData, RoleServer, ServerHandler, model::*, service::RequestContext};

struct ExistingServer<S> { state: S, apps: AppRouter<S> }
impl<S: Send + Sync + 'static> ServerHandler for ExistingServer<S> {
    fn get_info(&self) -> ServerConfig {
        let mut info = ServerConfig::default();
        self.apps.declare_capabilities(&mut info.capabilities);
        info
    }
    fn get_tool(&self, name: &str) -> Option<Tool> { self.apps.get_tool(name) }
    async fn list_tools(&self, request: Option<PaginatedRequestParams>, _: RequestContext<RoleServer>)
        -> Result<ListToolsResult, ErrorData> { self.apps.list_tools(request) }
    async fn list_resources(&self, request: Option<PaginatedRequestParams>, _: RequestContext<RoleServer>)
        -> Result<ListResourcesResult, ErrorData> { self.apps.list_resources(request) }
    async fn call_tool(&self, request: CallToolRequestParams, context: RequestContext<RoleServer>)
        -> Result<CallToolResponse, ErrorData> {
        // Authorize the original request before delegating.
        self.apps.call_tool(&self.state, request, context).await
    }
    async fn read_resource(&self, request: ReadResourceRequestParams, context: RequestContext<RoleServer>)
        -> Result<ReadResourceResponse, ErrorData> {
        // Select other resource owners by URI here when needed.
        self.apps.read_resource(&self.state, request, context).await
    }
}

§Low-level declarations

UiResource prepares a descriptor and matching HTML contents. ToolUi and ResourceUi prepare typed declarations and compose them into open rmcp metadata, preserving unknown keys. Omitted fields leave existing values intact; unequal supplied scalar/array values return MetadataError::Conflict without a partial update. These primitives remain usable without either optional feature.

use mcp_apps_server::{ResourceUi, UiResource, UiResourceUri};
let resource = UiResource::new(UiResourceUri::new("ui://inventory/dashboard")?, "dashboard");
let mut ui = ResourceUi::default();
ui.prefers_border = Some(true);
let contents = resource.html_contents("<!doctype html><html><body>Inventory</body></html>")
    .with_meta(ui.to_meta()?);

§Capabilities, security and limits

ui_capability inspects caller-supplied client capabilities and distinguishes absent, malformed and valid non-HTML support. On current rmcp requests use RequestContext::client_capabilities() rather than assume initialization is always the source. The consuming application chooses its fallback behavior.

HTML is supplied by the consumer, without parsing, sanitization or bundling. CSP, permissions and visibility are declarations for the host, not access control implemented by the server. The browser renders the interface and the host mediates communication. Local protocol checks do not establish real-host rendering or permission behavior. No runtime, transport or background work is started by this crate.

Structs§

AppRouter
An rmcp tool router and exact-URI registry of HTML resources.
AppServer
A ready-to-serve MCP server for a prepared application router and its state.
MetaObject
An open MCP metadata map, reused from rmcp for extension annotations.
PermissionRequest
An object-valued request for a browser permission, serialized as {}.
ResourceUi
Security and rendering declarations for a UI resource.
ToolUi
UI association and visibility declarations for a server tool.
UiCapability
A validated, borrowed client declaration of MCP Apps support.
UiCsp
Origin declarations from which the host constructs a Content Security Policy.
UiPermissions
Browser permission requests declared by a UI resource.
UiResource
A named UI resource used to prepare a descriptor and matching HTML contents.
UiResourceRoute
A registered HTML source with fixed identity and resource metadata.
UiResourceUri
An owned UI resource URI with valid RFC 3986 syntax and a literal ui:// prefix.

Enums§

CapabilityError
A malformed MCP Apps client capability declaration.
MetadataError
Metadata could not be prepared or composed with existing annotations.
RegistrationError
A registration or finalization failure, before serving requests.
UiUriError
A failure to construct a UiResourceUri.
UiVisibility
An actor allowed to discover or invoke a tool under its UI visibility policy.

Constants§

UI_EXTENSION_ID
The standard MCP Apps capability extension identifier.
UI_MIME_TYPE
The MCP Apps HTML MIME type required on returned resource contents.

Traits§

StaticUiResource
A UI resource whose HTML is embedded in the consuming binary.

Functions§

declare_ui_extension
Declare MCP Apps support in the server’s extension capabilities.
ui_capability
Inspect the client’s MCP Apps extension declaration.

Type Aliases§

HtmlFuture
The send-capable result of an HTML resource callback.

Attribute Macros§

app_router
Declare an application’s rmcp tools and their static UI resources together.

Derive Macros§

StaticUiResource
Derive a static resource’s declaration, embedded HTML and optional metadata.