# GIA File Tools — MCP Server

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

## Tools Provided

| Tool | Description |
|------|-------------|
| `read_file` | Read a file's content |
| `write_file` | Create or overwrite a file (atomic writes) |
| `replace_text` | Search-and-replace with fuzzy whitespace matching |
| `list_directory` | List files and folders |
| `search_files` | Grep-like search across files |
| `get_file_structure` | Recursive tree view |

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 (via GenericMcpTools)

```python
from ai.functions.mcp_generic import GenericMcpTools

# Connect to the published MCP server via uvx
file_tools = GenericMcpTools(
    command="uvx",
    args='["gia-file-tools"]',
    env='{"GIA_FILE_ROOT": "/path/to/sandbox"}'
)

# All 6 tools are now available to the agent
```

This works identically to how npx-based MCP servers are used:
```python
# npx example (Node.js)
GenericMcpTools(command="npx", args='["-y", "firecrawl-mcp"]', env='{"API_KEY": "..."}')

# uvx example (Python) — same pattern
GenericMcpTools(command="uvx", args='["gia-file-tools"]', env='{"GIA_FILE_ROOT": "/tmp/sandbox"}')
```
