//! External exposure of plugin MCP tools on the `dbx` MCP server. //! //! Author opt-in: installed, compatible plugins with a backend contribute //! their `mcp/tools` listing under `dbx___` names only when the //! manifest declares `external_tools: true`. Naming, parsing, and schema //! reduction are shared with the built-in AI agent //! (`dbx_core::ai::plugin_tools`) so one plugin tool surfaces under the same //! exposed name on both surfaces. //! //! Calls stay host-bound: the caller picks among the plugin's saved //! connections that the global MCP policy allows through `dbx_connection` //! (`connectionId` / `connectionName` are accepted as aliases), and the host //! generates the lifecycle payload from the saved connection — credentials //! never cross the process boundary, and a connection saved for plugin A can //! never be reached through plugin B's tools. use std::collections::HashSet; use std::sync::Arc; use serde_json::{json, Value}; #[doc(hidden)] pub use dbx_core::ai::plugin_tools::CONNECTION_ARGUMENT as PLUGIN_CONNECTION_ARGUMENT; use dbx_core::ai::plugin_tools::{ exposed_tool_name, plugin_prefixes, sanitize_schema, RawPluginTool, CONNECTION_ARGUMENT, HOST_BOUND_ARGUMENTS, }; /// Upper bound for the merged tools/list. Higher than the AI surface's cap: /// MCP clients paginate and let their users enable/disable tools themselves, /// so the host does not need to ration as aggressively. pub const MAX_TOTAL_PLUGIN_TOOLS: usize = 512; /// Plugin arguments the host resolves from the saved connection before the /// call is forwarded. pub const CONNECTION_SELECTOR_ARGUMENTS: &[&str] = &[CONNECTION_ARGUMENT, "connectionId", "connectionName"]; /// One plugin's discovered `mcp/tools` listing, keyed for exposure. #[derive(Debug, Clone)] pub struct PluginToolProvider { pub plugin_id: String, pub plugin_name: String, pub tools: Vec, } /// One externally exposed plugin tool. #[derive(Debug, Clone)] pub struct PluginToolEntry { pub plugin_id: String, pub plugin_name: String, pub exposed_name: String, pub tool: RawPluginTool, /// The plugin schema declares `connectionId`, so the host injects the /// bound connection's id into the forwarded arguments. pub injects_connection_id: bool, } /// Whether `name` sits in the plugin-tool namespace (`dbx___`). /// The static `dbx_*` router tools never contain `__`, so this cannot swallow /// one, and unknown plugin names simply fail resolution at call time. pub fn is_plugin_tool_name(name: &str) -> bool { let Some(rest) = name.strip_prefix("dbx_") else { return false }; let Some((prefix, _)) = rest.split_once("__") else { return false }; !prefix.is_empty() } /// Builds the exposed entries from raw provider listings. Deterministic: /// providers are ordered by plugin id (so prefix de-duplication is stable) /// and each plugin keeps its listing order. Exposed names live in the /// `dbx___` namespace: the shared AI-surface name plus the /// `dbx_` router prefix, which static tools never use with a `__` separator. pub fn build_catalog(providers: &[PluginToolProvider]) -> Vec { let mut sorted: Vec<&PluginToolProvider> = providers.iter().collect(); sorted.sort_by(|left, right| left.plugin_id.cmp(&right.plugin_id)); let prefixes = plugin_prefixes(sorted.iter().map(|provider| provider.plugin_id.as_str())); let mut entries = Vec::new(); 'providers: for provider in sorted { let prefix = &prefixes[&provider.plugin_id]; let mut used = HashSet::new(); for tool in &provider.tools { if entries.len() >= MAX_TOTAL_PLUGIN_TOOLS { log::warn!( "[mcp][plugin-tools] tool limit {MAX_TOTAL_PLUGIN_TOOLS} reached; remaining plugin tools skipped" ); break 'providers; } entries.push(PluginToolEntry { exposed_name: format!("dbx_{}", exposed_tool_name(prefix, &tool.name, &mut used)), plugin_id: provider.plugin_id.clone(), plugin_name: provider.plugin_name.clone(), injects_connection_id: tool.input_schema.pointer("/properties/connectionId").is_some(), tool: tool.clone(), }); } } entries } /// The caller-facing parameter schema: the plugin schema reduced to the same /// portable subset the AI surface uses, host-bound arguments removed, and an /// optional connection selector added when the plugin has allowed /// connections. The selector stays optional: with exactly one connection the /// host binds it, and connection-less tools work without one. pub fn external_tool_parameters(input_schema: &Value, connections: &[(String, String)]) -> Value { let mut schema = sanitize_schema(input_schema, 0); if schema.get("type").and_then(Value::as_str) != Some("object") { schema = json!({ "type": "object", "properties": {} }); } let object = schema.as_object_mut().expect("object schema"); let properties = object.entry("properties").or_insert_with(|| json!({})); if let Some(properties) = properties.as_object_mut() { for key in HOST_BOUND_ARGUMENTS { properties.remove(*key); } } let required = object .get("required") .and_then(Value::as_array) .map(|items| { items .iter() .filter_map(Value::as_str) .filter(|key| !HOST_BOUND_ARGUMENTS.contains(key)) .map(str::to_string) .collect::>() }) .unwrap_or_default(); if !required.is_empty() { object.insert("required".to_string(), json!(required)); } else { object.remove("required"); } if !connections.is_empty() { let choices = connections.iter().map(|(id, name)| format!("{id} = {name}")).collect::>().join("; "); let mut selector = json!({ "type": "string", "description": format!( "DBX connection to run this tool on. Omit to use the only allowed connection. ({choices})" ), }); if connections.len() > 1 { selector["enum"] = json!(connections.iter().map(|(id, _)| id.clone()).collect::>()); } object["properties"][CONNECTION_ARGUMENT] = selector; } schema } /// Caller-facing description, attributed to the owning plugin. pub fn external_tool_description(plugin_name: &str, tool: &RawPluginTool) -> String { let body = if tool.description.trim().is_empty() { tool.name.as_str() } else { tool.description.as_str() }; format!("[{plugin_name} plugin] {body}").chars().take(1_500).collect() } /// Resolves the connection binding for one external call. `selector` is the /// trimmed `dbx_connection` / `connectionId` / `connectionName` value, when /// the caller supplied one. Matching mirrors the AI surface: exact id first, /// then an unambiguous name. pub fn select_connection<'a>( connections: &'a [(String, String)], selector: Option<&str>, ) -> Result, String> { let available = || connections.iter().map(|(id, name)| format!("{id} ({name})")).collect::>().join(", "); let Some(selector) = selector.filter(|selector| !selector.trim().is_empty()) else { return match connections { [only] => Ok(Some(only)), [] => Ok(None), _ => Err(format!( "Pass `{CONNECTION_ARGUMENT}` to choose the connection. Allowed connections: {}", available() )), }; }; let requested = selector.trim(); connections .iter() .find(|(id, _)| id == requested) .or_else(|| { let mut by_name = connections.iter().filter(|(_, name)| name == requested); let first = by_name.next(); // A name is only a valid selector when it is unambiguous. first.filter(|_| by_name.next().is_none()) }) .map(Some) .ok_or_else(|| { format!("`{requested}` is not an allowed connection for this tool. Allowed connections: {}", available()) }) } /// Extracts the connection selector from raw call arguments (without /// consuming them), preferring the canonical `dbx_connection` key. pub fn connection_selector_from(arguments: &Value) -> Option<&str> { CONNECTION_SELECTOR_ARGUMENTS.iter().find_map(|key| arguments.get(*key).and_then(Value::as_str)) } /// Converts a plugin `mcp/call` answer (MCP `CallToolResult`-shaped JSON) /// into the rmcp wire type, degrading to a plain text payload for plugins /// that return something else. pub fn call_result_to_rmcp(value: Value) -> rmcp::model::CallToolResult { use rmcp::model::{CallToolResult, ContentBlock}; if let Ok(result) = serde_json::from_value::(value.clone()) { return result; } let text = if value.is_null() { "(the tool returned no output)".to_string() } else { value.to_string() }; let mut result = CallToolResult::success(vec![ContentBlock::text(text)]); result.is_error = None; result } /// The rmcp `Tool` for the external `tools/list` view. pub fn to_rmcp_tool(entry: &PluginToolEntry, connections: &[(String, String)]) -> rmcp::model::Tool { let annotations = entry.tool.annotations.as_object().filter(|annotations| !annotations.is_empty()).and_then(|annotations| { serde_json::from_value::(Value::Object(annotations.clone())).ok() }); let schema = external_tool_parameters(&entry.tool.input_schema, connections); let mut tool = rmcp::model::Tool::new( entry.exposed_name.clone(), external_tool_description(&entry.plugin_name, &entry.tool), Arc::new(schema.as_object().cloned().unwrap_or_default()), ); tool.annotations = annotations; tool } #[cfg(test)] mod tests { use super::*; use dbx_core::ai::plugin_tools::parse_tool_list; fn provider(plugin_id: &str, plugin_name: &str, tools: Value) -> PluginToolProvider { PluginToolProvider { plugin_id: plugin_id.to_string(), plugin_name: plugin_name.to_string(), tools: parse_tool_list(&tools), } } fn ssh_listing() -> Value { json!({ "tools": [ { "name": "sftp_list_dir", "description": "List a remote directory", "annotations": { "readOnlyHint": true }, "inputSchema": { "type": "object", "properties": { "connectionId": { "type": "string" }, "path": { "type": "string", "description": "Absolute path" } }, "required": ["connectionId", "path"] } }, { "name": "ssh_exec", "description": "Run a command", "inputSchema": { "type": "object", "properties": { "command": { "type": "string" } }, "required": ["command"] } } ] }) } #[test] fn plugin_namespace_cannot_swallow_static_router_names() { assert!(is_plugin_tool_name("dbx_ssh__sftp_list_dir")); assert!(is_plugin_tool_name("dbx_ssh__x__y")); assert!(!is_plugin_tool_name("dbx_list_connections")); assert!(!is_plugin_tool_name("dbx_ssh_underscore")); assert!(!is_plugin_tool_name("ssh__sftp_list_dir")); assert!(!is_plugin_tool_name("dbx____")); } #[test] fn catalog_exposes_prefixed_names_in_provider_order() { let providers = vec![ provider("io.dbx.ssh", "Terminal", ssh_listing()), provider("io.dbx.files", "Files", json!({ "tools": [{ "name": "files_list", "description": "List" }] })), ]; let entries = build_catalog(&providers); let names = entries.iter().map(|entry| entry.exposed_name.as_str()).collect::>(); assert_eq!(names, ["dbx_files__files_list", "dbx_ssh__sftp_list_dir", "dbx_ssh__ssh_exec"]); let sftp = entries.iter().find(|entry| entry.exposed_name == "dbx_ssh__sftp_list_dir").unwrap(); assert!(sftp.tool.read_only); assert!(sftp.injects_connection_id, "the plugin schema declares connectionId"); } #[test] fn catalog_is_plugin_agnostic_and_disambiguates_prefix_clashes() { // Any plugin id works; the prefix is the id's last segment, extended // leftward only when two plugins share it — the distinguishing part // of the id stays in the name instead of an install-order counter. let providers = vec![ provider("a.files", "Files A", json!({ "tools": [{ "name": "list", "description": "List" }] })), provider("b.files", "Files B", json!({ "tools": [{ "name": "list", "description": "List" }] })), provider("com.vendor.kubernetes", "K8s", json!({ "tools": [{ "name": "apply", "description": "Apply" }] })), ]; let entries = build_catalog(&providers); let names = entries.iter().map(|entry| entry.exposed_name.as_str()).collect::>(); assert_eq!(names, ["dbx_a_files__list", "dbx_b_files__list", "dbx_kubernetes__apply"]); } #[test] fn external_schema_strips_host_bound_arguments_and_adds_selector() { let providers = vec![provider("io.dbx.ssh", "Terminal", ssh_listing())]; let entries = build_catalog(&providers); let sftp = entries.iter().find(|entry| entry.exposed_name == "dbx_ssh__sftp_list_dir").unwrap(); let schema = external_tool_parameters( &sftp.tool.input_schema, &[("c1".to_string(), "prod".to_string()), ("c2".to_string(), "test".to_string())], ); assert!(schema.pointer("/properties/connectionId").is_none()); assert_eq!(schema["required"], json!(["path"]), "connectionId leaves the required list"); assert_eq!(schema["properties"][CONNECTION_ARGUMENT]["enum"], json!(["c1", "c2"])); let single = external_tool_parameters(&sftp.tool.input_schema, &[("c1".to_string(), "prod".to_string())]); assert!(single.pointer(&format!("/properties/{CONNECTION_ARGUMENT}/enum")).is_none()); assert!(single.pointer(&format!("/properties/{CONNECTION_ARGUMENT}")).is_some()); let none = external_tool_parameters(&sftp.tool.input_schema, &[]); assert!(none.pointer(&format!("/properties/{CONNECTION_ARGUMENT}")).is_none()); } #[test] fn selector_resolution_mirrors_the_ai_surface() { let connections = vec![("c1".to_string(), "prod".to_string()), ("c2".to_string(), "test".to_string())]; // Multiple connections need an explicit selector. assert!(select_connection(&connections, None).is_err()); // Exact id, unique name, unknown. assert_eq!(select_connection(&connections, Some("c2")).unwrap().unwrap().0, "c2"); assert_eq!(select_connection(&connections, Some("prod")).unwrap().unwrap().0, "c1"); assert!(select_connection(&connections, Some("c9")).is_err()); let single = vec![("c1".to_string(), "prod".to_string())]; assert_eq!(select_connection(&single, None).unwrap().unwrap().0, "c1"); let empty: Vec<(String, String)> = Vec::new(); assert!(select_connection(&empty, None).unwrap().is_none(), "connection-less tools stay callable"); } #[test] fn selector_extraction_prefers_the_canonical_argument() { let args = json!({ "connectionId": "k1", "path": "/" }); assert_eq!(connection_selector_from(&args), Some("k1")); let canonical = json!({ "dbx_connection": "k2", "connectionId": "k1" }); assert_eq!(connection_selector_from(&canonical), Some("k2")); assert_eq!(connection_selector_from(&json!({ "path": "/" })), None); } #[test] fn call_results_convert_with_a_text_fallback() { let shaped = call_result_to_rmcp(json!({ "content": [{ "type": "text", "text": "done" }], "isError": true })); assert_eq!(shaped.content.len(), 1); assert_eq!(shaped.is_error, Some(true)); let fallback = call_result_to_rmcp(json!({ "unexpected": "shape" })); assert_eq!(fallback.content.len(), 1); assert_eq!(fallback.is_error, None); } }