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}