Skip to main content

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}