gia-file-tools 0.1.2

MCP server exposing secure, sandboxed file operations (read, write, search, replace, tree)

GIA File Tools — MCP Server

A Model Context Protocol (MCP) server that exposes secure, sandboxed file operations to AI agents.

Tools Provided (10 total)

Tool	Description
read_file	Read the exact content of a text or code file
read_file_summarized	Read a large file from storage with context pruning to fit within token limits
write_file	Create a new file or completely overwrite an existing one (atomic write)
replace_text	Search-and-replace a block of text inside a file (supports fuzzy whitespace matching)
batch_replace	Replace multiple blocks of text in a file in one single operation
delete_file	Delete a single file
delete_directory	Delete a directory and all files within it
list_directory	List files and folders in a directory
search_files	Grep-like search across files for a string or regex pattern
get_file_structure	Recursive tree view of a directory structure

All paths are sandboxed to a root directory (set GIA_FILE_ROOT env var, defaults to cwd).

Local Development

# Install in dev mode
cd mcp/uvx
pip install -e .

# Run directly
gia-file-tools

# Test via uvx (from project root)
uvx --from ./mcp/uvx gia-file-tools

Publish to PyPI

cd mcp/uvx

# Build
pip install build
python -m build

# Upload (needs PyPI API token)
pip install twine
twine upload dist/*

After publishing, anyone can run:

uvx gia-file-tools

Use in GIA Agent System

The GenericMcp class (inheriting from ElectronAwareToolkit) is the native wrapper in the GIA backend.

from ai.functions.mcp import GenericMcp

# Connect to the published MCP server.
# The `conv_id` will automatically configure `GIA_FILE_ROOT` for a remote sandbox.
# If the user is connected via the Electron desktop app, the commands are automatically
# routed via WebSockets to execute locally on their own computer instead!
file_tools = GenericMcp(
    command="uvx",
    args='["gia-file-tools"]', 
    conv_id="abc-123-xyz",
    user=current_user
)

# All 10 tools are inherently registered and schema-aware.