Skip to main content

mcp_apps_server/
capabilities.rs

1//! Prepare and inspect standard MCP Apps extension capabilities.
2//!
3//! Consumers obtain client capabilities from their current request or supported
4//! connection lifecycle. These helpers do not manage that lifecycle.
5
6use 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/// A validated, borrowed client declaration of MCP Apps support.
14///
15/// Unknown settings remain in the original JSON object. This view neither
16/// copies nor changes the client's declaration.
17#[derive(Debug)]
18pub struct UiCapability<'a> {
19    raw: &'a JsonObject,
20}
21
22impl UiCapability<'_> {
23    /// Iterate over the declared MIME types in their original order.
24    ///
25    /// The declaration has already been checked to contain only strings.
26    /// Duplicate and unknown MIME types are retained.
27    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    /// Return whether the client declares the standard MCP Apps HTML MIME type.
37    ///
38    /// Matching uses the exact protocol value in [`UI_MIME_TYPE`].
39    pub fn supports_html(&self) -> bool {
40        self.mime_types().any(|mime_type| mime_type == UI_MIME_TYPE)
41    }
42}
43
44/// A malformed MCP Apps client capability declaration.
45#[derive(Debug)]
46#[non_exhaustive]
47pub enum CapabilityError {
48    /// The declared UI extension has no required `mimeTypes` setting.
49    MissingMimeTypes,
50    /// The `mimeTypes` setting is not a JSON array.
51    MimeTypesNotArray,
52    /// An entry in `mimeTypes` is not a JSON string.
53    MimeTypeNotString {
54        /// Zero-based position of the malformed entry.
55        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
78/// Inspect the client's MCP Apps extension declaration.
79///
80/// Returns `Ok(None)` when the extension is absent. A valid declaration can
81/// advertise no MIME types or types other than HTML; use
82/// [`UiCapability::supports_html`] to check HTML support.
83///
84/// Unknown settings are retained without validation or mutation.
85///
86/// # Errors
87///
88/// Returns [`CapabilityError`] when the declared extension omits `mimeTypes`,
89/// supplies a non-array value, or contains a non-string array member.
90pub 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
116/// Declare MCP Apps support in the server's extension capabilities.
117///
118/// Inserts an empty settings object only when the UI extension is absent.
119/// Existing UI settings and unrelated extensions are preserved. This does not
120/// enable the ordinary MCP tools or resources capabilities.
121pub 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}