use crate::mcp::registry::{ToolSpec, ToolStability};
use serde_json::Value;
use std::collections::HashSet;
use std::sync::LazyLock;
#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, Default)]
pub enum McpSurface {
#[default]
Direct,
Discovery,
}
impl McpSurface {
pub fn as_str(self) -> &'static str {
match self {
McpSurface::Direct => "direct",
McpSurface::Discovery => "discovery",
}
}
pub fn parse(s: &str) -> Option<Self> {
match s.to_lowercase().as_str() {
"direct" => Some(McpSurface::Direct),
"discovery" => Some(McpSurface::Discovery),
_ => None,
}
}
pub fn facades_enabled(self) -> bool {
matches!(self, McpSurface::Discovery)
}
}
impl std::fmt::Display for McpSurface {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
write!(f, "{}", self.as_str())
}
}
pub const PINNED_DISCOVERY_TOOLS: &[&str] = &[
"math_eval",
"edit_preflight",
"command_preflight",
"config_preflight",
"text_security_inspect",
];
pub const TOOL_SEARCH: &str = "tool_search";
pub const TOOL_INVOKE: &str = "tool_invoke";
pub fn is_discovery_facade(name: &str) -> bool {
name == TOOL_SEARCH || name == TOOL_INVOKE
}
pub fn is_pinned_tool(name: &str) -> bool {
PINNED_DISCOVERY_TOOLS.contains(&name)
}
pub fn tool_search_input_schema() -> Value {
serde_json::json!({
"type": "object",
"properties": {
"query": {
"type": "string",
"description": "Natural-language or keyword query naming the desired capability (e.g. \"summarize a unified diff\").",
"minLength": 1
},
"limit": {
"type": "integer",
"description": "Maximum matches to return (1-10).",
"minimum": 1,
"maximum": 10,
"default": 5
},
"detail": {
"type": "string",
"description": "summary returns purpose/category/required arguments; schema additionally returns the full input schema.",
"enum": ["summary", "schema"],
"default": "summary"
},
"include_deprecated": {
"type": "boolean",
"description": "Include deprecated tools in results. Deprecated tools are hidden unless exactly named or this is true.",
"default": false
}
},
"required": ["query"],
"additionalProperties": false
})
}
pub fn tool_search_output_schema() -> Value {
serde_json::json!({
"type": "object",
"properties": {
"matches": {
"type": "array",
"description": "Ranked matches in deterministic relevance order.",
"items": {"type": "object"}
},
"query": {"type": "string", "description": "Echo of the search query."}
},
"required": ["matches", "query"],
"additionalProperties": false
})
}
pub fn tool_invoke_input_schema() -> Value {
serde_json::json!({
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Canonical underlying tool name to invoke (e.g. \"patch_summary\"). Facade names are rejected.",
"minLength": 1
},
"arguments": {
"type": "object",
"description": "Arguments for the target tool. Defaults to {}.",
"default": {}
}
},
"required": ["name"],
"additionalProperties": false
})
}
pub const TOOL_SEARCH_DESCRIPTION: &str = "Search the local deterministic tool catalog by keyword. Returns ranked canonical tool names with purpose, category, and required arguments. Prefer preflight composites for proposed edits/commands/configs; use tool_search for long-tail utilities, then call tool_invoke with the chosen canonical name.";
pub const TOOL_INVOKE_DESCRIPTION: &str = "Invoke one canonical deterministic tool by name with its arguments. The target must be allowed by the active profile and audience; harness-only and hidden tools are rejected for model callers. Facade names (tool_search, tool_invoke) cannot be invoked through this router.";
#[derive(Debug, Clone)]
pub struct SearchParams {
pub query: String,
pub limit: usize,
pub detail_schema: bool,
pub include_deprecated: bool,
}
pub fn parse_search_params(args: &Value) -> Result<SearchParams, String> {
let obj = args
.as_object()
.ok_or_else(|| "Invalid arguments: expected object".to_string())?;
for key in obj.keys() {
if !["query", "limit", "detail", "include_deprecated"].contains(&key.as_str()) {
return Err(format!("Unexpected argument(s): {}", key));
}
}
let query = obj
.get("query")
.and_then(|v| v.as_str())
.ok_or_else(|| "Missing required argument: query".to_string())?;
if query.trim().is_empty() {
return Err("Argument 'query' must be a non-empty string".to_string());
}
if query.chars().count() > 500 {
return Err("Argument 'query' length exceeds maxLength 500".to_string());
}
let limit = match obj.get("limit") {
None => 5,
Some(v) => {
let n = v
.as_i64()
.or_else(|| v.as_u64().map(|u| u as i64))
.ok_or_else(|| "Argument 'limit' must be integer".to_string())?;
if v.as_bool().is_some() {
return Err("Argument 'limit' must be integer".to_string());
}
if !(1..=10).contains(&n) {
return Err(
"Argument 'limit' value out of range (minimum 1, maximum 10)".to_string(),
);
}
n as usize
}
};
let detail_schema = match obj.get("detail") {
None => false,
Some(v) => match v.as_str() {
Some("summary") => false,
Some("schema") => true,
Some(other) => {
return Err(format!(
"Argument 'detail' must be one of: summary, schema (got '{}')",
other
))
}
None => return Err("Argument 'detail' must be one of: summary, schema".to_string()),
},
};
let include_deprecated = match obj.get("include_deprecated") {
None => false,
Some(v) => v
.as_bool()
.ok_or_else(|| "Argument 'include_deprecated' must be boolean".to_string())?,
};
Ok(SearchParams {
query: query.to_string(),
limit,
detail_schema,
include_deprecated,
})
}
#[derive(Debug, Clone)]
pub struct InvokeParams {
pub target: String,
pub arguments: Value,
}
pub fn parse_invoke_params(args: &Value) -> Result<InvokeParams, String> {
let obj = args
.as_object()
.ok_or_else(|| "Invalid arguments: expected object".to_string())?;
for key in obj.keys() {
if !["name", "arguments"].contains(&key.as_str()) {
return Err(format!("Unexpected argument(s): {}", key));
}
}
let name = obj
.get("name")
.and_then(|v| v.as_str())
.ok_or_else(|| "Missing required argument: name".to_string())?;
if name.trim().is_empty() {
return Err("Argument 'name' must be a non-empty string".to_string());
}
if name.len() > 200 {
return Err("Argument 'name' length exceeds limit".to_string());
}
if is_discovery_facade(name) {
return Err(format!("recursive invocation of '{}' is not allowed", name));
}
let arguments = match obj.get("arguments") {
None => Value::Object(serde_json::Map::new()),
Some(v) if v.is_object() => v.clone(),
Some(_) => return Err("Invalid arguments: expected object".to_string()),
};
Ok(InvokeParams {
target: name.to_string(),
arguments,
})
}
#[derive(Debug, Clone)]
struct ScoredHit {
index: usize,
relevance: u8,
matched_tokens: usize,
}
fn useful_name_token(token: &str) -> bool {
!matches!(
token,
"check"
| "config"
| "convert"
| "data"
| "diff"
| "extract"
| "file"
| "inspect"
| "json"
| "list"
| "path"
| "text"
| "tool"
| "unit"
| "summarize"
| "validate"
)
}
fn useful_tag_token(token: &str) -> bool {
!matches!(token, "check" | "compare" | "data" | "text" | "tool")
}
fn tokenize(s: &str) -> Vec<String> {
s.split(|c: char| ['_', '-', '/', '.', ' ', ':'].contains(&c))
.flat_map(|part| {
vec![part.to_lowercase()]
})
.map(|t| t.trim_matches(|c: char| !c.is_alphanumeric()).to_string())
.filter(|t| !t.is_empty())
.collect()
}
fn query_tokens(query: &str) -> Vec<String> {
query
.split(|c: char| !c.is_alphanumeric())
.map(|t| t.to_lowercase())
.filter(|t| !t.is_empty())
.collect()
}
struct SearchIndexEntry {
spec: &'static ToolSpec,
name_lower: String,
aliases_lower: Vec<String>,
name_tokens: Vec<String>,
tag_tokens: Vec<String>,
description_tokens: Vec<String>,
}
static SEARCH_INDEX: LazyLock<Vec<SearchIndexEntry>> = LazyLock::new(|| {
crate::mcp::registry::all_tools_vec()
.iter()
.map(|spec| SearchIndexEntry {
spec,
name_lower: spec.name.to_lowercase(),
aliases_lower: spec
.aliases
.iter()
.map(|alias| alias.to_lowercase())
.collect(),
name_tokens: tokenize(spec.name),
tag_tokens: spec
.tags
.iter()
.flat_map(|tag| tokenize(tag))
.chain(tokenize(spec.category))
.collect(),
description_tokens: query_tokens(spec.description),
})
.collect()
});
fn score_index(
entry: &SearchIndexEntry,
query_lower: &str,
qtokens: &[String],
include_deprecated: bool,
) -> Option<(u8, usize, &'static str)> {
let spec = entry.spec;
let is_deprecated = spec.stability == ToolStability::Deprecated;
if is_deprecated && !include_deprecated && entry.name_lower != query_lower {
return None;
}
if entry.name_lower == query_lower {
return Some((0, usize::MAX, "exact_name"));
}
for alias in &entry.aliases_lower {
if alias == query_lower {
return Some((1, usize::MAX, "alias"));
}
}
let name_matches = qtokens
.iter()
.filter(|qt| {
entry.name_tokens.iter().any(|nt| {
useful_name_token(nt)
&& (nt.as_str() == qt.as_str()
|| (qt.len() >= 3 && nt.starts_with(qt.as_str()))
|| (nt.len() >= 3
&& qt.starts_with(nt.as_str())
&& qt.len() <= nt.len().saturating_add(3)))
})
})
.count();
let tag_matches = qtokens
.iter()
.filter(|qt| {
useful_tag_token(qt) && entry.tag_tokens.iter().any(|t| t.as_str() == qt.as_str())
})
.count();
if name_matches > 0 {
return Some((2, name_matches + tag_matches * 2, "name_token"));
}
if qtokens
.iter()
.any(|qt| qt.len() >= 5 && entry.name_lower.starts_with(qt.as_str()))
{
return Some((2, 1, "name_token"));
}
if tag_matches > 0 {
return Some((3, tag_matches, "tag"));
}
let description_matches = qtokens
.iter()
.filter(|qt| {
entry
.description_tokens
.iter()
.any(|t| t.as_str() == qt.as_str())
})
.count();
if description_matches > 0 {
return Some((4, description_matches, "description"));
}
if query_lower.len() <= 200 {
let dist = crate::text::levenshtein_distance(query_lower, &entry.name_lower);
let threshold = query_lower
.chars()
.count()
.min(entry.name_lower.chars().count())
/ 2;
if dist <= threshold {
return Some((5, 1, "close_match"));
}
for alias in &entry.aliases_lower {
let d = crate::text::levenshtein_distance(query_lower, alias);
let th = query_lower.chars().count().min(alias.chars().count()) / 2;
if d <= th {
return Some((5, 1, "close_match"));
}
}
}
None
}
pub fn required_arguments(spec: &ToolSpec) -> Vec<String> {
let schema = (spec.input_schema)();
schema
.get("required")
.and_then(|v| v.as_array())
.map(|arr| {
arr.iter()
.filter_map(|v| v.as_str().map(String::from))
.collect()
})
.unwrap_or_default()
}
pub fn deprecated_replacement(name: &str) -> Option<&'static str> {
match name {
"json_query" => Some("json_extract"),
_ => None,
}
}
pub fn search_filtered<'a>(
specs: &[&'a ToolSpec],
params: &SearchParams,
) -> Vec<(&'a ToolSpec, &'static str)> {
let query_lower = params.query.to_lowercase();
let qtokens = query_tokens(¶ms.query);
let allowed: HashSet<&str> = specs.iter().map(|spec| spec.name).collect();
let mut hits: Vec<(ScoredHit, &'static str)> = Vec::new();
for (index, entry) in SEARCH_INDEX.iter().enumerate() {
if !allowed.contains(entry.spec.name) {
continue;
}
if let Some((relevance, matched_tokens, reason)) =
score_index(entry, &query_lower, &qtokens, params.include_deprecated)
{
hits.push((
ScoredHit {
index,
relevance,
matched_tokens,
},
reason,
));
}
}
hits.sort_by(|a, b| {
a.0.relevance
.cmp(&b.0.relevance)
.then_with(|| b.0.matched_tokens.cmp(&a.0.matched_tokens))
.then_with(|| a.0.index.cmp(&b.0.index))
});
hits.truncate(params.limit);
hits.into_iter()
.map(|(h, reason)| (SEARCH_INDEX[h.index].spec, reason))
.collect()
}
pub fn matches_value(hits: &[(&ToolSpec, &'static str)], detail_schema: bool) -> Value {
let mut arr = Vec::new();
for (spec, reason) in hits {
let mut obj = serde_json::Map::new();
obj.insert("name".to_string(), Value::String(spec.name.to_string()));
obj.insert(
"purpose".to_string(),
Value::String(spec.description.to_string()),
);
obj.insert(
"category".to_string(),
Value::String(spec.category.to_string()),
);
obj.insert(
"required_arguments".to_string(),
Value::Array(
required_arguments(spec)
.into_iter()
.map(Value::String)
.collect(),
),
);
obj.insert(
"match_reason".to_string(),
Value::String(reason.to_string()),
);
if spec.stability == ToolStability::Deprecated {
obj.insert("deprecated".to_string(), Value::Bool(true));
if let Some(repl) = deprecated_replacement(spec.name) {
obj.insert("replacement".to_string(), Value::String(repl.to_string()));
}
}
if detail_schema {
obj.insert("inputSchema".to_string(), (spec.input_schema)());
}
arr.push(Value::Object(obj));
}
Value::Array(arr)
}
pub fn discovery_specs_for(
profile: &str,
audience: crate::mcp::registry::ToolListAudience,
) -> Vec<&'static ToolSpec> {
crate::mcp::registry::tools_for_profile_audience(profile, audience)
.into_iter()
.filter(|s| is_pinned_tool(s.name))
.collect::<Vec<_>>()
}
fn compact_description(desc: &str) -> String {
if desc.chars().count() > 120 {
let truncated: String = desc.chars().take(117).collect();
format!("{}...", truncated)
} else {
desc.to_string()
}
}
pub fn discovery_legacy_definitions(
profile: &str,
audience: crate::mcp::registry::ToolListAudience,
names: Option<&[String]>,
) -> Vec<crate::mcp::registry::ToolDefinition> {
let mut defs: Vec<crate::mcp::registry::ToolDefinition> = Vec::new();
for spec in discovery_specs_for(profile, audience) {
defs.push(crate::mcp::registry::ToolDefinition {
name: spec.name.to_string(),
description: compact_description(spec.description),
input_schema: crate::mcp::registry::compact_input_schema(&(spec.input_schema)()),
output_schema: None,
tier: None,
tags: None,
deprecated: None,
category: None,
llm_exposure: None,
cost: None,
});
}
defs.push(crate::mcp::registry::ToolDefinition {
name: TOOL_SEARCH.to_string(),
description: TOOL_SEARCH_DESCRIPTION.to_string(),
input_schema: tool_search_input_schema(),
output_schema: None,
tier: None,
tags: None,
deprecated: None,
category: Some("discovery".to_string()),
llm_exposure: None,
cost: None,
});
defs.push(crate::mcp::registry::ToolDefinition {
name: TOOL_INVOKE.to_string(),
description: TOOL_INVOKE_DESCRIPTION.to_string(),
input_schema: tool_invoke_input_schema(),
output_schema: None,
tier: None,
tags: None,
deprecated: None,
category: Some("discovery".to_string()),
llm_exposure: None,
cost: None,
});
if let Some(filter) = names {
defs.retain(|d| filter.iter().any(|n| n == &d.name));
}
defs
}
pub fn discovery_modern_values(
profile: &str,
audience: crate::mcp::registry::ToolListAudience,
names: Option<&[String]>,
) -> Vec<Value> {
let mut values: Vec<Value> = Vec::new();
for spec in discovery_specs_for(profile, audience) {
let annotations = serde_json::to_value(crate::mcp::registry::annotations_for_spec(spec))
.unwrap_or(serde_json::json!({}));
values.push(serde_json::json!({
"name": spec.name,
"description": compact_description(spec.description),
"inputSchema": crate::mcp::registry::compact_input_schema(&(spec.input_schema)()),
"annotations": annotations,
}));
}
let facade_annotations = serde_json::json!({
"readOnlyHint": true,
"destructiveHint": false,
"idempotentHint": true,
"openWorldHint": false
});
values.push(serde_json::json!({
"name": TOOL_SEARCH,
"description": TOOL_SEARCH_DESCRIPTION,
"inputSchema": tool_search_input_schema(),
"annotations": facade_annotations,
}));
values.push(serde_json::json!({
"name": TOOL_INVOKE,
"description": TOOL_INVOKE_DESCRIPTION,
"inputSchema": tool_invoke_input_schema(),
"annotations": facade_annotations,
}));
if let Some(filter) = names {
values.retain(|v| {
v.get("name")
.and_then(|n| n.as_str())
.is_some_and(|n| filter.iter().any(|f| f == n))
});
}
values
}
#[cfg(test)]
mod tests {
use super::*;
use crate::mcp::registry;
fn full_model_specs() -> Vec<&'static ToolSpec> {
registry::tools_for_profile_audience("full", registry::ToolListAudience::Model)
}
fn refs(specs: &[&'static ToolSpec]) -> Vec<&'static ToolSpec> {
specs.to_vec()
}
#[test]
fn surface_parse_roundtrip() {
assert_eq!(McpSurface::parse("direct"), Some(McpSurface::Direct));
assert_eq!(McpSurface::parse("DISCOVERY"), Some(McpSurface::Discovery));
assert_eq!(McpSurface::parse("bogus"), None);
assert_eq!(McpSurface::Direct.as_str(), "direct");
assert_eq!(McpSurface::Discovery.as_str(), "discovery");
assert!(!McpSurface::Direct.facades_enabled());
assert!(McpSurface::Discovery.facades_enabled());
}
#[test]
fn pinned_set_is_five_known_tools() {
assert_eq!(PINNED_DISCOVERY_TOOLS.len(), 5);
for name in PINNED_DISCOVERY_TOOLS {
assert!(
registry::get_tool(name).is_some(),
"pinned tool '{}' must exist",
name
);
}
}
#[test]
fn search_exact_name_wins() {
let specs = full_model_specs();
let r = refs(&specs);
let params = parse_search_params(&serde_json::json!({"query": "patch_summary"})).unwrap();
let hits = search_filtered(&r, ¶ms);
assert!(!hits.is_empty());
assert_eq!(hits[0].0.name, "patch_summary");
assert_eq!(hits[0].1, "exact_name");
}
#[test]
fn search_deprecated_hidden_unless_exact_or_included() {
let specs = full_model_specs();
let r = refs(&specs);
let params =
parse_search_params(&serde_json::json!({"query": "json pointer extract"})).unwrap();
let hits = search_filtered(&r, ¶ms);
let names: Vec<&str> = hits.iter().map(|(s, _)| s.name).collect();
assert!(
!names.contains(&"json_query"),
"deprecated json_query must be hidden from ordinary search"
);
let exact = parse_search_params(&serde_json::json!({"query": "json_query"})).unwrap();
let hits = search_filtered(&r, &exact);
assert!(hits.iter().any(|(s, _)| s.name == "json_query"));
let with_dep = parse_search_params(
&serde_json::json!({"query": "json pointer", "include_deprecated": true, "limit": 10}),
)
.unwrap();
let _ = search_filtered(&r, &with_dep);
}
#[test]
fn search_order_deterministic() {
let specs = full_model_specs();
let r = refs(&specs);
let params =
parse_search_params(&serde_json::json!({"query": "patch", "limit": 5})).unwrap();
let a = search_filtered(&r, ¶ms);
let b = search_filtered(&r, ¶ms);
let an: Vec<&str> = a.iter().map(|(s, _)| s.name).collect();
let bn: Vec<&str> = b.iter().map(|(s, _)| s.name).collect();
assert_eq!(an, bn);
assert_eq!(
serde_json::to_string(&matches_value(&a, false)).unwrap(),
serde_json::to_string(&matches_value(&b, false)).unwrap()
);
}
#[test]
fn invoke_rejects_facade_recursion() {
let err = parse_invoke_params(&serde_json::json!({"name": "tool_invoke"})).unwrap_err();
assert!(err.contains("recursive"));
let err = parse_invoke_params(&serde_json::json!({"name": "tool_search"})).unwrap_err();
assert!(err.contains("recursive"));
}
#[test]
fn facade_schemas_use_supported_keywords_only() {
for schema in [
tool_search_input_schema(),
tool_search_output_schema(),
tool_invoke_input_schema(),
] {
let obj = schema.as_object().unwrap();
for key in obj.keys() {
assert!(
[
"type",
"properties",
"required",
"additionalProperties",
"items",
"minItems",
"maxItems",
"uniqueItems",
"minLength",
"maxLength",
"pattern",
"minimum",
"maximum",
"exclusiveMinimum",
"exclusiveMaximum",
"multipleOf",
"enum",
"const",
"description",
"title",
"default",
"examples",
"$schema"
]
.contains(&key.as_str()),
"unexpected top-level schema key: {}",
key
);
}
}
}
}