Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/XxYouDeaDPunKxX/chatgpt-local-agent-mcp/llms.txt

Use this file to discover all available pages before exploring further.

The filesystem category covers 16 tools spanning four scopes (mcp:read, mcp:write, mcp:patch, mcp:delete) and five policy mode tiers (observe, diagnose, edit, destructive, and destructive again for patch and rollback). Read operations are gated by mcp:read and require only the observe mode, making them available in the most restricted server configurations. Write, patch, and delete operations require progressively broader permissions and create automatic backups when a workspace profile’s backup policy allows it. All tools resolve relative paths against a cwd parameter and respect workspace profile restrictions, including secret deny globs.
The workspace_info tool is categorized under workspace in the registry, but it requires the mcp:read scope and observe policy mode. It is documented here because it is the natural starting point when working with filesystem tools.

​
workspace_info

Required scope: mcp:read
Policy mode: observe
Risk tags: none Returns the list of workspace profiles configured on the server. Each profile entry describes its root path, the policy modes permitted within that profile, and whether backup is enabled. Use this tool to discover which directories are in scope and what operations are allowed before attempting any read or write actions. Parameters:
ParameterTypeRequiredDescription
(none)——This tool takes no input parameters.

​
stat

Required scope: mcp:read
Policy mode: observe
Risk tags: path-disclosure Returns metadata for a single local path: kind (file, directory, symlink, other, or missing), size in bytes, creation timestamp, and last-modified timestamp. If the path does not exist, returns exists: false with kind: "missing" rather than an error. Parameters:
ParameterTypeRequiredDescription
pathstring✅Path to inspect. Relative paths resolve against cwd.
cwdstring—Base directory for relative path resolution.

​
stat_many

Required scope: mcp:read
Policy mode: observe
Risk tags: path-disclosure Returns metadata for up to 200 paths in a single call. Each entry in the response matches the shape returned by stat. Paths are checked concurrently. Use this instead of calling stat in a loop when you need to inspect multiple paths at once. Parameters:
ParameterTypeRequiredDescription
pathsstring[]✅Array of 1–200 paths to inspect.
cwdstring—Base directory for relative path resolution.

​
list_dir

Required scope: mcp:read
Policy mode: observe
Risk tags: path-disclosure Lists the entries in a directory. Each entry includes name, absolute path, type, size, and last-modified timestamp. Entries that match workspace secret deny globs are silently omitted and counted in blockedEntries. Results are bounded by maxEntries (default 500, hard maximum 5,000); a truncated flag indicates when the listing was cut short. Parameters:
ParameterTypeRequiredDescription
pathstring✅Directory path to list.
cwdstring—Base directory for relative path resolution.
includeHiddenboolean—Include entries whose names start with .. Defaults to true.
maxEntriesinteger—Maximum entries to return (1–5000). Defaults to 500.

​
tree

Required scope: mcp:read
Policy mode: observe
Risk tags: path-disclosure Returns a bounded recursive directory tree rooted at path. Each entry includes its depth, absolute and relative path, kind, and size. By default, node_modules, .git, dist, data, coverage, and .next directories are excluded. Entries that match secret deny globs are silently omitted and counted in blockedEntries. A truncated flag indicates when maxEntries or maxDepth was reached before the full tree was traversed. Parameters:
ParameterTypeRequiredDescription
pathstring—Root directory to inspect. Defaults to ..
cwdstring—Base directory for relative path resolution.
maxDepthinteger—Maximum recursion depth (0–20). Defaults to 3.
maxEntriesinteger—Maximum entries to return (1–10000). Defaults to 1000.
includeHiddenboolean—Include entries whose names start with .. Defaults to false.
excludeDefaultsboolean—Apply the default exclusion list. Defaults to true.

​
read_file

Required scope: mcp:read
Policy mode: observe
Risk tags: secret-read Reads the full content of a single local file. The response includes the file content, encoding used, the absolute path, a sourceTrust classification (local_workspace_content or untrusted_external_content), and an instructionSafety note. Files larger than the output byte limit or larger than maxBytes are rejected with an error before any bytes are read. Parameters:
ParameterTypeRequiredDescription
pathstring✅File path to read.
cwdstring—Base directory for relative path resolution.
encoding"utf8" | "base64"—Output encoding. Defaults to "utf8".
maxBytesinteger—Reject files larger than this many bytes.

​
read_file_range

Required scope: mcp:read
Policy mode: observe
Risk tags: secret-read Reads a byte range from a file without loading the entire file into memory. Useful for inspecting large files by offset. The response includes the content slice, actual bytes read, the offset used, encoding, and source trust classification. Parameters:
ParameterTypeRequiredDescription
pathstring✅File path to read.
lengthinteger✅Maximum bytes to read (up to 10,000,000).
cwdstring—Base directory for relative path resolution.
offsetinteger—Byte offset to start reading from. Defaults to 0.
encoding"utf8" | "base64"—Output encoding. Defaults to "utf8".

​
read_many

Required scope: mcp:read
Policy mode: observe
Risk tags: secret-read Reads up to 50 files in a single call. Each file result includes its content, bytes read, total size, encoding, and source trust classification, or an error message if the file could not be read. A shared byte budget across all files (maxTotalBytes) prevents runaway output. Useful for batch-reading source files in a project. Parameters:
ParameterTypeRequiredDescription
pathsstring[]✅Array of 1–50 file paths to read.
cwdstring—Base directory for relative path resolution.
encoding"utf8" | "base64"—Output encoding. Defaults to "utf8".
maxBytesPerFileinteger—Per-file byte limit.
maxTotalBytesinteger—Total byte budget across all files (up to 10,000,000).

​
hash

Required scope: mcp:read
Policy mode: observe
Risk tags: content-fingerprint Computes a cryptographic hash of a file without returning its content. Useful for checking whether a file has changed, comparing a local copy against an expected checksum, or building a content digest without reading potentially sensitive data into the response. The default algorithm is SHA-256. Parameters:
ParameterTypeRequiredDescription
pathstring✅File to hash.
cwdstring—Base directory for relative path resolution.
algorithm"sha256" | "sha1" | "md5"—Hash algorithm. Defaults to "sha256".
maxBytesinteger—Reject files larger than this (up to 1,000,000,000). Defaults to 100,000,000.
Required scope: mcp:read
Policy mode: diagnose
Risk tags: content-discovery Performs bounded text search across all files under a directory. Supports plain-text and regex patterns. Each match result includes the file path, line number, and a preview of the matched line. Files matching workspace secret deny globs are silently skipped and counted in skippedSecretFiles. Safe regex validation rejects patterns with nested quantifiers or backreferences. The truncated flag is set when maxFiles or maxMatches is reached.
search requires diagnose policy mode rather than observe because it scans file content across potentially large directory trees, increasing the content-discovery surface area compared to a single file read.
Parameters:
ParameterTypeRequiredDescription
patternstring✅Text or regex pattern to search for.
pathstring—Root directory to search. Defaults to ..
cwdstring—Base directory for relative path resolution.
regexboolean—Treat pattern as a regular expression. Defaults to false.
maxFilesinteger—Maximum files to scan (1–10000). Defaults to 1000.
maxMatchesinteger—Maximum matches to return (1–2000). Defaults to 200.
includeHiddenboolean—Include hidden files and directories. Defaults to false.

​
write_file

Required scope: mcp:write
Policy mode: destructive
Risk tags: file-write Creates or replaces a local file. This is the preferred tool for whole-file writes — use it instead of shell redirection, Set-Content, Out-File, or heredoc writes. Writes are performed atomically via a temporary file and rename. Overwriting an existing file requires confirm: true. The default dryRun: true setting means the tool will report what it would do without writing anything — always pass dryRun: false with confirm: true to execute the write. When overwriting, a backup of the original file is created automatically if the workspace profile’s backup policy permits it. Backup IDs are returned in the response and can be used with rollback_backup. Parameters:
ParameterTypeRequiredDescription
pathstring✅File path to write.
contentstring✅Content to write.
cwdstring✅Required base directory for relative path resolution.
dryRunboolean—Simulate the write without executing. Defaults to true.
confirmboolean—Required when overwriting an existing file with dryRun: false.
encoding"utf8" | "base64"—Content encoding. Defaults to "utf8".
createParentsboolean—Create missing parent directories. Defaults to false.

​
mkdir

Required scope: mcp:write
Policy mode: edit
Risk tags: filesystem-mutation Creates a directory at the specified path. This is the preferred tool for directory creation instead of shell mkdir, md, or New-Item -ItemType Directory. The recursive flag (default true) creates any missing parent directories in the path. Unlike write, copy, and move, mkdir only requires edit policy mode rather than destructive. Parameters:
ParameterTypeRequiredDescription
pathstring✅Directory path to create.
cwdstring✅Required base directory for relative path resolution.
recursiveboolean—Create missing parent directories. Defaults to true.

​
copy

Required scope: mcp:write
Policy mode: destructive
Risk tags: file-write, overwrite Copies a file to a new location. This is the preferred tool for file copies instead of shell copy, cp, or Copy-Item. Directory copies are not yet supported. Copies are performed atomically. If the destination exists and overwrite: true is set, the existing destination file is backed up before being replaced. Requires confirm: true when dryRun: false. Parameters:
ParameterTypeRequiredDescription
fromstring✅Source file path.
tostring✅Destination file path.
cwdstring✅Required base directory for relative path resolution.
dryRunboolean—Simulate the copy without executing. Defaults to true.
confirmboolean—Required when executing with dryRun: false.
overwriteboolean—Allow overwriting an existing destination. Defaults to false.

​
move

Required scope: mcp:write
Policy mode: destructive
Risk tags: rename, overwrite Moves or renames a file. This is the preferred tool instead of shell move, mv, Rename-Item, or Move-Item. Directory moves are not yet supported. The source file is backed up before the rename. If overwrite: true is set and the destination exists, the destination is also backed up. Requires confirm: true when dryRun: false. Parameters:
ParameterTypeRequiredDescription
fromstring✅Source path.
tostring✅Destination path.
cwdstring✅Required base directory for relative path resolution.
dryRunboolean—Simulate the move without executing. Defaults to true.
confirmboolean—Required when executing with dryRun: false.
overwriteboolean—Allow overwriting an existing destination. Defaults to false.

​
delete

Required scope: mcp:delete
Policy mode: destructive
Risk tags: delete, irreversible Deletes a file. This is the preferred tool instead of shell Remove-Item, del, erase, or rm. Directory deletion is not yet supported. Before deletion, the file is backed up and the backup ID is returned in the response, providing a recovery path via rollback_backup. Requires confirm: true when dryRun: false.
delete requires the dedicated mcp:delete scope, separate from mcp:write. Grant this scope only when ChatGPT needs to remove files, not just modify them.
Parameters:
ParameterTypeRequiredDescription
pathstring✅Path to delete (files only).
cwdstring✅Required base directory for relative path resolution.
dryRunboolean—Simulate the deletion without executing. Defaults to true.
confirmboolean—Required when executing with dryRun: false.

​
apply_patch

Required scope: mcp:patch
Policy mode: destructive
Risk tags: patch, file-write Applies a unified diff patch to one or more files. This is the preferred tool for targeted edits instead of shell heredocs, Set-Content, or ad-hoc file rewrites when making changes that span multiple files or affect specific line ranges. The tool parses the patch to identify touched files, backs up each one, and then invokes git apply to apply the diff. A dryRun: true invocation runs git apply --check to validate the patch without writing anything.
apply_patch requires the mcp:patch scope, separate from mcp:write. Patch operations use git apply and require Git to be installed on PATH.
Parameters:
ParameterTypeRequiredDescription
patchstring✅Unified diff patch content.
cwdstring✅Required working directory for patch application.
dryRunboolean—Run git apply --check without writing. Defaults to true.
confirmboolean—Required when executing with dryRun: false.

​
rollback_backup

Required scope: mcp:write
Policy mode: destructive
Risk tags: rollback, file-write Restores a file from a backup created by a previous destructive operation (write_file, copy, move, delete, or apply_patch). The backup ID is returned in the response of whichever tool created the backup. By default, the file is restored to its original path. An optional destinationPath (absolute) allows restoring to a different location. Requires confirm: true when dryRun: false. Parameters:
ParameterTypeRequiredDescription
backupIdstring (UUID)✅Backup ID returned by a previous tool call.
dryRunboolean—Simulate the restore without writing. Defaults to true.
confirmboolean—Required when executing with dryRun: false.
destinationPathstring—Absolute restore destination. Defaults to the original path.
overwriteboolean—Allow overwriting an existing file at the destination. Defaults to false.

​
Notes on secret deny globs

Workspace profiles can define glob patterns under secretDenyGlobs to prevent ChatGPT from reading sensitive files. Any path that matches a secret deny glob is rejected or silently omitted depending on the tool:
  • stat, read_file, read_file_range, read_many, hash — return an error for matched paths
  • list_dir, tree — silently omit matched entries and increment blockedEntries
  • search — silently skip matched files and increment skippedSecretFiles
  • All write tools — reject destructive operations targeting matched paths
Common patterns to consider: **/.env, **/id_rsa, **/*.pem, **/*.key, **/secrets.*.

​
Notes on backup policy

Write, copy, move, delete, apply_patch, and rollback_backup all create file backups before mutating the filesystem, subject to the workspace profile’s backupPolicy setting. When backup is enabled, the backup ID is returned in the tool response and can be passed to rollback_backup to restore the previous state. When backup is skipped (for example because the workspace profile disables it), the response will still include a backupIds field but it will be empty.

Build docs developers (and LLMs) love

Get started for freeTalk to us