File Tools

Benchmarked against: Anthropic — Text editor tool Tools: ubi_read_file, ubi_write_file, ubi_edit_file, ubi_list_directory, ubi_search_code Server: Local UBI MCP Security: Restricted to allowed directories

File tools provide agents with the ability to read, write, edit, and search files on the local filesystem. They are the MCP equivalent of Claude Code's built-in Read, Write, Edit, and Grep tools, but available to any agent connected to the Local UBI server.

---

Tools reference

ubi_read_file

Read file contents with line numbers, supporting pagination.

Parameters:

Parameter	Type	Required	Default	Description
path	string	Yes	—	Absolute file path
offset	number	No	0	Line number to start from (0-based)
limit	number	No	2000	Max lines to return

Example:

ubi_read_file(path="/Users/xy2024air15/Documents/SuperPortia/CLAUDE.md")

Response:

{
  "content": "  1| # SuperPortia — 小克 Boot Config\n  2| \n  3| ## Identity\n...",
  "total_lines": 45,
  "offset": 0,
  "limit": 2000
}

For large files, use pagination:

ubi_read_file(
    path="/path/to/large-file.py",
    offset=100,
    limit=50
)
# Returns lines 100-149

---

ubi_write_file

Write content to a file. Creates the file if it doesn't exist, or overwrites if it does.

Safety feature: If the file already exists, a .bak backup is automatically created before overwriting.

Parameters:

Parameter	Type	Required	Description
path	string	Yes	Absolute file path
content	string	Yes	Full file content to write

Example:

ubi_write_file(
    path="/Users/xy2024air15/Documents/SuperPortia/scripts/example.sh",
    content="#!/bin/bash\necho 'Hello from SuperPortia'\n"
)

Response:

{
  "success": true,
  "path": "/Users/xy2024air15/Documents/SuperPortia/scripts/example.sh",
  "backup": "/Users/xy2024air15/Documents/SuperPortia/scripts/example.sh.bak",
  "bytes_written": 42
}

---

ubi_edit_file

Exact string replacement in a file. Like Claude Code's Edit tool — find an exact string and replace it.

Parameters:

Parameter	Type	Required	Default	Description
path	string	Yes	—	Absolute file path
old_string	string	Yes	—	Text to find (must be exact match)
new_string	string	Yes	—	Replacement text
replace_all	boolean	No	false	Replace all occurrences (vs. unique match)

Example — single replacement:

ubi_edit_file(
    path="/path/to/config.py",
    old_string='DEFAULT_ENGINE = "groq"',
    new_string='DEFAULT_ENGINE = "gemini"'
)

Example — replace all occurrences:

ubi_edit_file(
    path="/path/to/code.py",
    old_string="old_function_name",
    new_string="new_function_name",
    replace_all=True
)

Response:

{
  "success": true,
  "replacements": 1,
  "path": "/path/to/config.py"
}

Error — non-unique match:

{
  "error": "old_string found 3 times in file. Use replace_all=True or provide a more specific string.",
  "occurrences": 3
}

---

ubi_list_directory

List directory contents, optionally as a recursive tree.

Parameters:

Parameter	Type	Required	Default	Description
path	string	Yes	—	Absolute directory path
recursive	boolean	No	false	Show tree structure
max_depth	number	No	3	Max depth for recursive listing

Example — flat listing:

ubi_list_directory(path="/Users/xy2024air15/Documents/SuperPortia/ub")

Example — recursive tree:

ubi_list_directory(
    path="/Users/xy2024air15/Documents/SuperPortia/docs-site/docs",
    recursive=True,
    max_depth=2
)

---

ubi_search_code

Search for patterns in code files using grep/ripgrep.

Parameters:

Parameter	Type	Required	Default	Description
pattern	string	Yes	—	Regex pattern to search for
path	string	No	First allowed dir	Directory to search in
file_glob	string	No	All files	File pattern filter (e.g., *.py, *.ts)
max_results	number	No	50	Max matching lines to return

Example:

ubi_search_code(
    pattern="ingest_fragment",
    path="/Users/xy2024air15/Documents/SuperPortia/ub",
    file_glob="*.py"
)

Response:

{
  "matches": [
    {
      "file": "/Users/.../ub/mcp_server.py",
      "line": 142,
      "content": "async def ingest_fragment(path: str, input_type: str = 'file'):"
    },
    {
      "file": "/Users/.../ub/worker.py",
      "line": 89,
      "content": "    result = await ingest_fragment(content, source='api')"
    }
  ],
  "total_matches": 2
}

---

Comparison with Claude Code built-in tools

When running in Claude Code CLI, agents have access to both UBI file tools and Claude Code's native tools:

Operation	UBI Tool	Claude Code Tool	Difference
Read file	ubi_read_file	Read	UBI returns JSON; Read returns formatted text
Write file	ubi_write_file	Write	UBI creates .bak backup automatically
Edit file	ubi_edit_file	Edit	Same exact-match replacement model
List dir	ubi_list_directory	Glob / Bash ls	UBI supports recursive tree
Search code	ubi_search_code	Grep	Similar capabilities, different output format

When to use which:

Context	Use
Interactive CLI session	Claude Code native tools (faster, tighter integration)
Dispatch worker execution	UBI tools (available via MCP, sandboxed)
Cross-agent automation	UBI tools (any agent can use via MCP)
File operations needing backup	UBI ubi_write_file (automatic .bak)

---

Security

All file tools enforce directory restrictions:

Rule	Enforcement
Allowed directories only	Operations outside configured dirs return error
No symlink traversal	Symlinks that escape allowed dirs are blocked
Automatic backup	ubi_write_file creates .bak before overwriting
Read-only by default	Write/edit require explicit allowed directory config

---

Related pages

Page	Relationship
MCP Tools Overview	Full tool catalog
Run Command	Shell commands for operations beyond file tools
Computer Use	Browser-based alternative
File Ingestion (MTAAA)	Processing files through classification pipeline