objectiveai_mcp_plugin_framework/tools.rs
1//! The tools a plugin serves, swappable while it serves them.
2//!
3//! Tools are DECLARED with rmcp's own macros — `#[tool_router]`,
4//! `#[tool]` — which produce a [`ToolRouter`]. What rmcp has no route
5//! to is changing that set once a server is running: every
6//! `ToolRouter` mutator takes `&mut self`, every `ServerHandler`
7//! method takes `&self`, and the transport builds a fresh handler per
8//! session from an `Fn` factory. Nothing in that chain can hand a
9//! plugin back a way in.
10//!
11//! [`Tools`] is that way in. It holds the route list and one callback,
12//! and it is immutable but for [`replace`][Tools::replace] — which
13//! swaps the whole list and tells whoever is serving it. Hand it to
14//! [`serve`][crate::serve::serve], keep a clone of the `Arc`, and call
15//! `replace` whenever the set should change.
16//!
17//! ```no_run
18//! # use objectiveai_mcp_plugin_framework::tools::Tools;
19//! # use rmcp::handler::server::tool::{ToolRoute, ToolRouter};
20//! # struct State;
21//! # fn routes() -> Vec<ToolRoute<State>> { Vec::new() }
22//! # fn fewer_routes() -> Vec<ToolRoute<State>> { Vec::new() }
23//! let tools = Tools::new(routes());
24//! let handle = tools.clone();
25//!
26//! // Later, from anywhere: the served set changes, and the client is
27//! // told.
28//! handle.replace(fewer_routes());
29//! ```
30//!
31//! **No lock.** The route list is an [`ArcSwap`]: reads happen on every
32//! request and are wait-free, a swap happens rarely and is a single
33//! atomic store. A `RwLock` would put a lock on the hot path to make
34//! the cold path marginally simpler.
35
36use std::sync::{Arc, OnceLock};
37
38use arc_swap::ArcSwap;
39use rmcp::handler::server::tool::ToolRoute;
40
41/// A callback run after the route list is replaced, receiving the NEW
42/// list.
43///
44/// It is passed the routes rather than reading them back off [`Tools`]
45/// for a reason that is easy to miss: a closure holding
46/// `Arc<Tools<S>>` would close a cycle through the `notifier` field —
47/// `Tools` owns the closure, the closure owns `Tools` — and the whole
48/// structure would leak. Taking the list as an argument makes that
49/// cycle unrepresentable.
50type Notifier<S> = Box<dyn Fn(Arc<Vec<ToolRoute<S>>>) + Send + Sync>;
51
52/// The set of tools a plugin is serving.
53pub struct Tools<S> {
54 routes: ArcSwap<Vec<ToolRoute<S>>>,
55 /// Installed once by [`serve`][crate::serve::serve], never by a
56 /// plugin. `OnceLock` because "set exactly once, then read from
57 /// many threads" is precisely what it is for — no lock, no
58 /// `Option<Mutex<_>>`.
59 notifier: OnceLock<Notifier<S>>,
60}
61
62impl<S> std::fmt::Debug for Tools<S> {
63 fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
64 f.debug_struct("Tools")
65 .field("routes", &self.routes.load().len())
66 .field("notifier", &self.notifier.get().is_some())
67 .finish()
68 }
69}
70
71impl<S> Tools<S> {
72 /// The tools to start with — typically the whole of
73 /// `MyServer::tool_router()`, which is
74 /// [`into_iter`][IntoIterator]-able.
75 pub fn new(routes: impl IntoIterator<Item = ToolRoute<S>>) -> Arc<Self> {
76 Arc::new(Self {
77 routes: ArcSwap::from_pointee(routes.into_iter().collect()),
78 notifier: OnceLock::new(),
79 })
80 }
81
82 /// Replace the served tools, wholesale.
83 ///
84 /// The only mutation there is. After this returns, the new set is
85 /// what a request will route against, and whoever is serving has
86 /// been told — which for [`serve`][crate::serve::serve] means the
87 /// live router is rebuilt and the client is sent
88 /// `notifications/tools/list_changed`.
89 ///
90 /// Wholesale rather than add/remove because a partial edit has to
91 /// answer "what was there before?", and a plugin deciding its tool
92 /// set from its identity and arguments already knows the answer it
93 /// wants — it does not want to diff its way there.
94 pub fn replace(&self, routes: impl IntoIterator<Item = ToolRoute<S>>) {
95 let routes = Arc::new(routes.into_iter().collect::<Vec<_>>());
96 // Store BEFORE notifying: the callback's whole job is to make
97 // the world agree with this value, and it cannot do that if
98 // the value is not there yet.
99 self.routes.store(Arc::clone(&routes));
100 if let Some(notifier) = self.notifier.get() {
101 notifier(routes);
102 }
103 }
104
105 /// The tools currently served.
106 pub fn routes(&self) -> Arc<Vec<ToolRoute<S>>> {
107 self.routes.load_full()
108 }
109
110 /// Install the callback [`replace`][Self::replace] fires.
111 ///
112 /// Crate-internal and once-only: `serve` claims it, and a plugin
113 /// serving the same `Tools` twice would otherwise silently leave
114 /// one of the two servers stale. Returns `false` if it was already
115 /// claimed.
116 pub(crate) fn on_replace(
117 &self,
118 notifier: impl Fn(Arc<Vec<ToolRoute<S>>>) + Send + Sync + 'static,
119 ) -> bool {
120 self.notifier.set(Box::new(notifier)).is_ok()
121 }
122}
123
124#[cfg(test)]
125mod tests {
126 use super::*;
127 use rmcp::model::{CallToolResult, Tool};
128 use std::sync::atomic::{AtomicUsize, Ordering};
129
130 struct Server;
131
132 fn route(name: &'static str) -> ToolRoute<Server> {
133 let schema: Arc<rmcp::model::JsonObject> = Arc::new(Default::default());
134 ToolRoute::new_dyn(Tool::new(name, "", schema), |_context| {
135 Box::pin(async { Ok(CallToolResult::success(vec![])) })
136 })
137 }
138
139 fn names(tools: &Tools<Server>) -> Vec<String> {
140 tools
141 .routes()
142 .iter()
143 .map(|route| route.attr.name.to_string())
144 .collect()
145 }
146
147 #[test]
148 fn replace_swaps_the_served_set() {
149 let tools = Tools::new([route("alpha"), route("beta")]);
150 assert_eq!(names(&tools), ["alpha", "beta"]);
151
152 tools.replace([route("gamma")]);
153 assert_eq!(names(&tools), ["gamma"], "wholesale, not merged");
154
155 tools.replace([]);
156 assert!(names(&tools).is_empty(), "and emptying is allowed");
157 }
158
159 /// The notifier gets the NEW list, once per replace. Anything else
160 /// and a server wired to it would drift from what is served.
161 #[test]
162 fn the_notifier_receives_the_new_list_once_per_replace() {
163 let tools = Tools::new([route("alpha")]);
164 let calls = Arc::new(AtomicUsize::new(0));
165 let seen = Arc::new(ArcSwap::from_pointee(Vec::<String>::new()));
166
167 let (calls_in, seen_in) = (calls.clone(), seen.clone());
168 assert!(tools.on_replace(move |routes| {
169 calls_in.fetch_add(1, Ordering::SeqCst);
170 seen_in.store(Arc::new(
171 routes.iter().map(|r| r.attr.name.to_string()).collect(),
172 ));
173 }));
174
175 tools.replace([route("beta"), route("gamma")]);
176 assert_eq!(calls.load(Ordering::SeqCst), 1);
177 assert_eq!(seen.load().as_slice(), ["beta", "gamma"]);
178
179 tools.replace([route("delta")]);
180 assert_eq!(calls.load(Ordering::SeqCst), 2);
181 assert_eq!(seen.load().as_slice(), ["delta"]);
182 }
183
184 /// The store must land before the callback runs — the callback
185 /// exists to bring the world into line with it.
186 ///
187 /// Referencing `Tools` from inside its own callback takes a
188 /// [`Weak`][std::sync::Weak], never an `Arc`: an `Arc` would close
189 /// the cycle the notifier signature exists to avoid. This is the
190 /// supported way to look back, and the reason the new list is
191 /// passed as an argument is so that you rarely need to.
192 #[test]
193 fn the_new_routes_are_readable_from_inside_the_notifier() {
194 let tools = Tools::new([route("alpha")]);
195 let observed = Arc::new(ArcSwap::from_pointee(Vec::<String>::new()));
196
197 let weak = Arc::downgrade(&tools);
198 let observed_in = observed.clone();
199 tools.on_replace(move |_new| {
200 let Some(live) = weak.upgrade() else { return };
201 observed_in.store(Arc::new(
202 live.routes()
203 .iter()
204 .map(|r| r.attr.name.to_string())
205 .collect(),
206 ));
207 });
208
209 tools.replace([route("beta")]);
210 assert_eq!(
211 observed.load().as_slice(),
212 ["beta"],
213 "the swap is visible before the callback runs",
214 );
215 }
216
217 #[test]
218 fn replacing_without_a_notifier_is_fine() {
219 let tools = Tools::new([route("alpha")]);
220 tools.replace([route("beta")]);
221 assert_eq!(names(&tools), ["beta"]);
222 }
223
224 /// Two servers over one `Tools` would leave one of them stale, so
225 /// the second claim is refused rather than silently winning.
226 #[test]
227 fn the_notifier_can_only_be_claimed_once() {
228 let tools: Arc<Tools<Server>> = Tools::new([]);
229 assert!(tools.on_replace(|_| {}));
230 assert!(!tools.on_replace(|_| {}));
231 }
232}