tools.md

MCP Tool Reference

All tools require a valid Authorization: Bearer <secret> header. All path arguments are resolved and validated against the configured root directory before any I/O — symlinks are followed to their real path.

---

patch_apply

Apply a unified diff to an existing file, or create a new file from a /dev/null source header.

Input

Field	Type	Description
path	string	Absolute path to the target file
patch	string	Unified diff. May be wrapped in a markdown code fence (```diff … ```)

Behavior

• Strips markdown code fences before parsing.
• If the diff's source line is --- /dev/null, the file is created with the + lines as content (file must not already exist, or will be overwritten).
• Otherwise, reads the existing file and applies all hunks. If any hunk context does not match (file has drifted), returns PatchFailed and the file is not modified (atomic rename ensures no partial write).
• Returns an error in read-only mode.

Errors

Code	Condition
OutsideRoot	Path resolves outside the configured root
NotFound	File does not exist (non-/dev/null source)
PatchFailed	Hunk mismatch or malformed diff
ReadOnly	Server started with --read-only

---

append

Append content to the end of an existing file. Does not create the file if it is absent.

Input

Field	Type	Description
path	string	Absolute path to the target file
content	string	Content to append

Errors

Code	Condition
NotFound	File does not exist
OutsideRoot	Path outside root
ReadOnly	Read-only mode

---

write_file

Write content to a file, creating it if it does not exist or overwriting it entirely if it does. Parent directories are created automatically.

Input

Field	Type	Description
path	string	Absolute path to the file
content	string	Content to write

Errors

Code	Condition
OutsideRoot	Path outside root
PermissionDenied	OS-level permission denied
ReadOnly	Read-only mode

---

create_directory

Create a directory and any missing parent directories.

Input

Field	Type	Description
path	string	Absolute path to the directory to create

Errors

Code	Condition
OutsideRoot	Path outside root
ReadOnly	Read-only mode

---

move_file

Move or rename a file within the root. Both source and destination are independently validated.

Input

Field	Type	Description
source	string	Absolute path to the source file
destination	string	Absolute path to the destination

Errors

Code	Condition
OutsideRoot	Either path outside root. Source is not moved if destination fails.
NotFound	Source does not exist
ReadOnly	Read-only mode

---

shell_exec

Execute a whitelisted shell command. The command is invoked directly — no shell interpreter — so shell metacharacters in arguments are inert.

Allowed commands: grep, sed, awk, find, cat, head, tail, wc, sort, uniq, cut, tr, diff, file, stat, ls, du, rg

mkdir and mv are explicitly excluded from this list; use create_directory and move_file instead.

Input

Field	Type	Description
command	string	The command to run (must be in the whitelist)
args	string[]	Argument list. Path-like args (starting with / or containing ..) are validated against root before the process is spawned.

Output

exit_code: <N>
stdout:
<stdout text>
stderr:
<stderr text>

A non-zero exit code is returned as a success response (not an MCP error) — it is the caller's responsibility to inspect exit_code.

Errors

Code	Condition
CommandNotAllowed	Command not in whitelist. Message lists permitted commands.
OutsideRoot	A path-like argument resolves outside root. Process is not spawned.