SassyMCP

Read-only by default, mutating on change actions. Front door to the four-mode safety system gating shell and file tools. action="status" (default) reports the effective mode, derivation, sandbox roots, and active rules. set_mode sets permission.mode to strict (block destructive patterns), confirm (return a confirm token), sandbox (relaxed inside sandbox roots, anything outside is refused), or bypass (allow all except protected paths); mode="" clears the override so it derives from the legacy interceptor.destructiveAction setting. Switching to bypass requires confirm='YES' (exact, case-sensitive); the privilege mutations add_root (widens the sandbox jail), add_rule, and clear_rules also require confirm='YES', while remove_root (shrinks the jail) needs no confirmation. add_rule appends a JSON rule like {"action":"deny","tool":"sassy_shell","command":"rm"} (first match wins, before the mode default); clear_rules empties the list. Invalid modes and rules are rejected. Use to inspect or change safety gating; pair with sassy_shell_confirm in confirm mode.

Read-only. Returns the SassyMCP capabilities guide, the instruction manual for advanced features: dynamic desktop vision (sassy_screen_glance for cheap repeated watches, sassy_screen_watch for change-triggered frames, sassy_screen_diff for before/after verification, sassy_screen_capture for full-res), Android phone vision (sassy_phone_ui for the structured accessibility tree with coordinates, sassy_phone_state, sassy_phone_watch, sassy_phone_glance) and interaction (tap, swipe, type, key, open), sensitive context detection (interaction tools refuse on login, payment, account, 2FA, or permission screens unless confirmed=True after explicit user confirmation), pause/resume for user handoff, the setup wizard steps, and the hook playbook system (sassy_hooks_suggest/activate/deactivate with categories like web_audit, security_scan, code_review, phone_autonomous). Takes no parameters, returns plain text. Use before any vision, phone, or hook workflow to learn the tool roles and safety rules.

Read-only. Returns the current user context loaded at startup from the persona file at $SASSYMCP_HOME/persona.md (default ~/.sassymcp/persona.md): role, expertise, managed systems, active projects, and communication preferences. If no file exists it returns a template telling you how to create one. Takes no parameters, returns plain text. This is personal user configuration, not server state. Use when you need who-you-are-working-for context; to get it bundled with all persona documents in one call, use sassy_persona_full instead.

Read-only. Returns the decision framework defining when to act without discussion versus when to slow down: execute immediately for file ops, code changes, git, builds, and diagnostics; state approach then execute for architectural changes, schema changes, or breaking API changes; require explicit confirmation for production data destruction without backup, credential rotation on live systems, security posture reduction, or financial transactions; hard stop and refuse for SQLi/XSS/command-injection introduction, hardcoded secrets, or disabled auth. Takes no parameters, returns plain text. Use to calibrate caution on risky operations; pair with sassy_persona_full for the complete bundle.

Read-only. Loads the complete operating bundle in one call and returns a JSON object with six keys: style, decisions, practices, observability, capabilities, and context (each the same plain text document returned by the corresponding narrow tool). Takes no parameters. Call this on first connection to a SassyMCP session so the session starts with operating parameters, decision rules, engineering standards, the observability guide, the capabilities manual, and user context all at once. It is the heaviest of the persona tools in context cost; if you only need one section, call the narrow tool (sassy_persona_style, sassy_persona_decisions, sassy_persona_practices, sassy_persona_observability, sassy_persona_capabilities, or sassy_persona_context) instead.

Read-only. Returns the cross-system observability guide: which introspection tools exist and what each returns — sassy_get_config (system info, uptime, loaded modules), tool analytics (invocation counts, frequency scores), sassy_context_estimate (token use by tool definitions, critical for 100+ tool sessions), audit trail (every invocation with timestamp, sanitized args, elapsed ms), health metrics, cross-session status, and the capability map (sassy_self_check reconciles the module manifest against the live registry and flags BROKEN modules; sassy_tool_catalog lists every registered tool). Also prescribes the recommended first-call sequence: sassy_self_check, then sassy_tool_catalog, then sassy_persona_full, then sassy_hooks_suggest. Takes no parameters, returns plain text. Use when starting a session or debugging what the server can do.

Read-only. Returns the engineering standards document: security defaults applied to every project (input validation, output escaping, parameterized queries, CSRF, auth best practices, security headers, rate limiting, upload validation, secrets handling, dependency audits, TLS, structured logging), code quality rules (types, tests, comments explain why, error handling), architecture patterns (env config, health checks, graceful shutdown, idempotency, circuit breakers, feature flags), platform-specific guidelines (Cloudflare, Rust, Python, TypeScript, Go, Docker, Git), and MCP GitHub tool patterns (use sassy_gh_push_files rather than create_or_update_file for existing files). Takes no parameters, returns plain text. Use before writing or reviewing code to know the expected standards.

Read-only. Returns the expert-mode operating parameters injected into the AI session: execution priority (act first, explain later), communication style (declarative, no preambles, no safety disclaimers on standard operations), autonomy level (never ask permission for reversible operations, complete full scope), and precision standards (exact tool names, paths, line numbers, quantified results). Takes no parameters and returns a plain text document. Use when you want the session's behavior directives alone; for the whole bundle (style + decisions + practices + observability + capabilities + user context) in one call, use sassy_persona_full instead.

Read-only. Reads a text file with line-based pagination and returns numbered lines under a header showing how many lines were selected, the start line, the total line count, and how many remain. offset is 0-based and defaults to 0; a negative offset reads the last N lines (tail mode, where length is ignored); length caps lines returned (default 1000). Directories are refused with a pointer to sassy_list_dir. Use it for large files by paging; prefer sassy_read_multiple when you need several files in one call, and sassy_search_files to find text across a tree.

Read-only. Reads several files at once and concatenates them, each under a header like '--- path (N lines) ---'. paths is a JSON array of file paths (falls back to a comma-separated string if it is not valid JSON). A missing or unreadable file produces an inline error for that file without aborting the others. Use it to pull a handful of small files in one call; use sassy_read_file with offset/length for paging through a large file.

Read-only. Returns recent tool call records parsed from the structured JSONL audit log (the same store the audit module writes; sassy_audit_log reads the plain-text audit.log variant). Optional max_results=50 (docstring caps at 1-1000; the code takes the newest N entries), tool_name="" filters to one tool name, since_minutes=0 means all time or only calls within the last N minutes. Output includes the call entries newest-last, the returned count, and total_in_log (all lines in the file, including skipped/malformed). Returns an empty list with a note if no audit log exists. Use for session history, debugging what ran, and usage review; for raw log text use sassy_audit_log, for keyword search use sassy_audit_search. Overlap note: sassy_audit_log covers the same recent-call history as plain text — prefer this tool when you want structured, filterable records.

Mutating but non-destructive: instead of deleting, it moves the file or directory into a _DELETE_/ staging folder in the same parent directory, renaming with _1, _2 suffixes on collisions so nothing is silently lost. It moves the symlink itself, not its target. Refuses protected paths (SassyMCP source tree, ~/.sassymcp, existing _DELETE_ folders) and audits the interception. This is the required replacement for rm/del-style deletion: shell delete keywords are intercepted, and sassy_copy/sassy_move refuse to overwrite an existing destination until it is staged here first. Use it for any removal; review or restore items from the _DELETE_ folder later.

Read-only, takes no parameters. Returns the display configuration as JSON: every monitor with left/top/right/bottom/width/height, DPI scale_percent, and which is primary, plus a count. Uses native APIs on Windows (DPI-aware) and macOS (AppKit), falling back to a single-monitor pyautogui report elsewhere. Essential setup call for multi-monitor machines: run it before sassy_click or sassy_screenshot to translate absolute coordinates onto the right monitor.

Read-only with respect to the desktop; writes an image file. Saves a PNG screenshot of the screen and returns its path and pixel dimensions. path defaults to ~/sassymcp_screenshot.png; region is an 'x,y,w,h' string that takes precedence over monitor (a malformed region returns an explicit error instead of falling back to a full screenshot); monitor defaults to -1 (all monitors), 0 for primary, 1+ for others. The save path must pass validation and must not be a protected location. Use it to see the current screen state, especially before or after sassy_click/sassy_type_text; pair with sassy_screen_info for multi-monitor region math. Requires a GUI session; on headless hosts it returns an error.

Read-only. Searches recursively under path. search_type 'files' (default) matches pattern as a regex against filenames via a recursive glob filtered by file_pattern (e.g. '*.py'); 'content' matches pattern as a regex against file contents, skipping files over 5MB and emitting path:line: text (200 chars, optional context_lines of before/after context). ignore_case defaults to True; max_results defaults to 50 and is clamped to 1-500. Use it to locate files by name or find text across a tree; use sassy_read_file to read a specific hit and sassy_list_dir to browse instead.

Read-only diagnostic. Reconciles the declared module manifest against the live tool registry and reports verdict "whole" or "DEGRADED", package version, runtime (frozen for packaged builds, source for checkouts), pid, live_tool_count, and a per-module import report. It distinguishes real problems from expected absences: BROKEN modules (expected in the default load but fail to import, logged at ERROR) versus dormant_by_design (on-demand groups not yet toggled on, absent by design) versus pruned_low_usage (dropped by usage scoring) versus unsupported (optional modules failing on this platform, non-fatal). Takes no parameters. Use it to verify server health or to diagnose missing tools without confusing intentional lazy-loading with real failures.

Read-only. Lists all persistent terminal sessions as JSON: name, shell, pid, alive flag, uptime in seconds, output buffer size, exit code, plus a total count. Dead sessions remain listed until stopped. Use it to see what is running before sassy_session_read, sassy_session_send, or sassy_session_stop; auto-detached sassy_shell calls also appear here.

Read-only. Returns output from a named persistent session that arrived since the last read (the cursor advances, so each call yields only new text), truncated to the last 10000 characters, plus an alive flag and the total buffer size. Fails if the session name does not exist. Use it to poll long-running sessions created by sassy_session_start or auto-detached from sassy_shell (timeout over 120s) without sending input; use sassy_session_send to interact.

Mutating: types into a live persistent session like a terminal, with a newline appended automatically, and returns the last 5000 characters of new output after a brief pause. The input is scanned by the same gates as sassy_shell: blocklist matches and delete keywords (rm, del, Remove-Item) are refused here, because session input cannot be safely staged — use sassy_safe_delete for removals instead. Fails if the session does not exist or has exited. Use it to interact with REPLs, prompts, and dev servers running in a session; use sassy_shell for one-shot commands.

Mutating: spawns a persistent terminal session under a unique name and returns its status, shell, and pid. shell defaults to the host native shell (powershell/cmd/wsl on Windows; bash/zsh/sh on macOS/Linux); command optionally runs immediately after startup. Reuse of a live name and initial commands tripping the delete interceptor are refused. stderr is merged into stdout and the per-session buffer keeps the last 50000 characters (tail). Use it for long-running work like dev servers or builds that you poll with sassy_session_read; use sassy_shell for one-shot commands and stop sessions with sassy_session_stop when done.

Mutating: terminates a named persistent session's process (graceful terminate, force kill after 5s), removes the session, and returns the name, exit code, and the last 3000 characters of unread output. Fails if the session does not exist. Use it to clean up a session you started; use sassy_session_stop_all to kill everything at once.

Mutating: terminates every active persistent terminal session (each process is terminated and cleaned up) and returns a list of stopped names with exit codes plus a total count. Use it at the end of a task to clean up leftover dev servers, builds, and watchers; use sassy_session_stop when you only want to end one session.

Mutating. Overwrites a server configuration value and persists it to the SassyMCP home directory config.json immediately (the change affects current and future server runs). Required: key must be one of the supported config keys (defaultShell, fileReadLineLimit, fileWriteLineLimit, allowedDirectories, blockedCommands, interceptor.destructiveAction, interceptor.scanStringLiterals, permission.mode, permission.sandboxRoots, permission.rules, panel.enabled, panel.port) — unknown keys are rejected and the valid list is returned. Required: value is a JSON-encoded string that is parsed before storing (so pass '1000' for a number, '["x"]' for a list, '"powershell"' for a string); if parsing fails the raw string is stored. Returns the key with old and new values. Use to tune limits, the default shell, blocked commands, safety modes, or panel settings; inspect current values first with sassy_get_config.

Read-only scan of external tool availability. Checks six system binaries (nmap, tesseract, adb, scrcpy, plink, chrome) by searching PATH plus known install locations, and three Python packages (pytesseract, playwright, watchdog). For each tool it reports installed true/false, the resolved path, whether it is required, which sassy_* tools use it, and an install URL when missing. Only tesseract is marked required, since OCR/vision tools need it unconditionally. The returned summary lists installed, missing_required, and missing_optional. Takes no parameters and writes nothing. Use this first when diagnosing missing dependencies; when you are ready to install them, use sassy_setup_tools instead.

Mutating: creates a cryptographically secure auth token (secrets.token_urlsafe(32)) and saves it to ~/.sassymcp/tokens.json, replacing any existing entry for the same client_id, then locks the file to owner-only (chmod 0600 on POSIX, ACL lockdown on Windows). The client_id parameter defaults to "default" and identifies the MCP client (e.g. claude-desktop, cursor). The scopes parameter is a comma-separated string defaulting to "read,write"; valid scopes are read, write, and admin. The returned token is shown once only, with usage instructions for the SASSYMCP_AUTH_TOKEN environment variable, the Authorization: Bearer <token> header, and the ?token= query form. Use this when onboarding a new MCP client that needs to authenticate. Trust assumption (deliberate): this tool is intentionally not gated by a confirmation — any MCP client that can call tools can mint bearer tokens, equivalent to the generate-token CLI subcommand, so local automation can bootstrap client auth. Treat every minted token like a password and review ~/.sassymcp/tokens.json if a session behaves unexpectedly. For a read-only view of existing token state, call sassy_setup_status first.

Mutating when saving; read-only for check and open_browser. The action parameter (default "check") selects the step. action=check validates the GITHUB_TOKEN or GITHUB_PERSONAL_ACCESS_TOKEN environment variable against the GitHub API and reports the login and scopes, or that no token exists. action=open_browser opens the GitHub token creation page locally and returns instructions with the recommended scopes (Contents, Issues, Pull Requests, Metadata). action=save_token validates the supplied token parameter (must start with ghp_ or github_pat_) against api.github.com/user; on success it stores the token in the process environment and records github_configured plus the GitHub username in config. The token lasts only for this session unless also set in system env or MCP client config. action=skip records the skip. Use this to enable the sassy_github_* tools.

Manages the optional SassyMCP supporter license against LemonSqueezy. The action parameter (default "status") accepts status, activate, deactivate, validate; the key parameter is required only for activate and must look like XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX. All tool groups are unlocked for everyone with no key, so activating registers your seat and tier label but unlocks nothing. action=status is read-only and reports tier, addons, validity, email, expiry, the license file path, and any LemonSqueezy instance identifiers. action=activate registers this machine and mints a local HMAC payload for offline use. action=deactivate frees the machine's seat and deletes the local file. action=validate forces an immediate LemonSqueezy re-check (normally weekly). Use status to inspect the current tier; only activate with a key purchased from sassyconsultingllc.com/store.

Mutating: saves SSH credentials to the process environment and config, and can open a real test connection. The action parameter (default "check") accepts check, save, test, skip. action=check is read-only: reports whether plink (Windows) or native ssh (macOS/Linux) was found, plus which of SSH_HOST, SSH_USER, SSH_PASS, SSH_KEY, SSH_SESSION are set. action=save requires host and user plus at least one auth source: key (a .ppk path, preferred), session (a saved PuTTY session name), or password (fed via stdin, never in the process list); missing pieces return status=incomplete. action=test runs the actual ssh command with a 15 second timeout and reports connected, failed, or error. Credentials last only for this session unless also set in system env or MCP client config.

Read-only aggregated setup report with no parameters. Reports setup_complete, persona file existence/size/path, auth state (whether SASSYMCP_AUTH_TOKEN is set in the environment, whether ~/.sassymcp/tokens.json exists, and overall auth_active), integrations (GitHub token configured plus the saved GitHub username, SSH configured plus the saved SSH host), the config file path with its key names, the SassyMCP data directory, and the files currently in it. If setup is not complete it includes an action_required field pointing at the next steps. This is the best first call when diagnosing an unknown machine or confirming what first-run steps remain. It never modifies anything. To fix what it reports as missing, call sassy_setup_wizard for the persona, sassy_setup_github or sassy_setup_ssh for integrations, or sassy_setup_tools for dependencies.

Mutating installer for external tool dependencies; use action=check for the read-only report. The action parameter (default "check") accepts check, install, install_required, add_to_path. The tool_name parameter is required only for action=install and must be one of tesseract, adb, scrcpy, nmap, plink, cloudflared. action=check reports each tool as found with its path and required flag; only tesseract is required (OCR/vision need it unconditionally), while adb/scrcpy serve Android tools and plink serves SSH/Linux tools. action=install_required installs every missing required tool; action=install installs the named tool, both via the host package manager (winget, brew, or sudo apt-get) with a 180 second per-package timeout, so installs take minutes. Run action=add_to_path (or restart) afterward. For a read-only scan also covering Chrome and Python packages, use sassy_setup_check_tools.

Mutating: first-run questionnaire that writes the user profile to ~/.sassymcp/persona.md (keeping a one-deep persona.md.bak backup of any existing file before overwriting) and marks setup_complete in config. All parameters are optional: role (developer, sysadmin, security, devops, data, designer, manager, other; default developer), expertise_level (junior, mid, senior, principal, staff; default senior), communication_style (terse, balanced, verbose; default terse), security_posture (standard, hardened, paranoid; default standard), plus comma-separated specializations, languages, frameworks, newline-separated systems and projects, mcp_clients, and notes. The has_android and has_linux booleans (default false) drive the returned tools_to_install list: tesseract always included, adb and scrcpy when has_android is true, plink when has_linux is true. The wizard installs nothing itself; the response includes next_steps and a hint to run sassy_setup_tools(action=install_required), and reloads the persona module in-process. Re-run anytime to update the profile. The result includes a persona_backup field with the backup path (null on first run).

Mutating: executes an arbitrary shell command in the host shell — it can do anything the shell can. shell defaults to powershell on Windows or the login shell on macOS/Linux; POSIX shells run the command verbatim while PowerShell syntax is normalized. timeout_seconds defaults to 30 (clamped 1-300); over 120 the call auto-promotes to a background session, returning a JSON handle to poll with sassy_session_read. Safety gates always run: catastrophic blocklist entries hard-block, delete keywords auto-stage targets to _DELETE_/ when identifiable, and other destructive patterns block or return a confirmation_required token (when interceptor.destructiveAction is 'confirm'; redeem via sassy_shell_confirm). allow_pattern bypasses one named pattern only. Output shows [exit: N] plus stdout and stderr. Use for one-shot commands; prefer sassy_session_start for long-running work.

Mutating: executes a sassy_shell command that was returned as confirmation_required instead of hard-blocked, because interceptor.destructiveAction is set to 'confirm'. Tokens are single-use and expire after 60 seconds; each is bound to the exact command, shell, and working directory that produced it, so replay against anything different is rejected. HIGH-tier commands also require confirm_phrase to match the phrase shown in the original confirmation_required response. Execution is audit-logged as pattern_confirm_executed. Use it only as the second step of the confirm flow; it cannot start a command on its own.

Destructive and mutating: permanently deletes stored state from the persistent per-tool SQLite state store (tool_state.db in the SassyMCP home directory). Optional tool_name="": when given, deletes every key saved under that tool name; when empty, deletes ALL state for ALL tools across the server with no way to recover. Requires confirm='YES' (exact, case-sensitive) on every call, matching the sassy_permission privilege mutations and sassy_audit_clear. Use to reset a misbehaving tool's remembered state or to wipe the whole state store clean; read first with sassy_state_get and back up values with sassy_state_set if they matter.

Read-only. Retrieves one value from the persistent per-tool SQLite state store (tool_state.db in the SassyMCP home directory), surviving server restarts. Required: tool_name namespaces the key under a tool; required: key is the stored key. Returns the JSON-decoded value (whatever was saved with sassy_state_set) or null if the tool/key was never set. Use to read remembered state such as checkpoints, cursors, or preferences; use sassy_state_clear to delete and sassy_state_set to write. This is separate from the memory system — it is for tool operational state, not semantic memories.

Mutating. Persists a value into the per-tool SQLite state store (tool_state.db in the SassyMCP home directory), surviving server restarts. Required: tool_name namespaces the entry (any tool name can be used); required: key is the storage key; required: value is a string that is stored verbatim (the tool does not JSON-encode it — pass already-encoded JSON if you want structured values). Overwrites any existing value for the same tool/key pair. Returns a confirmation string. Use to checkpoint progress, save cursors, or persist preferences between sessions; read with sassy_state_get and delete with sassy_state_clear. Not a substitute for the memory system, which stores semantic facts.

Mutating: writes a new tar archive to disk. Creates a tar from a file or directory path in source; directory contents are stored under the top-level directory name. compress (default gz) accepts gz, bz2, xz, or none, and any other value returns an error. output defaults to the source path plus .tar.gz, .tar.bz2, .tar.xz, or .tar according to compress. Sensitive members are not blocked (full-directory backups must keep working): if any archived file matches the sensitive-read denylist (SSH keys, credential stores, ...), the archive is still created but the result carries a 'warning' field listing them and the event is audit-logged. Returns the created path, a file count, and the archive size in bytes. There is no password option, unlike sassy_unzip. Use it to bundle directories for transport or backup; use sassy_untar to extract what it creates.

Shows a desktop notification on the machine running SassyMCP; no files or data are changed. Routed per platform: Windows tries BurntToast, then .NET toast, then msg.exe; macOS uses osascript; Linux uses notify-send and fails if libnotify is not installed. title and message are required; duration accepts short or long (default short) and anything else is treated as short, mapping to normal or critical urgency on Linux. Returns sent or failed plus the method used, with a 10-second per-method timeout. Use it to alert on completion of a long-running task the user is watching for.

Read-only. Enumerates every currently registered tool derived live from the tool registry (so it never drifts from reality), returning total count, per-group counts, the applied filters, and tools grouped by group as name plus one-line purpose, sorted by group then name. group (default empty = all) filters to one tool group; use sassy_tool_groups to learn valid group names. query (default empty) is a case-insensitive substring match against the tool name or its purpose line. Use this as the client-agnostic capability map to see what the server can actually do; prefer it over sassy_tool_groups when you need tool-level detail rather than group metadata.

Mutating: flips a tool group's always_load flag in the running server process, enabling (enable=true, default) or disabling (enable=false) its modules, and attempts a tools/list_changed notification so capable clients (Claude Code, Cursor) refresh automatically. Clients that do not handle it (Claude Desktop today) need a manual server restart. group must be an exact group name (core, infrastructure, android, system, forensics, linux, github_quick, github_full, persona, utility, setup, memory, updater, combos, prompts); an unknown name returns an error listing the valid groups. Returns status, the group's modules, and whether the notification was sent. Use it to trim context by disabling heavy unused groups like github_full, or to load dormant capability on demand; check sassy_tool_groups first for current load status.

Read-only. Lists all available tool groups with their load status and metadata: member modules, one-line description, always_load flag, tool counts, network requirements, and per-group rate limits. Takes no parameters. Use this to see which groups are loaded before enabling more or diagnosing missing tools (missing tools are usually in a dormant on-demand group); use sassy_tool_group_toggle to change load state and sassy_tool_catalog to list the tools inside a group.

Read-only. Returns tool usage analytics tracked by the server and persisted across sessions in ~/.sassymcp/tool_usage.json (last 90 days, capped at 500 invocations per tool): unique_tools_ever, total_invocations, invocations_today, invocations_this_week, and a top_10 list of tool names with recency-weighted scores (0.0-1.0 via exponential decay, so recent calls count more). Takes no parameters. Use it to see which tools are actually exercised, to inform which groups are safe to disable, or to understand usage patterns; pair with sassy_tool_groups when deciding what to prune for context savings.

Mutating: sends keystrokes to the focused field. It always clears the field first with ctrl-a + backspace, so it never appends — if you need to preserve existing content, this is the wrong tool. If target_x and target_y are both nonzero it clicks there first; text is then typed with interval seconds between keystrokes (default 0.02). Works on Windows, macOS, and Linux via pyautogui. Returns the character count typed. Use it to fill GUI fields; use sassy_hotkey for shortcuts like ctrl+s and sassy_click for mouse actions.

Mutating: writes extracted files to disk. Extracts tar, tar.gz, tar.bz2, or tar.xz archives using a data-only extraction filter. destination defaults to the archive's parent directory under the archive name with the .tar extension removed. Existing files at the destination are silently overwritten. There is no password option, unlike sassy_unzip. Returns the extraction path, the file count, and a sample of the first 20 member names. Use it to open archives created by sassy_tar or downloaded from the web.

Mutating: writes extracted files to disk. Extracts a .zip archive to destination, defaulting to the archive's parent directory under the archive's stem name. password (default empty) unlocks encrypted zips. Zip-slip protection rejects the whole archive with an error if any entry path escapes the destination. Existing files at the destination are silently overwritten. Returns the extraction path, the file count, and a sample of the first 20 entry names. Use it to open zips from any source; use sassy_zip to create archives for extraction with this tool.

Mutating (writes a downloaded file to disk; does NOT execute anything). Downloads one release asset to staging and returns the local path plus a run command the user executes manually. Required: asset_name (exact filename; get valid names from sassy_update_list). Optional tag (default latest) and dest_dir (default LOCALAPPDATA/SassyMCP/updates on Windows, ~/SassyMCP/updates otherwise). If the release publishes a SHA-256 sidecar, the download is verified: on mismatch the file is deleted and the tool errors; with no sidecar it warns but proceeds. The run command is per asset type AND host OS: msiexec /i for .msi on Windows (.msi is Windows-only and refused with guidance on POSIX), Expand-Archive for .zip on Windows vs unzip -o plus chmod +x on POSIX, tar -xzf for .tar.gz/.tgz, direct path otherwise. Disabled in packaged/frozen builds: returns an error telling you to install a new release artifact instead. Requires network access.

Read-only. Returns the release notes for one release as JSON with tag, release name, published_at, the notes body, and the release URL. Optional tag; defaults to the latest release when omitted. If the tag is not found among recent releases it returns an error. Requires network access to the GitHub releases endpoint. Use to see what changed before deciding to upgrade; for the downloadable assets of that release use sassy_update_list, and to stage the download use sassy_update_apply. Does not check whether you are behind; for that use sassy_update_check.

Read-only (fetches remote release state; changes nothing). The apt-update equivalent: contacts the GitHub releases endpoint and reports current version versus latest version as JSON with an upgradable boolean and a one-line summary. Results are cached for 5 minutes; pass force=true to bypass the cache and hit the network again. If GitHub is unreachable it returns an error instead of guessing. Takes no other parameters and requires network access. Use as the first update step to learn whether an upgrade exists; then use sassy_update_changelog to read the notes, sassy_update_list to see the assets, and sassy_update_apply to download.

Read-only. Lists the downloadable assets for one release as JSON: tag, current version, asset_count, and per-asset name, size_bytes, download_url, content_type, and download count. Optional tag; defaults to the latest release. Lookup is limited to the five newest published releases (older tags return a not-found error) and drafts are excluded. Requires network access to the GitHub releases endpoint. Use after sassy_update_check to pick the right asset_name for sassy_update_apply; use sassy_update_changelog for the release notes. Nothing here downloads or installs anything.

Mutating: creates or overwrites files. mode defaults to 'rewrite' (full replace); on an existing file the prior contents are first snapshotted into the adjacent _DELETE_/ staging folder as stem.overwrite.<timestamp>.ext, so overwrites are recoverable. mode 'append' adds bytes to the end. Missing parent directories are created. encoding defaults to utf-8 (any Python codec name); line_endings defaults to 'preserve' (verbatim), with 'lf' and 'crlf' normalizing all line breaks (crlf is useful for Windows .bat/.ps1 files). It bypasses the shell-keyword interceptor entirely, but protected paths (SassyMCP source tree, ~/.sassymcp, ~/.ssh, ~/.aws, etc.) are refused. Use it to create files or full rewrites; prefer sassy_edit_block or sassy_edit_multi for small changes to existing files.