mcp_apps_server/
capabilities.rs1use std::{error::Error, fmt};
7
8use rmcp::model::{ClientCapabilities, JsonObject, ServerCapabilities};
9use serde_json::Value;
10
11use crate::{UI_EXTENSION_ID, UI_MIME_TYPE};
12
13#[derive(Debug)]
18pub struct UiCapability<'a> {
19 raw: &'a JsonObject,
20}
21
22impl UiCapability<'_> {
23 pub fn mime_types(&self) -> impl Iterator<Item = &str> {
28 self.raw
29 .get("mimeTypes")
30 .and_then(Value::as_array)
31 .into_iter()
32 .flatten()
33 .filter_map(Value::as_str)
34 }
35
36 pub fn supports_html(&self) -> bool {
40 self.mime_types().any(|mime_type| mime_type == UI_MIME_TYPE)
41 }
42}
43
44#[derive(Debug)]
46#[non_exhaustive]
47pub enum CapabilityError {
48 MissingMimeTypes,
50 MimeTypesNotArray,
52 MimeTypeNotString {
54 index: usize,
56 },
57}
58
59impl fmt::Display for CapabilityError {
60 fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
61 match self {
62 Self::MissingMimeTypes => {
63 formatter.write_str("MCP Apps client capability is missing mimeTypes")
64 }
65 Self::MimeTypesNotArray => {
66 formatter.write_str("MCP Apps client capability mimeTypes must be an array")
67 }
68 Self::MimeTypeNotString { index } => write!(
69 formatter,
70 "MCP Apps client capability mimeTypes[{index}] must be a string"
71 ),
72 }
73 }
74}
75
76impl Error for CapabilityError {}
77
78pub fn ui_capability(
91 capabilities: &ClientCapabilities,
92) -> Result<Option<UiCapability<'_>>, CapabilityError> {
93 let Some(raw) = capabilities
94 .extensions
95 .as_ref()
96 .and_then(|extensions| extensions.get(UI_EXTENSION_ID))
97 else {
98 return Ok(None);
99 };
100
101 let mime_types = raw
102 .get("mimeTypes")
103 .ok_or(CapabilityError::MissingMimeTypes)?
104 .as_array()
105 .ok_or(CapabilityError::MimeTypesNotArray)?;
106
107 for (index, mime_type) in mime_types.iter().enumerate() {
108 if !mime_type.is_string() {
109 return Err(CapabilityError::MimeTypeNotString { index });
110 }
111 }
112
113 Ok(Some(UiCapability { raw }))
114}
115
116pub fn declare_ui_extension(capabilities: &mut ServerCapabilities) {
122 capabilities
123 .extensions
124 .get_or_insert_default()
125 .entry(UI_EXTENSION_ID.to_owned())
126 .or_default();
127}
128
129#[cfg(test)]
130mod tests {
131 use rmcp::model::ExtensionCapabilities;
132 use serde_json::json;
133
134 use super::*;
135
136 fn client_with_ui(settings: Value) -> ClientCapabilities {
137 let mut capabilities = ClientCapabilities::default();
138 let mut extensions = ExtensionCapabilities::new();
139 extensions.insert(
140 "example/other".into(),
141 serde_json::from_value(json!({"x": 1})).unwrap(),
142 );
143 extensions.insert(
144 UI_EXTENSION_ID.into(),
145 serde_json::from_value(settings).unwrap(),
146 );
147 capabilities.extensions = Some(extensions);
148 capabilities
149 }
150
151 #[test]
152 fn client_capability_distinguishes_absence_invalid_shape_and_html_support() {
153 assert!(
154 ui_capability(&ClientCapabilities::default())
155 .unwrap()
156 .is_none()
157 );
158 let mut absent = client_with_ui(json!({"mimeTypes": []}));
159 absent.extensions.as_mut().unwrap().remove(UI_EXTENSION_ID);
160 assert!(ui_capability(&absent).unwrap().is_none());
161
162 assert!(matches!(
163 ui_capability(&client_with_ui(json!({}))),
164 Err(CapabilityError::MissingMimeTypes)
165 ));
166 for value in [Value::Null, json!(UI_MIME_TYPE), json!({}), json!(true)] {
167 assert!(matches!(
168 ui_capability(&client_with_ui(json!({"mimeTypes": value}))),
169 Err(CapabilityError::MimeTypesNotArray)
170 ));
171 }
172 assert!(matches!(
173 ui_capability(&client_with_ui(json!({"mimeTypes": [UI_MIME_TYPE, 1]}))),
174 Err(CapabilityError::MimeTypeNotString { index: 1 })
175 ));
176
177 for (types, supports_html) in [
178 (vec![], false),
179 (
180 vec!["text/html", "text/html; profile=mcp-app", "example/future"],
181 false,
182 ),
183 (vec!["example/future", UI_MIME_TYPE, UI_MIME_TYPE], true),
184 ] {
185 let capabilities = client_with_ui(json!({
186 "mimeTypes": types,
187 "future": {"enabled": true}
188 }));
189 let original = capabilities.clone();
190 let view = ui_capability(&capabilities).unwrap().unwrap();
191 assert_eq!(view.mime_types().collect::<Vec<_>>(), types);
192 assert_eq!(view.supports_html(), supports_html);
193 assert_eq!(capabilities, original);
194 }
195 }
196
197 #[test]
198 fn server_declaration_is_additive_and_idempotent() {
199 let mut capabilities = ServerCapabilities::default();
200 declare_ui_extension(&mut capabilities);
201 assert_eq!(
202 capabilities.extensions.as_ref().unwrap()[UI_EXTENSION_ID],
203 JsonObject::new()
204 );
205 assert!(capabilities.tools.is_none());
206 assert!(capabilities.resources.is_none());
207 let declared = capabilities.clone();
208 declare_ui_extension(&mut capabilities);
209 assert_eq!(capabilities, declared);
210
211 let mut existing = ServerCapabilities::default();
212 existing.extensions = client_with_ui(json!({"future": true})).extensions;
213 let original = existing.clone();
214 declare_ui_extension(&mut existing);
215 declare_ui_extension(&mut existing);
216 assert_eq!(existing, original);
217 }
218}