File System API

File System Server

doc_processing_std_tools.file_system

File System tools MCP server.

Provides tools for navigating, reading, writing, and editing files on the local filesystem. The container is the security boundary; path inputs are normalized and rejected only for embedded NUL bytes (sanitize_path is not containment — relative .. and absolute paths are allowed inside the sandbox). File reads are size-checked and output is truncated to protect the LLM context window.

apply_patch(path, patch)

Apply a unified diff (git diff format) to a file.

Parses headers (---, +++, @@) and applies the hunks to the target file.

Rejects patches if context lines don't match exactly (e.g., the file has drifted since the diff was generated). For safe single-string substitutions use edit_file; this tool is preferred for multi-line / structural edits where context lines are stable.

Parameters:

Name	Type	Description	Default
path	str	Path to the file to patch.	required
patch	str	Unified diff content to apply.	required

Returns:

Type	Description
str	Confirmation message.

copy_file(source, destination)

Copy a file, preserving metadata.

Parameters:

Name	Type	Description	Default
source	str	Path of the file to copy.	required
destination	str	Path for the copy.	required

Returns:

Type	Description
str	Confirmation message.

create_file(path, content, create_dirs=False)

Create a new file. Fails if the file already exists.

Parameters:

Name	Type	Description	Default
path	str	Path to the file to create.	required
content	str	Content to write.	required
create_dirs	bool	Whether to create parent directories if they don't exist.	False

Returns:

Type	Description
str	Confirmation message with the file path.

delete_file(path)

Delete a file.

Parameters:

Name	Type	Description	Default
path	str	Path to the file to delete.	required

Returns:

Type	Description
str	Confirmation message.

edit_file(path, old_string, new_string)

Replace exact text in a file (str_replace pattern).

Finds the exact old_string in the file and replaces it with new_string. The old_string must appear exactly once in the file.

Parameters:

Name	Type	Description	Default
path	str	Path to the file to edit.	required
old_string	str	The exact text to find (must appear exactly once).	required
new_string	str	The replacement text.	required

Returns:

Type	Description
str	Confirmation message.

get_directory_structure(path, max_depth=3, include_hidden=False)

Return a markdown-formatted directory tree.

Walks the directory recursively up to max_depth levels and formats the result as an indented tree using box-drawing characters.

Parameters:

Name	Type	Description	Default
path	str	Root directory path to list.	required
max_depth	int	Maximum depth of recursion (default 3).	3
include_hidden	bool	Whether to include hidden files/directories (names starting with '.').	False

Returns:

Type	Description
str	A markdown-formatted directory tree string.

get_file_metadata(path)

Return file metadata as a JSON string.

Parameters:

Name	Type	Description	Default
path	str	Path to the file or directory.	required

Returns:

Type	Description
str	JSON string with keys: path, size_bytes, size_human, modified,
str	created, is_file, is_dir, extension.

list_directory(path, include_hidden=False)

List files and directories with basic metadata.

Returns entries sorted with directories first, then files, alphabetically within each group.

Parameters:

Name	Type	Description	Default
path	str	Path to the directory to list.	required
include_hidden	bool	Whether to include hidden files/directories (names starting with '.').	False

Returns:

Type	Description
str	JSON list of entries, each with name, type ('file' or 'directory'),
str	and size (in bytes, for files).

move_file(source, destination)

Move or rename a file.

Parameters:

Name	Type	Description	Default
source	str	Current path of the file.	required
destination	str	New path for the file.	required

Returns:

Type	Description
str	Confirmation message.

read_file(path, offset=None, limit=None, encoding='utf-8')

Read file contents, optionally within a line range.

Parameters:

Name	Type	Description	Default
path	str	Path to the file to read.	required
offset	int | None	1-based starting line number (optional). Lines before this are skipped.	None
limit	int | None	Maximum number of lines to return from the offset (optional).	None
encoding	str	File encoding (default utf-8).	'utf-8'

Returns:

Type	Description
str	The file contents as a string (possibly truncated).

search_in_files(path, query, file_pattern='*', is_regex=False, max_results=50)

Search for text or regex across files in a directory.

Walks the directory and searches within each matching file for lines containing the query. For PDF files, checks for co-located .txt files (e.g., document.pdf.txt) that contain extracted text.

Parameters:

Name	Type	Description	Default
path	str	Root directory to search in.	required
query	str	Search string or regex pattern.	required
file_pattern	str	Glob pattern to filter files (default '*').	'*'
is_regex	bool	Whether the query is a regular expression.	False
max_results	int	Maximum number of matching lines to return (default 50).	50

Returns:

Type	Description
str	JSON string with a list of matches, each containing file, line,
str	and content.

write_file(path, content, create_dirs=False, encoding='utf-8')

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

Parameters:

Name	Type	Description	Default
path	str	Path to the file to write.	required
content	str	Content to write.	required
create_dirs	bool	Whether to create parent directories if they don't exist.	False
encoding	str	File encoding (default utf-8).	'utf-8'

Returns:

Type	Description
str	Confirmation message with the file path and bytes written.