kodegen_tools_filesystem-0.2.3 has been yanked.

kodegen-tools-filesystem

Memory-efficient, blazing-fast MCP (Model Context Protocol) filesystem tools for AI code generation agents.

Overview

kodegen-tools-filesystem provides a comprehensive suite of 14 filesystem and search tools exposed via the Model Context Protocol (MCP). Built on top of ripgrep's powerful search capabilities, it offers high-performance file operations, directory management, and advanced code search functionality for AI agents.

Features

File Operations

Read Files: Single or batch file reading with offset/length support
Write Files: Create or append with intelligent chunking
Edit Files: Surgical text replacement with exact string matching
Move/Delete: Rename, move, and delete file operations
File Info: Retrieve comprehensive file metadata

Directory Management

List Directories: Recursive listing with configurable depth
Create Directories: Recursive directory creation
Delete Directories: Safe recursive removal

Advanced Search (Powered by ripgrep)

File Search: Find files by name pattern with glob support
Content Search: Full-text search inside files with regex/PCRE2
Streaming Results: Asynchronous search with pagination
Session Management: Concurrent searches with cancellation support

Search Features

Dual regex engines (Rust regex + PCRE2 fallback)
Case-sensitive, case-insensitive, and smart-case modes
Word and line boundary matching
Binary file handling (auto-detect, skip, or force text)
Multiline pattern support
Search inside compressed files (.gz, .zip, .bz2, .xz)
Sort by path, modification time, access time, or creation time
Context lines (before/after match)
Invert match (show non-matching results)

Installation

Prerequisites

Rust nightly toolchain (edition 2024)
Cargo

From Source

git clone https://github.com/cyrup-ai/kodegen-tools-filesystem
cd kodegen-tools-filesystem
cargo build --release

The compiled binary will be available at target/release/kodegen-filesystem.

Usage

Running the Server

# Run with default settings
cargo run --bin kodegen-filesystem

# Run with custom allowed directories
KODEGEN_ALLOWED_DIRS="/path/to/workspace:/another/path" cargo run --bin kodegen-filesystem

# Run the release build
./target/release/kodegen-filesystem

Configuration

The server respects the following environment variables:

Variable	Description	Default
`KODEGEN_ALLOWED_DIRS`	Colon-separated list of allowed directories	Empty (all paths allowed)
`KODEGEN_DENIED_DIRS`	Colon-separated list of denied directories	Empty (no paths denied)

Path Access Rules:

Denied directories are checked first (blacklist takes precedence)
If KODEGEN_ALLOWED_DIRS is set, only those paths are accessible
If both are empty, all filesystem paths are accessible

Available Tools

The server exposes 14 MCP tools:

Category	Tool	Description
File Ops	`fs_read_file`	Read file contents with offset/length support
	`fs_read_multiple_files`	Batch read multiple files
	`fs_write_file`	Write or append to files
	`fs_edit_block`	Replace text blocks surgically
	`fs_move_file`	Move or rename files
	`fs_delete_file`	Delete files
	`fs_get_file_info`	Get file metadata
Directory	`fs_create_directory`	Create directories recursively
	`fs_list_directory`	List directory contents with depth
	`fs_delete_directory`	Delete directories recursively
Search	`fs_start_search`	Start file or content search
	`fs_get_search_results`	Paginate search results
	`fs_stop_search`	Cancel active search
	`fs_list_searches`	List active search sessions

Examples

Running Examples

# Comprehensive demo of all 14 tools
cargo run --example filesystem_demo

# Search examples
cargo run --example direct_search_basics
cargo run --example direct_search_patterns
cargo run --example direct_search_files
cargo run --example direct_search_output
cargo run --example direct_search_advanced

Search Example

use kodegen_mcp_client::tools;
use serde_json::json;

// Start a content search
let response = client.call_tool(
    tools::START_SEARCH,
    json!({
        "path": "/path/to/search",
        "pattern": "TODO",
        "search_type": "content",
        "case_mode": "insensitive",
        "max_results": 100
    })
).await?;

let session_id = response.session_id;

// Get results
let results = client.call_tool(
    tools::get_search_results,
    json!({
        "session_id": session_id,
        "offset": 0,
        "length": 50
    })
).await?;

Development

Building

# Debug build
cargo build

# Release build
cargo build --release

Testing

# Run all tests
cargo test

# Run with output
cargo test -- --nocapture

Code Quality

# Format code
cargo fmt

# Run linter
cargo clippy

# Auto-fix clippy warnings
cargo clippy --fix

Architecture

Core Components

Tool Modules: Each tool (read_file, write_file, etc.) is a self-contained module
Search Manager: Stateful coordinator for concurrent search sessions
Ripgrep Integration: Full ripgrep implementation with dual regex engines
Path Validation: Security layer for filesystem access control
HTTP Server: MCP protocol server using kodegen_server_http

Search Architecture

The search system uses a session-based model:

start_search creates a background search task and returns a session ID
get_search_results retrieves paginated results
stop_search cancels the background task
Sessions auto-expire after inactivity

License

Licensed under either of:

Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
MIT License (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Built with ❤️ by KODEGEN.ᴀɪ

kodegen_tools_filesystem 0.2.3