Struct Find 

pub struct Find {
    pub description_glob: ToolDescription,
    pub description_grep: ToolDescription,
    /* private fields */
}

Shared-state wrapper for file-search tool operations.

Holds configuration for both [glob] and [grep] searches. Fields that are not set via builder methods remain None, deferring to each tool’s internal default.

Fields

description_glob: ToolDescription

MCP Tool description for glob.

description_grep: ToolDescription

MCP Tool description for grep.

Implementations

impl Find

pub fn new() -> Self

Create a new Find with all options unset (tool defaults apply).

pub fn file_type(self, ft: impl Into<String>) -> Self

Restrict glob results to a filesystem kind ("file", "dir", "symlink").

pub const fn recursive(self, v: bool) -> Self

Search subdirectories recursively (default: true).

pub const fn max_results(self, n: u32) -> Self

Maximum number of glob entries to return.

pub const fn sort_by_mtime(self, v: bool) -> Self

Sort glob results by modification time, most recent first.

pub fn glob_format(self, f: impl Into<String>) -> Self

Output layout for glob results ("flat", "grouped", "tree").

pub fn name_glob(self, g: impl Into<String>) -> Self

Restrict grep to files whose names match this glob (e.g. "*.rs").

pub fn language(self, lang: impl Into<String>) -> Self

Restrict grep to files of a given language (e.g. "rust", "py").

pub const fn ignore_case(self, v: bool) -> Self

Case-insensitive matching.

pub const fn max_count(self, n: u32) -> Self

Maximum total number of grep matches across all files.

pub const fn context_before(self, n: u32) -> Self

Lines of context to include before each match.

pub const fn context_after(self, n: u32) -> Self

Lines of context to include after each match.

pub const fn hidden(self, v: bool) -> Self

Include hidden files / directories (names starting with .).

pub const fn gitignore(self, v: bool) -> Self

Respect .gitignore rules.

pub const fn timeout_ms(self, ms: u32) -> Self

Abort the search after this many milliseconds.

pub fn cwd(self, path: impl Into<PathBuf>) -> Self

Set the project root directory (used for path-validation guards).

pub fn allowlist( self, paths: impl IntoIterator<Item = impl Into<PathBuf>>, ) -> Self

Set the explicit path allowlist.

pub fn blocklist( self, paths: impl IntoIterator<Item = impl Into<PathBuf>>, ) -> Self

Set the explicit path blocklist.

pub fn add_allowlist_path(&mut self, path: PathBuf)

Add a path to the allowlist (for session-level persistence).

pub fn remove_allowlist_path(&mut self, path: &Path)

Remove a path from the allowlist (for AllowOnce cleanup).

If the path is not in the allowlist, this is a no-op.

pub const fn find_root(&self) -> &PathBuf

Get the project root path.

pub fn allowlist_ref(&self) -> Option<&[PathBuf]>

Get the allowlist (read-only reference).

pub fn blocklist_ref(&self) -> Option<&[PathBuf]>

Get the blocklist (read-only reference).

pub fn glob(&self, pattern: &str, path: &str) -> Result<GlobOutput, String>

Find filesystem entries matching a glob pattern.

See [glob] for details.

Errors

Returns an error when the search path does not exist, the pattern is invalid, or the operation times out.

pub fn glob_with( &self, pattern: &str, path: Option<String>, paths: Option<Vec<String>>, on_match: Option<Arc<GlobMatchCallback>>, ) -> Result<GlobOutput, String>

Like glob, but searches one or more targets in a single call (paths overrides path; each target is guard-resolved individually), optionally streaming matches live via on_match.

Each entry in path/paths may be a directory, a literal file, or a glob (with or without a directory prefix); the effective pattern and recursion are derived from its shape. Output paths are rebased to the CWD when they live under it (feature: relative-to-CWD resolution).

Errors

Returns an error when the search paths are missing, a pattern is invalid, or the operation times out.

pub fn glob_full( &self, pattern: &str, path: Option<String>, paths: Option<Vec<String>>, opts: GlobCallOptions, on_match: Option<Arc<GlobMatchCallback>>, ) -> Result<GlobOutput, String>

Like glob_with, with the schema-driven call options bundled in GlobCallOptions: optional file_type ("file", "dir", "symlink"), hidden and gitignore toggles, format ("flat", "grouped", "tree"), a sort_by_mtime toggle, an optional timeout_ms, and an optional max_results.

The effective result cap defaults to 200 (mirroring the reference tool) when neither this call’s max_results nor the builder’s is set, and the ceiling is fixed: a max_results above 200 is clamped down, so the caller can only lower the result set. A max_results of 0 is rejected.

hidden and gitignore default to true unless explicitly disabled (reference-tool behavior). sort_by_mtime defaults to true — the most recently modified files surface first. file_type filters results to one filesystem kind and is an extension over the reference tool.

Errors

Returns an error when a search path cannot be resolved, a pattern is invalid, file_type is unknown, max_results is zero, or the operation times out.

pub fn grep(&self, pattern: &str, path: &str) -> Result<GrepOutput, String>

Search file content for lines matching a regex pattern.

See [grep] for details.

Errors

Returns an error when the path cannot be resolved, the pattern is an invalid regex, or the operation times out.

pub fn grep_skipping( &self, pattern: &str, path: &str, skip: Option<u32>, ) -> Result<GrepOutput, String>

Like grep, but pages past the first file window with skip (files to skip before collecting results). Ignored for single-file scopes.

pub fn grep_with( &self, pattern: &str, path: Option<String>, paths: Option<Vec<String>>, skip: Option<u32>, line_range: Option<String>, ) -> Result<GrepOutput, String>

Search one or more targets in a single call, with optional pagination (skip) and a 1-based inclusive line_range ("start-end").

paths overrides path when present; each target is resolved and validated individually by the path guard, so the approval shown to the user is exactly the set of targets the search opens. line_range requires every target to be a single file.

Errors

Returns an error when a target cannot be resolved, no target is provided, the pattern is an invalid regex, or the operation times out.

pub fn grep_with_streaming( &self, pattern: &str, path: Option<String>, paths: Option<Vec<String>>, skip: Option<u32>, line_range: Option<String>, on_match: Option<Arc<GrepMatchCallback>>, ) -> Result<GrepOutput, String>

Like grep_with, optionally streaming each match live via on_match (formatted path:line, rebased for multi-target calls).

Trait Implementations

impl Default for Find

fn default() -> Self

Returns the “default value” for a type.