# 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

```bash
# 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

```bash
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:
```bash
uvx gia-file-tools
```

## Use in GIA Agent System

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

```python
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.
```
