SassyMCP

Mutating but non-destructive: rotates the active audit logs rather than deleting anything. Requires confirm='YES'; anything else is refused. Renames $SASSYMCP_HOME/audit.log and audit.jsonl (default ~/.sassymcp) to audit.cleared.<YYYYMMDDTHHMMSS>.log/.jsonl, then logs the rotation itself into the fresh log. Nothing is ever unlinked, so forensic history is preserved in the archives. Use when you want a fresh log tail while keeping history; prefer sassy_audit_log or sassy_audit_search for reading entries.

Read-only. Surfaces recent shell-interceptor pattern events from the local JSONL audit log (~/.sassymcp/audit.jsonl) as rows of timestamp | event | pattern | command (truncated to 120 chars). count caps rows (default 20), newest last. include_bypasses defaults to True, showing both pattern_block entries (commands refused) and pattern_bypass entries (allowed via sassy_shell's allow_pattern); set it False to see only refused commands. Use it to diagnose why a sassy_shell command was blocked and to pick the exact allow_pattern label for a retry. For general log history use sassy_audit_log.

Read-only. Returns the tail of the audit log (~/.sassymcp/audit.log), which records every tool call with timestamp, tool name, and sanitized (secret-redacted) arguments, plus policy and interceptor events. count sets how many of the most recent lines are returned (default 50), newest last. Use it to review what tools were called recently and with what arguments. When you need entries matching a term rather than the plain tail, use sassy_audit_search.

Read-only. Filters the audit log (~/.sassymcp/audit.log) for a case-insensitive keyword match on each line; keyword is required. Returns up to count matching lines (default 50), newest last, or a no-match notice. Use it to trace a specific command, pattern label (e.g. 'pattern_block'), or tool name through the log. For the unfiltered recent tail use sassy_audit_log; for structured interceptor block/bypass rows use sassy_audit_false_positives.

Read-only or mutating depending on its operations: it is a scheduling primitive, not a policy bypass: every operation goes through the normal tool call path — validation, audit, security/confirmation, and per-group rate limiting. operations is a JSON array of {"tool":..., "args":...} (max 50 operations; sassy_batch cannot be nested). max_concurrent caps simultaneous runs (1-16, default 5). timeout_seconds is a per-operation ceiling (default 60.0). stop_on_error (default false) skips pending operations after the first failure. Failures never raise: results return in request order, each with index, tool, ok, elapsed_ms, result, and error. Use for independent fan-out; prefer stop_on_error for dependent pipelines and sequential calls when steps depend on prior results.

Mutating: performs a real mouse click on the host desktop. Clicks at absolute screen coordinates (x, y required) with button defaulting to 'left' (also 'middle', 'right') and clicks defaulting to 1 for double-clicks and beyond. Coordinates are absolute across all monitors, so call sassy_screen_info first (or sassy_desktop_state) to find monitor positions and window locations. Works on Windows, macOS, and Linux via pyautogui. Use it for clicking GUI elements; use sassy_hotkey for keyboard shortcuts and sassy_type_text for entering text.

Read-only. Estimates how much of the context window is consumed by currently registered MCP tool definitions, reporting total estimated tokens, percentage of a 200K window, the heaviest tools, tool count, and actionable recommendations (e.g. disable unused groups, drop github_full when tool count is high). Takes no parameters. If the tool registry cannot be read, it returns a note pointing to the SASSYMCP_LOAD_ALL / SASSYMCP_GROUPS environment settings instead of numbers. Use this first when context feels low or before enabling heavy groups; follow up with sassy_tool_groups to see what is loaded and sassy_tool_group_toggle to disable what you do not need.

Mutating: duplicates a file or an entire directory tree. Files are copied with metadata (shutil.copy2); directories copy recursively. Parent directories of the destination are created as needed. Refuses protected sources or destinations (SassyMCP source tree, ~/.sassymcp) and refuses sources on the sensitive-read denylist (SSH keys, AWS/GPG credentials, /etc/shadow, browser login DBs, SassyMCP tokens) — copying such material is treated as read-equivalent exfiltration and refused like a content read. Also refuses to overwrite an existing destination — run sassy_safe_delete on the destination first if you really need to replace it. Use it to duplicate files or trees; use sassy_move when you want to relocate rather than duplicate.

Read-only. Lists visible open windows with title and absolute left/top/width/height coordinates spanning all monitors, returned as lean JSON. include_taskbar defaults to False, filtering out taskbar entries. Windows-only for window enumeration (pywinauto UIA backend); macOS enumerates via System Events and needs Accessibility permission granted to the app running SassyMCP; Linux returns an unsupported error. Requires a GUI session; headless hosts return an error. Use it with sassy_screen_info to locate UI elements before sassy_click, or for a quick sense of what is open on the desktop.

Read-only. Compares two files and returns a unified diff. Both files are read as UTF-8 (decoding errors replaced); returns an error if either path does not exist. context_lines (integer, default 3) sets how many unchanged lines surround each hunk. The response includes identical (true when files match), lines_added and lines_removed counts, and diff text truncated at 20,000 characters. It compares file contents only, not metadata like timestamps or permissions. Use it to verify exactly what changed between two file versions before copying, restoring, or reviewing them.

Mutating: replaces a single exact occurrence of old_text with new_text in an existing file, and the prior contents are snapshotted into the adjacent _DELETE_/ staging folder before anything is written, so the change is recoverable. Refuses protected paths and refuses to run when old_text has multiple exact matches (add more context to make it unique). If there is no exact match, nothing is written: a fuzzy fallback (80% similarity) reports the closest text and a character diff instead. Reading is UTF-8 with error replacement; encoding and line endings are preserved. Returns a preview of the changed region with line numbers. Use it for one surgical edit; prefer sassy_edit_multi for batching several edits in one call.

Mutating: applies several surgical edits to one existing file in a single call, with the prior contents snapshotted into the adjacent _DELETE_/ staging folder first. edits is a JSON string array of {"old", "new"} objects, applied in order against the evolving content. Any edit whose old text has zero or more than one match aborts the whole call before anything is written, so nothing is partially applied. The file must exist and protected paths are refused. Returns only a count of applied edits, no preview. Use it to batch multiple unique-match changes in one file; use sassy_edit_block when you want a single edit with a context preview.

Read-only. Returns the value of one environment variable from the SassyMCP server process; returns an error if the variable is not set. If the variable name contains token, key, secret, password, or api (case-insensitive), the value is masked: values longer than 12 characters show the first 4 and last 4 characters, shorter ones show as ****. Non-sensitive values are returned in full. Use it to check a single variable; use sassy_env_list when you need to browse the environment or do not know the exact name.

Read-only. Lists environment variables of the SassyMCP server process, sorted by name, with their count. filter_str (string, default empty) limits results to variable names containing that case-insensitive substring. Values that look sensitive (names containing token, key, secret, password, api, or credential) are masked to the first 4 and last 4 characters (or **** if short); other values are truncated at 200 characters. Use it to discover available variables before calling sassy_env_get, and use sassy_env_set to change one.

Mutating: changes the process environment of the running SassyMCP server. Sets one variable immediately for the server process and anything it spawns from this point on. It does NOT modify system or user environment settings, and the change is lost when the server restarts. Returns the variable name, scope process, and an expiry note. Use it only for values needed during the current session; for permanent configuration change the OS or shell profile instead of calling this.

Read-only. Returns JSON metadata for a path: resolved absolute path, type (file or directory), size in bytes, and modified/created epoch timestamps. For files it adds a line count (and last line index); Excel files (.xlsx, .xls, .xlsm) also get sheet names with row and column counts via openpyxl. For directories it adds item, file, and directory counts of the immediate children. Use it to inspect a path before reading or editing it; use sassy_list_dir to browse a directory's entries and sassy_read_file for contents.

Read-only. Returns the full SassyMCP configuration plus a live system snapshot: the config dict (default shell, file read/write line limits, allowed directories, blocked commands, interceptor and permission-engine settings, panel port/enabled), OS and Python details, process and system memory, disk usage, PID, uptime seconds, CPU count, loaded tool groups, and tool-usage stats from the audit log. Takes no parameters. Use to inspect current server settings before calling sassy_set_config, or to diagnose performance and environment issues. Prefer over guessing config values.

Read-only. Fetches one file from a repo and returns its contents plus SHA. Required: owner, repo, path (repo-relative file path). Optional ref (branch, tag, or commit SHA; default empty means the repo default branch). The API returns base64 content, but this tool decodes it for you and replaces the content field with decoded_content (UTF-8, errors replaced). Requires a GitHub token (GITHUB_TOKEN or GITHUB_PERSONAL_ACCESS_TOKEN). Use to read a file before pushing an updated copy with sassy_ghq_push; use sassy_ghq_get for directory paths only if you want the raw directory listing object. For the fuller variant (explicit tree traversal options) use the github_full tool sassy_gh_get_file_contents.

Mutating: creates a GitHub issue in the given repo. Required: owner, repo, title. Optional body (default empty string) and labels as a comma-separated string, e.g. labels bug,docs becomes a label array. Returns the created issue as JSON. Requires a GitHub token (GITHUB_TOKEN or GITHUB_PERSONAL_ACCESS_TOKEN). This is the lean daily-driver create path; for assignees, milestones, or other fields use the github_full tool sassy_gh_create_issue. To find existing issues first, call sassy_ghq_issues; to add a comment to an existing issue, use the github_full tool sassy_gh_add_issue_comment.

Read-only. Lists issues in a repo, 30 per page. Required: owner, repo. Optional state (open is default; closed or all are valid) and page (default 1; GitHub pages are 1-indexed). Returns the issue list as JSON. Note the GitHub issues endpoint includes pull requests in its results, so some entries may be PRs. Requires a GitHub token (GITHUB_TOKEN or GITHUB_PERSONAL_ACCESS_TOKEN). Use for a quick daily-driver listing; for label filters, sorting, direction, or custom page sizes use the github_full tool sassy_gh_list_issues. To create an issue use sassy_ghq_issue.

Mutating: creates a pull request. Required: owner, repo, title, head (source branch containing your commits), base (target branch the PR merges into, e.g. main). Optional body (default empty string). Returns the created PR as JSON. Requires a GitHub token (GITHUB_TOKEN or GITHUB_PERSONAL_ACCESS_TOKEN). The tool itself creates immediately with no draft mode; for draft PRs or more control use the github_full tool sassy_gh_create_pr. To review an existing PR end-to-end (metadata, diff, comments, CI status) in one call, use sassy_combo_pr_review instead of fetching pieces manually.

Mutating: applies a fixed branch-protection preset to branch (default main) in owner/repo. The preset blocks force pushes and deletions and enforces the rules on admins, but sets no required status checks and no required PR reviews. Returns the protection result as JSON. Requires a GitHub token (GITHUB_TOKEN or GITHUB_PERSONAL_ACCESS_TOKEN). Use for the quick standard lock-down of main; for custom rules (required reviews, approval counts, status checks, allowing force pushes) use the github_full tool sassy_gh_protect_branch instead, and to inspect or remove protection use sassy_gh_get_branch_protection or sassy_gh_remove_branch_protection.

Mutating: creates or updates multiple files in one atomic commit via the Git Data API, avoiding the SHA/ETag problems of single-file writes. Required: owner, repo, branch (must be the target branch name, e.g. main or a feature branch), message (commit message), files as a JSON string: an array of {path, content} objects. Malformed files JSON returns an error instead of pushing. Each file write overwrites the existing content at that path, so get the current content with sassy_ghq_get first when editing existing files. Requires a GitHub token (GITHUB_TOKEN or GITHUB_PERSONAL_ACCESS_TOKEN). For single-file operations, branches, or repos the github_full tool sassy_gh_push_files is the fuller equivalent.

Mutating session state: appends the named hook to the in-memory active hook list (hooks can be stacked). Read the playbook carefully afterward. hook_name is the exact hook ID; if not found, the tool returns an error plus the available hook names and substring-based suggestions. On success it returns the full expert playbook: name, owning module, description, and step-by-step instructions covering which tools to use, in what order, what to look for, and what not to do. Use sassy_hooks_list first to discover valid hook names. Activate a hook when a task matches a known domain and you want structured expert guidance; use sassy_hooks_deactivate to unload it.

Mutating: removes hooks from the in-memory active list for this session. hook_name is optional; pass a specific active hook name to deactivate just it, or pass nothing to clear all active hooks at once. Returns {"deactivated": name} on success or {"status": "all hooks deactivated"} when clearing; attempting to deactivate a hook that is not active returns an error. Use it when a playbook no longer applies to the task or you want a clean slate before activating a different one; use sassy_hooks_list to see which hooks are currently active.

Read-only. Lists every registered operational hook with metadata only (no full instructions): name, owning module, one-line description, and trigger phrases, plus a count and the names of currently active hooks. Takes no parameters. Use this to discover which playbooks exist before calling sassy_hooks_activate; if you know the user's request but not the right hook, use sassy_hooks_suggest to rank matches against the request text first.

Read-only. user_text is the user's request in free text (required); the tool scores it against each hook's trigger phrases and returns ranked matching hooks, the top_match name, and a hint naming the hook to consider activating. Returns an empty suggestion list with a note to proceed without a playbook when nothing matches. Use when you are unsure which hook applies or proactively when a request sounds like a known domain; then call sassy_hooks_activate with the top match.

Mutating: sends a real keyboard shortcut to the host. keys is a '+'-separated combination, e.g. 'ctrl+c', 'alt+tab', 'ctrl+shift+s', split and passed to pyautogui. Works on Windows, macOS, and Linux. There is no output validation beyond the confirmation echo, so verify the effect with sassy_screenshot if it matters. Use it for shortcuts like save, copy, or window switching; use sassy_type_text to type actual text into a field and sassy_click for mouse actions.

Can mutate or read depending on method. GET, HEAD, and OPTIONS run freely; POST, PUT, PATCH, and DELETE require allow_mutating=True (default False). Only http and https URLs are accepted, and SSRF validation blocks private IPs, link-local addresses, and cloud metadata endpoints. headers is a JSON object string, body is a UTF-8 string, timeout_seconds defaults to 15, and redirects are followed automatically. Returns status code, headers dict, method, url, and body, which is JSON-parsed when possible and otherwise plain text truncated at 10,000 characters. Use it for quick API calls; prefer web_inspector for deep page inspection.

Read-only. Health-checks one or more URLs with a HEAD request each and reports status code plus round-trip time. urls is a single comma-separated string. Each URL gets a 5-second timeout, redirects are followed, and the response lists per-URL results (status code and ms), with status blocked when SSRF validation rejects a URL or error when the request fails. SSRF protection blocks private IPs, link-local addresses, cloud metadata, and non-http(s) schemes. Use it for quick up/down and latency checks; prefer sassy_http when you need the response body or anything beyond HEAD.

Read-only. Lists directory entries with [FILE] and [DIR] prefixes, directories sorted before files alphabetically. depth controls recursion (default 2, clamped to 1-10). Below the top level, dotfiles and node_modules/__pycache__/.git are skipped, and per-level caps apply (500 entries at top, 100 deeper, 1000 lines total) with warnings naming how many items were hidden. Use it to explore a directory tree; use sassy_file_info for metadata about one path and sassy_read_file to read a file's contents.

Read-only: loads the standard session-start context bundle in one call. Call this at the START of every session. project (default "") is an optional substring filter that adds a project_memories section. Returns a dict with eight sections: critical (up to 10 priority-critical records), high_priority (up to 10), active_tasks (up to 10 tagged task-active), blockers (up to 10 tagged blocker), recent_memories (up to 10 most recently updated), project_memories (up to 15, only when project is given), patterns (up to 10 tagged pattern), and milestones (up to 5 newest). Use instead of issuing many separate searches at startup; use sassy_memory_search for targeted follow-up queries and sassy_memory_recall for one exact record.

Mutating and destructive: permanently deletes the single memory record whose key exactly matches. key (required) must match exactly — only that one record is removed, and there is no undo, trash, or recovery. Returns {"forgotten": true|false, "key", "error"}; forgotten is false with an error message if no record matches. Use only when stored information is obsolete, wrong, or should not persist across sessions. Milestones written by sassy_memory_log live in a separate append-only table and cannot be deleted by this tool. Never use to clear state at session end — that is what sassy_memory_handoff is for.

Mutating: runs the session-end handoff protocol — three writes at once. task (required) names the work. status defaults to "in-progress" (also: blocked, needs-review, paused, completed). completed, next_steps, blockers, files_touched are comma-separated lists; project scopes the entry; context_notes holds anything the next session must know. It (1) upserts memory record task_<slug>_<project>_state (task lowercased, spaces to underscores, first 40 chars) tagged task-active,handoff with high priority — repeat calls for the same task and project overwrite the previous handoff; (2) posts the payload to the crosslink channel "task-handoff"; (3) logs a milestone. Returns {"handoff_saved", "memory_key", "crosslink_channel", "next_session", "crosslink_posted"} — crosslink_posted is false when the crosslink post failed and the handoff is local-only. The next session resumes with sassy_memory_context plus sassy_crosslink_recv on "task-handoff". Use at session end or when context runs low — not as a substitute for sassy_memory_remember.

Mutating: appends a milestone event to the separate milestones table (not the memories table). event (required) is the free-text description of what happened (e.g. "deployed v1.0"); project and tags (comma-separated) are optional. Milestones are append-only — they cannot be edited or deleted, so phrase entries as finished facts. Returns {"logged", "project"}. Use for significant completions, decisions, or changes worth a durable timeline; use sassy_memory_remember for ongoing state you will later update, and sassy_memory_milestones to read the milestone history back.

Read-only: reads back milestone events written by sassy_memory_log, newest first. project (default "") is an optional substring filter on the project field. limit (default 20, hard-capped at 100) controls how many of the newest entries are returned. Returns {"count", "milestones"} with each entry carrying id, event, project, tags, and timestamp. Use to review the timeline of completions and decisions for a project or overall; use sassy_memory_search to find arbitrary memory records, which live in a different table.

Read-only: fetches one memory record by exact key match (fetching also bumps the record's access counter). key (required) must match exactly — if you do not know the key, use sassy_memory_search instead. Returns {"found", "memory", "error"} where memory is the full record (key, value, tags, priority, project, created_at, updated_at, access_count); when no record matches, found is false and error names the key. Use when you know precisely which record you need, e.g. a task state key from sassy_memory_handoff or sassy_memory_context. It does not search text: for keyword discovery use sassy_memory_search, and for the whole session-start bundle use sassy_memory_context.

Mutating: writes a persistent memory record (SQLite, survives server restarts). Upserts by key: if the key already exists the record is fully overwritten (value, tags, priority, project) and updated_at refreshed; otherwise a new record is created. key (required) is the unique identifier — use the naming conventions task_<concept>_<project>_state, pattern_<concept>, blocker_<concept>_<project>, decision_<concept> so later lookups work. value (required) is the content. tags is a comma-separated string (e.g. "task-active,tls"). priority defaults to "normal" (critical|high|normal|low); high-priority items appear in the session-start bundle. project scopes the record. Returns {"key", "action": "created"|"updated"}. Use whenever you learn something worth keeping across sessions; use sassy_memory_forget to remove a stale entry.

Read-only keyword search over all memories using substring matching (not semantic: the query must appear literally in the key or value). query (default "") is free text matched against keys and values; tags is a comma-separated list where each tag must appear in the record's tags; project is a substring match on the project field; priority is an exact match (critical|high|normal|low). All filters combine with AND. Results are ordered by most recently updated first and capped at 50 (limit defaults to 20; an empty query returns everything). Returns {"count", "results"} as full records. Use when you know what to find but not its key; use sassy_memory_recall for an exact key and sassy_memory_context for the standard session-start bundle.

Read-only: reports aggregate health of the memory system. Takes no parameters. Returns {"total_memories", "by_priority" (counts keyed by priority level), "milestones" (total milestone count), "projects" (sorted list of distinct non-empty project names)}. Use to get an overview of how much is stored and how it is organized before deciding how to query; use sassy_memory_context to load the actionable session-start bundle.

Read-only diagnostic. sample_json is a JSON string containing a sample GitHub API response; nothing is sent anywhere. The tool parses it, runs it through the same minifier applied to GitHub tool responses, and reports original_chars, minified_chars, savings_percent, original/minified estimated tokens (chars divided by 4), tokens_saved, and the minified_data itself. Invalid JSON returns an error instead of results. Use it to gauge how much the GitHub response shrinker will reduce a heavy github_full response before you commit to a large call; it is a test harness, not a live API caller.

Mutating: creates a directory, including any missing parents, and succeeds silently if the path already exists. Refuses paths that fail the read-path policy (blocked or protected locations). Returns the resolved path. sassy_write_file already creates missing parent directories, so call this mainly when you need an empty directory or an explicit container for later steps.

Mutating: moves or renames a file or directory to the destination path. Refuses protected sources and destinations, and refuses sources on the sensitive-read denylist (SSH keys, AWS/GPG credentials, /etc/shadow, browser login DBs, SassyMCP tokens) — moving such material is treated as read-equivalent exfiltration and refused like a content read. Also refuses to overwrite an existing destination — sassy_safe_delete the destination first if you genuinely need to replace it. Use it to relocate or rename; use sassy_copy to duplicate without removing the original, and sassy_safe_delete to remove instead.

Read-only health check for monitoring. Returns a small dict: status (always "healthy" when reachable), uptime_seconds, tool_calls_total, error_count, and whether dev live-reload is enabled. Counters accumulate in memory since server start and reset on restart. Takes no parameters. Use for liveness probes, load balancers, or a quick sanity check that the server is up. For CPU/memory/disk figures use sassy_observability_metrics instead.

Read-only. Returns real-time server metrics: uptime_seconds, tool_calls_total, error_rate (percent, rounded to two decimals), timestamp, version, and live_reload_enabled. Also includes cpu_percent, memory_percent, and disk_percent when psutil is installed (optional dependency). Takes no parameters; counters are in-memory since server start. Use for performance monitoring, capacity questions, and error-rate checks. For a simple up/down probe use sassy_observability_health.

Read-only. Returns the in-memory tool usage tracker's stats (per-tool call counts, success/error tallies, recency scores) plus pruning_suggestions: tool names whose usage score falls below a 0.05 threshold, i.e. candidates for disabling to slim the tool surface. Takes no parameters. Use to see which tools are actually used and which can be pruned. Differs from sassy_observability_metrics (aggregate server counters) by reporting per-tool usage. For raw recent call records use sassy_recent_tool_calls.

Read-only. Returns the offline-safe command listing built live from the tool registry, grouped by tool group with usage counts. Optional group filters to one group (see sassy_tool_groups for group names). Optional verbose=false returns names only (about a quarter of the tokens); true adds one-line purposes. LAN tools (SSH, wifi, adb wifi) are included since they need a network but not the internet. The response also lists tools unavailable offline and a system_prompt_snippet for pasting into a local model's prompt. Use before sassy_offline_handoff to build the local model's tool menu; never paste the full catalog into a small local model.

Mutating. Writes a structured offline handoff and optionally starts the local Hermes node. Required parameter task describes what was being worked on. Optional channel (default "joint") is the crosslink channel Hermes polls; next_steps is a newline- or semicolon-separated list of ordered steps; start_node=false, when true, launches hermes_node.py in a persistent session. The tool writes key task_offline_<channel>_state to memory, mirrors it to the crosslink channel, and returns the exact env line and launch command plus the node session name. Errors are returned inline if hermes_node.py is missing or no fallback model is ready. Use after sassy_offline_status confirms the link is down, when handing ongoing work to a local model; read Hermes replies with sassy_crosslink_recv.

Read-only. Runs the real network-state check and reports the full offline picture: link state (online, offline, or DNS-dead), DNS resolving, probe anchors, check age, gate mode and whether it is active, local loopback inference backends with available models and the chosen fallback, the hermes_node.py script path, counts of offline-safe vs LAN vs internet tools, and, when degraded, each unavailable tool with a named substitute. Optional probe=true (default) runs a fresh ~1-2 second probe; false reads the cached verdict instantly. Use as the first step when connectivity is suspect or before any offline workflow.

Mutating (start/stop/rotate change state). Controls the Control Panel, the loopback-only web UI for the permission engine, settings, event log, and classifiers. Optional action (default "status"): status returns running state, the startup-enabled flag, and a tokenless URL — the bearer token is never revealed here; start launches the panel and enables auto-start at future startups (flips panel.enabled in config) and returns a tokenless URL plus a hint to call action="url"; stop shuts it down and disables auto-start; url prints the tokenized URL without starting (this is the explicit token-reveal action); rotate regenerates the panel bearer token, persists it to the token file, audit-logs the rotation, and returns the new token (the old token stops working immediately, no restart needed). Binds 127.0.0.1 on the configured port (default 8765, auto-increments if taken). Send the token in the X-Panel-Token header (the ?token= query form is deprecated but still accepted). Use for interactive inspection and tuning of permissions/settings rather than doing it by hand with sassy_set_config.