Filesnormal access · Read only
directory_list
File System first: browse ONE known folder, directories first; never read file contents. Default compact pages contain up to 100 entries, including hidden files. Filter with entry_type/include_globs/exclude_globs; request detail=metadata for file sizes and modified times (directory/symlink size is null, never recursive). Follow next_cursor with the same path and optionally limit; other options are inherited. Cursors pin a bounded local snapshot for up to 120 seconds, with possible earlier cache eviction; later filesystem changes are not reflected. Check scan_complete, complete, skipped_entries, stop_reason and depth limits before claiming completeness or absence. A partial scan can have no more cached pages and still be incomplete. Use returned path strings verbatim, including khai-path: values for non-Unicode native names; name is display-only when name_lossy=true. Use directory_tree for a bounded project overview, file_find for descendant names, file_search for contents, and file_read/file_stat directly when the file is known. No shell listing or file_export is needed.
Inputs (14)
pathRequired- string · File or folder path. Absolute paths are preferred; relative paths start at the owner home folder. The current approved-root policy is always enforced. Reuse directory result path verbatim; khai-path: values preserve non-Unicode native names and undergo the same authorization checks. Do not reconstruct paths from lossy display names.
request_idConditional / optional- string · Optional correlation ID for this call.
offsetConditional / optional- integer · Legacy zero-based offset: performs a fresh scan and may skip/duplicate entries if the folder changes. Prefer cursor. Cannot be combined with cursor.
limitConditional / optional- integer · Maximum complete entries per page; default 100, capped by owner max_directory_entries and a 256 KiB / owner result-byte budget. May return fewer entries; follow next_cursor.
cursorConditional / optional- string · Opaque next_cursor from this tool. Reuse verbatim with the same path; options are inherited. Expires within 120 seconds or earlier on cache eviction/reconnect. On DIRECTORY_CURSOR_EXPIRED restart without cursor; do not merge snapshots.
detailConditional / optional- string · compact | metadata · compact (default): name/path/type and compatibility flags. metadata also returns file size in bytes and modified_at Unix seconds. Directory/symlink sizes are null.
entry_typeConditional / optional- string · all | file | directory | symlink | other · all by default. Return only the selected entry type.
include_hiddenConditional / optional- boolean · Default true. False excludes dot-prefixed names and Windows hidden-attribute entries. No implicit gitignore filtering.
include_globsConditional / optional- array · Optional case-sensitive globs matched against each native basename or root-relative path. Empty means all. No file contents are read.
exclude_globsConditional / optional- array · Explicit case-sensitive exclusions matched against basename or root-relative path. No default exclusions. In directory_tree a matching directory prunes its whole subtree.
sort_byConditional / optional- string · name | modified_at | size · Default name. Always directories first, then selected sort and native-name tie-break. Size/modified sorts require metadata I/O even with compact output. Null metadata sorts first in ascending order.
orderConditional / optional- string · asc | desc · Ascending by default. Descending reverses sorting within each group; directories still appear first.
max_scan_entriesConditional / optional- integer · Total directory entries examined across the snapshot, including filtered/skipped entries. Default 20000. An 8 MiB accounted snapshot memory limit also applies. Reaching a budget returns an explicitly incomplete subset, not an exact total.
max_time_msConditional / optional- integer · Cooperative scan deadline, default 2000 ms. Checked between filesystem operations; a blocked OS/network-drive operation cannot be interrupted. Sorting and serialization also take time.
Complete input schema
{
"type": "object",
"properties": {
"path": {
"type": "string",
"description": "File or folder path. Absolute paths are preferred; relative paths start at the owner home folder. The current approved-root policy is always enforced. Reuse directory result path verbatim; khai-path: values preserve non-Unicode native names and undergo the same authorization checks. Do not reconstruct paths from lossy display names.",
"minLength": 1
},
"request_id": {
"type": "string",
"description": "Optional correlation ID for this call.",
"minLength": 1
},
"offset": {
"type": "integer",
"minimum": 0,
"maximum": 1000000,
"description": "Legacy zero-based offset: performs a fresh scan and may skip/duplicate entries if the folder changes. Prefer cursor. Cannot be combined with cursor."
},
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 1000,
"description": "Maximum complete entries per page; default 100, capped by owner max_directory_entries and a 256 KiB / owner result-byte budget. May return fewer entries; follow next_cursor."
},
"cursor": {
"type": "string",
"minLength": 34,
"maxLength": 40,
"pattern": "^[0-9a-f]{32}:[0-9]{1,7}$",
"description": "Opaque next_cursor from this tool. Reuse verbatim with the same path; options are inherited. Expires within 120 seconds or earlier on cache eviction/reconnect. On DIRECTORY_CURSOR_EXPIRED restart without cursor; do not merge snapshots."
},
"detail": {
"type": "string",
"enum": [
"compact",
"metadata"
],
"description": "compact (default): name/path/type and compatibility flags. metadata also returns file size in bytes and modified_at Unix seconds. Directory/symlink sizes are null."
},
"entry_type": {
"type": "string",
"enum": [
"all",
"file",
"directory",
"symlink",
"other"
],
"description": "all by default. Return only the selected entry type."
},
"include_hidden": {
"type": "boolean",
"description": "Default true. False excludes dot-prefixed names and Windows hidden-attribute entries. No implicit gitignore filtering."
},
"include_globs": {
"type": "array",
"maxItems": 50,
"items": {
"type": "string",
"maxLength": 1024
},
"description": "Optional case-sensitive globs matched against each native basename or root-relative path. Empty means all. No file contents are read."
},
"exclude_globs": {
"type": "array",
"maxItems": 50,
"items": {
"type": "string",
"maxLength": 1024
},
"description": "Explicit case-sensitive exclusions matched against basename or root-relative path. No default exclusions. In directory_tree a matching directory prunes its whole subtree."
},
"sort_by": {
"type": "string",
"enum": [
"name",
"modified_at",
"size"
],
"description": "Default name. Always directories first, then selected sort and native-name tie-break. Size/modified sorts require metadata I/O even with compact output. Null metadata sorts first in ascending order."
},
"order": {
"type": "string",
"enum": [
"asc",
"desc"
],
"description": "Ascending by default. Descending reverses sorting within each group; directories still appear first."
},
"max_scan_entries": {
"type": "integer",
"minimum": 1,
"maximum": 100000,
"description": "Total directory entries examined across the snapshot, including filtered/skipped entries. Default 20000. An 8 MiB accounted snapshot memory limit also applies. Reaching a budget returns an explicitly incomplete subset, not an exact total."
},
"max_time_ms": {
"type": "integer",
"minimum": 1,
"maximum": 10000,
"description": "Cooperative scan deadline, default 2000 ms. Checked between filesystem operations; a blocked OS/network-drive operation cannot be interrupted. Sorting and serialization also take time."
}
},
"required": [
"path"
],
"additionalProperties": false,
"allOf": [
{
"not": {
"required": [
"cursor",
"offset"
]
}
}
]
}Filesnormal access · Read only
directory_tree
File System first: inspect a known project/folder structure across several levels in ONE bounded call. Returns flat depth-first entries with depth, parent_path and children_status so the AI can reconstruct a tree. Defaults: max_depth=2, compact detail, hidden entries included, no implicit exclusions, up to 100 entries per page. Directory nodes are retained as context even when entry_type/include_globs filter files; exclude_globs/include_hidden prune subtrees. Never follows descendant symlinks or reads file contents. Follow next_cursor with the same root; snapshot options are inherited and expire within 120 seconds. complete=false can mean more pages, depth limits, I/O errors or scan/time/memory limits: inspect each field before claiming the whole project was scanned. Use returned path verbatim, including khai-path: native path references. Prefer directory_list for one folder, file_find for a particular descendant filename and file_search for text. Do not crawl an entire drive when a narrower known folder answers the task.
Inputs (15)
pathRequired- string · File or folder path. Absolute paths are preferred; relative paths start at the owner home folder. The current approved-root policy is always enforced. Reuse directory result path verbatim; khai-path: values preserve non-Unicode native names and undergo the same authorization checks. Do not reconstruct paths from lossy display names.
request_idConditional / optional- string · Optional correlation ID for this call.
offsetConditional / optional- integer · Legacy zero-based offset: performs a fresh scan and may skip/duplicate entries if the folder changes. Prefer cursor. Cannot be combined with cursor.
limitConditional / optional- integer · Maximum complete entries per page; default 100, capped by owner max_directory_entries and a 256 KiB / owner result-byte budget. May return fewer entries; follow next_cursor.
cursorConditional / optional- string · Opaque next_cursor from this tool. Reuse verbatim with the same path; options are inherited. Expires within 120 seconds or earlier on cache eviction/reconnect. On DIRECTORY_CURSOR_EXPIRED restart without cursor; do not merge snapshots.
detailConditional / optional- string · compact | metadata · compact (default): name/path/type and compatibility flags. metadata also returns file size in bytes and modified_at Unix seconds. Directory/symlink sizes are null.
entry_typeConditional / optional- string · all | file | directory | symlink | other · Filter non-directory nodes by type. Directories are always retained for structure; exclude_globs explicitly prunes directories.
include_hiddenConditional / optional- boolean · Default true. False excludes dot-prefixed names and Windows hidden-attribute entries. No implicit gitignore filtering.
include_globsConditional / optional- array · Case-sensitive basename/root-relative globs for non-directory nodes. Directories are retained for ancestry. Use exclude_globs to prune whole subtrees.
exclude_globsConditional / optional- array · Explicit case-sensitive exclusions matched against basename or root-relative path. No default exclusions. In directory_tree a matching directory prunes its whole subtree.
sort_byConditional / optional- string · name | modified_at | size · Default name. Always directories first, then selected sort and native-name tie-break. Size/modified sorts require metadata I/O even with compact output. Null metadata sorts first in ascending order.
orderConditional / optional- string · asc | desc · Ascending by default. Descending reverses sorting within each group; directories still appear first.
max_scan_entriesConditional / optional- integer · Total directory entries examined across the snapshot, including filtered/skipped entries. Default 20000. An 8 MiB accounted snapshot memory limit also applies. Reaching a budget returns an explicitly incomplete subset, not an exact total.
max_time_msConditional / optional- integer · Cooperative scan deadline, default 2000 ms. Checked between filesystem operations; a blocked OS/network-drive operation cannot be interrupted. Sorting and serialization also take time.
max_depthConditional / optional- integer · Maximum entry depth relative to root, default 2. Root children have depth 1. Directories at the boundary get children_status=depth_limit; their contents are unknown, even if they might be empty.
Complete input schema
{
"type": "object",
"properties": {
"path": {
"type": "string",
"description": "File or folder path. Absolute paths are preferred; relative paths start at the owner home folder. The current approved-root policy is always enforced. Reuse directory result path verbatim; khai-path: values preserve non-Unicode native names and undergo the same authorization checks. Do not reconstruct paths from lossy display names.",
"minLength": 1
},
"request_id": {
"type": "string",
"description": "Optional correlation ID for this call.",
"minLength": 1
},
"offset": {
"type": "integer",
"minimum": 0,
"maximum": 1000000,
"description": "Legacy zero-based offset: performs a fresh scan and may skip/duplicate entries if the folder changes. Prefer cursor. Cannot be combined with cursor."
},
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 1000,
"description": "Maximum complete entries per page; default 100, capped by owner max_directory_entries and a 256 KiB / owner result-byte budget. May return fewer entries; follow next_cursor."
},
"cursor": {
"type": "string",
"minLength": 34,
"maxLength": 40,
"pattern": "^[0-9a-f]{32}:[0-9]{1,7}$",
"description": "Opaque next_cursor from this tool. Reuse verbatim with the same path; options are inherited. Expires within 120 seconds or earlier on cache eviction/reconnect. On DIRECTORY_CURSOR_EXPIRED restart without cursor; do not merge snapshots."
},
"detail": {
"type": "string",
"enum": [
"compact",
"metadata"
],
"description": "compact (default): name/path/type and compatibility flags. metadata also returns file size in bytes and modified_at Unix seconds. Directory/symlink sizes are null."
},
"entry_type": {
"type": "string",
"enum": [
"all",
"file",
"directory",
"symlink",
"other"
],
"description": "Filter non-directory nodes by type. Directories are always retained for structure; exclude_globs explicitly prunes directories."
},
"include_hidden": {
"type": "boolean",
"description": "Default true. False excludes dot-prefixed names and Windows hidden-attribute entries. No implicit gitignore filtering."
},
"include_globs": {
"type": "array",
"maxItems": 50,
"items": {
"type": "string",
"maxLength": 1024
},
"description": "Case-sensitive basename/root-relative globs for non-directory nodes. Directories are retained for ancestry. Use exclude_globs to prune whole subtrees."
},
"exclude_globs": {
"type": "array",
"maxItems": 50,
"items": {
"type": "string",
"maxLength": 1024
},
"description": "Explicit case-sensitive exclusions matched against basename or root-relative path. No default exclusions. In directory_tree a matching directory prunes its whole subtree."
},
"sort_by": {
"type": "string",
"enum": [
"name",
"modified_at",
"size"
],
"description": "Default name. Always directories first, then selected sort and native-name tie-break. Size/modified sorts require metadata I/O even with compact output. Null metadata sorts first in ascending order."
},
"order": {
"type": "string",
"enum": [
"asc",
"desc"
],
"description": "Ascending by default. Descending reverses sorting within each group; directories still appear first."
},
"max_scan_entries": {
"type": "integer",
"minimum": 1,
"maximum": 100000,
"description": "Total directory entries examined across the snapshot, including filtered/skipped entries. Default 20000. An 8 MiB accounted snapshot memory limit also applies. Reaching a budget returns an explicitly incomplete subset, not an exact total."
},
"max_time_ms": {
"type": "integer",
"minimum": 1,
"maximum": 10000,
"description": "Cooperative scan deadline, default 2000 ms. Checked between filesystem operations; a blocked OS/network-drive operation cannot be interrupted. Sorting and serialization also take time."
},
"max_depth": {
"type": "integer",
"minimum": 1,
"maximum": 8,
"description": "Maximum entry depth relative to root, default 2. Root children have depth 1. Directories at the boundary get children_status=depth_limit; their contents are unknown, even if they might be empty."
}
},
"required": [
"path"
],
"additionalProperties": false,
"allOf": [
{
"not": {
"required": [
"cursor",
"offset"
]
}
}
]
}Filesnormal access · Read only
file_stat
Inspect metadata for one file or folder without reading its contents. Returns size, modification time and file/directory/symlink flags; missing paths fail.
Inputs (2)
pathRequired- string · File or folder path. Absolute paths are preferred; relative paths start at the owner home folder. The current approved-root policy is always enforced. Reuse directory result path verbatim; khai-path: values preserve non-Unicode native names and undergo the same authorization checks. Do not reconstruct paths from lossy display names.
request_idConditional / optional- string · Optional correlation ID for this call.
Complete input schema
{
"type": "object",
"properties": {
"path": {
"type": "string",
"description": "File or folder path. Absolute paths are preferred; relative paths start at the owner home folder. The current approved-root policy is always enforced. Reuse directory result path verbatim; khai-path: values preserve non-Unicode native names and undergo the same authorization checks. Do not reconstruct paths from lossy display names.",
"minLength": 1
},
"request_id": {
"type": "string",
"description": "Optional correlation ID for this call.",
"minLength": 1
}
},
"required": [
"path"
],
"additionalProperties": false
}Filesnormal access · Read only
file_read
File System first: inspect one local file while working. Text streams in bounded pages, including files larger than the mutation limit; defaults return up to 10,000 lines and 256 KiB. Follow next_start_line AND next_start_column with unchanged options while truncated. For exact full contents keep reading all pages. source_encoding describes disk bytes; returned content is Unicode/UTF-8. Auto detects a Unicode BOM, otherwise assumes UTF-8; explicitly select legacy encodings when known. decode_errors=replace is only for inspecting damaged text; lossy previews must never be written back automatically. sha256 describes the entire RAW file only when sha256_complete is true; large reads may return null hash and total_lines. Inspect scan_limit_reached/decoded_entire_file before concluding completeness. Images/audio return native media and other binaries resources within the media size cap; this does not extract Office/PDF text. Use file_read_many for multiple known text paths, file_stat for metadata, file_search to locate text. Ordinary inspection, full reads and post-edit checks never imply file_export; export only when the user explicitly asks for a downloadable attachment.
Inputs (10)
pathRequired- string · File or folder path. Absolute paths are preferred; relative paths start at the owner home folder. The current approved-root policy is always enforced. Reuse directory result path verbatim; khai-path: values preserve non-Unicode native names and undergo the same authorization checks. Do not reconstruct paths from lossy display names.
encodingConditional / optional- string · auto | utf-8 | utf8 | utf-16le | utf-16be | windows-874 | tis-620 | windows-1252 | shift_jis | gb18030 | big5 · Auto detects a Unicode BOM, otherwise assumes UTF-8. For ambiguous legacy text specify its real encoding; there is no guessed legacy detection. Edits preserve the original BOM/encoding; encoding must match an existing BOM.
start_lineConditional / optional- integer · First text line, 1-based.
max_linesConditional / optional- integer · Maximum text lines. Follow next_start_line when truncated.
request_idConditional / optional- string · Optional correlation ID for this call.
decode_errorsConditional / optional- string · strict | replace · Strict rejects malformed bytes. Replace returns an inspection-only lossy preview with U+FFFD and decode_error_count; never use a lossy preview as replacement file content.
start_columnConditional / optional- integer · 1-based Unicode character column within start_line. Follow next_start_line AND next_start_column for giant-line continuation.
max_bytesConditional / optional- integer · Maximum returned UTF-8 text bytes, further capped by the engine output budget.
max_scan_bytesConditional / optional- integer · Raw-byte scan budget from file beginning. Reads also stop after 10 seconds.
compute_sha256Conditional / optional- boolean · Default true for files within the mutation size limit, false for larger files. True scans beyond the selected page to EOF within scan/time budgets. sha256 is null unless the entire raw file was scanned; never use null as an edit guard.
Complete input schema
{
"type": "object",
"properties": {
"path": {
"type": "string",
"description": "File or folder path. Absolute paths are preferred; relative paths start at the owner home folder. The current approved-root policy is always enforced. Reuse directory result path verbatim; khai-path: values preserve non-Unicode native names and undergo the same authorization checks. Do not reconstruct paths from lossy display names.",
"minLength": 1
},
"encoding": {
"type": "string",
"enum": [
"auto",
"utf-8",
"utf8",
"utf-16le",
"utf-16be",
"windows-874",
"tis-620",
"windows-1252",
"shift_jis",
"gb18030",
"big5"
],
"default": "auto",
"description": "Auto detects a Unicode BOM, otherwise assumes UTF-8. For ambiguous legacy text specify its real encoding; there is no guessed legacy detection. Edits preserve the original BOM/encoding; encoding must match an existing BOM."
},
"start_line": {
"type": "integer",
"description": "First text line, 1-based.",
"minimum": 1
},
"max_lines": {
"type": "integer",
"description": "Maximum text lines. Follow next_start_line when truncated.",
"minimum": 1,
"maximum": 10000
},
"request_id": {
"type": "string",
"description": "Optional correlation ID for this call.",
"minLength": 1
},
"decode_errors": {
"type": "string",
"enum": [
"strict",
"replace"
],
"default": "strict",
"description": "Strict rejects malformed bytes. Replace returns an inspection-only lossy preview with U+FFFD and decode_error_count; never use a lossy preview as replacement file content."
},
"start_column": {
"type": "integer",
"minimum": 1,
"description": "1-based Unicode character column within start_line. Follow next_start_line AND next_start_column for giant-line continuation."
},
"max_bytes": {
"type": "integer",
"minimum": 4,
"maximum": 1048576,
"default": 262144,
"description": "Maximum returned UTF-8 text bytes, further capped by the engine output budget."
},
"max_scan_bytes": {
"type": "integer",
"minimum": 8192,
"maximum": 2147483648,
"default": 268435456,
"description": "Raw-byte scan budget from file beginning. Reads also stop after 10 seconds."
},
"compute_sha256": {
"type": "boolean",
"description": "Default true for files within the mutation size limit, false for larger files. True scans beyond the selected page to EOF within scan/time budgets. sha256 is null unless the entire raw file was scanned; never use null as an edit guard."
}
},
"required": [
"path"
],
"additionalProperties": false
}Filesnormal access · Read only
file_read_many
Read 1–20 explicitly known local TEXT paths in one File System call. Each files[] entry has its own ok/result or error; one missing/denied/invalid file does not fail the others. Paths are checked independently against approved roots. No recursive discovery and no attachments. Defaults share 256 KiB total returned text, with 64 KiB per file; entries beyond the total budget return BATCH_OUTPUT_LIMIT. Use file_read for native media or per-file encoding/range differences and continue each truncated result using its next_start_line/next_start_column. Batch reads stop after a page and do not scan just to compute a hash; sha256 is present only when EOF was reached. Use file_find/file_search before this tool if paths are unknown.
Inputs (10)
encodingConditional / optional- string · auto | utf-8 | utf8 | utf-16le | utf-16be | windows-874 | tis-620 | windows-1252 | shift_jis | gb18030 | big5 · Auto detects a Unicode BOM, otherwise assumes UTF-8. For ambiguous legacy text specify its real encoding; there is no guessed legacy detection. Edits preserve the original BOM/encoding; encoding must match an existing BOM.
start_lineConditional / optional- integer · First text line, 1-based.
max_linesConditional / optional- integer · Maximum text lines. Follow next_start_line when truncated.
request_idConditional / optional- string · Optional correlation ID for this call.
decode_errorsConditional / optional- string · strict | replace · Strict rejects malformed bytes. Replace returns an inspection-only lossy preview with U+FFFD and decode_error_count; never use a lossy preview as replacement file content.
start_columnConditional / optional- integer · 1-based Unicode character column within start_line. Follow next_start_line AND next_start_column for giant-line continuation.
max_bytesConditional / optional- integer · Maximum returned UTF-8 text bytes, further capped by the engine output budget.
max_scan_bytesConditional / optional- integer · Raw-byte scan budget from file beginning. Reads also stop after 10 seconds.
pathsRequired- array · Explicit file paths, returned in this order including errors.
max_total_bytesConditional / optional- integer
Complete input schema
{
"type": "object",
"properties": {
"encoding": {
"type": "string",
"enum": [
"auto",
"utf-8",
"utf8",
"utf-16le",
"utf-16be",
"windows-874",
"tis-620",
"windows-1252",
"shift_jis",
"gb18030",
"big5"
],
"default": "auto",
"description": "Auto detects a Unicode BOM, otherwise assumes UTF-8. For ambiguous legacy text specify its real encoding; there is no guessed legacy detection. Edits preserve the original BOM/encoding; encoding must match an existing BOM."
},
"start_line": {
"type": "integer",
"description": "First text line, 1-based.",
"minimum": 1
},
"max_lines": {
"type": "integer",
"description": "Maximum text lines. Follow next_start_line when truncated.",
"minimum": 1,
"maximum": 10000
},
"request_id": {
"type": "string",
"description": "Optional correlation ID for this call.",
"minLength": 1
},
"decode_errors": {
"type": "string",
"enum": [
"strict",
"replace"
],
"default": "strict",
"description": "Strict rejects malformed bytes. Replace returns an inspection-only lossy preview with U+FFFD and decode_error_count; never use a lossy preview as replacement file content."
},
"start_column": {
"type": "integer",
"minimum": 1,
"description": "1-based Unicode character column within start_line. Follow next_start_line AND next_start_column for giant-line continuation."
},
"max_bytes": {
"type": "integer",
"minimum": 4,
"maximum": 1048576,
"default": 262144,
"description": "Maximum returned UTF-8 text bytes, further capped by the engine output budget."
},
"max_scan_bytes": {
"type": "integer",
"minimum": 8192,
"maximum": 2147483648,
"default": 268435456,
"description": "Raw-byte scan budget from file beginning. Reads also stop after 10 seconds."
},
"paths": {
"type": "array",
"minItems": 1,
"maxItems": 20,
"items": {
"type": "string",
"minLength": 1
},
"description": "Explicit file paths, returned in this order including errors."
},
"max_total_bytes": {
"type": "integer",
"minimum": 1024,
"maximum": 1048576,
"default": 262144
}
},
"required": [
"paths"
],
"additionalProperties": false
}Filesnormal access · Read only
file_find
File System first when a filename or relative path is known only partly. Search literal substrings in descendant relative paths, case-insensitive by default. Narrow path/exclude_dirs for large projects and follow next_offset with identical options. Read matches with file_read. Use file_search for text inside a file; this is not a shell command or regex engine. Scan/depth/skipped limits mean incomplete results, not proof of absence.
Inputs (8)
pathRequired- string · File or folder path. Absolute paths are preferred; relative paths start at the owner home folder. The current approved-root policy is always enforced. Reuse directory result path verbatim; khai-path: values preserve non-Unicode native names and undergo the same authorization checks. Do not reconstruct paths from lossy display names.
queryRequired- string · Nonempty filename/path substring.
max_depthConditional / optional- integer · Maximum recursive depth; defaults to 12.
request_idConditional / optional- string · Optional correlation ID for this call.
offsetConditional / optional- integer · Zero-based result offset, defaults to 0. Continue with next_offset using the same query/options. Directory changes can shift pages; restart if needed.
limitConditional / optional- integer · Maximum entries in this page, also bounded by the owner configuration.
case_sensitiveConditional / optional- boolean · Use exact letter case; defaults to case-insensitive literal substring matching, not regex.
exclude_dirsConditional / optional- array · Optional directory basenames to skip, e.g. ["node_modules", ".git", "target"]. No directories are excluded by default; symlinks are not followed.
Complete input schema
{
"type": "object",
"properties": {
"path": {
"type": "string",
"description": "File or folder path. Absolute paths are preferred; relative paths start at the owner home folder. The current approved-root policy is always enforced. Reuse directory result path verbatim; khai-path: values preserve non-Unicode native names and undergo the same authorization checks. Do not reconstruct paths from lossy display names.",
"minLength": 1
},
"query": {
"type": "string",
"description": "Nonempty filename/path substring.",
"minLength": 1
},
"max_depth": {
"type": "integer",
"description": "Maximum recursive depth; defaults to 12.",
"minimum": 0,
"maximum": 64
},
"request_id": {
"type": "string",
"description": "Optional correlation ID for this call.",
"minLength": 1
},
"offset": {
"type": "integer",
"minimum": 0,
"maximum": 1000000,
"description": "Zero-based result offset, defaults to 0. Continue with next_offset using the same query/options. Directory changes can shift pages; restart if needed."
},
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"description": "Maximum entries in this page, also bounded by the owner configuration."
},
"case_sensitive": {
"type": "boolean",
"default": false,
"description": "Use exact letter case; defaults to case-insensitive literal substring matching, not regex."
},
"exclude_dirs": {
"type": "array",
"maxItems": 50,
"uniqueItems": true,
"items": {
"type": "string",
"minLength": 1,
"pattern": "^[^/\\\\]+$"
},
"description": "Optional directory basenames to skip, e.g. [\"node_modules\", \".git\", \"target\"]. No directories are excluded by default; symlinks are not followed."
}
},
"required": [
"path",
"query"
],
"additionalProperties": false
}Filesnormal access · Read only
file_search
File System first for finding text in files/folders. Literal case-insensitive search by default; regex=true enables bounded Rust regex. Use include_globs/exclude_globs and exclude_dirs to narrow scope. Prefer result_mode=matches for individual-occurrence pagination with line, Unicode column and context; follow next_offset with identical options. Default result_mode=files preserves matching-file pagination and up to 10 line snippets. Files are decoded strictly using a Unicode BOM/UTF-8 or explicit legacy encoding. Results include whole-file raw-byte SHA-256 and source_encoding. Scans have per-file mutation-size limits, total byte/entry/depth limits and a 10-second deadline. Check truncated, skipped_files, scan_limit_reached and depth_limited_directories before saying nothing exists; use file_read for large/skipped files. Search is not PDF/Office extraction. Ordinary text search should not use shell or export.
Inputs (14)
pathRequired- string · File or folder path. Absolute paths are preferred; relative paths start at the owner home folder. The current approved-root policy is always enforced. Reuse directory result path verbatim; khai-path: values preserve non-Unicode native names and undergo the same authorization checks. Do not reconstruct paths from lossy display names.
queryRequired- string · Nonempty text substring.
max_depthConditional / optional- integer · Maximum recursive depth; defaults to 12.
request_idConditional / optional- string · Optional correlation ID for this call.
offsetConditional / optional- integer · Zero-based result offset, defaults to 0. Continue with next_offset using the same query/options. Directory changes can shift pages; restart if needed.
limitConditional / optional- integer · Maximum entries in this page, also bounded by the owner configuration.
case_sensitiveConditional / optional- boolean · Use exact letter case; defaults to case-insensitive literal substring matching, not regex.
exclude_dirsConditional / optional- array · Optional directory basenames to skip, e.g. ["node_modules", ".git", "target"]. No directories are excluded by default; symlinks are not followed.
context_linesConditional / optional- integer · Lines before and after each match. Returns up to 10 matching lines per file, each context line bounded to 500 characters; use file_read for exact untruncated text.
encodingConditional / optional- string · auto | utf-8 | utf8 | utf-16le | utf-16be | windows-874 | tis-620 | windows-1252 | shift_jis | gb18030 | big5 · Auto detects a Unicode BOM, otherwise assumes UTF-8. For ambiguous legacy text specify its real encoding; there is no guessed legacy detection. Edits preserve the original BOM/encoding; encoding must match an existing BOM.
regexConditional / optional- boolean · Rust regular expression syntax; no backreferences or lookaround. False treats query literally, including multiline text.
result_modeConditional / optional- string · files | matches · Use matches for fine pagination: offset/limit count individual occurrences, including multiple occurrences on one line. Files preserves legacy pagination by matching file with up to 10 line snippets.
include_globsConditional / optional- array · Case-sensitive glob patterns against slash-separated paths relative to the search root. Use **/*.rs or *.json. Excludes win; exclude_dirs prunes traversal.
exclude_globsConditional / optional- array · Case-sensitive glob patterns against slash-separated paths relative to the search root. Use **/*.rs or *.json. Excludes win; exclude_dirs prunes traversal.
Complete input schema
{
"type": "object",
"properties": {
"path": {
"type": "string",
"description": "File or folder path. Absolute paths are preferred; relative paths start at the owner home folder. The current approved-root policy is always enforced. Reuse directory result path verbatim; khai-path: values preserve non-Unicode native names and undergo the same authorization checks. Do not reconstruct paths from lossy display names.",
"minLength": 1
},
"query": {
"type": "string",
"description": "Nonempty text substring.",
"minLength": 1
},
"max_depth": {
"type": "integer",
"description": "Maximum recursive depth; defaults to 12.",
"minimum": 0,
"maximum": 64
},
"request_id": {
"type": "string",
"description": "Optional correlation ID for this call.",
"minLength": 1
},
"offset": {
"type": "integer",
"minimum": 0,
"maximum": 1000000,
"description": "Zero-based result offset, defaults to 0. Continue with next_offset using the same query/options. Directory changes can shift pages; restart if needed."
},
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"description": "Maximum entries in this page, also bounded by the owner configuration."
},
"case_sensitive": {
"type": "boolean",
"default": false,
"description": "Use exact letter case; defaults to case-insensitive literal substring matching, not regex."
},
"exclude_dirs": {
"type": "array",
"maxItems": 50,
"uniqueItems": true,
"items": {
"type": "string",
"minLength": 1,
"pattern": "^[^/\\\\]+$"
},
"description": "Optional directory basenames to skip, e.g. [\"node_modules\", \".git\", \"target\"]. No directories are excluded by default; symlinks are not followed."
},
"context_lines": {
"type": "integer",
"minimum": 0,
"maximum": 3,
"default": 1,
"description": "Lines before and after each match. Returns up to 10 matching lines per file, each context line bounded to 500 characters; use file_read for exact untruncated text."
},
"encoding": {
"type": "string",
"enum": [
"auto",
"utf-8",
"utf8",
"utf-16le",
"utf-16be",
"windows-874",
"tis-620",
"windows-1252",
"shift_jis",
"gb18030",
"big5"
],
"default": "auto",
"description": "Auto detects a Unicode BOM, otherwise assumes UTF-8. For ambiguous legacy text specify its real encoding; there is no guessed legacy detection. Edits preserve the original BOM/encoding; encoding must match an existing BOM."
},
"regex": {
"type": "boolean",
"default": false,
"description": "Rust regular expression syntax; no backreferences or lookaround. False treats query literally, including multiline text."
},
"result_mode": {
"type": "string",
"enum": [
"files",
"matches"
],
"default": "files",
"description": "Use matches for fine pagination: offset/limit count individual occurrences, including multiple occurrences on one line. Files preserves legacy pagination by matching file with up to 10 line snippets."
},
"include_globs": {
"type": "array",
"maxItems": 50,
"items": {
"type": "string",
"maxLength": 1024
},
"description": "Case-sensitive glob patterns against slash-separated paths relative to the search root. Use **/*.rs or *.json. Excludes win; exclude_dirs prunes traversal."
},
"exclude_globs": {
"type": "array",
"maxItems": 50,
"items": {
"type": "string",
"maxLength": 1024
},
"description": "Case-sensitive glob patterns against slash-separated paths relative to the search root. Use **/*.rs or *.json. Excludes win; exclude_dirs prunes traversal."
}
},
"required": [
"path",
"query"
],
"additionalProperties": false
}Filesnormal access · Read only
file_export
Deliver one existing local file to the user in the current conversation as an MCP embedded resource. Use ONLY when the user explicitly asks to receive, attach, send back, or download that file in the conversation; an earlier explicit delivery request in the same task also counts. Creating or saving a file, editing code, finishing a report, mentioning a path, or completing a task does not by itself request attachment. Do not call this tool for your own reading, analysis, preview, verification, backup, format conversion, or as an automatic final step. Use file_read to inspect contents and file_stat/directory_list to check files; otherwise leave the result at the requested local path and summarize the work. Exporting to PDF/CSV or saving into a local folder means creating/converting a local file, not attaching it here. This tool sends the complete bounded file contents to the MCP client with the detected MIME type, keeps the original on disk, and neither converts formats nor uploads to external storage. Attach only the requested files and do not repeat a successful attachment unless the user requests another copy.
Inputs (2)
pathRequired- string · Existing regular file the user explicitly requested to receive in this conversation. This selects the attachment, not an output or conversion destination. Absolute paths are preferred; relative paths start at the owner home folder. The current approved-root policy is always enforced. Reuse directory result path verbatim; khai-path: values preserve non-Unicode native names and undergo the same authorization checks. Do not reconstruct paths from lossy display names.
request_idConditional / optional- string · Optional correlation ID for this call.
Complete input schema
{
"type": "object",
"properties": {
"path": {
"type": "string",
"description": "Existing regular file the user explicitly requested to receive in this conversation. This selects the attachment, not an output or conversion destination. Absolute paths are preferred; relative paths start at the owner home folder. The current approved-root policy is always enforced. Reuse directory result path verbatim; khai-path: values preserve non-Unicode native names and undergo the same authorization checks. Do not reconstruct paths from lossy display names.",
"minLength": 1
},
"request_id": {
"type": "string",
"description": "Optional correlation ID for this call.",
"minLength": 1
}
},
"required": [
"path"
],
"additionalProperties": false
}Fileselevated access · Changes state
file_write
Atomically create one Unicode file or replace its full contents at a local path. Existing files require overwrite=true. For a small edit prefer file_replace_text after file_read. Parent creation is explicit. Verify contents with file_read or metadata with file_stat, then summarize the result and its local path. A request to create, save, or edit a file does not by itself request a conversation attachment; do not automatically call file_export after writing. Empty content creates/clears a file. Pass expected_sha256 for intentional replacement of known current bytes. Returns resulting size and sha256_after; dry_run describes proposed bytes without saving. Prefer edits over rewriting unrelated text. Supports explicit legacy encoding or automatic Unicode BOM/UTF-8. Existing encoding/BOM and untouched newline bytes are preserved; supplied text/newlines are exact. Unrepresentable characters or malformed existing bytes fail without writing. Results include a bounded text diff (also on dry_run), raw-byte hashes and source_encoding. A truncated diff is a preview, not a complete patch. Mutations retain the configured size limit; use file_read for large read-only inspection.
Inputs (8)
pathRequired- string · File or folder path. Absolute paths are preferred; relative paths start at the owner home folder. The current approved-root policy is always enforced. Reuse directory result path verbatim; khai-path: values preserve non-Unicode native names and undergo the same authorization checks. Do not reconstruct paths from lossy display names.
contentRequired- string · Complete UTF-8 contents, including intended newlines.
overwriteConditional / optional- boolean · Allow replacement of an existing file.
parentsConditional / optional- boolean · Create missing parent directories.
request_idConditional / optional- string · Optional correlation ID for this call.
dry_runConditional / optional- boolean · Validate the request without performing the mutation. Native dry runs validate input and permission; they do not prove that a UI target still exists.
expected_sha256Conditional / optional- string · Whole-file SHA-256 from file_read/file_search or the last mutation. If current bytes differ, nothing is written; read again before retrying.
encodingConditional / optional- string · auto | utf-8 | utf8 | utf-16le | utf-16be | windows-874 | tis-620 | windows-1252 | shift_jis | gb18030 | big5 · Auto detects a Unicode BOM, otherwise assumes UTF-8. For ambiguous legacy text specify its real encoding; there is no guessed legacy detection. Edits preserve the original BOM/encoding; encoding must match an existing BOM.
Complete input schema
{
"type": "object",
"properties": {
"path": {
"type": "string",
"description": "File or folder path. Absolute paths are preferred; relative paths start at the owner home folder. The current approved-root policy is always enforced. Reuse directory result path verbatim; khai-path: values preserve non-Unicode native names and undergo the same authorization checks. Do not reconstruct paths from lossy display names.",
"minLength": 1
},
"content": {
"type": "string",
"description": "Complete UTF-8 contents, including intended newlines."
},
"overwrite": {
"type": "boolean",
"description": "Allow replacement of an existing file.",
"default": false
},
"parents": {
"type": "boolean",
"description": "Create missing parent directories.",
"default": false
},
"request_id": {
"type": "string",
"description": "Optional correlation ID for this call.",
"minLength": 1
},
"dry_run": {
"type": "boolean",
"description": "Validate the request without performing the mutation. Native dry runs validate input and permission; they do not prove that a UI target still exists.",
"default": false
},
"expected_sha256": {
"type": "string",
"pattern": "^[a-fA-F0-9]{64}$",
"description": "Whole-file SHA-256 from file_read/file_search or the last mutation. If current bytes differ, nothing is written; read again before retrying."
},
"encoding": {
"type": "string",
"enum": [
"auto",
"utf-8",
"utf8",
"utf-16le",
"utf-16be",
"windows-874",
"tis-620",
"windows-1252",
"shift_jis",
"gb18030",
"big5"
],
"default": "auto",
"description": "Auto detects a Unicode BOM, otherwise assumes UTF-8. For ambiguous legacy text specify its real encoding; there is no guessed legacy detection. Edits preserve the original BOM/encoding; encoding must match an existing BOM."
}
},
"required": [
"path",
"content"
],
"additionalProperties": false
}Fileselevated access · Changes state
file_replace_text
Preferred File System tool for editing existing Unicode code, config and text after file_read. Send an exact expected/replacement pair OR up to 100 ordered related edits for ONE file. Empty replacement deletes matching text. Each expected must occur exactly expected_occurrences times (default 1); all edits are validated before one atomic write, so any mismatch leaves the original unchanged. Supply expected_sha256 from the read to reject stale whole-file contents. Preserves file permission bits. Returns per-edit first_line, replacement counts and before/after SHA-256 (dry_run hashes describe the proposed result). Verify affected lines with file_read; do not repeat a successful edit or automatically attach with file_export. Use file_write for a new file or intentional full replacement, and file_append only for adding at the end. Supports explicit legacy encoding or automatic Unicode BOM/UTF-8. Existing encoding/BOM and untouched newline bytes are preserved; supplied text/newlines are exact. Unrepresentable characters or malformed existing bytes fail without writing. Results include a bounded text diff (also on dry_run), raw-byte hashes and source_encoding. A truncated diff is a preview, not a complete patch. Mutations retain the configured size limit; use file_read for large read-only inspection.
Inputs (9)
pathRequired- string · File or folder path. Absolute paths are preferred; relative paths start at the owner home folder. The current approved-root policy is always enforced. Reuse directory result path verbatim; khai-path: values preserve non-Unicode native names and undergo the same authorization checks. Do not reconstruct paths from lossy display names.
expectedConditional / optional- string · Exact current text to replace.
replacementConditional / optional- string · Replacement text; empty deletes the matching text.
expected_occurrencesConditional / optional- integer · Exact number of non-overlapping matches required; defaults to 1.
request_idConditional / optional- string · Optional correlation ID for this call.
dry_runConditional / optional- boolean · Validate the request without performing the mutation. Native dry runs validate input and permission; they do not prove that a UI target still exists.
expected_sha256Conditional / optional- string · Whole-file SHA-256 from file_read/file_search or the last mutation. If current bytes differ, nothing is written; read again before retrying.
editsConditional / optional- array · Ordered related edits in this single file. Each precondition is checked against the preceding edit result. All must match before any write; a failed edit changes nothing. Use this OR the top-level expected/replacement pair.
encodingConditional / optional- string · auto | utf-8 | utf8 | utf-16le | utf-16be | windows-874 | tis-620 | windows-1252 | shift_jis | gb18030 | big5 · Auto detects a Unicode BOM, otherwise assumes UTF-8. For ambiguous legacy text specify its real encoding; there is no guessed legacy detection. Edits preserve the original BOM/encoding; encoding must match an existing BOM.
Complete input schema
{
"type": "object",
"properties": {
"path": {
"type": "string",
"description": "File or folder path. Absolute paths are preferred; relative paths start at the owner home folder. The current approved-root policy is always enforced. Reuse directory result path verbatim; khai-path: values preserve non-Unicode native names and undergo the same authorization checks. Do not reconstruct paths from lossy display names.",
"minLength": 1
},
"expected": {
"type": "string",
"description": "Exact current text to replace.",
"minLength": 1
},
"replacement": {
"type": "string",
"description": "Replacement text; empty deletes the matching text."
},
"expected_occurrences": {
"type": "integer",
"description": "Exact number of non-overlapping matches required; defaults to 1.",
"minimum": 1,
"maximum": 1000
},
"request_id": {
"type": "string",
"description": "Optional correlation ID for this call.",
"minLength": 1
},
"dry_run": {
"type": "boolean",
"description": "Validate the request without performing the mutation. Native dry runs validate input and permission; they do not prove that a UI target still exists.",
"default": false
},
"expected_sha256": {
"type": "string",
"pattern": "^[a-fA-F0-9]{64}$",
"description": "Whole-file SHA-256 from file_read/file_search or the last mutation. If current bytes differ, nothing is written; read again before retrying."
},
"edits": {
"type": "array",
"minItems": 1,
"maxItems": 100,
"description": "Ordered related edits in this single file. Each precondition is checked against the preceding edit result. All must match before any write; a failed edit changes nothing. Use this OR the top-level expected/replacement pair.",
"items": {
"type": "object",
"properties": {
"expected": {
"type": "string",
"description": "Exact current text to replace.",
"minLength": 1
},
"replacement": {
"type": "string",
"description": "Replacement text; empty deletes the matching text."
},
"expected_occurrences": {
"type": "integer",
"description": "Exact number of non-overlapping matches required; defaults to 1.",
"minimum": 1,
"maximum": 1000
}
},
"required": [
"expected",
"replacement"
],
"additionalProperties": false
}
},
"encoding": {
"type": "string",
"enum": [
"auto",
"utf-8",
"utf8",
"utf-16le",
"utf-16be",
"windows-874",
"tis-620",
"windows-1252",
"shift_jis",
"gb18030",
"big5"
],
"default": "auto",
"description": "Auto detects a Unicode BOM, otherwise assumes UTF-8. For ambiguous legacy text specify its real encoding; there is no guessed legacy detection. Edits preserve the original BOM/encoding; encoding must match an existing BOM."
}
},
"required": [
"path"
],
"additionalProperties": false,
"oneOf": [
{
"required": [
"expected",
"replacement"
],
"not": {
"required": [
"edits"
]
}
},
{
"required": [
"edits"
],
"not": {
"anyOf": [
{
"required": [
"expected"
]
},
{
"required": [
"replacement"
]
},
{
"required": [
"expected_occurrences"
]
}
]
}
}
]
}Fileselevated access · Changes state
file_edit_json
File System first for structured edits to an existing JSON file. Apply 1–100 ordered set/remove/test operations using RFC 6901 pointers (empty path is the root, ~0 means ~, ~1 means /). Set creates/replaces an object key whose parent exists, replaces an existing array index, or appends with /-. Remove requires an existing key/index and cannot remove the root. Test compares JSON values and aborts the entire batch on mismatch. Missing parent containers are never guessed. Invalid JSON, encoding, a failed test or stale expected_sha256 writes nothing. All edits validate before a single atomic replacement; dry_run returns the projected diff/hashes without writing. Preserves encoding/BOM and detected indentation/newline convention, but JSON serialization may reorder keys or normalize numeric spelling. No comments/JSONC support. Keep ordinary JSON work here instead of shell. Export only for an explicitly requested attachment.
Inputs (6)
pathRequired- string · File or folder path. Absolute paths are preferred; relative paths start at the owner home folder. The current approved-root policy is always enforced. Reuse directory result path verbatim; khai-path: values preserve non-Unicode native names and undergo the same authorization checks. Do not reconstruct paths from lossy display names.
encodingConditional / optional- string · auto | utf-8 | utf8 | utf-16le | utf-16be | windows-874 | tis-620 | windows-1252 | shift_jis | gb18030 | big5 · Auto detects a Unicode BOM, otherwise assumes UTF-8. For ambiguous legacy text specify its real encoding; there is no guessed legacy detection. Edits preserve the original BOM/encoding; encoding must match an existing BOM.
expected_sha256Conditional / optional- string · Whole-file SHA-256 from file_read/file_search or the last mutation. If current bytes differ, nothing is written; read again before retrying.
dry_runConditional / optional- boolean · Validate the request without performing the mutation. Native dry runs validate input and permission; they do not prove that a UI target still exists.
request_idConditional / optional- string · Optional correlation ID for this call.
editsRequired- array
Complete input schema
{
"type": "object",
"properties": {
"path": {
"type": "string",
"description": "File or folder path. Absolute paths are preferred; relative paths start at the owner home folder. The current approved-root policy is always enforced. Reuse directory result path verbatim; khai-path: values preserve non-Unicode native names and undergo the same authorization checks. Do not reconstruct paths from lossy display names.",
"minLength": 1
},
"encoding": {
"type": "string",
"enum": [
"auto",
"utf-8",
"utf8",
"utf-16le",
"utf-16be",
"windows-874",
"tis-620",
"windows-1252",
"shift_jis",
"gb18030",
"big5"
],
"default": "auto",
"description": "Auto detects a Unicode BOM, otherwise assumes UTF-8. For ambiguous legacy text specify its real encoding; there is no guessed legacy detection. Edits preserve the original BOM/encoding; encoding must match an existing BOM."
},
"expected_sha256": {
"type": "string",
"pattern": "^[a-fA-F0-9]{64}$",
"description": "Whole-file SHA-256 from file_read/file_search or the last mutation. If current bytes differ, nothing is written; read again before retrying."
},
"dry_run": {
"type": "boolean",
"description": "Validate the request without performing the mutation. Native dry runs validate input and permission; they do not prove that a UI target still exists.",
"default": false
},
"request_id": {
"type": "string",
"description": "Optional correlation ID for this call.",
"minLength": 1
},
"edits": {
"type": "array",
"minItems": 1,
"maxItems": 100,
"items": {
"type": "object",
"properties": {
"op": {
"type": "string",
"enum": [
"set",
"remove",
"test"
]
},
"path": {
"type": "string"
},
"value": {}
},
"required": [
"op",
"path"
],
"additionalProperties": false
}
}
},
"required": [
"path",
"edits"
],
"additionalProperties": false
}Fileselevated access · Changes state
file_append
Append text to a file, creating it if absent. Include your own newlines. Repeating a successful call appends twice; inspect current contents with file_read before retrying. Parent-directory creation is explicit. Verify the appended contents with file_read; completing an append is not a request to attach the file with file_export. Appends use one atomic replacement, preserve file permission bits and return resulting size/sha256_after. Optional expected_sha256 rejects a stale source. Empty content is allowed. Supports explicit legacy encoding or automatic Unicode BOM/UTF-8. Existing encoding/BOM and untouched newline bytes are preserved; supplied text/newlines are exact. Unrepresentable characters or malformed existing bytes fail without writing. Results include a bounded text diff (also on dry_run), raw-byte hashes and source_encoding. A truncated diff is a preview, not a complete patch. Mutations retain the configured size limit; use file_read for large read-only inspection.
Inputs (7)
pathRequired- string · File or folder path. Absolute paths are preferred; relative paths start at the owner home folder. The current approved-root policy is always enforced. Reuse directory result path verbatim; khai-path: values preserve non-Unicode native names and undergo the same authorization checks. Do not reconstruct paths from lossy display names.
contentRequired- string · Exact text to append.
parentsConditional / optional- boolean · Create missing parent directories.
request_idConditional / optional- string · Optional correlation ID for this call.
dry_runConditional / optional- boolean · Validate the request without performing the mutation. Native dry runs validate input and permission; they do not prove that a UI target still exists.
expected_sha256Conditional / optional- string · Whole-file SHA-256 from file_read/file_search or the last mutation. If current bytes differ, nothing is written; read again before retrying.
encodingConditional / optional- string · auto | utf-8 | utf8 | utf-16le | utf-16be | windows-874 | tis-620 | windows-1252 | shift_jis | gb18030 | big5 · Auto detects a Unicode BOM, otherwise assumes UTF-8. For ambiguous legacy text specify its real encoding; there is no guessed legacy detection. Edits preserve the original BOM/encoding; encoding must match an existing BOM.
Complete input schema
{
"type": "object",
"properties": {
"path": {
"type": "string",
"description": "File or folder path. Absolute paths are preferred; relative paths start at the owner home folder. The current approved-root policy is always enforced. Reuse directory result path verbatim; khai-path: values preserve non-Unicode native names and undergo the same authorization checks. Do not reconstruct paths from lossy display names.",
"minLength": 1
},
"content": {
"type": "string",
"description": "Exact text to append."
},
"parents": {
"type": "boolean",
"description": "Create missing parent directories.",
"default": false
},
"request_id": {
"type": "string",
"description": "Optional correlation ID for this call.",
"minLength": 1
},
"dry_run": {
"type": "boolean",
"description": "Validate the request without performing the mutation. Native dry runs validate input and permission; they do not prove that a UI target still exists.",
"default": false
},
"expected_sha256": {
"type": "string",
"pattern": "^[a-fA-F0-9]{64}$",
"description": "Whole-file SHA-256 from file_read/file_search or the last mutation. If current bytes differ, nothing is written; read again before retrying."
},
"encoding": {
"type": "string",
"enum": [
"auto",
"utf-8",
"utf8",
"utf-16le",
"utf-16be",
"windows-874",
"tis-620",
"windows-1252",
"shift_jis",
"gb18030",
"big5"
],
"default": "auto",
"description": "Auto detects a Unicode BOM, otherwise assumes UTF-8. For ambiguous legacy text specify its real encoding; there is no guessed legacy detection. Edits preserve the original BOM/encoding; encoding must match an existing BOM."
}
},
"required": [
"path",
"content"
],
"additionalProperties": false
}Fileselevated access · Changes state
directory_create
Create one directory. Set parents=true to create missing ancestors and exist_ok=true to accept an existing directory. Never replaces a file.
Inputs (5)
pathRequired- string · File or folder path. Absolute paths are preferred; relative paths start at the owner home folder. The current approved-root policy is always enforced. Reuse directory result path verbatim; khai-path: values preserve non-Unicode native names and undergo the same authorization checks. Do not reconstruct paths from lossy display names.
parentsConditional / optional- boolean · Create missing ancestor directories.
exist_okConditional / optional- boolean · Accept an existing directory.
request_idConditional / optional- string · Optional correlation ID for this call.
dry_runConditional / optional- boolean · Validate the request without performing the mutation. Native dry runs validate input and permission; they do not prove that a UI target still exists.
Complete input schema
{
"type": "object",
"properties": {
"path": {
"type": "string",
"description": "File or folder path. Absolute paths are preferred; relative paths start at the owner home folder. The current approved-root policy is always enforced. Reuse directory result path verbatim; khai-path: values preserve non-Unicode native names and undergo the same authorization checks. Do not reconstruct paths from lossy display names.",
"minLength": 1
},
"parents": {
"type": "boolean",
"description": "Create missing ancestor directories.",
"default": false
},
"exist_ok": {
"type": "boolean",
"description": "Accept an existing directory.",
"default": false
},
"request_id": {
"type": "string",
"description": "Optional correlation ID for this call.",
"minLength": 1
},
"dry_run": {
"type": "boolean",
"description": "Validate the request without performing the mutation. Native dry runs validate input and permission; they do not prove that a UI target still exists.",
"default": false
}
},
"required": [
"path"
],
"additionalProperties": false
}Fileselevated access · Changes state
file_copy
Copy a file or folder to a new destination through the shared path policy. Existing destinations require overwrite=true. The source stays in place. Rejects symlink mutation and copying a folder into itself.
Inputs (6)
pathRequired- string · File or folder path. Absolute paths are preferred; relative paths start at the owner home folder. The current approved-root policy is always enforced. Reuse directory result path verbatim; khai-path: values preserve non-Unicode native names and undergo the same authorization checks. Do not reconstruct paths from lossy display names.
destinationRequired- string · Full destination path, including the final name.
overwriteConditional / optional- boolean · Allow replacing the destination.
parentsConditional / optional- boolean · Create missing destination parents.
request_idConditional / optional- string · Optional correlation ID for this call.
dry_runConditional / optional- boolean · Validate the request without performing the mutation. Native dry runs validate input and permission; they do not prove that a UI target still exists.
Complete input schema
{
"type": "object",
"properties": {
"path": {
"type": "string",
"description": "File or folder path. Absolute paths are preferred; relative paths start at the owner home folder. The current approved-root policy is always enforced. Reuse directory result path verbatim; khai-path: values preserve non-Unicode native names and undergo the same authorization checks. Do not reconstruct paths from lossy display names.",
"minLength": 1
},
"destination": {
"type": "string",
"description": "Full destination path, including the final name.",
"minLength": 1
},
"overwrite": {
"type": "boolean",
"description": "Allow replacing the destination.",
"default": false
},
"parents": {
"type": "boolean",
"description": "Create missing destination parents.",
"default": false
},
"request_id": {
"type": "string",
"description": "Optional correlation ID for this call.",
"minLength": 1
},
"dry_run": {
"type": "boolean",
"description": "Validate the request without performing the mutation. Native dry runs validate input and permission; they do not prove that a UI target still exists.",
"default": false
}
},
"required": [
"path",
"destination"
],
"additionalProperties": false
}Fileselevated access · Changes state
file_move
Move or rename one file/folder. destination includes the new final name; use this tool for renaming too. Existing destinations require overwrite=true. The source is removed after a successful move; inspect both paths before retrying.
Inputs (6)
pathRequired- string · File or folder path. Absolute paths are preferred; relative paths start at the owner home folder. The current approved-root policy is always enforced. Reuse directory result path verbatim; khai-path: values preserve non-Unicode native names and undergo the same authorization checks. Do not reconstruct paths from lossy display names.
destinationRequired- string · Full new path, including the final name.
overwriteConditional / optional- boolean · Allow replacing the destination.
parentsConditional / optional- boolean · Create missing destination parents.
request_idConditional / optional- string · Optional correlation ID for this call.
dry_runConditional / optional- boolean · Validate the request without performing the mutation. Native dry runs validate input and permission; they do not prove that a UI target still exists.
Complete input schema
{
"type": "object",
"properties": {
"path": {
"type": "string",
"description": "File or folder path. Absolute paths are preferred; relative paths start at the owner home folder. The current approved-root policy is always enforced. Reuse directory result path verbatim; khai-path: values preserve non-Unicode native names and undergo the same authorization checks. Do not reconstruct paths from lossy display names.",
"minLength": 1
},
"destination": {
"type": "string",
"description": "Full new path, including the final name.",
"minLength": 1
},
"overwrite": {
"type": "boolean",
"description": "Allow replacing the destination.",
"default": false
},
"parents": {
"type": "boolean",
"description": "Create missing destination parents.",
"default": false
},
"request_id": {
"type": "string",
"description": "Optional correlation ID for this call.",
"minLength": 1
},
"dry_run": {
"type": "boolean",
"description": "Validate the request without performing the mutation. Native dry runs validate input and permission; they do not prove that a UI target still exists.",
"default": false
}
},
"required": [
"path",
"destination"
],
"additionalProperties": false
}Fileselevated access · Changes state
file_trash
Move one file/folder to the operating system Trash/Recycle Bin. Recovery uses the OS. Nonempty folders require recursive=true. A missing Trash backend fails; this never falls back to permanent deletion.
Inputs (4)
pathRequired- string · File or folder path. Absolute paths are preferred; relative paths start at the owner home folder. The current approved-root policy is always enforced. Reuse directory result path verbatim; khai-path: values preserve non-Unicode native names and undergo the same authorization checks. Do not reconstruct paths from lossy display names.
recursiveConditional / optional- boolean · Permit a nonempty folder and its descendants.
request_idConditional / optional- string · Optional correlation ID for this call.
dry_runConditional / optional- boolean · Validate the request without performing the mutation. Native dry runs validate input and permission; they do not prove that a UI target still exists.
Complete input schema
{
"type": "object",
"properties": {
"path": {
"type": "string",
"description": "File or folder path. Absolute paths are preferred; relative paths start at the owner home folder. The current approved-root policy is always enforced. Reuse directory result path verbatim; khai-path: values preserve non-Unicode native names and undergo the same authorization checks. Do not reconstruct paths from lossy display names.",
"minLength": 1
},
"recursive": {
"type": "boolean",
"description": "Permit a nonempty folder and its descendants.",
"default": false
},
"request_id": {
"type": "string",
"description": "Optional correlation ID for this call.",
"minLength": 1
},
"dry_run": {
"type": "boolean",
"description": "Validate the request without performing the mutation. Native dry runs validate input and permission; they do not prove that a UI target still exists.",
"default": false
}
},
"required": [
"path"
],
"additionalProperties": false
}Filesfull access · Changes state
file_delete_permanently
Permanently delete one file/folder without OS recovery. Requires Full Access and confirm_permanent=true for the exact intended target. Prefer file_trash for ordinary removal. Inspect the path and use dry_run before broad recursive deletion.
Inputs (5)
pathRequired- string · File or folder path. Absolute paths are preferred; relative paths start at the owner home folder. The current approved-root policy is always enforced. Reuse directory result path verbatim; khai-path: values preserve non-Unicode native names and undergo the same authorization checks. Do not reconstruct paths from lossy display names.
recursiveConditional / optional- boolean · Permit a nonempty folder and its descendants.
confirm_permanentRequired- boolean · Explicit confirmation that permanent deletion of this target is intended.
request_idConditional / optional- string · Optional correlation ID for this call.
dry_runConditional / optional- boolean · Validate the request without performing the mutation. Native dry runs validate input and permission; they do not prove that a UI target still exists.
Complete input schema
{
"type": "object",
"properties": {
"path": {
"type": "string",
"description": "File or folder path. Absolute paths are preferred; relative paths start at the owner home folder. The current approved-root policy is always enforced. Reuse directory result path verbatim; khai-path: values preserve non-Unicode native names and undergo the same authorization checks. Do not reconstruct paths from lossy display names.",
"minLength": 1
},
"recursive": {
"type": "boolean",
"description": "Permit a nonempty folder and its descendants.",
"default": false
},
"confirm_permanent": {
"const": true,
"type": "boolean",
"description": "Explicit confirmation that permanent deletion of this target is intended."
},
"request_id": {
"type": "string",
"description": "Optional correlation ID for this call.",
"minLength": 1
},
"dry_run": {
"type": "boolean",
"description": "Validate the request without performing the mutation. Native dry runs validate input and permission; they do not prove that a UI target still exists.",
"default": false
}
},
"required": [
"path",
"confirm_permanent"
],
"additionalProperties": false
}Applicationsnormal access · Read only
app_list
List running desktop applications/processes. Reuse the returned pid/path with app_get_info or app_activate; use window_list to inspect their windows.
Inputs (1)
request_idConditional / optional- string · Optional correlation ID for this call.
Complete input schema
{
"type": "object",
"properties": {
"request_id": {
"type": "string",
"description": "Optional correlation ID for this call.",
"minLength": 1
}
},
"required": [],
"additionalProperties": false
}Applicationsnormal access · Read only
app_get_active
Identify the foreground application. Returns native application identity where supported. Use app_get_info for a particular app and ui_observe for its controls.
Inputs (1)
request_idConditional / optional- string · Optional correlation ID for this call.
Complete input schema
{
"type": "object",
"properties": {
"request_id": {
"type": "string",
"description": "Optional correlation ID for this call.",
"minLength": 1
}
},
"required": [],
"additionalProperties": false
}Applicationsnormal access · Read only
app_get_info
Inspect one application identified by pid, exact name or macOS bundle ID. Prefer a pid from app_list to disambiguate installations.
Inputs (4)
pidConditional / optional- integer · Process ID returned by app_list or app_get_active.
app_nameConditional / optional- string · Exact application/process name; use an absolute path if several installations share the name.
bundle_idConditional / optional- string · macOS application bundle identifier. Use only on macOS.
request_idConditional / optional- string · Optional correlation ID for this call.
Complete input schema
{
"type": "object",
"properties": {
"pid": {
"type": "integer",
"description": "Process ID returned by app_list or app_get_active.",
"minimum": 1
},
"app_name": {
"type": "string",
"description": "Exact application/process name; use an absolute path if several installations share the name.",
"minLength": 1
},
"bundle_id": {
"type": "string",
"description": "macOS application bundle identifier. Use only on macOS.",
"minLength": 1
},
"request_id": {
"type": "string",
"description": "Optional correlation ID for this call.",
"minLength": 1
}
},
"required": [],
"additionalProperties": false,
"anyOf": [
{
"required": [
"pid"
]
},
{
"required": [
"app_name"
]
},
{
"required": [
"bundle_id"
]
}
]
}Applicationselevated access · Changes state
app_launch
Launch an installed application. Prefer its absolute executable/.app path; Linux/Windows may also use app_name; macOS requires path or bundle_id. This does not launch Khai-Hub managed Chrome; use browser_launch for browser automation.
Inputs (6)
pathConditional / optional- string · Absolute executable or .app path.
app_nameConditional / optional- string · Exact application/process name; use an absolute path if several installations share the name.
bundle_idConditional / optional- string · macOS application bundle identifier. Use only on macOS.
activateConditional / optional- boolean · Bring the launched app forward where supported.
request_idConditional / optional- string · Optional correlation ID for this call.
dry_runConditional / optional- boolean · Validate the request without performing the mutation. Native dry runs validate input and permission; they do not prove that a UI target still exists.
Complete input schema
{
"type": "object",
"properties": {
"path": {
"type": "string",
"description": "Absolute executable or .app path.",
"minLength": 1
},
"app_name": {
"type": "string",
"description": "Exact application/process name; use an absolute path if several installations share the name.",
"minLength": 1
},
"bundle_id": {
"type": "string",
"description": "macOS application bundle identifier. Use only on macOS.",
"minLength": 1
},
"activate": {
"type": "boolean",
"description": "Bring the launched app forward where supported.",
"default": true
},
"request_id": {
"type": "string",
"description": "Optional correlation ID for this call.",
"minLength": 1
},
"dry_run": {
"type": "boolean",
"description": "Validate the request without performing the mutation. Native dry runs validate input and permission; they do not prove that a UI target still exists.",
"default": false
}
},
"required": [],
"additionalProperties": false,
"anyOf": [
{
"required": [
"path"
]
},
{
"required": [
"app_name"
]
},
{
"required": [
"bundle_id"
]
}
]
}Applicationselevated access · Changes state
app_activate
Bring one running application to the foreground. Reuse a pid from app_list/app_get_active. This targets the app, not just one window.
Inputs (5)
pidConditional / optional- integer · Process ID returned by app_list or app_get_active.
app_nameConditional / optional- string · Exact application/process name; use an absolute path if several installations share the name.
bundle_idConditional / optional- string · macOS application bundle identifier. Use only on macOS.
request_idConditional / optional- string · Optional correlation ID for this call.
dry_runConditional / optional- boolean · Validate the request without performing the mutation. Native dry runs validate input and permission; they do not prove that a UI target still exists.
Complete input schema
{
"type": "object",
"properties": {
"pid": {
"type": "integer",
"description": "Process ID returned by app_list or app_get_active.",
"minimum": 1
},
"app_name": {
"type": "string",
"description": "Exact application/process name; use an absolute path if several installations share the name.",
"minLength": 1
},
"bundle_id": {
"type": "string",
"description": "macOS application bundle identifier. Use only on macOS.",
"minLength": 1
},
"request_id": {
"type": "string",
"description": "Optional correlation ID for this call.",
"minLength": 1
},
"dry_run": {
"type": "boolean",
"description": "Validate the request without performing the mutation. Native dry runs validate input and permission; they do not prove that a UI target still exists.",
"default": false
}
},
"required": [],
"additionalProperties": false,
"anyOf": [
{
"required": [
"pid"
]
},
{
"required": [
"app_name"
]
},
{
"required": [
"bundle_id"
]
}
]
}Applicationselevated access · Changes state
app_hide
Hide one running application where the native platform supports hiding. Reuse a pid from app_list/app_get_active. This targets the app, not just one window.
Inputs (5)
pidConditional / optional- integer · Process ID returned by app_list or app_get_active.
app_nameConditional / optional- string · Exact application/process name; use an absolute path if several installations share the name.
bundle_idConditional / optional- string · macOS application bundle identifier. Use only on macOS.
request_idConditional / optional- string · Optional correlation ID for this call.
dry_runConditional / optional- boolean · Validate the request without performing the mutation. Native dry runs validate input and permission; they do not prove that a UI target still exists.
Complete input schema
{
"type": "object",
"properties": {
"pid": {
"type": "integer",
"description": "Process ID returned by app_list or app_get_active.",
"minimum": 1
},
"app_name": {
"type": "string",
"description": "Exact application/process name; use an absolute path if several installations share the name.",
"minLength": 1
},
"bundle_id": {
"type": "string",
"description": "macOS application bundle identifier. Use only on macOS.",
"minLength": 1
},
"request_id": {
"type": "string",
"description": "Optional correlation ID for this call.",
"minLength": 1
},
"dry_run": {
"type": "boolean",
"description": "Validate the request without performing the mutation. Native dry runs validate input and permission; they do not prove that a UI target still exists.",
"default": false
}
},
"required": [],
"additionalProperties": false,
"anyOf": [
{
"required": [
"pid"
]
},
{
"required": [
"app_name"
]
},
{
"required": [
"bundle_id"
]
}
]
}Applicationselevated access · Changes state
app_quit
Request a normal quit of one application; it may display an unsaved-document prompt. Reuse a pid from app_list/app_get_active. This targets the app, not just one window.
Inputs (5)
pidConditional / optional- integer · Process ID returned by app_list or app_get_active.
app_nameConditional / optional- string · Exact application/process name; use an absolute path if several installations share the name.
bundle_idConditional / optional- string · macOS application bundle identifier. Use only on macOS.
request_idConditional / optional- string · Optional correlation ID for this call.
dry_runConditional / optional- boolean · Validate the request without performing the mutation. Native dry runs validate input and permission; they do not prove that a UI target still exists.
Complete input schema
{
"type": "object",
"properties": {
"pid": {
"type": "integer",
"description": "Process ID returned by app_list or app_get_active.",
"minimum": 1
},
"app_name": {
"type": "string",
"description": "Exact application/process name; use an absolute path if several installations share the name.",
"minLength": 1
},
"bundle_id": {
"type": "string",
"description": "macOS application bundle identifier. Use only on macOS.",
"minLength": 1
},
"request_id": {
"type": "string",
"description": "Optional correlation ID for this call.",
"minLength": 1
},
"dry_run": {
"type": "boolean",
"description": "Validate the request without performing the mutation. Native dry runs validate input and permission; they do not prove that a UI target still exists.",
"default": false
}
},
"required": [],
"additionalProperties": false,
"anyOf": [
{
"required": [
"pid"
]
},
{
"required": [
"app_name"
]
},
{
"required": [
"bundle_id"
]
}
]
}Applicationselevated access · Changes state
app_force_quit
Force one application to terminate. Unsaved work may be lost; use app_quit for normal shutdown. Reuse a pid from app_list/app_get_active. This targets the app, not just one window.
Inputs (5)
pidConditional / optional- integer · Process ID returned by app_list or app_get_active.
app_nameConditional / optional- string · Exact application/process name; use an absolute path if several installations share the name.
bundle_idConditional / optional- string · macOS application bundle identifier. Use only on macOS.
request_idConditional / optional- string · Optional correlation ID for this call.
dry_runConditional / optional- boolean · Validate the request without performing the mutation. Native dry runs validate input and permission; they do not prove that a UI target still exists.
Complete input schema
{
"type": "object",
"properties": {
"pid": {
"type": "integer",
"description": "Process ID returned by app_list or app_get_active.",
"minimum": 1
},
"app_name": {
"type": "string",
"description": "Exact application/process name; use an absolute path if several installations share the name.",
"minLength": 1
},
"bundle_id": {
"type": "string",
"description": "macOS application bundle identifier. Use only on macOS.",
"minLength": 1
},
"request_id": {
"type": "string",
"description": "Optional correlation ID for this call.",
"minLength": 1
},
"dry_run": {
"type": "boolean",
"description": "Validate the request without performing the mutation. Native dry runs validate input and permission; they do not prove that a UI target still exists.",
"default": false
}
},
"required": [],
"additionalProperties": false,
"anyOf": [
{
"required": [
"pid"
]
},
{
"required": [
"app_name"
]
},
{
"required": [
"bundle_id"
]
}
]
}Applicationselevated access · Changes state
app_open_file
Open an approved local file in its OS-associated desktop application. This launches/activates an app; use file_read when only its contents are needed.
Inputs (3)
pathRequired- string · File or folder path. Absolute paths are preferred; relative paths start at the owner home folder. The current approved-root policy is always enforced.
request_idConditional / optional- string · Optional correlation ID for this call.
dry_runConditional / optional- boolean · Validate the request without performing the mutation. Native dry runs validate input and permission; they do not prove that a UI target still exists.
Complete input schema
{
"type": "object",
"properties": {
"path": {
"type": "string",
"description": "File or folder path. Absolute paths are preferred; relative paths start at the owner home folder. The current approved-root policy is always enforced.",
"minLength": 1
},
"request_id": {
"type": "string",
"description": "Optional correlation ID for this call.",
"minLength": 1
},
"dry_run": {
"type": "boolean",
"description": "Validate the request without performing the mutation. Native dry runs validate input and permission; they do not prove that a UI target still exists.",
"default": false
}
},
"required": [
"path"
],
"additionalProperties": false
}Applicationselevated access · Changes state
app_open_url
Open an HTTP(S) URL in the owner default browser. This does not create a managed automation tab. Use browser_new_tab/browser_navigate when subsequent DOM automation is intended.
Inputs (3)
urlRequired- string · HTTP or HTTPS URL.
request_idConditional / optional- string · Optional correlation ID for this call.
dry_runConditional / optional- boolean · Validate the request without performing the mutation. Native dry runs validate input and permission; they do not prove that a UI target still exists.
Complete input schema
{
"type": "object",
"properties": {
"url": {
"type": "string",
"description": "HTTP or HTTPS URL.",
"minLength": 1
},
"request_id": {
"type": "string",
"description": "Optional correlation ID for this call.",
"minLength": 1
},
"dry_run": {
"type": "boolean",
"description": "Validate the request without performing the mutation. Native dry runs validate input and permission; they do not prove that a UI target still exists.",
"default": false
}
},
"required": [
"url"
],
"additionalProperties": false
}Clipboardnormal access · Read only
clipboard_read
Read clipboard text as MCP TextContent and report whether text exists.
Inputs (1)
request_idConditional / optional- string · Optional correlation ID for this call.
Complete input schema
{
"type": "object",
"properties": {
"request_id": {
"type": "string",
"description": "Optional correlation ID for this call.",
"minLength": 1
}
},
"required": [],
"additionalProperties": false
}Clipboardnormal access · Read only
clipboard_has_text
Check whether the clipboard contains text without returning that text.
Inputs (1)
request_idConditional / optional- string · Optional correlation ID for this call.
Complete input schema
{
"type": "object",
"properties": {
"request_id": {
"type": "string",
"description": "Optional correlation ID for this call.",
"minLength": 1
}
},
"required": [],
"additionalProperties": false
}Clipboardnormal access · Read only
clipboard_list_types
List clipboard data types without changing the clipboard.
Inputs (1)
request_idConditional / optional- string · Optional correlation ID for this call.
Complete input schema
{
"type": "object",
"properties": {
"request_id": {
"type": "string",
"description": "Optional correlation ID for this call.",
"minLength": 1
}
},
"required": [],
"additionalProperties": false
}Clipboardelevated access · Changes state
clipboard_write
Replace clipboard text. Empty text is allowed. This does not paste into an application; use keyboard_paste when pasting into the focused control is intended.
Inputs (3)
textRequired- string · Exact clipboard text.
request_idConditional / optional- string · Optional correlation ID for this call.
dry_runConditional / optional- boolean · Validate the request without performing the mutation. Native dry runs validate input and permission; they do not prove that a UI target still exists.
Complete input schema
{
"type": "object",
"properties": {
"text": {
"type": "string",
"description": "Exact clipboard text."
},
"request_id": {
"type": "string",
"description": "Optional correlation ID for this call.",
"minLength": 1
},
"dry_run": {
"type": "boolean",
"description": "Validate the request without performing the mutation. Native dry runs validate input and permission; they do not prove that a UI target still exists.",
"default": false
}
},
"required": [
"text"
],
"additionalProperties": false
}Clipboardelevated access · Changes state
clipboard_clear
Clear the system clipboard. This removes its current contents and does not undo previous pastes.
Inputs (2)
request_idConditional / optional- string · Optional correlation ID for this call.
dry_runConditional / optional- boolean · Validate the request without performing the mutation. Native dry runs validate input and permission; they do not prove that a UI target still exists.
Complete input schema
{
"type": "object",
"properties": {
"request_id": {
"type": "string",
"description": "Optional correlation ID for this call.",
"minLength": 1
},
"dry_run": {
"type": "boolean",
"description": "Validate the request without performing the mutation. Native dry runs validate input and permission; they do not prove that a UI target still exists.",
"default": false
}
},
"required": [],
"additionalProperties": false
}Commands & taskselevated access · Changes state
shell_run
Run one direct executable with an argv array for builds, tests, Git or other CLI work. Prefer file_*/directory_* for files and browser_*/app_*/ui_* for computer work. Shell syntax is not parsed: pipes, redirection and && require an explicit interpreter at Full Access. Returns a task_id for task_* tools. On failure inspect stderr and affected state before retrying; partial_change=null means effects are unknown. Use it directly for real executable work such as builds, tests, Git, package managers and supported document conversion; do not use cat/sed/echo or a script just to substitute for available File System reads/edits. Permission denial is not permission to bypass a tool using another tool. Process exit and output EOF are separate: inspect output_complete/output_pending/output_failed and stdout_truncated/stderr_truncated. Finished snapshots allow up to one additional second for readers to drain. If output_pending is true, inspect the same task_id later; if output_failed is true, report partial output. Never rerun a completed command merely because output is still pending.
Inputs (12)
executableRequired- string · Executable name from PATH or absolute path, never a complete command line.
argumentsConditional / optional- array · Exact argument array.
cwdConditional / optional- string · File or folder path. Absolute paths are preferred; relative paths start at the owner home folder. The current approved-root policy is always enforced.
privilegeConditional / optional- string · user | admin · Admin requires Full Access and OS authorization.
executionConditional / optional- string · auto | foreground | background · Auto waits briefly; background returns immediately; foreground cancels on timeout.
timeout_secondsConditional / optional- number · Bounded timeout in seconds.
max_output_bytesConditional / optional- integer · Maximum output bytes returned, bounded by the owner configuration.
tail_linesConditional / optional- integer · Return only the final N log lines; 0 means no line filter.
include_stdoutConditional / optional- boolean · Include standard output.
include_stderrConditional / optional- boolean · Include standard error.
request_idConditional / optional- string · Optional correlation ID for this call.
dry_runConditional / optional- boolean · Validate the request without performing the mutation. Native dry runs validate input and permission; they do not prove that a UI target still exists.
Complete input schema
{
"type": "object",
"properties": {
"executable": {
"type": "string",
"description": "Executable name from PATH or absolute path, never a complete command line.",
"minLength": 1
},
"arguments": {
"type": "array",
"items": {
"type": "string",
"description": "One literal argv entry."
},
"description": "Exact argument array.",
"minItems": 0,
"maxItems": 1000
},
"cwd": {
"type": "string",
"description": "File or folder path. Absolute paths are preferred; relative paths start at the owner home folder. The current approved-root policy is always enforced.",
"minLength": 1
},
"privilege": {
"type": "string",
"enum": [
"user",
"admin"
],
"description": "Admin requires Full Access and OS authorization.",
"default": "user"
},
"execution": {
"type": "string",
"enum": [
"auto",
"foreground",
"background"
],
"description": "Auto waits briefly; background returns immediately; foreground cancels on timeout.",
"default": "auto"
},
"timeout_seconds": {
"type": "number",
"description": "Bounded timeout in seconds.",
"minimum": 0.1,
"maximum": 600
},
"max_output_bytes": {
"type": "integer",
"description": "Maximum output bytes returned, bounded by the owner configuration.",
"minimum": 1,
"maximum": 8388608
},
"tail_lines": {
"type": "integer",
"description": "Return only the final N log lines; 0 means no line filter.",
"minimum": 0
},
"include_stdout": {
"type": "boolean",
"description": "Include standard output.",
"default": true
},
"include_stderr": {
"type": "boolean",
"description": "Include standard error.",
"default": true
},
"request_id": {
"type": "string",
"description": "Optional correlation ID for this call.",
"minLength": 1
},
"dry_run": {
"type": "boolean",
"description": "Validate the request without performing the mutation. Native dry runs validate input and permission; they do not prove that a UI target still exists.",
"default": false
}
},
"required": [
"executable"
],
"additionalProperties": false
}Commands & tasksfull access · Read only
ai_cli_status
Check a local coding-agent executable and owner opt-in without starting a task. Returns installed and owner_enabled; authentication is checked only when a task starts. Full Access is required, but the owner toggle may be off.
Inputs (2)
providerConditional / optional- string · codex | claude · Installed local coding-agent provider.
request_idConditional / optional- string · Optional correlation ID for this call.
Complete input schema
{
"type": "object",
"properties": {
"provider": {
"type": "string",
"enum": [
"codex",
"claude"
],
"description": "Installed local coding-agent provider.",
"default": "codex"
},
"request_id": {
"type": "string",
"description": "Optional correlation ID for this call.",
"minLength": 1
}
},
"required": [],
"additionalProperties": false
}Commands & tasksfull access · Changes state
ai_cli_run
Start an owner-enabled local Codex or Claude coding task. Requires Full Access and AI CLI opt-in. The child agent may change files. Returns a Khai-Hub task_id; use task_wait/task_result to collect progress and the provider session_id for continuation. Process exit and output EOF are separate: inspect output_complete/output_pending/output_failed and stdout_truncated/stderr_truncated. Finished snapshots allow up to one additional second for readers to drain. If output_pending is true, inspect the same task_id later; if output_failed is true, report partial output. Never rerun a completed command merely because output is still pending.
Inputs (9)
providerConditional / optional- string · codex | claude · Installed local coding-agent provider.
promptRequired- string · Complete instruction to send to the local coding agent.
cwdConditional / optional- string · File or folder path. Absolute paths are preferred; relative paths start at the owner home folder. The current approved-root policy is always enforced.
modelConditional / optional- string · Optional provider-specific model identifier.
max_output_bytesConditional / optional- integer · Maximum output bytes returned, bounded by the owner configuration.
tail_linesConditional / optional- integer · Return only the final N log lines; 0 means no line filter.
timeout_secondsConditional / optional- number · Bounded timeout in seconds.
request_idConditional / optional- string · Optional correlation ID for this call.
dry_runConditional / optional- boolean · Validate the request without performing the mutation. Native dry runs validate input and permission; they do not prove that a UI target still exists.
Complete input schema
{
"type": "object",
"properties": {
"provider": {
"type": "string",
"enum": [
"codex",
"claude"
],
"description": "Installed local coding-agent provider.",
"default": "codex"
},
"prompt": {
"type": "string",
"description": "Complete instruction to send to the local coding agent.",
"minLength": 1
},
"cwd": {
"type": "string",
"description": "File or folder path. Absolute paths are preferred; relative paths start at the owner home folder. The current approved-root policy is always enforced.",
"minLength": 1
},
"model": {
"type": "string",
"description": "Optional provider-specific model identifier.",
"minLength": 1
},
"max_output_bytes": {
"type": "integer",
"description": "Maximum output bytes returned, bounded by the owner configuration.",
"minimum": 1,
"maximum": 8388608
},
"tail_lines": {
"type": "integer",
"description": "Return only the final N log lines; 0 means no line filter.",
"minimum": 0
},
"timeout_seconds": {
"type": "number",
"description": "Bounded timeout in seconds.",
"minimum": 0.1,
"maximum": 600
},
"request_id": {
"type": "string",
"description": "Optional correlation ID for this call.",
"minLength": 1
},
"dry_run": {
"type": "boolean",
"description": "Validate the request without performing the mutation. Native dry runs validate input and permission; they do not prove that a UI target still exists.",
"default": false
}
},
"required": [
"prompt"
],
"additionalProperties": false
}Commands & tasksfull access · Changes state
ai_cli_resume
Continue an existing provider session with a new prompt. Requires Full Access and owner AI CLI opt-in. session_id is the Codex/Claude session identifier from a previous result, not the Khai-Hub task_id. Returns a new Khai-Hub task_id to track. Process exit and output EOF are separate: inspect output_complete/output_pending/output_failed and stdout_truncated/stderr_truncated. Finished snapshots allow up to one additional second for readers to drain. If output_pending is true, inspect the same task_id later; if output_failed is true, report partial output. Never rerun a completed command merely because output is still pending.
Inputs (9)
providerConditional / optional- string · codex | claude · Installed local coding-agent provider.
promptRequired- string · Complete instruction to send to the local coding agent.
cwdConditional / optional- string · File or folder path. Absolute paths are preferred; relative paths start at the owner home folder. The current approved-root policy is always enforced.
modelConditional / optional- string · Optional provider-specific model identifier.
max_output_bytesConditional / optional- integer · Maximum output bytes returned, bounded by the owner configuration.
tail_linesConditional / optional- integer · Return only the final N log lines; 0 means no line filter.
session_idRequired- string · Exact provider session ID from the prior task result.
request_idConditional / optional- string · Optional correlation ID for this call.
dry_runConditional / optional- boolean · Validate the request without performing the mutation. Native dry runs validate input and permission; they do not prove that a UI target still exists.
Complete input schema
{
"type": "object",
"properties": {
"provider": {
"type": "string",
"enum": [
"codex",
"claude"
],
"description": "Installed local coding-agent provider.",
"default": "codex"
},
"prompt": {
"type": "string",
"description": "Complete instruction to send to the local coding agent.",
"minLength": 1
},
"cwd": {
"type": "string",
"description": "File or folder path. Absolute paths are preferred; relative paths start at the owner home folder. The current approved-root policy is always enforced.",
"minLength": 1
},
"model": {
"type": "string",
"description": "Optional provider-specific model identifier.",
"minLength": 1
},
"max_output_bytes": {
"type": "integer",
"description": "Maximum output bytes returned, bounded by the owner configuration.",
"minimum": 1,
"maximum": 8388608
},
"tail_lines": {
"type": "integer",
"description": "Return only the final N log lines; 0 means no line filter.",
"minimum": 0
},
"session_id": {
"type": "string",
"description": "Exact provider session ID from the prior task result.",
"minLength": 1
},
"request_id": {
"type": "string",
"description": "Optional correlation ID for this call.",
"minLength": 1
},
"dry_run": {
"type": "boolean",
"description": "Validate the request without performing the mutation. Native dry runs validate input and permission; they do not prove that a UI target still exists.",
"default": false
}
},
"required": [
"prompt",
"session_id"
],
"additionalProperties": false
}Commands & taskselevated access · Read only
task_status
Read the current task state without waiting. A completed task can include bounded output. Shell tasks require Elevated access; AI tasks require Full Access. The task origin is resolved from the saved task, never supplied by the caller. AI task inspection/cancellation remains available after delegation is switched off. Process exit and output EOF are separate: inspect output_complete/output_pending/output_failed and stdout_truncated/stderr_truncated. Finished snapshots allow up to one additional second for readers to drain. If output_pending is true, inspect the same task_id later; if output_failed is true, report partial output. Never rerun a completed command merely because output is still pending.
Inputs (6)
task_idRequired- string · Exact Khai-Hub task_id returned by shell_run, ai_cli_run or ai_cli_resume in this engine session.
max_output_bytesConditional / optional- integer · Maximum output bytes returned, bounded by the owner configuration.
tail_linesConditional / optional- integer · Return only the final N log lines; 0 means no line filter.
include_stdoutConditional / optional- boolean · Include standard output.
include_stderrConditional / optional- boolean · Include standard error.
request_idConditional / optional- string · Optional correlation ID for this call.
Complete input schema
{
"type": "object",
"properties": {
"task_id": {
"type": "string",
"pattern": "^khai_[0-9A-Fa-f]{32}$",
"description": "Exact Khai-Hub task_id returned by shell_run, ai_cli_run or ai_cli_resume in this engine session."
},
"max_output_bytes": {
"type": "integer",
"description": "Maximum output bytes returned, bounded by the owner configuration.",
"minimum": 1,
"maximum": 8388608
},
"tail_lines": {
"type": "integer",
"description": "Return only the final N log lines; 0 means no line filter.",
"minimum": 0
},
"include_stdout": {
"type": "boolean",
"description": "Include standard output.",
"default": true
},
"include_stderr": {
"type": "boolean",
"description": "Include standard error.",
"default": true
},
"request_id": {
"type": "string",
"description": "Optional correlation ID for this call.",
"minLength": 1
}
},
"required": [
"task_id"
],
"additionalProperties": false
}Commands & taskselevated access · Read only
task_wait
Wait for an existing task for a bounded time. A still-running result is not a failure; keep the same task_id for another wait. Shell tasks require Elevated access; AI tasks require Full Access. The task origin is resolved from the saved task, never supplied by the caller. AI task inspection/cancellation remains available after delegation is switched off. Process exit and output EOF are separate: inspect output_complete/output_pending/output_failed and stdout_truncated/stderr_truncated. Finished snapshots allow up to one additional second for readers to drain. If output_pending is true, inspect the same task_id later; if output_failed is true, report partial output. Never rerun a completed command merely because output is still pending.
Inputs (7)
task_idRequired- string · Exact Khai-Hub task_id returned by shell_run, ai_cli_run or ai_cli_resume in this engine session.
max_output_bytesConditional / optional- integer · Maximum output bytes returned, bounded by the owner configuration.
tail_linesConditional / optional- integer · Return only the final N log lines; 0 means no line filter.
include_stdoutConditional / optional- boolean · Include standard output.
include_stderrConditional / optional- boolean · Include standard error.
timeout_secondsConditional / optional- number · Bounded timeout in seconds.
request_idConditional / optional- string · Optional correlation ID for this call.
Complete input schema
{
"type": "object",
"properties": {
"task_id": {
"type": "string",
"pattern": "^khai_[0-9A-Fa-f]{32}$",
"description": "Exact Khai-Hub task_id returned by shell_run, ai_cli_run or ai_cli_resume in this engine session."
},
"max_output_bytes": {
"type": "integer",
"description": "Maximum output bytes returned, bounded by the owner configuration.",
"minimum": 1,
"maximum": 8388608
},
"tail_lines": {
"type": "integer",
"description": "Return only the final N log lines; 0 means no line filter.",
"minimum": 0
},
"include_stdout": {
"type": "boolean",
"description": "Include standard output.",
"default": true
},
"include_stderr": {
"type": "boolean",
"description": "Include standard error.",
"default": true
},
"timeout_seconds": {
"type": "number",
"description": "Bounded timeout in seconds.",
"minimum": 0.1,
"maximum": 600
},
"request_id": {
"type": "string",
"description": "Optional correlation ID for this call.",
"minLength": 1
}
},
"required": [
"task_id"
],
"additionalProperties": false
}Commands & taskselevated access · Read only
task_logs
Read bounded stdout/stderr for a running or completed task without starting it again. Shell tasks require Elevated access; AI tasks require Full Access. The task origin is resolved from the saved task, never supplied by the caller. AI task inspection/cancellation remains available after delegation is switched off. Process exit and output EOF are separate: inspect output_complete/output_pending/output_failed and stdout_truncated/stderr_truncated. Finished snapshots allow up to one additional second for readers to drain. If output_pending is true, inspect the same task_id later; if output_failed is true, report partial output. Never rerun a completed command merely because output is still pending.
Inputs (6)
task_idRequired- string · Exact Khai-Hub task_id returned by shell_run, ai_cli_run or ai_cli_resume in this engine session.
max_output_bytesConditional / optional- integer · Maximum output bytes returned, bounded by the owner configuration.
tail_linesConditional / optional- integer · Return only the final N log lines; 0 means no line filter.
include_stdoutConditional / optional- boolean · Include standard output.
include_stderrConditional / optional- boolean · Include standard error.
request_idConditional / optional- string · Optional correlation ID for this call.
Complete input schema
{
"type": "object",
"properties": {
"task_id": {
"type": "string",
"pattern": "^khai_[0-9A-Fa-f]{32}$",
"description": "Exact Khai-Hub task_id returned by shell_run, ai_cli_run or ai_cli_resume in this engine session."
},
"max_output_bytes": {
"type": "integer",
"description": "Maximum output bytes returned, bounded by the owner configuration.",
"minimum": 1,
"maximum": 8388608
},
"tail_lines": {
"type": "integer",
"description": "Return only the final N log lines; 0 means no line filter.",
"minimum": 0
},
"include_stdout": {
"type": "boolean",
"description": "Include standard output.",
"default": true
},
"include_stderr": {
"type": "boolean",
"description": "Include standard error.",
"default": true
},
"request_id": {
"type": "string",
"description": "Optional correlation ID for this call.",
"minLength": 1
}
},
"required": [
"task_id"
],
"additionalProperties": false
}Commands & taskselevated access · Read only
task_result
Collect the latest result and output of an existing task. If it is still running, use task_wait; this call does not wait. Shell tasks require Elevated access; AI tasks require Full Access. The task origin is resolved from the saved task, never supplied by the caller. AI task inspection/cancellation remains available after delegation is switched off. Process exit and output EOF are separate: inspect output_complete/output_pending/output_failed and stdout_truncated/stderr_truncated. Finished snapshots allow up to one additional second for readers to drain. If output_pending is true, inspect the same task_id later; if output_failed is true, report partial output. Never rerun a completed command merely because output is still pending.
Inputs (6)
task_idRequired- string · Exact Khai-Hub task_id returned by shell_run, ai_cli_run or ai_cli_resume in this engine session.
max_output_bytesConditional / optional- integer · Maximum output bytes returned, bounded by the owner configuration.
tail_linesConditional / optional- integer · Return only the final N log lines; 0 means no line filter.
include_stdoutConditional / optional- boolean · Include standard output.
include_stderrConditional / optional- boolean · Include standard error.
request_idConditional / optional- string · Optional correlation ID for this call.
Complete input schema
{
"type": "object",
"properties": {
"task_id": {
"type": "string",
"pattern": "^khai_[0-9A-Fa-f]{32}$",
"description": "Exact Khai-Hub task_id returned by shell_run, ai_cli_run or ai_cli_resume in this engine session."
},
"max_output_bytes": {
"type": "integer",
"description": "Maximum output bytes returned, bounded by the owner configuration.",
"minimum": 1,
"maximum": 8388608
},
"tail_lines": {
"type": "integer",
"description": "Return only the final N log lines; 0 means no line filter.",
"minimum": 0
},
"include_stdout": {
"type": "boolean",
"description": "Include standard output.",
"default": true
},
"include_stderr": {
"type": "boolean",
"description": "Include standard error.",
"default": true
},
"request_id": {
"type": "string",
"description": "Optional correlation ID for this call.",
"minLength": 1
}
},
"required": [
"task_id"
],
"additionalProperties": false
}Commands & taskselevated access · Changes state
task_cancel
Cancel an existing task and its managed process group. Cancellation does not roll back external file or application changes. Shell tasks require Elevated access; AI tasks require Full Access. The task origin is resolved from the saved task, never supplied by the caller. AI task inspection/cancellation remains available after delegation is switched off.
Inputs (3)
task_idRequired- string · Exact Khai-Hub task_id returned by shell_run, ai_cli_run or ai_cli_resume in this engine session.
request_idConditional / optional- string · Optional correlation ID for this call.
dry_runConditional / optional- boolean · Validate the request without performing the mutation. Native dry runs validate input and permission; they do not prove that a UI target still exists.
Complete input schema
{
"type": "object",
"properties": {
"task_id": {
"type": "string",
"pattern": "^khai_[0-9A-Fa-f]{32}$",
"description": "Exact Khai-Hub task_id returned by shell_run, ai_cli_run or ai_cli_resume in this engine session."
},
"request_id": {
"type": "string",
"description": "Optional correlation ID for this call.",
"minLength": 1
},
"dry_run": {
"type": "boolean",
"description": "Validate the request without performing the mutation. Native dry runs validate input and permission; they do not prove that a UI target still exists.",
"default": false
}
},
"required": [
"task_id"
],
"additionalProperties": false
}Browsernormal access · Read only
browser_status
Check managed Chrome readiness without launching it. If state=not_running, call browser_launch at Elevated/Full access. Follow required_action/retry_after_ms and do not retry an unchanged non-retryable failure.
Inputs (1)
request_idConditional / optional- string · Optional correlation ID for this call.
Complete input schema
{
"type": "object",
"properties": {
"request_id": {
"type": "string",
"description": "Optional correlation ID for this call.",
"minLength": 1
}
},
"required": [],
"additionalProperties": false
}Browserelevated access · Changes state
browser_launch
Start or reuse Khai-Hub managed Chrome with its isolated profile. Call when browser_status reports not_running. Returns browser readiness; get tab IDs with browser_list_tabs. This does not control unrelated personal browser tabs.
Inputs (4)
urlConditional / optional- string · Optional initial HTTP(S) URL or about:blank.
timeout_secondsConditional / optional- number · Launch timeout in seconds.
request_idConditional / optional- string · Optional correlation ID for this call.
dry_runConditional / optional- boolean · Validate the request without performing the mutation. Native dry runs validate input and permission; they do not prove that a UI target still exists.
Complete input schema
{
"type": "object",
"properties": {
"url": {
"type": "string",
"description": "Optional initial HTTP(S) URL or about:blank.",
"minLength": 1
},
"timeout_seconds": {
"type": "number",
"description": "Launch timeout in seconds.",
"minimum": 0.1,
"maximum": 300
},
"request_id": {
"type": "string",
"description": "Optional correlation ID for this call.",
"minLength": 1
},
"dry_run": {
"type": "boolean",
"description": "Validate the request without performing the mutation. Native dry runs validate input and permission; they do not prove that a UI target still exists.",
"default": false
}
},
"required": [],
"additionalProperties": false
}Browsernormal access · Read only
browser_list_tabs
List tabs in the running Khai-Hub managed browser. Reuse the returned tab IDs for browser_* calls. It does not enumerate arbitrary personal browser sessions.
Inputs (1)
request_idConditional / optional- string · Optional correlation ID for this call.
Complete input schema
{
"type": "object",
"properties": {
"request_id": {
"type": "string",
"description": "Optional correlation ID for this call.",
"minLength": 1
}
},
"required": [],
"additionalProperties": false
}Browserelevated access · Changes state
browser_new_tab
Create one managed browser tab at an HTTP(S) URL or about:blank and return its tab ID. Managed Chrome must already be running.
Inputs (3)
urlRequired- string · Initial HTTP(S) URL or about:blank.
request_idConditional / optional- string · Optional correlation ID for this call.
dry_runConditional / optional- boolean · Validate the request without performing the mutation. Native dry runs validate input and permission; they do not prove that a UI target still exists.
Complete input schema
{
"type": "object",
"properties": {
"url": {
"type": "string",
"description": "Initial HTTP(S) URL or about:blank.",
"minLength": 1
},
"request_id": {
"type": "string",
"description": "Optional correlation ID for this call.",
"minLength": 1
},
"dry_run": {
"type": "boolean",
"description": "Validate the request without performing the mutation. Native dry runs validate input and permission; they do not prove that a UI target still exists.",
"default": false
}
},
"required": [
"url"
],
"additionalProperties": false
}Browserelevated access · Changes state
browser_close_tab
Close one managed browser tab. Reuse its exact tab_id from browser_list_tabs. Closing may discard unsaved page state.
Inputs (3)
tab_idRequired- string · Exact managed tab ID from browser_list_tabs or browser_new_tab. Never an OS window ID.
request_idConditional / optional- string · Optional correlation ID for this call.
dry_runConditional / optional- boolean · Validate the request without performing the mutation. Native dry runs validate input and permission; they do not prove that a UI target still exists.
Complete input schema
{
"type": "object",
"properties": {
"tab_id": {
"type": "string",
"description": "Exact managed tab ID from browser_list_tabs or browser_new_tab. Never an OS window ID.",
"minLength": 1
},
"request_id": {
"type": "string",
"description": "Optional correlation ID for this call.",
"minLength": 1
},
"dry_run": {
"type": "boolean",
"description": "Validate the request without performing the mutation. Native dry runs validate input and permission; they do not prove that a UI target still exists.",
"default": false
}
},
"required": [
"tab_id"
],
"additionalProperties": false
}Browserelevated access · Changes state
browser_navigate
Navigate one managed tab to an HTTP(S) URL. Use browser_query/browser_wait afterwards to inspect the new document; selectors from the previous document may be stale.
Inputs (4)
tab_idRequired- string · Exact managed tab ID from browser_list_tabs or browser_new_tab. Never an OS window ID.
urlRequired- string · Destination HTTP(S) URL.
request_idConditional / optional- string · Optional correlation ID for this call.
dry_runConditional / optional- boolean · Validate the request without performing the mutation. Native dry runs validate input and permission; they do not prove that a UI target still exists.
Complete input schema
{
"type": "object",
"properties": {
"tab_id": {
"type": "string",
"description": "Exact managed tab ID from browser_list_tabs or browser_new_tab. Never an OS window ID.",
"minLength": 1
},
"url": {
"type": "string",
"description": "Destination HTTP(S) URL.",
"minLength": 1
},
"request_id": {
"type": "string",
"description": "Optional correlation ID for this call.",
"minLength": 1
},
"dry_run": {
"type": "boolean",
"description": "Validate the request without performing the mutation. Native dry runs validate input and permission; they do not prove that a UI target still exists.",
"default": false
}
},
"required": [
"tab_id",
"url"
],
"additionalProperties": false
}Browsernormal access · Read only
browser_query
Read DOM elements matching a CSS selector in one managed tab. Inspect this result before browser_click or browser_type. Returns bounded element data; use browser_screenshot only when DOM content is insufficient.
Inputs (3)
tab_idRequired- string · Exact managed tab ID from browser_list_tabs or browser_new_tab. Never an OS window ID.
selectorRequired- string · CSS selector to inspect.
request_idConditional / optional- string · Optional correlation ID for this call.
Complete input schema
{
"type": "object",
"properties": {
"tab_id": {
"type": "string",
"description": "Exact managed tab ID from browser_list_tabs or browser_new_tab. Never an OS window ID.",
"minLength": 1
},
"selector": {
"type": "string",
"description": "CSS selector to inspect.",
"minLength": 1
},
"request_id": {
"type": "string",
"description": "Optional correlation ID for this call.",
"minLength": 1
}
},
"required": [
"tab_id",
"selector"
],
"additionalProperties": false
}Browserelevated access · Changes state
browser_click
Click a DOM element matching a CSS selector in one managed tab. First inspect the current page with browser_query. A click can submit a form or navigate; inspect the result before repeating it.
Inputs (4)
tab_idRequired- string · Exact managed tab ID from browser_list_tabs or browser_new_tab. Never an OS window ID.
selectorRequired- string · CSS selector for the intended current-page element.
request_idConditional / optional- string · Optional correlation ID for this call.
dry_runConditional / optional- boolean · Validate the request without performing the mutation. Native dry runs validate input and permission; they do not prove that a UI target still exists.
Complete input schema
{
"type": "object",
"properties": {
"tab_id": {
"type": "string",
"description": "Exact managed tab ID from browser_list_tabs or browser_new_tab. Never an OS window ID.",
"minLength": 1
},
"selector": {
"type": "string",
"description": "CSS selector for the intended current-page element.",
"minLength": 1
},
"request_id": {
"type": "string",
"description": "Optional correlation ID for this call.",
"minLength": 1
},
"dry_run": {
"type": "boolean",
"description": "Validate the request without performing the mutation. Native dry runs validate input and permission; they do not prove that a UI target still exists.",
"default": false
}
},
"required": [
"tab_id",
"selector"
],
"additionalProperties": false
}Browserelevated access · Changes state
browser_type
Set the text of an editable DOM element and dispatch its input/change events. This replaces its value; include the whole desired text. Inspect the selector with browser_query first. This does not press Enter or submit a form.
Inputs (5)
tab_idRequired- string · Exact managed tab ID from browser_list_tabs or browser_new_tab. Never an OS window ID.
selectorRequired- string · CSS selector for an editable element.
textRequired- string · Complete desired value; empty clears it.
request_idConditional / optional- string · Optional correlation ID for this call.
dry_runConditional / optional- boolean · Validate the request without performing the mutation. Native dry runs validate input and permission; they do not prove that a UI target still exists.
Complete input schema
{
"type": "object",
"properties": {
"tab_id": {
"type": "string",
"description": "Exact managed tab ID from browser_list_tabs or browser_new_tab. Never an OS window ID.",
"minLength": 1
},
"selector": {
"type": "string",
"description": "CSS selector for an editable element.",
"minLength": 1
},
"text": {
"type": "string",
"description": "Complete desired value; empty clears it."
},
"request_id": {
"type": "string",
"description": "Optional correlation ID for this call.",
"minLength": 1
},
"dry_run": {
"type": "boolean",
"description": "Validate the request without performing the mutation. Native dry runs validate input and permission; they do not prove that a UI target still exists.",
"default": false
}
},
"required": [
"tab_id",
"selector",
"text"
],
"additionalProperties": false
}Browsernormal access · Read only
browser_wait
Wait until a CSS selector exists in one managed tab, using a bounded timeout. It tests existence, not visibility or enabled state. This read-only tool does not accept JavaScript expressions; use browser_evaluate for explicit script execution.
Inputs (5)
tab_idRequired- string · Exact managed tab ID from browser_list_tabs or browser_new_tab. Never an OS window ID.
selectorRequired- string · CSS selector whose existence to wait for.
timeout_secondsConditional / optional- number · Maximum wait in seconds; defaults to 30.
poll_interval_secondsConditional / optional- number · Polling interval in seconds.
request_idConditional / optional- string · Optional correlation ID for this call.
Complete input schema
{
"type": "object",
"properties": {
"tab_id": {
"type": "string",
"description": "Exact managed tab ID from browser_list_tabs or browser_new_tab. Never an OS window ID.",
"minLength": 1
},
"selector": {
"type": "string",
"description": "CSS selector whose existence to wait for.",
"minLength": 1
},
"timeout_seconds": {
"type": "number",
"description": "Maximum wait in seconds; defaults to 30.",
"minimum": 0.1,
"maximum": 300
},
"poll_interval_seconds": {
"type": "number",
"description": "Polling interval in seconds.",
"minimum": 0.05,
"maximum": 2
},
"request_id": {
"type": "string",
"description": "Optional correlation ID for this call.",
"minLength": 1
}
},
"required": [
"tab_id",
"selector"
],
"additionalProperties": false
}Browsernormal access · Read only
browser_screenshot
Capture one managed browser tab as MCP ImageContent. Use browser_query for semantic page content; this is for visual inspection. full_page captures beyond the viewport where supported.
Inputs (5)
tab_idRequired- string · Exact managed tab ID from browser_list_tabs or browser_new_tab. Never an OS window ID.
formatConditional / optional- string · png | jpeg · Image format.
qualityConditional / optional- integer · JPEG quality.
full_pageConditional / optional- boolean · Capture the whole page.
request_idConditional / optional- string · Optional correlation ID for this call.
Complete input schema
{
"type": "object",
"properties": {
"tab_id": {
"type": "string",
"description": "Exact managed tab ID from browser_list_tabs or browser_new_tab. Never an OS window ID.",
"minLength": 1
},
"format": {
"type": "string",
"enum": [
"png",
"jpeg"
],
"description": "Image format.",
"default": "jpeg"
},
"quality": {
"type": "integer",
"description": "JPEG quality.",
"minimum": 1,
"maximum": 100
},
"full_page": {
"type": "boolean",
"description": "Capture the whole page.",
"default": false
},
"request_id": {
"type": "string",
"description": "Optional correlation ID for this call.",
"minLength": 1
}
},
"required": [
"tab_id"
],
"additionalProperties": false
}Browserelevated access · Changes state
browser_evaluate
Execute an explicit JavaScript expression in one managed tab and return its result. Scripts can change page state and are therefore Elevated operations. Prefer browser_query/click/type when they express the task. Inspect affected state before retrying a failed script.
Inputs (4)
tab_idRequired- string · Exact managed tab ID from browser_list_tabs or browser_new_tab. Never an OS window ID.
expressionRequired- string · JavaScript expression evaluated in the page.
request_idConditional / optional- string · Optional correlation ID for this call.
dry_runConditional / optional- boolean · Validate the request without performing the mutation. Native dry runs validate input and permission; they do not prove that a UI target still exists.
Complete input schema
{
"type": "object",
"properties": {
"tab_id": {
"type": "string",
"description": "Exact managed tab ID from browser_list_tabs or browser_new_tab. Never an OS window ID.",
"minLength": 1
},
"expression": {
"type": "string",
"description": "JavaScript expression evaluated in the page.",
"minLength": 1
},
"request_id": {
"type": "string",
"description": "Optional correlation ID for this call.",
"minLength": 1
},
"dry_run": {
"type": "boolean",
"description": "Validate the request without performing the mutation. Native dry runs validate input and permission; they do not prove that a UI target still exists.",
"default": false
}
},
"required": [
"tab_id",
"expression"
],
"additionalProperties": false
}Native UInormal access · Read only
ui_observe
Observe the accessibility tree of a selected native app/window. Returns controls and selectors to reuse in ui_* actions. Use browser_query for managed web pages and window_list for window discovery.
Inputs (9)
pidConditional / optional- integer · Process ID returned by app_list or app_get_active.
app_nameConditional / optional- string · Exact application/process name; use an absolute path if several installations share the name.
bundle_idConditional / optional- string · macOS application bundle identifier. Use only on macOS.
window_idConditional / optional- string · Exact window ID returned by window_list or window_get_active.
window_indexConditional / optional- integer · Zero-based window index for a selected app; macOS may require this with pid or bundle_id.
max_depthConditional / optional- integer · Maximum accessibility tree depth.
max_itemsConditional / optional- integer · Maximum returned elements.
compactConditional / optional- boolean · Request compact native output.
request_idConditional / optional- string · Optional correlation ID for this call.
Complete input schema
{
"type": "object",
"properties": {
"pid": {
"type": "integer",
"description": "Process ID returned by app_list or app_get_active.",
"minimum": 1
},
"app_name": {
"type": "string",
"description": "Exact application/process name; use an absolute path if several installations share the name.",
"minLength": 1
},
"bundle_id": {
"type": "string",
"description": "macOS application bundle identifier. Use only on macOS.",
"minLength": 1
},
"window_id": {
"type": "string",
"description": "Exact window ID returned by window_list or window_get_active.",
"minLength": 1
},
"window_index": {
"type": "integer",
"description": "Zero-based window index for a selected app; macOS may require this with pid or bundle_id.",
"minimum": 0
},
"max_depth": {
"type": "integer",
"description": "Maximum accessibility tree depth.",
"minimum": 0,
"maximum": 15
},
"max_items": {
"type": "integer",
"description": "Maximum returned elements.",
"minimum": 1,
"maximum": 10000
},
"compact": {
"type": "boolean",
"description": "Request compact native output.",
"default": false
},
"request_id": {
"type": "string",
"description": "Optional correlation ID for this call.",
"minLength": 1
}
},
"required": [],
"additionalProperties": false,
"anyOf": [
{
"required": [
"window_id"
]
},
{
"required": [
"pid"
]
},
{
"required": [
"app_name"
]
},
{
"required": [
"bundle_id"
]
}
]
}Native UInormal access · Read only
ui_observe_summary
Read a compact semantic summary of a selected app/window before requesting a deeper tree. Use browser_query for managed web pages and window_list for window discovery.
Inputs (9)
pidConditional / optional- integer · Process ID returned by app_list or app_get_active.
app_nameConditional / optional- string · Exact application/process name; use an absolute path if several installations share the name.
bundle_idConditional / optional- string · macOS application bundle identifier. Use only on macOS.
window_idConditional / optional- string · Exact window ID returned by window_list or window_get_active.
window_indexConditional / optional- integer · Zero-based window index for a selected app; macOS may require this with pid or bundle_id.
max_depthConditional / optional- integer · Maximum accessibility tree depth.
max_itemsConditional / optional- integer · Maximum returned elements.
compactConditional / optional- boolean · Request compact native output.
request_idConditional / optional- string · Optional correlation ID for this call.
Complete input schema
{
"type": "object",
"properties": {
"pid": {
"type": "integer",
"description": "Process ID returned by app_list or app_get_active.",
"minimum": 1
},
"app_name": {
"type": "string",
"description": "Exact application/process name; use an absolute path if several installations share the name.",
"minLength": 1
},
"bundle_id": {
"type": "string",
"description": "macOS application bundle identifier. Use only on macOS.",
"minLength": 1
},
"window_id": {
"type": "string",
"description": "Exact window ID returned by window_list or window_get_active.",
"minLength": 1
},
"window_index": {
"type": "integer",
"description": "Zero-based window index for a selected app; macOS may require this with pid or bundle_id.",
"minimum": 0
},
"max_depth": {
"type": "integer",
"description": "Maximum accessibility tree depth.",
"minimum": 0,
"maximum": 15
},
"max_items": {
"type": "integer",
"description": "Maximum returned elements.",
"minimum": 1,
"maximum": 10000
},
"compact": {
"type": "boolean",
"description": "Request compact native output.",
"default": false
},
"request_id": {
"type": "string",
"description": "Optional correlation ID for this call.",
"minLength": 1
}
},
"required": [],
"additionalProperties": false,
"anyOf": [
{
"required": [
"window_id"
]
},
{
"required": [
"pid"
]
},
{
"required": [
"app_name"
]
},
{
"required": [
"bundle_id"
]
}
]
}Native UInormal access · Read only
ui_observe_changes
Observe current semantic state with change information where the backend supports it. Inspect returned state rather than assuming change tracking is identical across OSes. Use browser_query for managed web pages and window_list for window discovery.
Inputs (9)
pidConditional / optional- integer · Process ID returned by app_list or app_get_active.
app_nameConditional / optional- string · Exact application/process name; use an absolute path if several installations share the name.
bundle_idConditional / optional- string · macOS application bundle identifier. Use only on macOS.
window_idConditional / optional- string · Exact window ID returned by window_list or window_get_active.
window_indexConditional / optional- integer · Zero-based window index for a selected app; macOS may require this with pid or bundle_id.
max_depthConditional / optional- integer · Maximum accessibility tree depth.
max_itemsConditional / optional- integer · Maximum returned elements.
compactConditional / optional- boolean · Request compact native output.
request_idConditional / optional- string · Optional correlation ID for this call.
Complete input schema
{
"type": "object",
"properties": {
"pid": {
"type": "integer",
"description": "Process ID returned by app_list or app_get_active.",
"minimum": 1
},
"app_name": {
"type": "string",
"description": "Exact application/process name; use an absolute path if several installations share the name.",
"minLength": 1
},
"bundle_id": {
"type": "string",
"description": "macOS application bundle identifier. Use only on macOS.",
"minLength": 1
},
"window_id": {
"type": "string",
"description": "Exact window ID returned by window_list or window_get_active.",
"minLength": 1
},
"window_index": {
"type": "integer",
"description": "Zero-based window index for a selected app; macOS may require this with pid or bundle_id.",
"minimum": 0
},
"max_depth": {
"type": "integer",
"description": "Maximum accessibility tree depth.",
"minimum": 0,
"maximum": 15
},
"max_items": {
"type": "integer",
"description": "Maximum returned elements.",
"minimum": 1,
"maximum": 10000
},
"compact": {
"type": "boolean",
"description": "Request compact native output.",
"default": false
},
"request_id": {
"type": "string",
"description": "Optional correlation ID for this call.",
"minLength": 1
}
},
"required": [],
"additionalProperties": false,
"anyOf": [
{
"required": [
"window_id"
]
},
{
"required": [
"pid"
]
},
{
"required": [
"app_name"
]
},
{
"required": [
"bundle_id"
]
}
]
}Native UInormal access · Read only
ui_inspect
Inspect semantic element records in a selected native app/window. Use bounded max_items/max_depth and reuse the returned identifiers. Use browser_query for managed web pages and window_list for window discovery.
Inputs (9)
pidConditional / optional- integer · Process ID returned by app_list or app_get_active.
app_nameConditional / optional- string · Exact application/process name; use an absolute path if several installations share the name.
bundle_idConditional / optional- string · macOS application bundle identifier. Use only on macOS.
window_idConditional / optional- string · Exact window ID returned by window_list or window_get_active.
window_indexConditional / optional- integer · Zero-based window index for a selected app; macOS may require this with pid or bundle_id.
max_depthConditional / optional- integer · Maximum accessibility tree depth.
max_itemsConditional / optional- integer · Maximum returned elements.
compactConditional / optional- boolean · Request compact native output.
request_idConditional / optional- string · Optional correlation ID for this call.
Complete input schema
{
"type": "object",
"properties": {
"pid": {
"type": "integer",
"description": "Process ID returned by app_list or app_get_active.",
"minimum": 1
},
"app_name": {
"type": "string",
"description": "Exact application/process name; use an absolute path if several installations share the name.",
"minLength": 1
},
"bundle_id": {
"type": "string",
"description": "macOS application bundle identifier. Use only on macOS.",
"minLength": 1
},
"window_id": {
"type": "string",
"description": "Exact window ID returned by window_list or window_get_active.",
"minLength": 1
},
"window_index": {
"type": "integer",
"description": "Zero-based window index for a selected app; macOS may require this with pid or bundle_id.",
"minimum": 0
},
"max_depth": {
"type": "integer",
"description": "Maximum accessibility tree depth.",
"minimum": 0,
"maximum": 15
},
"max_items": {
"type": "integer",
"description": "Maximum returned elements.",
"minimum": 1,
"maximum": 10000
},
"compact": {
"type": "boolean",
"description": "Request compact native output.",
"default": false
},
"request_id": {
"type": "string",
"description": "Optional correlation ID for this call.",
"minLength": 1
}
},
"required": [],
"additionalProperties": false,
"anyOf": [
{
"required": [
"window_id"
]
},
{
"required": [
"pid"
]
},
{
"required": [
"app_name"
]
},
{
"required": [
"bundle_id"
]
}
]
}Native UInormal access · Read only
ui_find
Find a native control by semantic selector within an app/window. Reuse the returned element_id for ui_click/ui_set_value. Selector fields vary by OS; prefer a stable identifier or exact visible label.
Inputs (9)
pidConditional / optional- integer · Process ID returned by app_list or app_get_active.
app_nameConditional / optional- string · Exact application/process name; use an absolute path if several installations share the name.
bundle_idConditional / optional- string · macOS application bundle identifier. Use only on macOS.
window_idConditional / optional- string · Exact window ID returned by window_list or window_get_active.
window_indexConditional / optional- integer · Zero-based window index for a selected app; macOS may require this with pid or bundle_id.
selectorRequired- object
max_depthConditional / optional- integer · Maximum accessibility tree depth.
max_itemsConditional / optional- integer · Maximum returned elements.
request_idConditional / optional- string · Optional correlation ID for this call.
Complete input schema
{
"type": "object",
"properties": {
"pid": {
"type": "integer",
"description": "Process ID returned by app_list or app_get_active.",
"minimum": 1
},
"app_name": {
"type": "string",
"description": "Exact application/process name; use an absolute path if several installations share the name.",
"minLength": 1
},
"bundle_id": {
"type": "string",
"description": "macOS application bundle identifier. Use only on macOS.",
"minLength": 1
},
"window_id": {
"type": "string",
"description": "Exact window ID returned by window_list or window_get_active.",
"minLength": 1
},
"window_index": {
"type": "integer",
"description": "Zero-based window index for a selected app; macOS may require this with pid or bundle_id.",
"minimum": 0
},
"selector": {
"type": "object",
"properties": {
"element_id": {
"type": "string",
"description": "Exact element ID from ui_observe, ui_inspect or ui_find.",
"minLength": 1
},
"automation_id": {
"type": "string",
"description": "Windows UI Automation identifier.",
"minLength": 1
},
"identifier": {
"type": "string",
"description": "macOS accessibility identifier.",
"minLength": 1
},
"title": {
"type": "string",
"description": "Exact element title.",
"minLength": 1
},
"name": {
"type": "string",
"description": "Exact Windows element name.",
"minLength": 1
},
"role": {
"type": "string",
"description": "Native role, such as AXButton on macOS.",
"minLength": 1
},
"label_or_text": {
"type": "string",
"description": "Visible element label/text.",
"minLength": 1
},
"index": {
"type": "integer",
"description": "Zero-based matching-element index.",
"minimum": 0
}
},
"required": [],
"additionalProperties": false,
"minProperties": 1
},
"max_depth": {
"type": "integer",
"description": "Maximum accessibility tree depth.",
"minimum": 0,
"maximum": 15
},
"max_items": {
"type": "integer",
"description": "Maximum returned elements.",
"minimum": 1,
"maximum": 10000
},
"request_id": {
"type": "string",
"description": "Optional correlation ID for this call.",
"minLength": 1
}
},
"required": [
"selector"
],
"additionalProperties": false,
"anyOf": [
{
"required": [
"window_id"
]
},
{
"required": [
"pid"
]
},
{
"required": [
"app_name"
]
},
{
"required": [
"bundle_id"
]
}
]
}Native UInormal access · Read only
ui_read_value
Read the current value of one native control. Use an element_id or selector from the latest ui_observe/ui_find result; app/window context disambiguates the target.
Inputs (8)
pidConditional / optional- integer · Process ID returned by app_list or app_get_active.
app_nameConditional / optional- string · Exact application/process name; use an absolute path if several installations share the name.
bundle_idConditional / optional- string · macOS application bundle identifier. Use only on macOS.
window_idConditional / optional- string · Exact window ID returned by window_list or window_get_active.
window_indexConditional / optional- integer · Zero-based window index for a selected app; macOS may require this with pid or bundle_id.
element_idConditional / optional- string · Reuse an element ID from the most recent ui_observe/ui_find/ui_inspect result. Never invent IDs.
selectorConditional / optional- object
request_idConditional / optional- string · Optional correlation ID for this call.
Complete input schema
{
"type": "object",
"properties": {
"pid": {
"type": "integer",
"description": "Process ID returned by app_list or app_get_active.",
"minimum": 1
},
"app_name": {
"type": "string",
"description": "Exact application/process name; use an absolute path if several installations share the name.",
"minLength": 1
},
"bundle_id": {
"type": "string",
"description": "macOS application bundle identifier. Use only on macOS.",
"minLength": 1
},
"window_id": {
"type": "string",
"description": "Exact window ID returned by window_list or window_get_active.",
"minLength": 1
},
"window_index": {
"type": "integer",
"description": "Zero-based window index for a selected app; macOS may require this with pid or bundle_id.",
"minimum": 0
},
"element_id": {
"type": "string",
"description": "Reuse an element ID from the most recent ui_observe/ui_find/ui_inspect result. Never invent IDs.",
"minLength": 1
},
"selector": {
"type": "object",
"properties": {
"element_id": {
"type": "string",
"description": "Exact element ID from ui_observe, ui_inspect or ui_find.",
"minLength": 1
},
"automation_id": {
"type": "string",
"description": "Windows UI Automation identifier.",
"minLength": 1
},
"identifier": {
"type": "string",
"description": "macOS accessibility identifier.",
"minLength": 1
},
"title": {
"type": "string",
"description": "Exact element title.",
"minLength": 1
},
"name": {
"type": "string",
"description": "Exact Windows element name.",
"minLength": 1
},
"role": {
"type": "string",
"description": "Native role, such as AXButton on macOS.",
"minLength": 1
},
"label_or_text": {
"type": "string",
"description": "Visible element label/text.",
"minLength": 1
},
"index": {
"type": "integer",
"description": "Zero-based matching-element index.",
"minimum": 0
}
},
"required": [],
"additionalProperties": false,
"minProperties": 1
},
"request_id": {
"type": "string",
"description": "Optional correlation ID for this call.",
"minLength": 1
}
},
"required": [],
"additionalProperties": false,
"anyOf": [
{
"required": [
"element_id"
]
},
{
"required": [
"selector"
]
}
],
"allOf": [
{
"anyOf": [
{
"required": [
"window_id"
]
},
{
"required": [
"pid"
]
},
{
"required": [
"app_name"
]
},
{
"required": [
"bundle_id"
]
}
]
}
]
}Native UIelevated access · Changes state
ui_click
Click one semantic native control. The action may submit or navigate, so observe the resulting state before repeating. Use an element_id or selector from the latest ui_observe/ui_find result; app/window context disambiguates the target.
Inputs (9)
pidConditional / optional- integer · Process ID returned by app_list or app_get_active.
app_nameConditional / optional- string · Exact application/process name; use an absolute path if several installations share the name.
bundle_idConditional / optional- string · macOS application bundle identifier. Use only on macOS.
window_idConditional / optional- string · Exact window ID returned by window_list or window_get_active.
window_indexConditional / optional- integer · Zero-based window index for a selected app; macOS may require this with pid or bundle_id.
element_idConditional / optional- string · Reuse an element ID from the most recent ui_observe/ui_find/ui_inspect result. Never invent IDs.
selectorConditional / optional- object
request_idConditional / optional- string · Optional correlation ID for this call.
dry_runConditional / optional- boolean · Validate the request without performing the mutation. Native dry runs validate input and permission; they do not prove that a UI target still exists.
Complete input schema
{
"type": "object",
"properties": {
"pid": {
"type": "integer",
"description": "Process ID returned by app_list or app_get_active.",
"minimum": 1
},
"app_name": {
"type": "string",
"description": "Exact application/process name; use an absolute path if several installations share the name.",
"minLength": 1
},
"bundle_id": {
"type": "string",
"description": "macOS application bundle identifier. Use only on macOS.",
"minLength": 1
},
"window_id": {
"type": "string",
"description": "Exact window ID returned by window_list or window_get_active.",
"minLength": 1
},
"window_index": {
"type": "integer",
"description": "Zero-based window index for a selected app; macOS may require this with pid or bundle_id.",
"minimum": 0
},
"element_id": {
"type": "string",
"description": "Reuse an element ID from the most recent ui_observe/ui_find/ui_inspect result. Never invent IDs.",
"minLength": 1
},
"selector": {
"type": "object",
"properties": {
"element_id": {
"type": "string",
"description": "Exact element ID from ui_observe, ui_inspect or ui_find.",
"minLength": 1
},
"automation_id": {
"type": "string",
"description": "Windows UI Automation identifier.",
"minLength": 1
},
"identifier": {
"type": "string",
"description": "macOS accessibility identifier.",
"minLength": 1
},
"title": {
"type": "string",
"description": "Exact element title.",
"minLength": 1
},
"name": {
"type": "string",
"description": "Exact Windows element name.",
"minLength": 1
},
"role": {
"type": "string",
"description": "Native role, such as AXButton on macOS.",
"minLength": 1
},
"label_or_text": {
"type": "string",
"description": "Visible element label/text.",
"minLength": 1
},
"index": {
"type": "integer",
"description": "Zero-based matching-element index.",
"minimum": 0
}
},
"required": [],
"additionalProperties": false,
"minProperties": 1
},
"request_id": {
"type": "string",
"description": "Optional correlation ID for this call.",
"minLength": 1
},
"dry_run": {
"type": "boolean",
"description": "Validate the request without performing the mutation. Native dry runs validate input and permission; they do not prove that a UI target still exists.",
"default": false
}
},
"required": [],
"additionalProperties": false,
"anyOf": [
{
"required": [
"element_id"
]
},
{
"required": [
"selector"
]
}
],
"allOf": [
{
"anyOf": [
{
"required": [
"window_id"
]
},
{
"required": [
"pid"
]
},
{
"required": [
"app_name"
]
},
{
"required": [
"bundle_id"
]
}
]
}
]
}Native UIelevated access · Changes state
ui_focus
Give keyboard focus to one native control. Use an element_id or selector from the latest ui_observe/ui_find result; app/window context disambiguates the target.
Inputs (9)
pidConditional / optional- integer · Process ID returned by app_list or app_get_active.
app_nameConditional / optional- string · Exact application/process name; use an absolute path if several installations share the name.
bundle_idConditional / optional- string · macOS application bundle identifier. Use only on macOS.
window_idConditional / optional- string · Exact window ID returned by window_list or window_get_active.
window_indexConditional / optional- integer · Zero-based window index for a selected app; macOS may require this with pid or bundle_id.
element_idConditional / optional- string · Reuse an element ID from the most recent ui_observe/ui_find/ui_inspect result. Never invent IDs.
selectorConditional / optional- object
request_idConditional / optional- string · Optional correlation ID for this call.
dry_runConditional / optional- boolean · Validate the request without performing the mutation. Native dry runs validate input and permission; they do not prove that a UI target still exists.
Complete input schema
{
"type": "object",
"properties": {
"pid": {
"type": "integer",
"description": "Process ID returned by app_list or app_get_active.",
"minimum": 1
},
"app_name": {
"type": "string",
"description": "Exact application/process name; use an absolute path if several installations share the name.",
"minLength": 1
},
"bundle_id": {
"type": "string",
"description": "macOS application bundle identifier. Use only on macOS.",
"minLength": 1
},
"window_id": {
"type": "string",
"description": "Exact window ID returned by window_list or window_get_active.",
"minLength": 1
},
"window_index": {
"type": "integer",
"description": "Zero-based window index for a selected app; macOS may require this with pid or bundle_id.",
"minimum": 0
},
"element_id": {
"type": "string",
"description": "Reuse an element ID from the most recent ui_observe/ui_find/ui_inspect result. Never invent IDs.",
"minLength": 1
},
"selector": {
"type": "object",
"properties": {
"element_id": {
"type": "string",
"description": "Exact element ID from ui_observe, ui_inspect or ui_find.",
"minLength": 1
},
"automation_id": {
"type": "string",
"description": "Windows UI Automation identifier.",
"minLength": 1
},
"identifier": {
"type": "string",
"description": "macOS accessibility identifier.",
"minLength": 1
},
"title": {
"type": "string",
"description": "Exact element title.",
"minLength": 1
},
"name": {
"type": "string",
"description": "Exact Windows element name.",
"minLength": 1
},
"role": {
"type": "string",
"description": "Native role, such as AXButton on macOS.",
"minLength": 1
},
"label_or_text": {
"type": "string",
"description": "Visible element label/text.",
"minLength": 1
},
"index": {
"type": "integer",
"description": "Zero-based matching-element index.",
"minimum": 0
}
},
"required": [],
"additionalProperties": false,
"minProperties": 1
},
"request_id": {
"type": "string",
"description": "Optional correlation ID for this call.",
"minLength": 1
},
"dry_run": {
"type": "boolean",
"description": "Validate the request without performing the mutation. Native dry runs validate input and permission; they do not prove that a UI target still exists.",
"default": false
}
},
"required": [],
"additionalProperties": false,
"anyOf": [
{
"required": [
"element_id"
]
},
{
"required": [
"selector"
]
}
],
"allOf": [
{
"anyOf": [
{
"required": [
"window_id"
]
},
{
"required": [
"pid"
]
},
{
"required": [
"app_name"
]
},
{
"required": [
"bundle_id"
]
}
]
}
]
}Native UIelevated access · Changes state
ui_set_value
Set the value of one editable native control. Supply the complete intended value; empty text clears it. Use an element_id or selector from the latest ui_observe/ui_find result; app/window context disambiguates the target.
Inputs (10)
pidConditional / optional- integer · Process ID returned by app_list or app_get_active.
app_nameConditional / optional- string · Exact application/process name; use an absolute path if several installations share the name.
bundle_idConditional / optional- string · macOS application bundle identifier. Use only on macOS.
window_idConditional / optional- string · Exact window ID returned by window_list or window_get_active.
window_indexConditional / optional- integer · Zero-based window index for a selected app; macOS may require this with pid or bundle_id.
element_idConditional / optional- string · Reuse an element ID from the most recent ui_observe/ui_find/ui_inspect result. Never invent IDs.
selectorConditional / optional- object
valueRequired- string · Complete new control value.
request_idConditional / optional- string · Optional correlation ID for this call.
dry_runConditional / optional- boolean · Validate the request without performing the mutation. Native dry runs validate input and permission; they do not prove that a UI target still exists.
Complete input schema
{
"type": "object",
"properties": {
"pid": {
"type": "integer",
"description": "Process ID returned by app_list or app_get_active.",
"minimum": 1
},
"app_name": {
"type": "string",
"description": "Exact application/process name; use an absolute path if several installations share the name.",
"minLength": 1
},
"bundle_id": {
"type": "string",
"description": "macOS application bundle identifier. Use only on macOS.",
"minLength": 1
},
"window_id": {
"type": "string",
"description": "Exact window ID returned by window_list or window_get_active.",
"minLength": 1
},
"window_index": {
"type": "integer",
"description": "Zero-based window index for a selected app; macOS may require this with pid or bundle_id.",
"minimum": 0
},
"element_id": {
"type": "string",
"description": "Reuse an element ID from the most recent ui_observe/ui_find/ui_inspect result. Never invent IDs.",
"minLength": 1
},
"selector": {
"type": "object",
"properties": {
"element_id": {
"type": "string",
"description": "Exact element ID from ui_observe, ui_inspect or ui_find.",
"minLength": 1
},
"automation_id": {
"type": "string",
"description": "Windows UI Automation identifier.",
"minLength": 1
},
"identifier": {
"type": "string",
"description": "macOS accessibility identifier.",
"minLength": 1
},
"title": {
"type": "string",
"description": "Exact element title.",
"minLength": 1
},
"name": {
"type": "string",
"description": "Exact Windows element name.",
"minLength": 1
},
"role": {
"type": "string",
"description": "Native role, such as AXButton on macOS.",
"minLength": 1
},
"label_or_text": {
"type": "string",
"description": "Visible element label/text.",
"minLength": 1
},
"index": {
"type": "integer",
"description": "Zero-based matching-element index.",
"minimum": 0
}
},
"required": [],
"additionalProperties": false,
"minProperties": 1
},
"value": {
"type": "string",
"description": "Complete new control value."
},
"request_id": {
"type": "string",
"description": "Optional correlation ID for this call.",
"minLength": 1
},
"dry_run": {
"type": "boolean",
"description": "Validate the request without performing the mutation. Native dry runs validate input and permission; they do not prove that a UI target still exists.",
"default": false
}
},
"required": [
"value"
],
"additionalProperties": false,
"anyOf": [
{
"required": [
"element_id"
]
},
{
"required": [
"selector"
]
}
],
"allOf": [
{
"anyOf": [
{
"required": [
"window_id"
]
},
{
"required": [
"pid"
]
},
{
"required": [
"app_name"
]
},
{
"required": [
"bundle_id"
]
}
]
}
]
}Native UIelevated access · Changes state
ui_select
Select one native list/menu control identified by its semantic selector. Use an element_id or selector from the latest ui_observe/ui_find result; app/window context disambiguates the target.
Inputs (9)
pidConditional / optional- integer · Process ID returned by app_list or app_get_active.
app_nameConditional / optional- string · Exact application/process name; use an absolute path if several installations share the name.
bundle_idConditional / optional- string · macOS application bundle identifier. Use only on macOS.
window_idConditional / optional- string · Exact window ID returned by window_list or window_get_active.
window_indexConditional / optional- integer · Zero-based window index for a selected app; macOS may require this with pid or bundle_id.
element_idConditional / optional- string · Reuse an element ID from the most recent ui_observe/ui_find/ui_inspect result. Never invent IDs.
selectorConditional / optional- object
request_idConditional / optional- string · Optional correlation ID for this call.
dry_runConditional / optional- boolean · Validate the request without performing the mutation. Native dry runs validate input and permission; they do not prove that a UI target still exists.
Complete input schema
{
"type": "object",
"properties": {
"pid": {
"type": "integer",
"description": "Process ID returned by app_list or app_get_active.",
"minimum": 1
},
"app_name": {
"type": "string",
"description": "Exact application/process name; use an absolute path if several installations share the name.",
"minLength": 1
},
"bundle_id": {
"type": "string",
"description": "macOS application bundle identifier. Use only on macOS.",
"minLength": 1
},
"window_id": {
"type": "string",
"description": "Exact window ID returned by window_list or window_get_active.",
"minLength": 1
},
"window_index": {
"type": "integer",
"description": "Zero-based window index for a selected app; macOS may require this with pid or bundle_id.",
"minimum": 0
},
"element_id": {
"type": "string",
"description": "Reuse an element ID from the most recent ui_observe/ui_find/ui_inspect result. Never invent IDs.",
"minLength": 1
},
"selector": {
"type": "object",
"properties": {
"element_id": {
"type": "string",
"description": "Exact element ID from ui_observe, ui_inspect or ui_find.",
"minLength": 1
},
"automation_id": {
"type": "string",
"description": "Windows UI Automation identifier.",
"minLength": 1
},
"identifier": {
"type": "string",
"description": "macOS accessibility identifier.",
"minLength": 1
},
"title": {
"type": "string",
"description": "Exact element title.",
"minLength": 1
},
"name": {
"type": "string",
"description": "Exact Windows element name.",
"minLength": 1
},
"role": {
"type": "string",
"description": "Native role, such as AXButton on macOS.",
"minLength": 1
},
"label_or_text": {
"type": "string",
"description": "Visible element label/text.",
"minLength": 1
},
"index": {
"type": "integer",
"description": "Zero-based matching-element index.",
"minimum": 0
}
},
"required": [],
"additionalProperties": false,
"minProperties": 1
},
"request_id": {
"type": "string",
"description": "Optional correlation ID for this call.",
"minLength": 1
},
"dry_run": {
"type": "boolean",
"description": "Validate the request without performing the mutation. Native dry runs validate input and permission; they do not prove that a UI target still exists.",
"default": false
}
},
"required": [],
"additionalProperties": false,
"anyOf": [
{
"required": [
"element_id"
]
},
{
"required": [
"selector"
]
}
],
"allOf": [
{
"anyOf": [
{
"required": [
"window_id"
]
},
{
"required": [
"pid"
]
},
{
"required": [
"app_name"
]
},
{
"required": [
"bundle_id"
]
}
]
}
]
}Native UIelevated access · Changes state
ui_menu_select
Activate one native menu item identified by its semantic selector. Observe/open the relevant menu first. Use an element_id or selector from the latest ui_observe/ui_find result; app/window context disambiguates the target.
Inputs (9)
pidConditional / optional- integer · Process ID returned by app_list or app_get_active.
app_nameConditional / optional- string · Exact application/process name; use an absolute path if several installations share the name.
bundle_idConditional / optional- string · macOS application bundle identifier. Use only on macOS.
window_idConditional / optional- string · Exact window ID returned by window_list or window_get_active.
window_indexConditional / optional- integer · Zero-based window index for a selected app; macOS may require this with pid or bundle_id.
element_idConditional / optional- string · Reuse an element ID from the most recent ui_observe/ui_find/ui_inspect result. Never invent IDs.
selectorConditional / optional- object
request_idConditional / optional- string · Optional correlation ID for this call.
dry_runConditional / optional- boolean · Validate the request without performing the mutation. Native dry runs validate input and permission; they do not prove that a UI target still exists.
Complete input schema
{
"type": "object",
"properties": {
"pid": {
"type": "integer",
"description": "Process ID returned by app_list or app_get_active.",
"minimum": 1
},
"app_name": {
"type": "string",
"description": "Exact application/process name; use an absolute path if several installations share the name.",
"minLength": 1
},
"bundle_id": {
"type": "string",
"description": "macOS application bundle identifier. Use only on macOS.",
"minLength": 1
},
"window_id": {
"type": "string",
"description": "Exact window ID returned by window_list or window_get_active.",
"minLength": 1
},
"window_index": {
"type": "integer",
"description": "Zero-based window index for a selected app; macOS may require this with pid or bundle_id.",
"minimum": 0
},
"element_id": {
"type": "string",
"description": "Reuse an element ID from the most recent ui_observe/ui_find/ui_inspect result. Never invent IDs.",
"minLength": 1
},
"selector": {
"type": "object",
"properties": {
"element_id": {
"type": "string",
"description": "Exact element ID from ui_observe, ui_inspect or ui_find.",
"minLength": 1
},
"automation_id": {
"type": "string",
"description": "Windows UI Automation identifier.",
"minLength": 1
},
"identifier": {
"type": "string",
"description": "macOS accessibility identifier.",
"minLength": 1
},
"title": {
"type": "string",
"description": "Exact element title.",
"minLength": 1
},
"name": {
"type": "string",
"description": "Exact Windows element name.",
"minLength": 1
},
"role": {
"type": "string",
"description": "Native role, such as AXButton on macOS.",
"minLength": 1
},
"label_or_text": {
"type": "string",
"description": "Visible element label/text.",
"minLength": 1
},
"index": {
"type": "integer",
"description": "Zero-based matching-element index.",
"minimum": 0
}
},
"required": [],
"additionalProperties": false,
"minProperties": 1
},
"request_id": {
"type": "string",
"description": "Optional correlation ID for this call.",
"minLength": 1
},
"dry_run": {
"type": "boolean",
"description": "Validate the request without performing the mutation. Native dry runs validate input and permission; they do not prove that a UI target still exists.",
"default": false
}
},
"required": [],
"additionalProperties": false,
"anyOf": [
{
"required": [
"element_id"
]
},
{
"required": [
"selector"
]
}
],
"allOf": [
{
"anyOf": [
{
"required": [
"window_id"
]
},
{
"required": [
"pid"
]
},
{
"required": [
"app_name"
]
},
{
"required": [
"bundle_id"
]
}
]
}
]
}Inputelevated access · Changes state
keyboard_type
Type text into the focused control using native input. Use only when browser_* or ui_* cannot express the operation. Focus the intended app/control and refresh stale screen coordinates before acting.
Inputs (3)
textRequired- string · Exact text to type.
request_idConditional / optional- string · Optional correlation ID for this call.
dry_runConditional / optional- boolean · Validate the request without performing the mutation. Native dry runs validate input and permission; they do not prove that a UI target still exists.
Complete input schema
{
"type": "object",
"properties": {
"text": {
"type": "string",
"description": "Exact text to type."
},
"request_id": {
"type": "string",
"description": "Optional correlation ID for this call.",
"minLength": 1
},
"dry_run": {
"type": "boolean",
"description": "Validate the request without performing the mutation. Native dry runs validate input and permission; they do not prove that a UI target still exists.",
"default": false
}
},
"required": [
"text"
],
"additionalProperties": false
}Inputelevated access · Changes state
keyboard_paste
Paste text into the focused control via the clipboard. The original clipboard is restored by default. Use only when browser_* or ui_* cannot express the operation. Focus the intended app/control and refresh stale screen coordinates before acting.
Inputs (4)
textRequired- string · Exact text to paste.
restore_clipboardConditional / optional- boolean · Restore the original clipboard after pasting.
request_idConditional / optional- string · Optional correlation ID for this call.
dry_runConditional / optional- boolean · Validate the request without performing the mutation. Native dry runs validate input and permission; they do not prove that a UI target still exists.
Complete input schema
{
"type": "object",
"properties": {
"text": {
"type": "string",
"description": "Exact text to paste."
},
"restore_clipboard": {
"type": "boolean",
"description": "Restore the original clipboard after pasting.",
"default": true
},
"request_id": {
"type": "string",
"description": "Optional correlation ID for this call.",
"minLength": 1
},
"dry_run": {
"type": "boolean",
"description": "Validate the request without performing the mutation. Native dry runs validate input and permission; they do not prove that a UI target still exists.",
"default": false
}
},
"required": [
"text"
],
"additionalProperties": false
}Inputelevated access · Changes state
keyboard_press
Press and release one key. Use only when browser_* or ui_* cannot express the operation. Focus the intended app/control and refresh stale screen coordinates before acting.
Inputs (3)
keyRequired- string · Native key name such as Return, Tab or Escape.
request_idConditional / optional- string · Optional correlation ID for this call.
dry_runConditional / optional- boolean · Validate the request without performing the mutation. Native dry runs validate input and permission; they do not prove that a UI target still exists.
Complete input schema
{
"type": "object",
"properties": {
"key": {
"type": "string",
"description": "Native key name such as Return, Tab or Escape.",
"minLength": 1
},
"request_id": {
"type": "string",
"description": "Optional correlation ID for this call.",
"minLength": 1
},
"dry_run": {
"type": "boolean",
"description": "Validate the request without performing the mutation. Native dry runs validate input and permission; they do not prove that a UI target still exists.",
"default": false
}
},
"required": [
"key"
],
"additionalProperties": false
}Inputelevated access · Changes state
keyboard_hotkey
Press and release a key combination. Put modifiers first and the ordinary key last. Use only when browser_* or ui_* cannot express the operation. Focus the intended app/control and refresh stale screen coordinates before acting.
Inputs (3)
keysRequired- array · Ordered combination, e.g. [control, shift, s].
request_idConditional / optional- string · Optional correlation ID for this call.
dry_runConditional / optional- boolean · Validate the request without performing the mutation. Native dry runs validate input and permission; they do not prove that a UI target still exists.
Complete input schema
{
"type": "object",
"properties": {
"keys": {
"type": "array",
"items": {
"type": "string",
"description": "Modifier/key name such as control, shift, command or c.",
"minLength": 1
},
"description": "Ordered combination, e.g. [control, shift, s].",
"minItems": 1,
"maxItems": 8
},
"request_id": {
"type": "string",
"description": "Optional correlation ID for this call.",
"minLength": 1
},
"dry_run": {
"type": "boolean",
"description": "Validate the request without performing the mutation. Native dry runs validate input and permission; they do not prove that a UI target still exists.",
"default": false
}
},
"required": [
"keys"
],
"additionalProperties": false
}Inputelevated access · Changes state
keyboard_key_down
Hold one key down. Pair this with keyboard_key_up; input_release_all is the recovery action. Use only when browser_* or ui_* cannot express the operation. Focus the intended app/control and refresh stale screen coordinates before acting.
Inputs (3)
keyRequired- string · Native key name.
request_idConditional / optional- string · Optional correlation ID for this call.
dry_runConditional / optional- boolean · Validate the request without performing the mutation. Native dry runs validate input and permission; they do not prove that a UI target still exists.
Complete input schema
{
"type": "object",
"properties": {
"key": {
"type": "string",
"description": "Native key name.",
"minLength": 1
},
"request_id": {
"type": "string",
"description": "Optional correlation ID for this call.",
"minLength": 1
},
"dry_run": {
"type": "boolean",
"description": "Validate the request without performing the mutation. Native dry runs validate input and permission; they do not prove that a UI target still exists.",
"default": false
}
},
"required": [
"key"
],
"additionalProperties": false
}Inputelevated access · Changes state
keyboard_key_up
Release a previously held key. Use only when browser_* or ui_* cannot express the operation. Focus the intended app/control and refresh stale screen coordinates before acting.
Inputs (3)
keyRequired- string · Native key name.
request_idConditional / optional- string · Optional correlation ID for this call.
dry_runConditional / optional- boolean · Validate the request without performing the mutation. Native dry runs validate input and permission; they do not prove that a UI target still exists.
Complete input schema
{
"type": "object",
"properties": {
"key": {
"type": "string",
"description": "Native key name.",
"minLength": 1
},
"request_id": {
"type": "string",
"description": "Optional correlation ID for this call.",
"minLength": 1
},
"dry_run": {
"type": "boolean",
"description": "Validate the request without performing the mutation. Native dry runs validate input and permission; they do not prove that a UI target still exists.",
"default": false
}
},
"required": [
"key"
],
"additionalProperties": false
}Inputelevated access · Changes state
pointer_move
Move the pointer to explicit desktop coordinates. Use only when browser_* or ui_* cannot express the operation. Focus the intended app/control and refresh stale screen coordinates before acting.
Inputs (4)
xRequired- integer · Desktop X.
yRequired- integer · Desktop Y.
request_idConditional / optional- string · Optional correlation ID for this call.
dry_runConditional / optional- boolean · Validate the request without performing the mutation. Native dry runs validate input and permission; they do not prove that a UI target still exists.
Complete input schema
{
"type": "object",
"properties": {
"x": {
"type": "integer",
"description": "Desktop X."
},
"y": {
"type": "integer",
"description": "Desktop Y."
},
"request_id": {
"type": "string",
"description": "Optional correlation ID for this call.",
"minLength": 1
},
"dry_run": {
"type": "boolean",
"description": "Validate the request without performing the mutation. Native dry runs validate input and permission; they do not prove that a UI target still exists.",
"default": false
}
},
"required": [
"x",
"y"
],
"additionalProperties": false
}Inputelevated access · Changes state
pointer_click
Left-click explicit desktop coordinates. Use only when browser_* or ui_* cannot express the operation. Focus the intended app/control and refresh stale screen coordinates before acting.
Inputs (4)
xRequired- integer · Desktop X.
yRequired- integer · Desktop Y.
request_idConditional / optional- string · Optional correlation ID for this call.
dry_runConditional / optional- boolean · Validate the request without performing the mutation. Native dry runs validate input and permission; they do not prove that a UI target still exists.
Complete input schema
{
"type": "object",
"properties": {
"x": {
"type": "integer",
"description": "Desktop X."
},
"y": {
"type": "integer",
"description": "Desktop Y."
},
"request_id": {
"type": "string",
"description": "Optional correlation ID for this call.",
"minLength": 1
},
"dry_run": {
"type": "boolean",
"description": "Validate the request without performing the mutation. Native dry runs validate input and permission; they do not prove that a UI target still exists.",
"default": false
}
},
"required": [
"x",
"y"
],
"additionalProperties": false
}Inputelevated access · Changes state
pointer_double_click
Double-left-click explicit desktop coordinates. Use only when browser_* or ui_* cannot express the operation. Focus the intended app/control and refresh stale screen coordinates before acting.
Inputs (4)
xRequired- integer · Desktop X.
yRequired- integer · Desktop Y.
request_idConditional / optional- string · Optional correlation ID for this call.
dry_runConditional / optional- boolean · Validate the request without performing the mutation. Native dry runs validate input and permission; they do not prove that a UI target still exists.
Complete input schema
{
"type": "object",
"properties": {
"x": {
"type": "integer",
"description": "Desktop X."
},
"y": {
"type": "integer",
"description": "Desktop Y."
},
"request_id": {
"type": "string",
"description": "Optional correlation ID for this call.",
"minLength": 1
},
"dry_run": {
"type": "boolean",
"description": "Validate the request without performing the mutation. Native dry runs validate input and permission; they do not prove that a UI target still exists.",
"default": false
}
},
"required": [
"x",
"y"
],
"additionalProperties": false
}Inputelevated access · Changes state
pointer_right_click
Right-click explicit desktop coordinates. Use only when browser_* or ui_* cannot express the operation. Focus the intended app/control and refresh stale screen coordinates before acting.
Inputs (4)
xRequired- integer · Desktop X.
yRequired- integer · Desktop Y.
request_idConditional / optional- string · Optional correlation ID for this call.
dry_runConditional / optional- boolean · Validate the request without performing the mutation. Native dry runs validate input and permission; they do not prove that a UI target still exists.
Complete input schema
{
"type": "object",
"properties": {
"x": {
"type": "integer",
"description": "Desktop X."
},
"y": {
"type": "integer",
"description": "Desktop Y."
},
"request_id": {
"type": "string",
"description": "Optional correlation ID for this call.",
"minLength": 1
},
"dry_run": {
"type": "boolean",
"description": "Validate the request without performing the mutation. Native dry runs validate input and permission; they do not prove that a UI target still exists.",
"default": false
}
},
"required": [
"x",
"y"
],
"additionalProperties": false
}Inputelevated access · Changes state
pointer_drag
Drag the left mouse button between explicit desktop points. Use only when browser_* or ui_* cannot express the operation. Focus the intended app/control and refresh stale screen coordinates before acting.
Inputs (5)
fromRequired- object
toRequired- object
duration_secondsConditional / optional- number · Drag duration where supported.
request_idConditional / optional- string · Optional correlation ID for this call.
dry_runConditional / optional- boolean · Validate the request without performing the mutation. Native dry runs validate input and permission; they do not prove that a UI target still exists.
Complete input schema
{
"type": "object",
"properties": {
"from": {
"type": "object",
"properties": {
"x": {
"type": "integer",
"description": "Horizontal desktop coordinate."
},
"y": {
"type": "integer",
"description": "Vertical desktop coordinate."
}
},
"required": [
"x",
"y"
],
"additionalProperties": false
},
"to": {
"type": "object",
"properties": {
"x": {
"type": "integer",
"description": "Horizontal desktop coordinate."
},
"y": {
"type": "integer",
"description": "Vertical desktop coordinate."
}
},
"required": [
"x",
"y"
],
"additionalProperties": false
},
"duration_seconds": {
"type": "number",
"description": "Drag duration where supported.",
"minimum": 0.05,
"maximum": 10
},
"request_id": {
"type": "string",
"description": "Optional correlation ID for this call.",
"minLength": 1
},
"dry_run": {
"type": "boolean",
"description": "Validate the request without performing the mutation. Native dry runs validate input and permission; they do not prove that a UI target still exists.",
"default": false
}
},
"required": [
"from",
"to"
],
"additionalProperties": false
}Inputelevated access · Changes state
pointer_scroll
Scroll vertically at the current pointer. Positive amount scrolls down, negative scrolls up. Amount uses discrete steps on Windows/Linux and a native pixel delta on macOS. Use only when browser_* or ui_* cannot express the operation. Focus the intended app/control and refresh stale screen coordinates before acting.
Inputs (3)
amountRequired- integer · Signed scroll amount; positive down, negative up.
request_idConditional / optional- string · Optional correlation ID for this call.
dry_runConditional / optional- boolean · Validate the request without performing the mutation. Native dry runs validate input and permission; they do not prove that a UI target still exists.
Complete input schema
{
"type": "object",
"properties": {
"amount": {
"type": "integer",
"description": "Signed scroll amount; positive down, negative up.",
"minimum": -100,
"maximum": 100
},
"request_id": {
"type": "string",
"description": "Optional correlation ID for this call.",
"minLength": 1
},
"dry_run": {
"type": "boolean",
"description": "Validate the request without performing the mutation. Native dry runs validate input and permission; they do not prove that a UI target still exists.",
"default": false
}
},
"required": [
"amount"
],
"additionalProperties": false
}Inputelevated access · Changes state
pointer_button_down
Hold a mouse button at explicit desktop coordinates. Pair with pointer_button_up. Use only when browser_* or ui_* cannot express the operation. Focus the intended app/control and refresh stale screen coordinates before acting.
Inputs (5)
buttonConditional / optional- string · left | right · Mouse button.
xRequired- integer · Desktop X.
yRequired- integer · Desktop Y.
request_idConditional / optional- string · Optional correlation ID for this call.
dry_runConditional / optional- boolean · Validate the request without performing the mutation. Native dry runs validate input and permission; they do not prove that a UI target still exists.
Complete input schema
{
"type": "object",
"properties": {
"button": {
"type": "string",
"enum": [
"left",
"right"
],
"description": "Mouse button.",
"default": "left"
},
"x": {
"type": "integer",
"description": "Desktop X."
},
"y": {
"type": "integer",
"description": "Desktop Y."
},
"request_id": {
"type": "string",
"description": "Optional correlation ID for this call.",
"minLength": 1
},
"dry_run": {
"type": "boolean",
"description": "Validate the request without performing the mutation. Native dry runs validate input and permission; they do not prove that a UI target still exists.",
"default": false
}
},
"required": [
"x",
"y"
],
"additionalProperties": false
}Inputelevated access · Changes state
pointer_button_up
Release a held mouse button at explicit desktop coordinates. Use only when browser_* or ui_* cannot express the operation. Focus the intended app/control and refresh stale screen coordinates before acting.
Inputs (5)
buttonConditional / optional- string · left | right · Mouse button.
xRequired- integer · Desktop X.
yRequired- integer · Desktop Y.
request_idConditional / optional- string · Optional correlation ID for this call.
dry_runConditional / optional- boolean · Validate the request without performing the mutation. Native dry runs validate input and permission; they do not prove that a UI target still exists.
Complete input schema
{
"type": "object",
"properties": {
"button": {
"type": "string",
"enum": [
"left",
"right"
],
"description": "Mouse button.",
"default": "left"
},
"x": {
"type": "integer",
"description": "Desktop X."
},
"y": {
"type": "integer",
"description": "Desktop Y."
},
"request_id": {
"type": "string",
"description": "Optional correlation ID for this call.",
"minLength": 1
},
"dry_run": {
"type": "boolean",
"description": "Validate the request without performing the mutation. Native dry runs validate input and permission; they do not prove that a UI target still exists.",
"default": false
}
},
"required": [
"x",
"y"
],
"additionalProperties": false
}Inputelevated access · Changes state
input_release_all
Release held keys/buttons as supported by the native backend. Use only when browser_* or ui_* cannot express the operation. Focus the intended app/control and refresh stale screen coordinates before acting.
Inputs (2)
request_idConditional / optional- string · Optional correlation ID for this call.
dry_runConditional / optional- boolean · Validate the request without performing the mutation. Native dry runs validate input and permission; they do not prove that a UI target still exists.
Complete input schema
{
"type": "object",
"properties": {
"request_id": {
"type": "string",
"description": "Optional correlation ID for this call.",
"minLength": 1
},
"dry_run": {
"type": "boolean",
"description": "Validate the request without performing the mutation. Native dry runs validate input and permission; they do not prove that a UI target still exists.",
"default": false
}
},
"required": [],
"additionalProperties": false
}Capturenormal access · Read only
screen_capture
Capture a native display, rectangular region or window as MCP ImageContent. target=region requires region; target=window requires a window/app selector. Prefer browser_screenshot for a managed web tab and ui_observe for controls.
Inputs (9)
targetConditional / optional- string · display | region | window · Capture target.
display_idConditional / optional- string · Native display ID; omit for the default display.
regionConditional / optional- object
pidConditional / optional- integer · Process ID returned by app_list or app_get_active.
app_nameConditional / optional- string · Exact application/process name; use an absolute path if several installations share the name.
bundle_idConditional / optional- string · macOS application bundle identifier. Use only on macOS.
window_idConditional / optional- string · Exact window ID returned by window_list or window_get_active.
window_indexConditional / optional- integer · Zero-based window index for a selected app; macOS may require this with pid or bundle_id.
request_idConditional / optional- string · Optional correlation ID for this call.
Complete input schema
{
"type": "object",
"properties": {
"target": {
"type": "string",
"enum": [
"display",
"region",
"window"
],
"description": "Capture target.",
"default": "display"
},
"display_id": {
"type": "string",
"description": "Native display ID; omit for the default display.",
"minLength": 1
},
"region": {
"type": "object",
"properties": {
"x": {
"type": "integer",
"description": "Left desktop coordinate."
},
"y": {
"type": "integer",
"description": "Top desktop coordinate."
},
"width": {
"type": "integer",
"description": "Positive width.",
"minimum": 1
},
"height": {
"type": "integer",
"description": "Positive height.",
"minimum": 1
}
},
"required": [
"x",
"y",
"width",
"height"
],
"additionalProperties": false
},
"pid": {
"type": "integer",
"description": "Process ID returned by app_list or app_get_active.",
"minimum": 1
},
"app_name": {
"type": "string",
"description": "Exact application/process name; use an absolute path if several installations share the name.",
"minLength": 1
},
"bundle_id": {
"type": "string",
"description": "macOS application bundle identifier. Use only on macOS.",
"minLength": 1
},
"window_id": {
"type": "string",
"description": "Exact window ID returned by window_list or window_get_active.",
"minLength": 1
},
"window_index": {
"type": "integer",
"description": "Zero-based window index for a selected app; macOS may require this with pid or bundle_id.",
"minimum": 0
},
"request_id": {
"type": "string",
"description": "Optional correlation ID for this call.",
"minLength": 1
}
},
"required": [],
"additionalProperties": false,
"allOf": [
{
"if": {
"properties": {
"target": {
"const": "region"
}
},
"required": [
"target"
]
},
"then": {
"required": [
"region"
]
}
},
{
"if": {
"properties": {
"target": {
"const": "window"
}
},
"required": [
"target"
]
},
"then": {
"anyOf": [
{
"required": [
"window_id"
]
},
{
"required": [
"pid"
]
},
{
"required": [
"app_name"
]
},
{
"required": [
"bundle_id"
]
}
]
}
}
]
}Capturenormal access · Read only
screen_ocr
Capture a native screen area and extract text locally. Returns OCR text items/confidence; use screen_capture when the image itself is needed. Optional text/exact/min_confidence filter recognized items.
Inputs (12)
targetConditional / optional- string · display | region | window · Capture target.
display_idConditional / optional- string · Native display ID; omit for the default display.
regionConditional / optional- object
pidConditional / optional- integer · Process ID returned by app_list or app_get_active.
app_nameConditional / optional- string · Exact application/process name; use an absolute path if several installations share the name.
bundle_idConditional / optional- string · macOS application bundle identifier. Use only on macOS.
window_idConditional / optional- string · Exact window ID returned by window_list or window_get_active.
window_indexConditional / optional- integer · Zero-based window index for a selected app; macOS may require this with pid or bundle_id.
textConditional / optional- string · Optional text substring filter.
exactConditional / optional- boolean · Require case-insensitive exact matching for text.
min_confidenceConditional / optional- number · Minimum recognition confidence.
request_idConditional / optional- string · Optional correlation ID for this call.
Complete input schema
{
"type": "object",
"properties": {
"target": {
"type": "string",
"enum": [
"display",
"region",
"window"
],
"description": "Capture target.",
"default": "display"
},
"display_id": {
"type": "string",
"description": "Native display ID; omit for the default display.",
"minLength": 1
},
"region": {
"type": "object",
"properties": {
"x": {
"type": "integer",
"description": "Left desktop coordinate."
},
"y": {
"type": "integer",
"description": "Top desktop coordinate."
},
"width": {
"type": "integer",
"description": "Positive width.",
"minimum": 1
},
"height": {
"type": "integer",
"description": "Positive height.",
"minimum": 1
}
},
"required": [
"x",
"y",
"width",
"height"
],
"additionalProperties": false
},
"pid": {
"type": "integer",
"description": "Process ID returned by app_list or app_get_active.",
"minimum": 1
},
"app_name": {
"type": "string",
"description": "Exact application/process name; use an absolute path if several installations share the name.",
"minLength": 1
},
"bundle_id": {
"type": "string",
"description": "macOS application bundle identifier. Use only on macOS.",
"minLength": 1
},
"window_id": {
"type": "string",
"description": "Exact window ID returned by window_list or window_get_active.",
"minLength": 1
},
"window_index": {
"type": "integer",
"description": "Zero-based window index for a selected app; macOS may require this with pid or bundle_id.",
"minimum": 0
},
"text": {
"type": "string",
"description": "Optional text substring filter.",
"minLength": 1
},
"exact": {
"type": "boolean",
"description": "Require case-insensitive exact matching for text.",
"default": false
},
"min_confidence": {
"type": "number",
"description": "Minimum recognition confidence.",
"minimum": 0,
"maximum": 1
},
"request_id": {
"type": "string",
"description": "Optional correlation ID for this call.",
"minLength": 1
}
},
"required": [],
"additionalProperties": false,
"allOf": [
{
"if": {
"properties": {
"target": {
"const": "region"
}
},
"required": [
"target"
]
},
"then": {
"required": [
"region"
]
}
},
{
"if": {
"properties": {
"target": {
"const": "window"
}
},
"required": [
"target"
]
},
"then": {
"anyOf": [
{
"required": [
"window_id"
]
},
{
"required": [
"pid"
]
},
{
"required": [
"app_name"
]
},
{
"required": [
"bundle_id"
]
}
]
}
}
]
}Windowsnormal access · Read only
window_list
List native windows and their IDs; optionally filter/select by application.
Inputs (4)
pidConditional / optional- integer · Process ID returned by app_list or app_get_active.
app_nameConditional / optional- string · Exact application/process name; use an absolute path if several installations share the name.
bundle_idConditional / optional- string · macOS application bundle identifier. Use only on macOS.
request_idConditional / optional- string · Optional correlation ID for this call.
Complete input schema
{
"type": "object",
"properties": {
"pid": {
"type": "integer",
"description": "Process ID returned by app_list or app_get_active.",
"minimum": 1
},
"app_name": {
"type": "string",
"description": "Exact application/process name; use an absolute path if several installations share the name.",
"minLength": 1
},
"bundle_id": {
"type": "string",
"description": "macOS application bundle identifier. Use only on macOS.",
"minLength": 1
},
"request_id": {
"type": "string",
"description": "Optional correlation ID for this call.",
"minLength": 1
}
},
"required": [],
"additionalProperties": false
}Windowsnormal access · Read only
window_get_active
Read the currently active native window and its identity.
Inputs (1)
request_idConditional / optional- string · Optional correlation ID for this call.
Complete input schema
{
"type": "object",
"properties": {
"request_id": {
"type": "string",
"description": "Optional correlation ID for this call.",
"minLength": 1
}
},
"required": [],
"additionalProperties": false
}Windowsnormal access · Read only
window_get_bounds
Read the position and size of one native window. Reuse window_id and application context from window_list/window_get_active.
Inputs (6)
pidConditional / optional- integer · Process ID returned by app_list or app_get_active.
app_nameConditional / optional- string · Exact application/process name; use an absolute path if several installations share the name.
bundle_idConditional / optional- string · macOS application bundle identifier. Use only on macOS.
window_idConditional / optional- string · Exact window ID returned by window_list or window_get_active.
window_indexConditional / optional- integer · Zero-based window index for a selected app; macOS may require this with pid or bundle_id.
request_idConditional / optional- string · Optional correlation ID for this call.
Complete input schema
{
"type": "object",
"properties": {
"pid": {
"type": "integer",
"description": "Process ID returned by app_list or app_get_active.",
"minimum": 1
},
"app_name": {
"type": "string",
"description": "Exact application/process name; use an absolute path if several installations share the name.",
"minLength": 1
},
"bundle_id": {
"type": "string",
"description": "macOS application bundle identifier. Use only on macOS.",
"minLength": 1
},
"window_id": {
"type": "string",
"description": "Exact window ID returned by window_list or window_get_active.",
"minLength": 1
},
"window_index": {
"type": "integer",
"description": "Zero-based window index for a selected app; macOS may require this with pid or bundle_id.",
"minimum": 0
},
"request_id": {
"type": "string",
"description": "Optional correlation ID for this call.",
"minLength": 1
}
},
"required": [],
"additionalProperties": false,
"anyOf": [
{
"required": [
"window_id"
]
},
{
"required": [
"pid"
]
},
{
"required": [
"app_name"
]
},
{
"required": [
"bundle_id"
]
}
]
}Windowsnormal access · Read only
window_get_display
Identify the display containing one native window. Reuse window_id and application context from window_list/window_get_active.
Inputs (6)
pidConditional / optional- integer · Process ID returned by app_list or app_get_active.
app_nameConditional / optional- string · Exact application/process name; use an absolute path if several installations share the name.
bundle_idConditional / optional- string · macOS application bundle identifier. Use only on macOS.
window_idConditional / optional- string · Exact window ID returned by window_list or window_get_active.
window_indexConditional / optional- integer · Zero-based window index for a selected app; macOS may require this with pid or bundle_id.
request_idConditional / optional- string · Optional correlation ID for this call.
Complete input schema
{
"type": "object",
"properties": {
"pid": {
"type": "integer",
"description": "Process ID returned by app_list or app_get_active.",
"minimum": 1
},
"app_name": {
"type": "string",
"description": "Exact application/process name; use an absolute path if several installations share the name.",
"minLength": 1
},
"bundle_id": {
"type": "string",
"description": "macOS application bundle identifier. Use only on macOS.",
"minLength": 1
},
"window_id": {
"type": "string",
"description": "Exact window ID returned by window_list or window_get_active.",
"minLength": 1
},
"window_index": {
"type": "integer",
"description": "Zero-based window index for a selected app; macOS may require this with pid or bundle_id.",
"minimum": 0
},
"request_id": {
"type": "string",
"description": "Optional correlation ID for this call.",
"minLength": 1
}
},
"required": [],
"additionalProperties": false,
"anyOf": [
{
"required": [
"window_id"
]
},
{
"required": [
"pid"
]
},
{
"required": [
"app_name"
]
},
{
"required": [
"bundle_id"
]
}
]
}Windowselevated access · Changes state
window_activate
Bring one native window to the foreground. Reuse window_id and application context from window_list/window_get_active.
Inputs (7)
pidConditional / optional- integer · Process ID returned by app_list or app_get_active.
app_nameConditional / optional- string · Exact application/process name; use an absolute path if several installations share the name.
bundle_idConditional / optional- string · macOS application bundle identifier. Use only on macOS.
window_idConditional / optional- string · Exact window ID returned by window_list or window_get_active.
window_indexConditional / optional- integer · Zero-based window index for a selected app; macOS may require this with pid or bundle_id.
request_idConditional / optional- string · Optional correlation ID for this call.
dry_runConditional / optional- boolean · Validate the request without performing the mutation. Native dry runs validate input and permission; they do not prove that a UI target still exists.
Complete input schema
{
"type": "object",
"properties": {
"pid": {
"type": "integer",
"description": "Process ID returned by app_list or app_get_active.",
"minimum": 1
},
"app_name": {
"type": "string",
"description": "Exact application/process name; use an absolute path if several installations share the name.",
"minLength": 1
},
"bundle_id": {
"type": "string",
"description": "macOS application bundle identifier. Use only on macOS.",
"minLength": 1
},
"window_id": {
"type": "string",
"description": "Exact window ID returned by window_list or window_get_active.",
"minLength": 1
},
"window_index": {
"type": "integer",
"description": "Zero-based window index for a selected app; macOS may require this with pid or bundle_id.",
"minimum": 0
},
"request_id": {
"type": "string",
"description": "Optional correlation ID for this call.",
"minLength": 1
},
"dry_run": {
"type": "boolean",
"description": "Validate the request without performing the mutation. Native dry runs validate input and permission; they do not prove that a UI target still exists.",
"default": false
}
},
"required": [],
"additionalProperties": false,
"anyOf": [
{
"required": [
"window_id"
]
},
{
"required": [
"pid"
]
},
{
"required": [
"app_name"
]
},
{
"required": [
"bundle_id"
]
}
]
}Windowselevated access · Changes state
window_close
Request closing one window; unsaved-document prompts may appear. Reuse window_id and application context from window_list/window_get_active.
Inputs (7)
pidConditional / optional- integer · Process ID returned by app_list or app_get_active.
app_nameConditional / optional- string · Exact application/process name; use an absolute path if several installations share the name.
bundle_idConditional / optional- string · macOS application bundle identifier. Use only on macOS.
window_idConditional / optional- string · Exact window ID returned by window_list or window_get_active.
window_indexConditional / optional- integer · Zero-based window index for a selected app; macOS may require this with pid or bundle_id.
request_idConditional / optional- string · Optional correlation ID for this call.
dry_runConditional / optional- boolean · Validate the request without performing the mutation. Native dry runs validate input and permission; they do not prove that a UI target still exists.
Complete input schema
{
"type": "object",
"properties": {
"pid": {
"type": "integer",
"description": "Process ID returned by app_list or app_get_active.",
"minimum": 1
},
"app_name": {
"type": "string",
"description": "Exact application/process name; use an absolute path if several installations share the name.",
"minLength": 1
},
"bundle_id": {
"type": "string",
"description": "macOS application bundle identifier. Use only on macOS.",
"minLength": 1
},
"window_id": {
"type": "string",
"description": "Exact window ID returned by window_list or window_get_active.",
"minLength": 1
},
"window_index": {
"type": "integer",
"description": "Zero-based window index for a selected app; macOS may require this with pid or bundle_id.",
"minimum": 0
},
"request_id": {
"type": "string",
"description": "Optional correlation ID for this call.",
"minLength": 1
},
"dry_run": {
"type": "boolean",
"description": "Validate the request without performing the mutation. Native dry runs validate input and permission; they do not prove that a UI target still exists.",
"default": false
}
},
"required": [],
"additionalProperties": false,
"anyOf": [
{
"required": [
"window_id"
]
},
{
"required": [
"pid"
]
},
{
"required": [
"app_name"
]
},
{
"required": [
"bundle_id"
]
}
]
}Windowselevated access · Changes state
window_minimize
Minimize one native window. Reuse window_id and application context from window_list/window_get_active.
Inputs (7)
pidConditional / optional- integer · Process ID returned by app_list or app_get_active.
app_nameConditional / optional- string · Exact application/process name; use an absolute path if several installations share the name.
bundle_idConditional / optional- string · macOS application bundle identifier. Use only on macOS.
window_idConditional / optional- string · Exact window ID returned by window_list or window_get_active.
window_indexConditional / optional- integer · Zero-based window index for a selected app; macOS may require this with pid or bundle_id.
request_idConditional / optional- string · Optional correlation ID for this call.
dry_runConditional / optional- boolean · Validate the request without performing the mutation. Native dry runs validate input and permission; they do not prove that a UI target still exists.
Complete input schema
{
"type": "object",
"properties": {
"pid": {
"type": "integer",
"description": "Process ID returned by app_list or app_get_active.",
"minimum": 1
},
"app_name": {
"type": "string",
"description": "Exact application/process name; use an absolute path if several installations share the name.",
"minLength": 1
},
"bundle_id": {
"type": "string",
"description": "macOS application bundle identifier. Use only on macOS.",
"minLength": 1
},
"window_id": {
"type": "string",
"description": "Exact window ID returned by window_list or window_get_active.",
"minLength": 1
},
"window_index": {
"type": "integer",
"description": "Zero-based window index for a selected app; macOS may require this with pid or bundle_id.",
"minimum": 0
},
"request_id": {
"type": "string",
"description": "Optional correlation ID for this call.",
"minLength": 1
},
"dry_run": {
"type": "boolean",
"description": "Validate the request without performing the mutation. Native dry runs validate input and permission; they do not prove that a UI target still exists.",
"default": false
}
},
"required": [],
"additionalProperties": false,
"anyOf": [
{
"required": [
"window_id"
]
},
{
"required": [
"pid"
]
},
{
"required": [
"app_name"
]
},
{
"required": [
"bundle_id"
]
}
]
}Windowselevated access · Changes state
window_maximize
Maximize one native window where supported. Reuse window_id and application context from window_list/window_get_active.
Inputs (7)
pidConditional / optional- integer · Process ID returned by app_list or app_get_active.
app_nameConditional / optional- string · Exact application/process name; use an absolute path if several installations share the name.
bundle_idConditional / optional- string · macOS application bundle identifier. Use only on macOS.
window_idConditional / optional- string · Exact window ID returned by window_list or window_get_active.
window_indexConditional / optional- integer · Zero-based window index for a selected app; macOS may require this with pid or bundle_id.
request_idConditional / optional- string · Optional correlation ID for this call.
dry_runConditional / optional- boolean · Validate the request without performing the mutation. Native dry runs validate input and permission; they do not prove that a UI target still exists.
Complete input schema
{
"type": "object",
"properties": {
"pid": {
"type": "integer",
"description": "Process ID returned by app_list or app_get_active.",
"minimum": 1
},
"app_name": {
"type": "string",
"description": "Exact application/process name; use an absolute path if several installations share the name.",
"minLength": 1
},
"bundle_id": {
"type": "string",
"description": "macOS application bundle identifier. Use only on macOS.",
"minLength": 1
},
"window_id": {
"type": "string",
"description": "Exact window ID returned by window_list or window_get_active.",
"minLength": 1
},
"window_index": {
"type": "integer",
"description": "Zero-based window index for a selected app; macOS may require this with pid or bundle_id.",
"minimum": 0
},
"request_id": {
"type": "string",
"description": "Optional correlation ID for this call.",
"minLength": 1
},
"dry_run": {
"type": "boolean",
"description": "Validate the request without performing the mutation. Native dry runs validate input and permission; they do not prove that a UI target still exists.",
"default": false
}
},
"required": [],
"additionalProperties": false,
"anyOf": [
{
"required": [
"window_id"
]
},
{
"required": [
"pid"
]
},
{
"required": [
"app_name"
]
},
{
"required": [
"bundle_id"
]
}
]
}Windowselevated access · Changes state
window_restore
Restore one minimized/maximized native window where supported. Reuse window_id and application context from window_list/window_get_active.
Inputs (7)
pidConditional / optional- integer · Process ID returned by app_list or app_get_active.
app_nameConditional / optional- string · Exact application/process name; use an absolute path if several installations share the name.
bundle_idConditional / optional- string · macOS application bundle identifier. Use only on macOS.
window_idConditional / optional- string · Exact window ID returned by window_list or window_get_active.
window_indexConditional / optional- integer · Zero-based window index for a selected app; macOS may require this with pid or bundle_id.
request_idConditional / optional- string · Optional correlation ID for this call.
dry_runConditional / optional- boolean · Validate the request without performing the mutation. Native dry runs validate input and permission; they do not prove that a UI target still exists.
Complete input schema
{
"type": "object",
"properties": {
"pid": {
"type": "integer",
"description": "Process ID returned by app_list or app_get_active.",
"minimum": 1
},
"app_name": {
"type": "string",
"description": "Exact application/process name; use an absolute path if several installations share the name.",
"minLength": 1
},
"bundle_id": {
"type": "string",
"description": "macOS application bundle identifier. Use only on macOS.",
"minLength": 1
},
"window_id": {
"type": "string",
"description": "Exact window ID returned by window_list or window_get_active.",
"minLength": 1
},
"window_index": {
"type": "integer",
"description": "Zero-based window index for a selected app; macOS may require this with pid or bundle_id.",
"minimum": 0
},
"request_id": {
"type": "string",
"description": "Optional correlation ID for this call.",
"minLength": 1
},
"dry_run": {
"type": "boolean",
"description": "Validate the request without performing the mutation. Native dry runs validate input and permission; they do not prove that a UI target still exists.",
"default": false
}
},
"required": [],
"additionalProperties": false,
"anyOf": [
{
"required": [
"window_id"
]
},
{
"required": [
"pid"
]
},
{
"required": [
"app_name"
]
},
{
"required": [
"bundle_id"
]
}
]
}Windowselevated access · Changes state
window_set_frame
Set the complete position and size of one native window. Supply all four frame fields; use window_get_bounds first to preserve unchanged dimensions. Reuse window_id and application context from window_list/window_get_active.
Inputs (8)
pidConditional / optional- integer · Process ID returned by app_list or app_get_active.
app_nameConditional / optional- string · Exact application/process name; use an absolute path if several installations share the name.
bundle_idConditional / optional- string · macOS application bundle identifier. Use only on macOS.
window_idConditional / optional- string · Exact window ID returned by window_list or window_get_active.
window_indexConditional / optional- integer · Zero-based window index for a selected app; macOS may require this with pid or bundle_id.
frameRequired- object
request_idConditional / optional- string · Optional correlation ID for this call.
dry_runConditional / optional- boolean · Validate the request without performing the mutation. Native dry runs validate input and permission; they do not prove that a UI target still exists.
Complete input schema
{
"type": "object",
"properties": {
"pid": {
"type": "integer",
"description": "Process ID returned by app_list or app_get_active.",
"minimum": 1
},
"app_name": {
"type": "string",
"description": "Exact application/process name; use an absolute path if several installations share the name.",
"minLength": 1
},
"bundle_id": {
"type": "string",
"description": "macOS application bundle identifier. Use only on macOS.",
"minLength": 1
},
"window_id": {
"type": "string",
"description": "Exact window ID returned by window_list or window_get_active.",
"minLength": 1
},
"window_index": {
"type": "integer",
"description": "Zero-based window index for a selected app; macOS may require this with pid or bundle_id.",
"minimum": 0
},
"frame": {
"type": "object",
"properties": {
"x": {
"type": "integer",
"description": "Left desktop coordinate."
},
"y": {
"type": "integer",
"description": "Top desktop coordinate."
},
"width": {
"type": "integer",
"description": "Positive width.",
"minimum": 1
},
"height": {
"type": "integer",
"description": "Positive height.",
"minimum": 1
}
},
"required": [
"x",
"y",
"width",
"height"
],
"additionalProperties": false
},
"request_id": {
"type": "string",
"description": "Optional correlation ID for this call.",
"minLength": 1
},
"dry_run": {
"type": "boolean",
"description": "Validate the request without performing the mutation. Native dry runs validate input and permission; they do not prove that a UI target still exists.",
"default": false
}
},
"required": [
"frame"
],
"additionalProperties": false,
"anyOf": [
{
"required": [
"window_id"
]
},
{
"required": [
"pid"
]
},
{
"required": [
"app_name"
]
},
{
"required": [
"bundle_id"
]
}
]
}Libraries & diagnosticsnormal access · Read only
health
Diagnose a failed tool or inspect readiness on request. Omit tool to check all visible public tools; pass an exact public tool name to check one. Reports ready/state, permission or missing dependency, retryability and remediation. Do not call before every tool.
Inputs (2)
toolConditional / optional- string · Exact visible public tool name to diagnose. Omit for all.
request_idConditional / optional- string · Optional correlation ID for this call.
Complete input schema
{
"type": "object",
"properties": {
"tool": {
"type": "string",
"description": "Exact visible public tool name to diagnose. Omit for all.",
"minLength": 1
},
"request_id": {
"type": "string",
"description": "Optional correlation ID for this call.",
"minLength": 1
}
},
"required": [],
"additionalProperties": false
}Libraries & diagnosticsnormal access · Read only
workspace
List absolute workspace paths explicitly configured by the Desktop owner. This is discovery only: it does not change cwd or grant filesystem access.
Inputs (1)
request_idConditional / optional- string · Optional correlation ID for this call.
Complete input schema
{
"type": "object",
"properties": {
"request_id": {
"type": "string",
"description": "Optional correlation ID for this call.",
"minLength": 1
}
},
"required": [],
"additionalProperties": false
}Libraries & diagnosticsnormal access · Read only
skills_list
List owner-imported local SKILL.md metadata and opaque IDs. Importing shares a managed snapshot; removing it revokes discovery. Use skills_read with an exact returned ID.
Inputs (1)
request_idConditional / optional- string · Optional correlation ID for this call.
Complete input schema
{
"type": "object",
"properties": {
"request_id": {
"type": "string",
"description": "Optional correlation ID for this call.",
"minLength": 1
}
},
"required": [],
"additionalProperties": false
}Libraries & diagnosticsnormal access · Read only
skills_read
Read one owner-imported SKILL.md by its exact opaque ID from skills_list. Validates managed location and SHA-256; stale/removed IDs fail. Returned guidance cannot widen tool permissions.
Inputs (2)
skill_idRequired- string · Exact opaque ID returned by skills_list, never a path or guessed name.
request_idConditional / optional- string · Optional correlation ID for this call.
Complete input schema
{
"type": "object",
"properties": {
"skill_id": {
"type": "string",
"description": "Exact opaque ID returned by skills_list, never a path or guessed name.",
"minLength": 1
},
"request_id": {
"type": "string",
"description": "Optional correlation ID for this call.",
"minLength": 1
}
},
"required": [
"skill_id"
],
"additionalProperties": false
}