turul_mcp_builders/traits/
tool_traits.rs

1//! Framework traits for MCP tool construction
2//!
3//! **IMPORTANT**: These are framework features, NOT part of the MCP specification.
4//! The MCP specification defines concrete types only.
5
6use std::collections::HashMap;
7use serde_json::Value;
8
9// Import protocol types (spec-defined)
10use turul_mcp_protocol::{Tool, ToolSchema};
11use turul_mcp_protocol::tools::ToolAnnotations;
12
13/// Base metadata trait - matches TypeScript BaseMetadata interface
14pub trait HasBaseMetadata {
15    /// Programmatic identifier (fallback display name)
16    fn name(&self) -> &str;
17
18    /// Human-readable display name (UI contexts)
19    fn title(&self) -> Option<&str> {
20        None
21    }
22}
23
24/// Tool description trait
25pub trait HasDescription {
26    fn description(&self) -> Option<&str> {
27        None
28    }
29}
30
31/// Input schema trait
32pub trait HasInputSchema {
33    fn input_schema(&self) -> &ToolSchema;
34}
35
36/// Output schema trait
37pub trait HasOutputSchema {
38    fn output_schema(&self) -> Option<&ToolSchema> {
39        None
40    }
41}
42
43/// Annotations trait
44pub trait HasAnnotations {
45    fn annotations(&self) -> Option<&ToolAnnotations> {
46        None
47    }
48}
49
50/// Tool-specific meta trait (separate from RPC _meta)
51pub trait HasToolMeta {
52    fn tool_meta(&self) -> Option<&HashMap<String, Value>> {
53        None
54    }
55}
56
57/// Complete tool definition - composed from fine-grained traits
58///
59/// This trait represents a complete MCP tool that can be registered with a server
60/// and invoked by clients. When you implement the required metadata traits, you automatically
61/// get `ToolDefinition` for free via blanket implementation.
62pub trait ToolDefinition:
63    HasBaseMetadata +           // name, title
64    HasDescription +            // description
65    HasInputSchema +            // inputSchema
66    HasOutputSchema +           // outputSchema
67    HasAnnotations +            // annotations
68    HasToolMeta +               // _meta (tool-specific)
69    Send +
70    Sync
71{
72    /// Display name precedence: title > annotations.title > name (matches TypeScript spec)
73    fn display_name(&self) -> &str {
74        if let Some(title) = self.title() {
75            title
76        } else if let Some(annotations) = self.annotations() {
77            if let Some(title) = &annotations.title {
78                title
79            } else {
80                self.name()
81            }
82        } else {
83            self.name()
84        }
85    }
86
87    /// Convert to concrete Tool struct for protocol serialization
88    fn to_tool(&self) -> Tool {
89        Tool {
90            name: self.name().to_string(),
91            title: self.title().map(String::from),
92            description: self.description().map(String::from),
93            input_schema: self.input_schema().clone(),
94            output_schema: self.output_schema().cloned(),
95            annotations: self.annotations().cloned(),
96            meta: self.tool_meta().cloned(),
97        }
98    }
99}
100
101/// Blanket implementation: any type implementing all required traits gets ToolDefinition
102impl<T> ToolDefinition for T
103where
104    T: HasBaseMetadata
105        + HasDescription
106        + HasInputSchema
107        + HasOutputSchema
108        + HasAnnotations
109        + HasToolMeta
110        + Send
111        + Sync,
112{
113    // Default implementations provided by trait definition
114}
turul_mcp_builders/traits/tool_traits.rs

turul_mcp_builders/traits/
tool_traits.rs
