Skip to main content

objectiveai_mcp_plugin_framework/
config.rs

1//! What a plugin gets to decide about serving.
2//!
3//! Two kinds of thing live here. The port and the keep-alive shape the
4//! SERVER; everything else is the plugin's `initialize` reply, which
5//! ObjectiveAI keeps verbatim and reports through
6//! `agents mcp servers list`.
7//!
8//! Most of the wire shape is fixed by the laboratory host — see
9//! [`crate::serve`] — and a knob for something that can only hold one
10//! value is just a way to get it wrong. These are the ones that
11//! genuinely vary.
12
13use std::time::Duration;
14
15use rmcp::model::Icon;
16
17/// How to serve, and how to introduce yourself.
18///
19/// [`name`][Self::name] and [`version`][Self::version] are constructor
20/// arguments rather than optional fields because they are not
21/// decoration: the proxy DERIVES its routing prefix from them, so they
22/// decide the tool names the agent actually sees. The rest are
23/// reporting only.
24#[derive(Debug, Clone, PartialEq)]
25pub struct Config {
26    /// The port the plugin's manifest declares under `mcp.port`.
27    ///
28    /// The host publishes exactly that port, so this and the manifest
29    /// are two halves that have to agree: a mismatch means the host
30    /// publishes a port nothing is listening on, and the plugin looks
31    /// dead rather than misconfigured.
32    pub port: u16,
33
34    /// The server name — load-bearing, not cosmetic.
35    ///
36    /// The proxy builds each upstream's ROUTING PREFIX from it
37    /// (`_` and `.` normalize to `-`), and prepends `<prefix>_` to
38    /// every tool name the agent sees. It is also the key the
39    /// agent-SDK runners file this server under in their `mcpServers`
40    /// config.
41    ///
42    /// Prefixes escalate only as far as uniqueness demands: `name`,
43    /// then `name-version` on collision, then `name-version-index`.
44    /// Two plugins sharing a name AND version therefore fall through
45    /// to a positional index — legal, but unreadable and tied to sort
46    /// order. Pick a distinct name.
47    pub name: String,
48
49    /// The server version — the prefix collision tie-breaker (see
50    /// [`name`][Self::name]), and reported by `servers/list`.
51    pub version: String,
52
53    /// Human-readable title. Reporting only.
54    pub title: Option<String>,
55
56    /// What this server is. Reporting only.
57    pub description: Option<String>,
58
59    /// Where to read more. Reporting only.
60    pub website_url: Option<String>,
61
62    /// Icons for a UI to show. Reporting only.
63    pub icons: Option<Vec<Icon>>,
64
65    /// How a model should use this server — the one field here written
66    /// FOR the agent rather than about the plugin. Surfaced through
67    /// `agents mcp servers list`.
68    pub instructions: Option<String>,
69
70    /// How often to ping an idle SSE stream, or `None` to never.
71    ///
72    /// Worth having because the connection crosses podman's port
73    /// publish and whatever sits between: an idle stream can be
74    /// reaped by something in the middle that has no idea the plugin
75    /// is simply thinking.
76    pub sse_keep_alive: Option<Duration>,
77}
78
79impl Config {
80    /// The config for a plugin whose manifest declares
81    /// `mcp.port = port`, identifying itself as `name`/`version`.
82    ///
83    /// Both identifiers are required for the reason on
84    /// [`name`][Self::name]: defaulting them would silently hand every
85    /// plugin the same routing prefix.
86    pub fn new(port: u16, name: impl Into<String>, version: impl Into<String>) -> Self {
87        Self {
88            port,
89            name: name.into(),
90            version: version.into(),
91            title: None,
92            description: None,
93            website_url: None,
94            icons: None,
95            instructions: None,
96            sse_keep_alive: Some(Duration::from_secs(15)),
97        }
98    }
99
100    /// Set the human-readable title.
101    pub fn with_title(mut self, title: impl Into<String>) -> Self {
102        self.title = Some(title.into());
103        self
104    }
105
106    /// Set what this server is.
107    pub fn with_description(mut self, description: impl Into<String>) -> Self {
108        self.description = Some(description.into());
109        self
110    }
111
112    /// Set where to read more.
113    pub fn with_website_url(mut self, website_url: impl Into<String>) -> Self {
114        self.website_url = Some(website_url.into());
115        self
116    }
117
118    /// Set the icons a UI may show.
119    pub fn with_icons(mut self, icons: impl IntoIterator<Item = Icon>) -> Self {
120        self.icons = Some(icons.into_iter().collect());
121        self
122    }
123
124    /// Set how a model should use this server.
125    pub fn with_instructions(mut self, instructions: impl Into<String>) -> Self {
126        self.instructions = Some(instructions.into());
127        self
128    }
129}
130
131#[cfg(test)]
132mod tests {
133    use super::*;
134
135    /// The two that decide the agent-visible tool names are the two a
136    /// caller cannot forget.
137    #[test]
138    fn identity_is_required_and_the_rest_is_not() {
139        let config = Config::new(8080, "hello-channel", "0.1.6");
140        assert_eq!(config.port, 8080);
141        assert_eq!(config.name, "hello-channel");
142        assert_eq!(config.version, "0.1.6");
143        assert_eq!(config.title, None);
144        assert_eq!(config.description, None);
145        assert_eq!(config.website_url, None);
146        assert_eq!(config.icons, None);
147        assert_eq!(config.instructions, None);
148    }
149
150    #[test]
151    fn the_optional_reporting_fields_are_settable() {
152        let config = Config::new(1, "n", "v")
153            .with_title("Title")
154            .with_description("What it does")
155            .with_website_url("https://objectiveai.dev")
156            .with_instructions("Call greet.");
157        assert_eq!(config.title.as_deref(), Some("Title"));
158        assert_eq!(config.description.as_deref(), Some("What it does"));
159        assert_eq!(config.website_url.as_deref(), Some("https://objectiveai.dev"));
160        assert_eq!(config.instructions.as_deref(), Some("Call greet."));
161    }
162}