Persist any value for any tool across sessions.

Retrieve persistent state for a tool. Returns JSON-encoded value.

Clear state for a specific tool or all tools.

Return real-time server metrics and performance data.

Simple health check for monitoring tools and load balancers.

Full usage tracker stats + pruning suggestions.

Get full SassyMCP configuration and system info.

Returns: config settings, system info (OS, Python, memory, disk), uptime, loaded modules, and tool usage stats. DC get_config equivalent.

Set a runtime config value.

Supported keys: defaultShell, fileReadLineLimit, fileWriteLineLimit, allowedDirectories, blockedCommands. value: JSON-encoded value (e.g. '"powershell"', '1000', '[]')

View and control the permission engine (sassymcp.policy).

Single front door for the four-mode safety system that gates the shell and file tools. The future Control Panel UI writes the same config keys this tool does.

action: status (default) show effective mode, how it was derived, the sandbox roots, and the active allow/ask/deny rules. set_mode set permission.mode. mode= one of: strict — block destructive patterns everywhere confirm — destructive patterns need a confirm token sandbox — relaxed gating INSIDE the sandbox roots; anything resolving outside is refused bypass — allow all except protected paths "" — clear the override; derive from the legacy interceptor.destructiveAction setting add_root add path= to permission.sandboxRoots (the jail) remove_root remove path= from permission.sandboxRoots add_rule append rule= (JSON: {"action","tool","path","command"}) to permission.rules; first match wins, evaluated before the mode default clear_rules remove all rules

Control the SassyMCP Control Panel — the loopback web UI for the permission engine, settings, event log, and classifiers.

action: status (default) — running state + URL (with token) if up start — launch the panel and enable it at future startups stop — shut the panel down and disable auto-start url — print the tokenized URL (does not start it)

The panel binds 127.0.0.1 only and requires the per-install token (stored owner-only in ~/.sassymcp/control_panel.token). Open the printed URL in a browser on this machine.

Get recent tool call history from audit log.

max_results: how many to return (1-1000) tool_name: filter to specific tool (optional) since_minutes: only calls within last N minutes (0=all)

Estimate current context window usage from MCP tool definitions.

Shows: total estimated tokens, % of 200K window, heaviest tools. Use this to understand why your context is running low.

Show tool usage analytics: invocation counts, trends, top tools.

Tracks which tools you actually use to inform smart loading. Data persists across sessions in ~/.sassymcp/tool_usage.json.

List available tool groups and their load status.

Shows which groups are loaded, their tool counts, and descriptions. Use sassy_tool_group_toggle to enable/disable groups.

Proprioceptive self-check: reconcile the declared module manifest against the live tool registry and surface any module that FAILED to import — the silent drop _load_modules()'s try/except otherwise hides.

Answers "am I whole?" with a real readout instead of phantom limbs. A tool can be legitimately absent for three reasons, all reported separately so none is mistaken for a regression:

• dormant — in an on-demand group (always_load=False) not yet toggled on or usage-boosted. Absent BY DESIGN; appears after sassy_tool_group_toggle or a usage boost.

• pruned — low usage score dropped it from the default load (see _tool_loader.get_pruned_tools).

• unsupported — module import raises on THIS platform, but it was never in the default load, so the failure is non-fatal.

The one real regression is:

• BROKEN — an expected-loaded module whose import raises, so its tools never register and the loss is silent.

Every BROKEN module is logged at ERROR (server log / audit substrate) so the amputation is loud, not silent. verdict='whole' == every expected module imports cleanly.

Catalog every registered tool: name, one-line purpose, group.

Client-agnostic capability map for ANY MCP wrapper — enumerate what this server can actually do without loading each tool's schema. Derived live from the registry, so it never drifts from reality the way hand-written capability prose does (the drift that makes absent lazy-loaded tools look like missing ones).

group: filter to one tool group (see sassy_tool_groups). Empty = all. query: case-insensitive substring match on tool name or purpose.

Enable or disable a tool group. Emits tools/list_changed notification.

NOTE: clients vary. MCP clients that handle tools/list_changed (Claude Code, Cursor, etc.) refresh automatically; clients that don't (Claude Desktop today) require a manual server restart.

group: core, android, system, github_quick, github_full, v020, persona enable: True to load, False to unload

Test the GitHub response minifier on sample JSON.

Paste a GitHub API response and see how much it shrinks. Shows before/after token estimates.

List all available operational hooks.

Hooks are expert playbooks that teach the AI HOW to approach a task. When activated, the AI gets pre-loaded domain expertise — the right "lens" for the job. Use sassy_hooks_activate to load one.

Activate an operational hook. Returns the full expert playbook.

The playbook contains step-by-step instructions for HOW to approach the task — which tools to use, in what order, what to look for, and what NOT to do. Follow it.

Use sassy_hooks_list to see available hooks.

Deactivate a hook or all hooks.

hook_name: specific hook to deactivate, or empty to clear all.

Suggest hooks based on what the user is trying to do.

Pass the user's request text. Returns matching hooks ranked by relevance. The AI should call this when it's unsure which hook to use, or proactively when the user's request matches a known domain.

Surgical file edit: find old_text and replace with new_text.

• Exact match preferred; fuzzy fallback with diff reporting

• Fails if multiple exact matches found (provide more context)

• Preserves file encoding and line endings

• Returns a preview of the change with surrounding context

• Refuses edits on protected paths

• Snapshots existing content to DELETE/ before applying

Apply multiple edits to a file in one call.

edits format (JSON string): [{"old": "text to find", "new": "replacement"}, ...]

Edits are applied in order. Each must have exactly one match. Refuses edits on protected paths and snapshots existing content to DELETE/ before applying.

Get an environment variable value. Returns error if not set.

Set an environment variable for the current SassyMCP process.

Persists for the lifetime of the server. Does NOT modify system env. For permanent changes, use the registry or system settings.

List environment variables. Optional filter by name substring. Sensitive values (tokens, keys, secrets) are masked.

Show a desktop notification. duration: short or long.

Useful for alerting when a long-running task completes. Routed at the head: Windows toast (BurntToast -> .NET -> msg.exe), macOS osascript notification, Linux notify-send.

Create a zip archive from a file or directory.

source: path to file or directory to zip output: output zip path (defaults to source + .zip) compression: deflated (default), stored (no compression), bzip2, lzma

Extract a zip archive.

archive: path to .zip file destination: extract to this directory (defaults to archive parent) password: for encrypted zips

Create a tar archive. compress: gz, bz2, xz, or none.

Extract a tar/tar.gz/tar.bz2/tar.xz archive.

Compare two files and return a unified diff.

context_lines: number of surrounding lines to show (default 3). Returns the diff text plus stats (added, removed, changed lines).

Make an HTTP request. Lightweight alternative to web_inspector for quick API calls.

method: GET, HEAD, OPTIONS, POST, PUT, PATCH, DELETE headers: JSON object of headers, e.g. {"Authorization": "Bearer xxx"} body: request body (string or JSON) allow_mutating: required True for state-changing verbs (POST, PUT, PATCH, DELETE). The MCP tool surface is reachable by an LLM that may be partially adversarial; gating mutating verbs behind an explicit flag stops an "innocent fetch" prompt from being steered into a DELETE against an internal service.

Quick health check on multiple URLs. Returns status code and response time for each.

urls: comma-separated list of URLs to check.

Check for a newer SassyMCP release (apt-update equivalent).

Caches the result for 5 minutes; pass force=True to bypass the cache.

List downloadable assets for a release (apt-list-upgradable equivalent).

tag defaults to the latest release.

Return the release notes body for a tag (defaults to latest).

Download an asset to staging. Returns the path + a run command.

Does NOT execute the installer — the user runs the returned command when ready. Disabled in packaged/frozen builds so marketplace installs remain a fixed graded version; upgrade by installing a new release artifact instead.

Store a memory that persists across sessions.

key: unique identifier (use naming convention: task_state, pattern, blocker, decision) value: the memory content (what happened, what was learned, current state) tags: comma-separated (e.g. "task-active,tls,security") priority: critical | high | normal | low project: project name (e.g. "sassymcp", "sassy-browser")

Recall a specific memory by key.

Search memories by text, tags, project, or priority.

query: free text search across keys and values tags: comma-separated tag filter (e.g. "pattern,tls") project: filter by project name priority: filter by priority level

Delete a memory. Use when information is no longer relevant.

Load full context for session startup. Returns critical memories, active tasks, blockers, recent milestones, and learned patterns.

Call this at the START of every session. This is how you know what's been happening and what needs to continue.

project: optional filter to focus on a specific project

Log a milestone event. Use for significant completions, decisions, or changes.

event: what happened (e.g. "deployed v1.0", "fixed TLS cert chain", "merged PR #42") project: which project tags: comma-separated (e.g. "deployment,milestone")

View recent milestones, optionally filtered by project.

Write a session handoff — saves state to BOTH memory and crosslink.

The next session calls sassy_memory_context and sassy_crosslink_recv to pick up exactly where you left off.

task: what you were working on status: in-progress | blocked | needs-review | paused | completed completed: comma-separated list of completed items next_steps: comma-separated ordered list of what to do next blockers: comma-separated list of blockers files_touched: comma-separated list of files modified project: project name context_notes: critical context the next session needs

Memory system stats: total memories, priorities, projects, milestones.

First-run setup wizard. Generates ~/.sassymcp/persona.md from your answers.

Call with your profile to personalize SassyMCP. All fields optional.

role: developer | sysadmin | security | devops | data | designer | manager | other expertise_level: junior | mid | senior | principal | staff specializations: Comma-separated areas (e.g. "web security, cloud infra, mobile") languages: Comma-separated (e.g. "Python, Rust, TypeScript, Go") frameworks: Comma-separated (e.g. "React, FastAPI, Cloudflare Workers") systems: Newline-separated "hostname — OS — role" entries projects: Newline-separated "name — status — description" entries communication_style: terse | balanced | verbose security_posture: standard | hardened | paranoid mcp_clients: Which AI tools connect (e.g. "Claude Desktop, Cursor, Grok Desktop") has_android: True if the user has an Android phone to control (installs adb + scrcpy) has_linux: True if the user works with a Linux server or WSL (installs plink) notes: Anything else the AI should know about how you work

Check setup status: is persona configured? Auth tokens? Config state?

Generate a new auth token for MCP client authentication.

Creates a secure token and saves it to ~/.sassymcp/tokens.json. Use this token in SASSYMCP_AUTH_TOKEN env var or in client config.

client_id: identifier for the client (e.g. "claude-desktop", "grok", "cursor") scopes: comma-separated permissions (read, write, admin)

Guide GitHub token setup. Opens browser, validates, saves.

action: check | open_browser | save_token | skip token: the GitHub PAT to save (only for save_token action)

Guide SSH/Linux remote setup. Checks plink, saves creds, tests connection.

action: check | save | test | skip host: SSH hostname or IP (for save action) user: SSH username (for save action) password: SSH password (optional; fed via stdin at test time, not on the argv list) key: path to a .ppk private key (preferred over password) session: saved PuTTY session name (carries host+user+key)

Authentication priority at test time: session > key > Pageant > password-via-stdin. Pass at least ONE auth source on save, otherwise the call returns status=incomplete (no false 'saved' on empty creds).

Scan for external tools and report availability. Tesseract is required.

Checks: nmap, Tesseract OCR (REQUIRED), adb, scrcpy, plink (PuTTY), Chrome/Chromium. Also checks Python packages: pytesseract, playwright. Use sassy_setup_tools for winget-based auto-install.

Manage your SassyMCP supporter license against LemonSqueezy.

All tool groups are unlocked for everyone — no key required. A license is an optional supporter purchase; activating one records your tier label (shown in the banner, control panel, cockpit).

action: status | activate | deactivate | validate key: LemonSqueezy license key (format XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX), required for activate.

activate: calls LS to register this machine as an instance, then mints a local HMAC payload so offline use works. validate: forces an immediate LS re-check (normally weekly). deactivate: calls LS to free this machine's seat and removes the local file.

Execute a shell command in the host's native shell.

shell: Windows -> powershell (default), cmd, wsl. macOS/Linux -> zsh/bash (default is the login shell), sh. Leave empty to use the host default. Automatically normalizes syntax (e.g. && to ; for PowerShell); POSIX shells run the command verbatim.

timeout_seconds > 120: auto-promoted to a background session and returns a JSON handle ({"auto_detached": true, "session_name": ...}). Poll with sassy_session_read; stop with sassy_session_stop. This is because synchronous waits past the MCP client's ~240s response wall wedge the connection. For known long-running work, prefer calling sassy_session_start directly with a memorable name.

allow_pattern: opt-in escape hatch for power users. When set to a specific pattern label (e.g. 'truncate-by-redirect') OR to '*', a regex-pattern match with that label is allowed to execute instead of being blocked. The bypass is recorded as a 'pattern_bypass' audit entry. Keyword matches (rm/del/remove-item) are NEVER affected by this flag — only regex patterns can be opted out, and only one pattern at a time.

Tiered destructive-action handling: when interceptor.destructiveAction = "confirm" (config), MEDIUM- and HIGH-tier pattern matches return a confirmation_required JSON payload with a single-use token instead of hard-blocking. Call sassy_shell_confirm(token) (HIGH tier also requires a typed phrase) to actually run the command. LOW-tier matches always run after a log entry. The default action remains "block".

Execute a sassy_shell command previously returned as confirmation_required.

Tokens are single-use, expire after 60s, and are bound to the exact command + shell + cwd that produced them. HIGH-tier tokens also require confirm_phrase to match the phrase shown in the original confirmation_required response — replays against a different command are rejected.

Get expert-mode operating parameters. Directives for execution priority, communication style, autonomy level, and precision standards.

Get the decision framework. Defines when to execute immediately vs state approach vs confirm vs hard-stop.

Get engineering standards. Security defaults, code quality rules, architecture patterns, platform-specific guidelines, MCP tool patterns.

Get the cross-system observability guide. What introspection tools are available, what they return, and the recommended first-call sequence.

Get current user context from ~/.sassymcp/persona.md. Returns user's role, systems, projects, and preferences.

Get the SassyMCP capabilities guide. How to use dynamic vision, phone interaction, pause/resume, sensitive context detection, and setup wizard. This is the instruction manual for SassyMCP's advanced features.

Load the complete operating bundle: style + decisions + practices + observability + capabilities + user context. Call this on first connection.

Read recent audit log entries.

Search audit log for a keyword.

Show recent shell-interceptor pattern matches (blocks + bypasses).

Surfaces the noisy-pattern events you'd otherwise have to grep for. Each row: timestamp | event | pattern | command (truncated).

Args: count: max rows to return (newest last). include_bypasses: if False, show only blocks (commands that actually got refused). True also includes pattern_bypass entries — useful for auditing what the allow_pattern flag has been used to let through.

Rotate the audit log to a timestamped archive.

The log is NEVER unlinked — always renamed to audit.cleared..log so forensic history is preserved. Pass confirm='YES' to proceed.

Get display configuration: all monitors with resolution, position, DPI scaling, and which is primary. Essential for multi-monitor setups.

Get desktop state: open windows and positions. Lean output. Coordinates are absolute across all monitors. Windows: pywinauto. macOS: System Events (needs Accessibility permission).

Click at absolute screen coordinates (works across multiple monitors). Use sassy_screen_info to find monitor positions first.

Type text into a field. Always clears field first with ctrl-a + backspace. If target_x/target_y provided, clicks the field first.

Press keyboard shortcut. Keys separated by +, e.g. ctrl+c.

Take screenshot. Optional region as x,y,w,h. monitor=-1 for all, 0 for primary, 1+ for others.

Push files atomically (create or update). THE daily-driver tool.

files: JSON array of {"path": "...", "content": "..."} objects. Uses Git Data API — no SHA bugs, no ETag nonsense.

Get file contents + SHA from a repo.

Create an issue. labels: comma-separated.

List issues.

Create a pull request.

Protect a branch (no force push, no delete, enforce on admins).

Manage external tool dependencies (tesseract, adb, nmap, plink, scrcpy, cloudflared).

action: check | install | install_required | add_to_path tool_name: which tool to install (only for action=install)

check -- report all tools: found, path, required flag install -- winget-install a specific tool by name install_required -- winget-install any missing required tools (always: tesseract) add_to_path -- re-run PATH bootstrap (after placing tools in tools/ dir)

tesseract is always required -- OCR/vision tools need it unconditionally. adb + scrcpy are needed for Android tools. plink for SSH/Linux tools.

Start a persistent terminal session.

name: unique session identifier (e.g. 'build', 'dev-server') shell: Windows -> powershell/cmd/wsl; macOS/Linux -> bash/zsh/sh. Leave empty for the host's native shell. command: optional initial command to run immediately

Send input to a running session.

Like typing in a terminal. Newline is appended automatically. Input is scanned by the delete interceptor — delete keywords are refused here (use sassy_shell or sassy_safe_delete instead, where targets are safely staged to DELETE/).

Read new output from a session without sending input.

Returns only text that arrived since the last read.

List all active terminal sessions.

Stop and clean up a terminal session.

Stop all active terminal sessions.

Move a file or directory to a DELETE staging folder for review.

Instead of permanent deletion, items are moved to a DELETE folder in the same parent directory. This minimises data loss from AI hallucinations or accidental deletions.

Read file contents with line-based pagination.

offset >= 0 : start from that line (0-based) offset < 0 : read last N lines (tail) length : max lines to return (ignored when offset < 0)

Read multiple files at once. paths = JSON array of file paths.

Write or append to a file. mode: rewrite | append.

encoding: any Python codec name (utf-8, utf-16, ascii, latin-1, ...). line_endings: 'preserve' (default — write content verbatim), 'lf' (normalize all CRLF/CR to LF before writing), 'crlf' (normalize all to CRLF — useful for Windows .bat / .ps1 files generated from a model that emits LF).

Rewrite mode on an existing file first snapshots the prior contents into the adjacent DELETE/ staging folder so destructive overwrites can always be undone. Protected paths (SassyMCP source tree, ~/.sassymcp) are refused.

Bypasses the shell-keyword interceptor entirely — content with words like 'format' or 'rm -rf' as data inside scripts is fine. Path validation runs _check_write_path (allowedDirectories + sensitive-read denylist + protected roots) so an LLM cannot write into ~/.ssh, ~/.aws, the SassyMCP source tree, etc. even when allowedDirectories is empty.

List directory contents. [FILE]/[DIR] prefixes. depth controls recursion.

Search for files by name or content.

search_type: files | content file_pattern: glob filter e.g. '.py', '.js' context_lines: lines of context around content matches

Move or rename a file/directory.

Blocks moves from/to protected paths and refuses to overwrite an existing destination without an explicit sassy_safe_delete first.

Copy a file or directory tree.

Refuses protected src/dst and refuses to silently overwrite an existing destination (use sassy_safe_delete on the destination first if you really need to replace it).

Get detailed file/directory metadata.

Includes: size, timestamps, line count (text), sheet info (Excel).

Create a directory (and any missing parents).