Files
dbx/crates/dbx-mcp/src/plugin_tools.rs
T

361 lines
16 KiB
Rust

//! 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_<prefix>__<tool>` 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<RawPluginTool>,
}
/// 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_<prefix>__<tool>`).
/// 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_<prefix>__<tool>` 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<PluginToolEntry> {
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::<Vec<_>>()
})
.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::<Vec<_>>().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::<Vec<_>>());
}
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<Option<&'a (String, String)>, String> {
let available = || connections.iter().map(|(id, name)| format!("{id} ({name})")).collect::<Vec<_>>().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::<CallToolResult>(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::<rmcp::model::ToolAnnotations>(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::<Vec<_>>();
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::<Vec<_>>();
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);
}
}