lean_ctx/server/
tool_trait.rs

1use rmcp::ErrorData;
2use rmcp::model::{ContentBlock, Tool};
3use serde_json::{Map, Value};
4
5/// Outcome of a shell execution, carried alongside the rendered text so the
6/// MCP dispatch layer can surface failures in protocol metadata instead of
7/// only as an `[exit:N]` text footer (GitHub #389: clients had no programmatic
8/// way to detect ctx_shell failures and resorted to fragile regex matching).
9#[derive(Debug, Clone, Copy, PartialEq, Eq)]
10pub enum ShellOutcome {
11    /// The command ran; carries its real exit code (0 = success).
12    Exit(i32),
13    /// The command never ran (allowlist/validation rejection, or a
14    /// precondition failure such as an unreadable/oversized input file).
15    Blocked,
16}
17
18impl ShellOutcome {
19    /// Whether this outcome must be reported as a tool error (`isError: true`).
20    pub fn is_error(self) -> bool {
21        match self {
22            ShellOutcome::Exit(code) => code != 0,
23            ShellOutcome::Blocked => true,
24        }
25    }
26
27    /// Structured payload for `CallToolResult.structuredContent`, so guards
28    /// can read `exitCode`/`blocked` instead of parsing output text. Success
29    /// (exit 0) intentionally returns `None` — the happy path stays
30    /// token-neutral for clients that render structured content.
31    pub fn structured(self) -> Option<serde_json::Value> {
32        match self {
33            ShellOutcome::Exit(0) => None,
34            ShellOutcome::Exit(code) => Some(serde_json::json!({ "exitCode": code })),
35            ShellOutcome::Blocked => Some(serde_json::json!({ "blocked": true })),
36        }
37    }
38}
39
40/// Result returned by an McpTool handler.
41pub struct ToolOutput {
42    pub text: String,
43    pub original_tokens: usize,
44    pub saved_tokens: usize,
45    pub mode: Option<String>,
46    /// Path associated with the tool call (for record_call_with_path).
47    pub path: Option<String>,
48    /// True when the tool mutated state that clients should know about
49    /// (e.g. dynamic tool categories changed).
50    pub changed: bool,
51    /// Set by shell-executing tools so dispatch can populate `isError` +
52    /// `structuredContent` on the MCP result (GitHub #389). `None` for tools
53    /// that don't run shell commands.
54    pub shell_outcome: Option<ShellOutcome>,
55    /// Override content blocks for non-text responses (e.g. images).
56    /// When set, dispatch uses these instead of wrapping `text` in TextContent.
57    pub content_blocks: Option<Vec<ContentBlock>>,
58}
59
60impl ToolOutput {
61    pub fn simple(text: String) -> Self {
62        Self {
63            text,
64            original_tokens: 0,
65            saved_tokens: 0,
66            mode: None,
67            path: None,
68            changed: false,
69            shell_outcome: None,
70            content_blocks: None,
71        }
72    }
73
74    /// Compact one-line summary for headers_only response verbosity.
75    pub fn to_header_line(&self, tool_name: &str) -> String {
76        let path_str = self.path.as_deref().unwrap_or("—");
77        let mode_str = self.mode.as_deref().unwrap_or("—");
78        let sent = self.original_tokens.saturating_sub(self.saved_tokens);
79        let pct = if self.original_tokens > 0 {
80            (self.saved_tokens as f64 / self.original_tokens as f64 * 100.0) as u32
81        } else {
82            0
83        };
84        format!("[{tool_name}: {path_str}, mode={mode_str}, {sent} tok sent, -{pct}%]")
85    }
86
87    pub fn with_savings(text: String, original: usize, saved: usize) -> Self {
88        Self {
89            text,
90            original_tokens: original,
91            saved_tokens: saved,
92            mode: None,
93            path: None,
94            changed: false,
95            shell_outcome: None,
96            content_blocks: None,
97        }
98    }
99
100    /// Construct a ToolOutput for image/binary content blocks.
101    /// Bypasses all text processing in the dispatch pipeline.
102    pub fn image(blocks: Vec<ContentBlock>, path: String) -> Self {
103        Self {
104            text: String::new(),
105            original_tokens: 0,
106            saved_tokens: 0,
107            mode: Some("image".to_string()),
108            path: Some(path),
109            changed: false,
110            shell_outcome: None,
111            content_blocks: Some(blocks),
112        }
113    }
114}
115
116/// Trait for a self-contained MCP tool. Each tool provides its own schema
117/// definition and handler, eliminating the possibility of schema/handler drift.
118///
119/// This trait is the plugin interface for LcpTools: any implementation can be
120/// registered at runtime via `ToolRegistry::register()`. Future plugin system
121/// will load implementations from shared libraries or subprocess bridges.
122///
123/// Handlers are synchronous because all existing tool handlers are sync.
124/// The async boundary (cache locks, session reads) is handled by the dispatch
125/// layer before calling `handle`.
126pub trait McpTool: Send + Sync {
127    /// Tool name as registered in the MCP protocol (e.g. "ctx_tree").
128    fn name(&self) -> &'static str;
129
130    /// MCP tool definition including JSON schema. This replaces the
131    /// corresponding entry in `granular_tool_defs()`.
132    fn tool_def(&self) -> Tool;
133
134    /// Execute the tool. Args are the raw JSON-RPC arguments.
135    /// `ctx` provides access to resolved paths and project state.
136    fn handle(&self, args: &Map<String, Value>, ctx: &ToolContext)
137    -> Result<ToolOutput, ErrorData>;
138
139    /// Whether *this* invocation yields a machine-readable payload (e.g. JSON)
140    /// that must reach the client byte-exact and parseable. When `true`, the
141    /// dispatch pipeline suppresses every human-oriented decoration
142    /// (auto-context briefing, verify footer, hints, checkpoints, deprecation
143    /// notices) and terse compression for this call, returning the pure body.
144    /// Keyed on `args` because most tools emit machine-readable output only for
145    /// an opt-in format flag (e.g. `format=json`); defaults to `false` (#990).
146    fn produces_machine_readable(&self, _args: Option<&Map<String, Value>>) -> bool {
147        false
148    }
149}
150
151/// Context passed to tool handlers. Contains pre-resolved values that
152/// many tools need, avoiding repeated async lock acquisition inside
153/// handlers. Extended with shared server state for tools that need
154/// cache/session access.
155pub struct ToolContext {
156    pub project_root: String,
157    /// Session-scoped trusted roots (MCP `roots/list`, config `extra_roots`),
158    /// snapshotted from the session so sync handlers can honor them without an
159    /// async lock. Empty = single-root jail behaviour (#403).
160    pub extra_roots: Vec<String>,
161    pub minimal: bool,
162    /// Pre-resolved paths keyed by argument name (e.g. "path" -> "/abs/dir").
163    pub resolved_paths: std::collections::HashMap<String, String>,
164    /// CRP mode for compression-aware tools.
165    pub crp_mode: crate::tools::CrpMode,
166    /// Shared cache handle for tools that need read/write access.
167    pub cache: Option<crate::tools::SharedCache>,
168    /// Shared session handle for tools that need session access.
169    pub session: Option<std::sync::Arc<tokio::sync::RwLock<crate::core::session::SessionState>>>,
170    /// Tool call records for session-aware tools (e.g. ctx_session status).
171    pub tool_calls:
172        Option<std::sync::Arc<tokio::sync::RwLock<Vec<crate::core::protocol::ToolCallRecord>>>>,
173    /// Current agent identity for multi-agent tools.
174    pub agent_id: Option<std::sync::Arc<tokio::sync::RwLock<Option<String>>>>,
175    /// Active workflow run state.
176    pub workflow:
177        Option<std::sync::Arc<tokio::sync::RwLock<Option<crate::core::workflow::WorkflowRun>>>>,
178    /// Context ledger for handoff operations.
179    pub ledger:
180        Option<std::sync::Arc<tokio::sync::RwLock<crate::core::context_ledger::ContextLedger>>>,
181    /// Client name (cursor, claude, etc.).
182    pub client_name: Option<std::sync::Arc<tokio::sync::RwLock<String>>>,
183    /// Pipeline stats for metrics/proof tools.
184    pub pipeline_stats:
185        Option<std::sync::Arc<tokio::sync::RwLock<crate::core::pipeline::PipelineStats>>>,
186    /// Global call counter for context tools.
187    pub call_count: Option<std::sync::Arc<std::sync::atomic::AtomicUsize>>,
188    /// Autonomy state for search repeat detection.
189    pub autonomy: Option<std::sync::Arc<crate::tools::autonomy::AutonomyState>>,
190    /// Pre-computed context pressure snapshot for synchronous gate decisions.
191    pub pressure_snapshot: Option<crate::core::context_ledger::ContextPressure>,
192    /// Errors from path resolution (PathJail rejection, secret path, etc.).
193    /// Keyed by argument name (e.g. "path" -> "path escapes project root: ...").
194    pub path_errors: std::collections::HashMap<String, String>,
195    /// Shared in-memory BM25 index cache for semantic search.
196    pub bm25_cache: Option<crate::core::bm25_cache::SharedBm25Cache>,
197    /// MCP progress notification sender for long-running operations.
198    pub progress_sender: Option<crate::server::progress::SharedProgressSender>,
199}
200
201impl Default for ToolContext {
202    /// Minimal context: `project_root` empty, all shared-state handles `None`.
203    /// Single source for the one-shot CLI ctx (`cli::call_cmd::oneshot_ctx`) and
204    /// the `empty_ctx` test helper — adding a field no longer breaks either.
205    fn default() -> Self {
206        Self {
207            project_root: String::new(),
208            extra_roots: Vec::new(),
209            minimal: false,
210            resolved_paths: std::collections::HashMap::new(),
211            crp_mode: crate::tools::CrpMode::Off,
212            cache: None,
213            session: None,
214            tool_calls: None,
215            agent_id: None,
216            workflow: None,
217            ledger: None,
218            client_name: None,
219            pipeline_stats: None,
220            call_count: None,
221            autonomy: None,
222            pressure_snapshot: None,
223            path_errors: std::collections::HashMap::new(),
224            bm25_cache: None,
225            progress_sender: None,
226        }
227    }
228}
229
230impl ToolContext {
231    pub fn resolved_path(&self, arg: &str) -> Option<&str> {
232        self.resolved_paths.get(arg).map(String::as_str)
233    }
234
235    /// Returns the path resolution error for a given key, if any.
236    pub fn path_error(&self, key: &str) -> Option<&str> {
237        self.path_errors.get(key).map(String::as_str)
238    }
239
240    /// Sync path resolution using `project_root` + session `extra_roots`. Thin
241    /// wrapper over [`crate::core::path_resolve::resolve_tool_path_with_roots`]
242    /// for sync tool handlers.
243    pub fn resolve_path_sync(&self, path: &str) -> Result<String, String> {
244        crate::core::path_resolve::resolve_tool_path_with_roots(
245            Some(&self.project_root),
246            None,
247            path,
248            &self.extra_roots,
249        )
250    }
251
252    /// Default-deny write gate for the read-only tier (#475). Write-capable tool
253    /// handlers must call this with an already-resolved absolute path before
254    /// touching the filesystem; it errors if the path is inside a configured
255    /// `read_only_roots` subtree. A no-op (always `Ok`) when no read-only roots
256    /// are configured, so non-users pay nothing. Thin wrapper over the single
257    /// choke point [`crate::core::pathjail::enforce_writable`] — the low-level
258    /// atomic writers call the same function, so this is the ergonomic,
259    /// early-error layer, not the only line of defence.
260    pub fn ensure_writable(&self, resolved_path: &str) -> Result<(), String> {
261        crate::core::pathjail::enforce_writable(std::path::Path::new(resolved_path))
262    }
263}
264
265// ── Arg extraction helpers (mirror server/helpers.rs for standalone use) ──
266
267/// Extract a resolved path from context with differentiated error messages.
268/// Returns descriptive errors for: missing param, PathJail rejection, wrong type.
269pub fn require_resolved_path(
270    ctx: &ToolContext,
271    args: &Map<String, Value>,
272    key: &str,
273) -> Result<String, ErrorData> {
274    if let Some(path) = ctx.resolved_path(key) {
275        return Ok(path.to_string());
276    }
277    if let Some(err) = ctx.path_error(key) {
278        return Err(ErrorData::invalid_params(format!("{key}: {err}"), None));
279    }
280    if let Some(val) = args.get(key)
281        && !val.is_string()
282    {
283        let type_name = match val {
284            Value::Number(_) => "number",
285            Value::Bool(_) => "boolean",
286            Value::Array(_) => "array",
287            Value::Object(_) => "object",
288            Value::Null => "null",
289            Value::String(_) => unreachable!(),
290        };
291        return Err(ErrorData::invalid_params(
292            format!("{key} must be a string, got {type_name}"),
293            None,
294        ));
295    }
296    Err(ErrorData::invalid_params(
297        format!("{key} is required"),
298        None,
299    ))
300}
301
302pub fn get_str(args: &Map<String, Value>, key: &str) -> Option<String> {
303    args.get(key).and_then(|v| v.as_str()).map(String::from)
304}
305
306pub fn get_int(args: &Map<String, Value>, key: &str) -> Option<i64> {
307    args.get(key)
308        .and_then(|v| v.as_i64().or_else(|| v.as_str()?.parse().ok()))
309}
310
311/// Read a non-negative integer argument as `usize`.
312///
313/// Returns `None` for missing or negative values. This avoids the
314/// `negative_i64 as usize` wrap to `usize::MAX`, which previously let an agent
315/// trigger unbounded allocations (e.g. `top_k`, `limit`, `max_results`) → OOM.
316/// Callers should still apply a sensible upper cap on the result.
317pub fn get_usize(args: &Map<String, Value>, key: &str) -> Option<usize> {
318    get_int(args, key).and_then(|n| usize::try_from(n).ok())
319}
320
321pub fn get_bool(args: &Map<String, Value>, key: &str) -> Option<bool> {
322    args.get(key).and_then(serde_json::Value::as_bool)
323}
324
325pub fn get_f64(args: &Map<String, Value>, key: &str) -> Option<f64> {
326    args.get(key).and_then(serde_json::Value::as_f64)
327}
328
329pub fn get_str_array(args: &Map<String, Value>, key: &str) -> Option<Vec<String>> {
330    args.get(key).and_then(|v| v.as_array()).map(|arr| {
331        arr.iter()
332            .filter_map(|v| v.as_str().map(String::from))
333            .collect()
334    })
335}
336
337#[cfg(test)]
338mod tests {
339    use super::*;
340    use serde_json::json;
341
342    fn empty_ctx() -> ToolContext {
343        ToolContext::default()
344    }
345
346    #[test]
347    fn require_resolved_path_returns_resolved() {
348        let mut ctx = empty_ctx();
349        ctx.resolved_paths
350            .insert("path".to_string(), "/abs/file.rs".to_string());
351        let args: Map<String, Value> = Map::new();
352        let result = require_resolved_path(&ctx, &args, "path");
353        assert_eq!(result.unwrap(), "/abs/file.rs");
354    }
355
356    #[test]
357    fn require_resolved_path_surfaces_jail_error() {
358        let mut ctx = empty_ctx();
359        ctx.path_errors.insert(
360            "path".to_string(),
361            "path escapes project root /project".to_string(),
362        );
363        let args: Map<String, Value> = Map::new();
364        let result = require_resolved_path(&ctx, &args, "path");
365        assert!(result.is_err());
366        let err = result.unwrap_err();
367        let msg = format!("{err:?}");
368        assert!(msg.contains("escapes project root"), "got: {msg}");
369    }
370
371    #[test]
372    fn require_resolved_path_detects_non_string() {
373        let ctx = empty_ctx();
374        let mut args: Map<String, Value> = Map::new();
375        args.insert("path".to_string(), json!(42));
376        let result = require_resolved_path(&ctx, &args, "path");
377        assert!(result.is_err());
378        let err = result.unwrap_err();
379        let msg = format!("{err:?}");
380        assert!(msg.contains("must be a string, got number"), "got: {msg}");
381    }
382
383    #[test]
384    fn require_resolved_path_missing_param() {
385        let ctx = empty_ctx();
386        let args: Map<String, Value> = Map::new();
387        let result = require_resolved_path(&ctx, &args, "path");
388        assert!(result.is_err());
389        let err = result.unwrap_err();
390        let msg = format!("{err:?}");
391        assert!(msg.contains("path is required"), "got: {msg}");
392    }
393
394    #[test]
395    fn get_int_coerces_string_to_number() {
396        let mut args = Map::new();
397        args.insert("n".into(), json!("42"));
398        assert_eq!(super::get_int(&args, "n"), Some(42));
399    }
400
401    #[test]
402    fn get_int_native_number_still_works() {
403        let mut args = Map::new();
404        args.insert("n".into(), json!(7));
405        assert_eq!(super::get_int(&args, "n"), Some(7));
406    }
407
408    #[test]
409    fn get_int_invalid_string_returns_none() {
410        let mut args = Map::new();
411        args.insert("n".into(), json!("not_a_number"));
412        assert_eq!(super::get_int(&args, "n"), None);
413    }
414
415    #[test]
416    fn get_usize_coerces_string() {
417        let mut args = Map::new();
418        args.insert("n".into(), json!("100"));
419        assert_eq!(super::get_usize(&args, "n"), Some(100));
420    }
421
422    #[test]
423    fn get_usize_negative_string_returns_none() {
424        let mut args = Map::new();
425        args.insert("n".into(), json!("-5"));
426        assert_eq!(super::get_usize(&args, "n"), None);
427    }
428}
lean_ctx/server/tool_trait.rs

lean_ctx/server/
tool_trait.rs
