SassyMCP
OfficialSassyMCP is an all-in-one MCP server providing 274 tools across 36 modules for file ops, shell/terminal, desktop & Android automation, GitHub, security, networking, memory, vision, and more — replacing 75+ individual MCP servers.
File & editor: read/write/search/move/copy/edit files with safe-delete interception (staging to
_DELETE_/) and protected-path enforcement.Shell & sessions: run commands in PowerShell/CMD/WSL/bash/zsh, persistent terminal sessions, delete-command interception, confirmation tokens for destructive actions.
Desktop automation: screenshots, clicking, typing, hotkeys, window management, multi-monitor info, OCR (Tesseract).
Dynamic vision: real-time screen glance/watch/diff with change detection, low-context grayscale captures.
Android phone control: ADB-based tap/swipe/type/key, UI accessibility tree reading, phone state, pause/resume with sensitive context auto-blocking (login/payment screens).
GitHub & Git: atomic file pushes via Git Data API, issues, PRs, branch protection, full GitHub API (80 tools) with response minification.
Memory & state: persistent key-value memory, cross-session reminders, milestones, handoffs, pattern learning.
Setup & configuration: guided persona wizard, GitHub token setup, SSH creds, external tool detection (nmap, adb, scrcpy, plink, tesseract), license management.
Permission engine: four modes (strict/confirm/sandbox/bypass) with allow/ask/deny rules, protected paths always enforced, control panel web UI.
Observability & meta: health checks, metrics, tool stats, context estimation, tool usage analytics, tool catalog/self-check.
Utility & network: env var management, zip/tar, HTTP requests/ping, diffs, toasts, port/WiFi/DNS scans, security audits (hash, certs, firewall), registry, event logs, Bluetooth, clipboard sync.
Remote access: SSH execution (plink), HTTP/SSE/HTTPS transports, Cloudflare Tunnel support, multiple isolated instances via
SASSYMCP_HOME.System cross-platform: works on Windows/macOS/Linux with host-appropriate commands routing.
Provides Android device interaction, including UI automation via accessibility tree, tap/swipe/type input, real-time screen monitoring with change detection, and sensitive context detection for auth/payment screens.
Provides Bluetooth management on Windows systems as part of the Windows system module, handling device discovery and connectivity.
Provides Git version control operations, including repository management, commits, and related workflows, often integrated with GitHub.
Provides comprehensive GitHub integration, including file operations (push, get), issue and pull request management, branch protection, and atomic multi-file commits via the Git Data API.
Provides SSH-based remote Linux management, allowing execution of commands and system administration on remote Linux hosts.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@SassyMCP Check my GitHub notifications and summarize what needs my attention."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
SassyMCP
One MCP server to replace them all.
278 tools | 39 modules | 18 tool groups | Replaces 75+ MCP servers | ~35MB standalone exe
Last updated: 2026-11-08 — v1.18.0 | free for personal use, every tool included; commercial license for work
Compatible with Claude Desktop, Grok Desktop, Cursor, Windsurf, and any MCP client.
The official GitHub MCP server has critical SHA-handling bugs. SassyMCP's GitHub module uses correct blob SHA lookups, proper path encoding, atomic multi-file commits via Git Data API, retry logic with exponential backoff, and rate-limit awareness. It's a drop-in replacement that actually works.
Why SassyMCP?
The MCP ecosystem is fragmented. Need file operations? Install Filesystem server. Need terminal? Desktop Commander. GitHub? Another server. Android? Another. Screenshots? Another. You end up with 6-10 separate MCP servers, each consuming context window, each with its own config, bugs, and update cycle.
SassyMCP replaces 75+ individual MCP servers — including Desktop Commander (5.9k stars), Windows-MCP (5k stars), GitHub MCP Server (28.6k stars), Anthropic's official Filesystem and Memory servers, mobile-mcp (4.4k stars), and dozens more — with a single ~35MB exe.
Key differentiators:
Smart Tool Loading — Only loads tool groups you use. Reduces context window overhead from ~25K tokens to ~5K tokens by default.
Dynamic Vision — Real-time screen monitoring with change detection for both desktop and Android. No more screenshot-and-pray.
Android Interaction — Full phone control via UI accessibility tree: tap, swipe, type, with automatic sensitive context detection (auth/payment screens auto-block).
Pause/Resume — User takes over the phone for manual steps (login, 2FA, account selection), AI watches and learns, then resumes autonomously.
Usage Tracking — ML-lite scoring of tool invocations with exponential decay. Your most-used tools load first.
Context Estimation — Built-in tool to measure how much of your 200K context window tool definitions consume.
Response Minification — GitHub API responses stripped of URL metadata bloat (40-70% smaller).
Safe Delete — Delete commands (
rm,del,Remove-Item, etc.) are intercepted across all shells. Instead of destroying files, targets are moved to a_DELETE_/staging folder in the same directory for human review — protecting against AI hallucinations.Guided Setup — Wizard walks through persona, GitHub token, SSH credentials, and optional tool discovery.
Related MCP server: Auralis Commander
What It Replaces
Domain | SassyMCP Module | Replaces | Top Alternative |
File operations | FileOps, Editor | 11 filesystem/editor MCP servers | Filesystem (Anthropic official) |
Shell / terminal | Shell, Session | 5 shell MCP servers | Desktop Commander (5.9k stars) |
Desktop automation | UIAutomation, Vision | 9 desktop MCP servers | Windows-MCP (5k stars) |
GitHub / Git | GitHub Quick, GitHub Full | 5 GitHub/Git MCP servers | GitHub MCP Server (28.6k stars) |
Android / phone | ADB, PhoneScreen | 9 mobile MCP servers | mobile-mcp (4.4k stars) |
Network scanning | NetworkAudit | 8 nmap/security MCP servers | mcp-for-security (601 stars) |
Security auditing | SecurityAudit | 8 security MCP servers | mcp-security-hub (509 stars) |
SSH / remote Linux | Linux | 7 SSH MCP servers | ssh-mcp (365 stars) |
Memory / state | Memory, StateManager | 7 memory MCP servers | mcp-memory-service (1.6k stars) |
OCR / screen reading | Vision | 7 OCR/vision MCP servers | |
Web inspection | WebInspector, Utility | 7 web/fetch MCP servers | Fetch (Anthropic official) |
Windows system | Registry, ProcessManager, Clipboard, EventLog, Bluetooth | 13 Windows MCP servers | Windows-MCP (5k stars) |
Plus features with no MCP server equivalent: phone pause/resume with sensitive context detection (auto-blocks on login/payment screens), operational hooks (14 expert playbooks), safe delete interception, Windows autorun forensics, Android+Windows clipboard sync, usage-weighted smart loading.
Licensing
Free for personal use. Commercial use needs a license. Everyone runs the same build with every tool group unlocked and no key required. There is no free/pro split, no gated groups, and no crippled demo; the 278 tools in the module table below are the product, out of the box. What a commercial license changes is your right to use it for work, not which features you get.
Your situation | What you need |
Personal projects, learning, hobby automation, coursework | Free |
Trying it at work to decide | Free for 30 days |
Using it in your job, on client work, or across a team | Commercial license, one seat per person |
The full plain-English terms, including what counts as commercial use, are in LICENSING.md. The binding text is LICENSE.
It's not open source. The source is public so you can read and audit what runs on your machine, but you may not redistribute it, sell it, or host it as a service for others.
Supporter licenses (optional): individuals who want to fund development can buy a one-time supporter license through LemonSqueezy. It records a supporter badge in the startup banner, control panel, and VS Code cockpit and unlocks nothing, because nothing is locked. A supporter license does not cover commercial use. Refunds revoke the badge automatically.
Activation flow (commercial and supporter keys):
Purchase at
https://sassyconsultingllc.com/store— LemonSqueezy emails you a key (XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX).Activate from your AI agent:
sassy_setup_license action=activate key=...Or from a terminal:
sassymcp.exe setupopens the interactive menu.
Offline operation: Once activated, a local HMAC-signed payload lets the license tier validate fully offline. A weekly re-check against LS catches refunds and cancellations; a faster startup check against the SassyMCP billing oracle cuts refund-to-revocation latency to seconds. Missing, expired, tampered, or corrupt license files just show the free label — tool availability is never affected.
Back-compat: SASSYMCP_LICENSE_BYPASS=1 (the old dev escape hatch that unlocked gated groups) is accepted and ignored — there is nothing left to bypass.
Running supervised (sassymcp supervise)
For always-on / remote deployments, run SassyMCP under its built-in supervisor instead of bare launcher scripts:
sassymcp.exe supervise start # bridge only (127.0.0.1:21001)
sassymcp.exe supervise start --tunnel-mode managed # also run the cloudflared tunnel as a child
sassymcp.exe supervise status # JSON status; exit code != 0 if unhealthy
sassymcp.exe supervise stop # graceful stopThe supervisor owns the runtime tree and makes it self-healing and orphan-proof:
No orphans, ever. A hard kill of the supervisor (crash,
kill -9,taskkill /f) takes every child with it — on Windows via a Job Object (KILL_ON_JOB_CLOSE), on Linux via process groups +PR_SET_PDEATHSIG. No leftover bridge holding a wedged SQLite/WAL lock, which is what the oldtaskkill-based scripts caused.Self-healing. Crashed children restart with exponential backoff (and give up cleanly after a crash-loop, rather than spinning).
Catches hangs. An HTTP readiness probe recycles a hung-but-alive bridge — the failure a Windows scheduled task can never detect.
Crash-survivable control. A pidfile + on-disk registry under
$SASSYMCP_HOMEmeansupervise status/stopwork even when the bridge is down, so an operator or agent can recover a wedged system.
start-supervised.bat wraps this as the recommended Windows launcher. stdio mode (Claude Desktop pipe) is client-owned and intentionally not supervised.
Modules
Module | Tools | Group | Description |
Meta | 11 | meta | Context estimation, tool usage analytics, group management |
Batch | 1 | meta | Multi-tool batch fan-out in a single call |
FileOps | 10 | core | Read, write, search, move, copy, edit, mkdir, file info, safe delete |
Shell | 2 | core | PowerShell, CMD, WSL execution with syntax normalization and delete interception |
UIAutomation | 6 | core | Desktop state, click, type, hotkeys, screenshots, screen info |
Editor | 2 | core | Surgical find/replace, multi-edit |
Audit | 4 | core | Audit log read, search, clear, false-positive tracking |
Session | 6 | core | Persistent terminal sessions (start, read, send, stop) |
GitHub Quick | 6 | github_quick | Daily-driver: push_files, get_file, issue, PR, protect |
GitHub Full | 80 | github_full | Complete GitHub API: repos, issues, PRs, actions, security, gists |
Persona | 7 | persona | Expert-mode directives, decision framework, engineering standards |
Utility | 11 | utility | Env vars, toast, zip/tar/unzip/untar, HTTP requests, file diff |
SetupWizard | 7 | setup | Setup wizard, GitHub token guide, SSH setup, tool checker, license activation |
ToolsManager | 1 | setup | External tool bootstrap and detection |
Observability | 3 | infrastructure | Health, metrics, tool stats |
StateManager | 3 | infrastructure | Persistent key-value state across sessions |
RuntimeConfig | 5 | infrastructure | Permission modes, runtime config, recent tool calls |
Offline | 3 | infrastructure | Offline fallback status and local-model handoff |
Memory | 9 | memory | Persistent cross-session memory, milestones, task handoffs, pattern learning |
Updater | 4 | updater | Version checks, changelog, self-update |
ADB | 10 | android | Android shell, packages, file transfer, logcat, screencap |
PhoneScreen | 14 | android | UI tree reader, phone glance/watch, tap/swipe/type/key, pause/resume, scrcpy |
iPhone | 6 | iphone | iOS device info, screenshot, syslog, apps, IPA install — experimental, needs libimobiledevice |
NetworkAudit | 7 | system | netstat, ARP, WiFi scan, port scan, DNS, traceroute |
ProcessManager | 5 | system | Cross-platform process list/kill, system info |
Bluetooth | 3 | system | Windows + Android BT enumeration |
EventLog | 3 | system | Windows Event Log + Android logcat |
Clipboard | 4 | system | Cross-platform clipboard sync |
SecurityAudit | 7 | forensics | Hash, permissions, certs, APK, firewall, Defender |
Registry | 4 | forensics | Read, write, export, autorun forensics (Windows) |
Vision | 8 | v020 | Screen capture, OCR, dynamic glance/watch/diff |
AppLauncher | 6 | v020 | Launch apps, focus/close/resize/snap windows |
WebInspector | 5 | v020 | Security headers, URL screenshots, tech stack detection |
Crosslink | 7 | v020 | Cross-session messaging via HTTP API + SQLite |
Coordination | 4 | v020 | Multi-agent coordination board and peer delegation |
Linux | 1 | linux | Remote SSH execution via plink/OpenSSH |
Combos | 3 | combos | Multi-step workflows in one call: PR review, phone observe, codebase grep |
Prompts | 0 | prompts | MCP slash-menu shortcuts (no tools — prompts only) |
SelfMod | 0 | — | Retired stub — self-modification removed (no tools) |
Counts generated from the registered tool set (278 tools across 39 modules, 18 groups; the prompts group exposes MCP prompts rather than tools).
Full per-tool reference (generated): docs/TOOLS.md.
iPhone support (experimental)
SassyMCP can talk to iPhones over USB via libimobiledevice. This is new in v1.16.0 and experimental — Android-over-ADB remains the mature path.
Prerequisites
Install libimobiledevice:
brew install libimobiledevice(macOS) orsudo apt install libimobiledevice-utils(Linux). Windows hosts have limited support — use WSL2 or a macOS/Linux host.Pair the device once: run
idevicepair pairand tap Trust on the iPhone. iOS 17+ requires this pairing step before any tool will see the device.If several iPhones are connected, pass the
udidparameter (fromsassy_iphone_list) to target one.
Tools: sassy_iphone_list, sassy_iphone_info, sassy_iphone_screenshot, sassy_iphone_syslog (bounded capture), sassy_iphone_apps, sassy_iphone_install (requires confirm='YES'). Every tool degrades gracefully when the binaries or a trusted device are missing — you'll get an install hint or a pairing reminder, never a traceback.
Dynamic Vision
Desktop (Vision module)
Traditional MCP screenshots are blind — you capture one frame and hope it's the right one. SassyMCP's dynamic vision changes this:
Tool | Purpose |
| Fast grayscale capture at ~3-6KB. Call repeatedly to "watch" the screen. |
| Monitor for N seconds, returns only frames where content changed (pixel diff threshold). |
| Before/after comparison — takes frame, waits, takes another, returns both + a diff image highlighting changes. |
All three use grayscale + heavy JPEG compression to keep context cost minimal. A glance is ~2KB vs ~14KB for a full-color capture.
Android (PhoneScreen module)
The phone isn't just a camera target — SassyMCP reads its UI accessibility tree:
Tool | Purpose |
| Reads every visible UI element — text, description, coordinates, clickable/focused/checked state. Structured data, not pixels. |
| Foreground app, screen on/off, battery, WiFi, notification count. |
| Low-res grayscale phone screenshot via direct pipe (~4-8KB). |
| Monitors UI tree changes over duration. Returns snapshots only when elements change. |
Phone Interaction
Full touch input via ADB — the AI can operate the phone:
Tool | Purpose |
| Tap screen coordinates |
| Swipe between two points |
| Type text into focused field |
| Send key events (HOME, BACK, ENTER, VOLUME, etc.) |
| Launch an app by package name |
Sensitive Context Detection
All interaction tools (tap, swipe, type) automatically scan the UI tree before executing. If they detect login screens, payment forms, account selectors, 2FA prompts, or permission dialogs, the tool refuses to execute and returns what it sees instead. The AI then describes the screen to you and asks what to do. Pass confirmed=True after explicit user approval.
Safe Delete (Delete Interception)
AI agents can hallucinate destructive commands. SassyMCP intercepts all delete-family commands across every shell and every tool entry point, then moves targets to a _DELETE_/ staging folder instead of destroying them. Every interception is written to the audit log with the raw command, parsed targets, and move results.
Coverage — every destructive path is gated:
Tool | Guard |
| Intercepts delete commands, stages targets to |
| Same interceptor — persistent terminals can't bypass |
| Refuses destructive commands on the remote host |
| Refuses destructive commands on Android device (override with |
| Explicit staging tool — moves symlinks as symlinks (no |
| Snapshots existing file into |
| Refuses protected paths, snapshots existing content to |
| Refuses existing destination (no silent overwrite), refuses protected src/dst |
| Refuses silent destination overwrite, refuses protected src/dst |
| Rotates the audit log instead of deleting it; requires |
Intercepted command keywords: rm, rmdir, unlink (Unix/WSL), del, erase, rd (CMD), Remove-Item, ri, rni (PowerShell aliases), sdelete / sdelete64 (Sysinternals).
Also caught (beyond bare keywords):
Shell wrappers —
powershell -c "del foo",cmd /c del foo,bash -c "rm foo",wsl -- rm foo(payload is recursively scanned)Base64 payloads —
powershell -EncodedCommand <base64>is decoded (UTF-16-LE) and recursively scanned.NETcalls —[System.IO.File]::Delete(...),[System.IO.Directory]::Delete(...)Clear-Content,Set-Content -Value ''(literal empty only — normal-Value "foo"is allowed)Out-File -Force,New-Item -Force(overwrite-style)copy /y,xcopy /y— CMD silent-overwrite flagsrobocopy /MIRandrobocopy /PURGE— mirror/purge modes delete destination filesTruncate-by-redirect —
> file.txt,type foo > bar.txt,cmd; > file.txt(append>>and stream2>/&>correctly ignored)Move-Item foo $nullAssignment prefixes —
$null = ri foois correctly unwrapped
Protected roots (refused by every guarded tool, not just the interceptor): the SassyMCP source tree itself, ~/.sassymcp/ (audit + config), and any _DELETE_/ staging folder (no staging recursion). Protection uses resolve() so path traversal (..\), symlinks, and Windows 8.3 short names all normalize correctly before the check.
Scenario | Result |
| Hard-blocked by the always-on blocklist — no move attempted |
| Blocked, file moved to |
| Blocked, all |
| Blocked, |
| Blocked — payload is unwrapped and intercepted |
| Blocked — |
| Prior content snapshotted to |
| Executes normally — not a delete command |
Name collisions in _DELETE_/ are handled automatically with counter suffixes (file.txt, file_1.txt, file_2.txt). On Windows, paths with backslashes (C:\Users\foo\bar) are preserved correctly by the parser — no shlex mangling.
Pause / Resume
For complex flows where the user needs to take over:
Tool | Purpose |
| Blocks all interaction tools. Observation tools (ui, glance, watch) still work. |
| Unblocks interaction. AI picks up where it left off, informed by everything it observed during pause. |
Workflow:
AI operates phone autonomously for routine tasks
AI hits a login screen → sensitive context auto-blocks → AI tells the user
User says "hold on" → AI calls
sassy_phone_pauseUser logs in manually. AI watches via
sassy_phone_ui/sassy_phone_glanceUser says "done" → AI calls
sassy_phone_resumeAI continues, now aware the user logged into a specific account
Permission Engine & Control Panel
SassyMCP gates the shell and file tools through one policy engine
(sassymcp.policy) with four modes, set via sassy_permission set_mode or
the Control Panel:
Mode | Behavior |
| Block destructive patterns everywhere (default) |
| Destructive patterns return a confirm token |
| Relaxed gating inside the project roots; anything resolving outside the jail is refused — run an ungated model, confined to a folder |
| Allow everything except protected paths (explicit, audited) |
A Claude-style allow / ask / deny rules layer (tool-glob + path-glob +
command-regex; first match wins) overrides the mode default. The
catastrophic block-list (format, mkfs, …) and the protected-path
invariant (the SassyMCP source tree + ~/.sassymcp) hold in every mode,
including bypass.
The Control Panel is a localhost web UI for all of the above — a live
event log, the settings/mode editor, and a classifier + rules editor. It
binds 127.0.0.1 only and needs the per-install token in
~/.sassymcp/control_panel.token. Start it with sassy_panel start (or set
panel.enabled / SASSYMCP_PANEL=1 to launch it at boot), then open the
printed http://127.0.0.1:8765/?token=… URL.
Tool profiles
Tool profiles gate which tools an MCP session can see (tools/list) and
call (tools/call) — a per-session, human-controlled subset of the
catalog, managed from the Control Panel (a Profiles tab, backed by
GET/POST /api/profile). There is deliberately no MCP tool that can
switch or widen the profile, so a session can never escalate itself out of
a restrictive profile; fan-out through sassy_batch respects the same
gate.
Profile | Tool groups |
| All 18 groups (default on every start) |
| meta, core, infrastructure, utility, github_quick, github_full, v020, memory, persona, setup, updater |
| meta, core, infrastructure, forensics, utility, system, memory |
| meta, core, infrastructure, android, iphone, utility, memory |
| meta, core, infrastructure, system, linux, utility, memory, updater |
| Every tool whose curated MCP annotation is |
| An explicit group set you tick in the dashboard |
Rules worth knowing:
Session-scoped, never persisted. A restart always comes back up on
full. Profiles are a runtime seatbelt, not access control — the panel token is the trust boundary.metastays on. Its introspection tools (sassy_tool_groups,sassy_self_check, …) are the session's only window into what it can see; hiding them would strand the session with no way to inspect the gate.Widening needs
confirm='YES'. Any switch that would expose a currently-hidden tool is an audited escalation and requires explicit confirmation (the panel UI sends it for you, mirroring the bypass-mode convention). Narrowing never does.A tool hidden from
tools/listis also uncallable viatools/call— a client cannot call what it cannot see.
Guided Setup
On first launch (no ~/.sassymcp/persona.md), the wizard tools are prominently available and the AI is given an onboarding playbook via the registered hook. The flow is conversational — the AI asks, you answer, it calls the tools.
Onboarding procedure (recommended order)
Each step is independent and skippable. Just tell the AI "set up SassyMCP" or "let's get started" and it'll walk this:
# | Step | Tool | What happens |
0 | License (optional) |
| Reports supporter tier. All tools are unlocked regardless — a key just registers your seat and supporter status. |
1 | Persona |
| Asks the questionnaire below, generates |
2 | GitHub |
| Validates an existing |
3 | SSH / Linux |
| Locates |
4 | Optional tools |
| Scans for |
✓ | Status check |
| Shows what's configured, what's still missing, and the action_required hint. Run this any time. |
⚙️ | Auth tokens |
| Generates a 32-byte URL-safe token for HTTP/tunnel mode and writes |
Skip any step with action="skip" (where supported) — config records the skip so the AI doesn't re-prompt.
The persona questionnaire
sassy_setup_wizard accepts these fields. All optional — defaults shown.
Field | Values / format | Default |
|
|
|
|
|
|
| Comma-separated areas — e.g. | empty |
| Comma-separated — e.g. | empty |
| Comma-separated — e.g. | empty |
| Newline-separated | empty |
| Newline-separated | empty |
|
|
|
|
|
|
| Which AI tools connect — e.g. | empty |
| Free-form text — anything else the AI should know about how you work | empty |
Output goes to ~/.sassymcp/persona.md (the persona module reads it on every session) and the run is recorded in ~/.sassymcp/config.json (setup_complete, setup_timestamp, setup_version). Re-run sassy_setup_wizard any time to regenerate — the persona module hot-reloads with the new profile.
Triggering the flow from your client
The onboarding hook fires on phrases like "setup", "first time", "get started", "onboard", "new user", "set up sassymcp". Anything close to those will pull the playbook into the AI's context. If you want to drive it manually, just call sassy_setup_status first to see where you are, then walk the table above.
Smart Loading
By default, SassyMCP only loads frequently-used tool groups. This keeps tool definitions under 5% of your context window.
# Default: loads core, github_quick, persona, meta, utility, setup, infrastructure
uv run sassymcp
# Load everything (~22K tokens of context)
SASSYMCP_LOAD_ALL=1 uv run sassymcp
# Load specific groups
SASSYMCP_GROUPS=core,github_quick,android,v020 uv run sassymcpAvailable Groups
Group | Modules | Default |
| fileops, shell, ui_automation, editor, audit, session | Yes |
| meta | Yes |
| observability, state_manager, runtime_config | Yes |
| github_quick (6 lean tools) | Yes |
| persona | Yes |
| utility | Yes |
| setup_wizard, tools_manager | Yes |
| memory | Yes |
| updater | Yes |
| combos (4 tools) | No |
| prompts (slash-menu shortcuts) | Yes |
| github_ops (80 tools) | No |
| adb, phone_screen | No |
| network_audit, process_manager, security_audit, registry, bluetooth, eventlog, clipboard | No |
| vision, app_launcher, web_inspector, crosslink | No |
| linux | No |
Install
Pick whichever entry point matches how you already work. All four converge on the same shared brain at ~/.sassymcp/ — your persona, memory, license, and audit log are visible to every connected MCP client.
One-click via DXT (Claude Desktop)
Download sassymcp.dxt from the latest release, double-click — Claude Desktop installs it. On first launch, sassymcp auto-detects every other MCP client on your machine (Cursor, VS Code Copilot, Windsurf, Continue, Cline, Zed, Grok Desktop) and patches each one's config so they all see SassyMCP without you editing any JSON.
VS Code extension
Install the VS Code extension from the .vsix attached to the latest release until the Visual Studio Marketplace listing is live. The extension locates sassymcp.exe (PATH or the sassymcp.exePath setting), runs the same auto-config CLI, and adds a status bar item showing supporter-tier label and brain health. Command palette: Open Sassy Brain Cockpit, Run Setup Wizard, Reinstall Client Configs, Open Audit Log, Open _DELETE_ Folder, Show Brain Status.
Manual auto-config CLI
If you have sassymcp.exe already (from a GitHub release or pip install) and want to register it with every MCP client without per-client JSON editing:
sassymcp-installThat detects Claude Desktop, VS Code Copilot, Cursor, Windsurf, Continue, Cline, Zed, and Grok Desktop and patches each one's config atomically. Re-running is a noop. Take a look first with sassymcp-install --dry-run. Remove with sassymcp-install --uninstall. The CLI takes a timestamped backup of any existing config before its first edit.
Portable bundle
The portable zip (sassymcp-v*-portable.zip with bundled adb, nmap, plink, scrcpy, tesseract, cloudflared, and the start-*.bat launchers) is no longer published — the release pipeline does not build it. Use the standalone executable below (and install any helper tools you need on PATH), or pip install sassymcp for the full Python install.
Standalone executable (no tools bundled)
If you don't need the bundled nmap / adb / cloudflared (or you have them on PATH already), grab just sassymcp.exe (~35 MB) from the latest release. Drop it anywhere and point your MCP client at it.
First-run wizard: Double-click sassymcp.exe (or run it from a terminal with no flags) on a fresh machine and you'll get an interactive menu — auto-detect AI agents and register SassyMCP, activate a LemonSqueezy license key, generate / list bearer tokens, or start the HTTP server. Run sassymcp.exe setup anytime to re-open the menu. Once a persona is configured, bare invocation falls back to starting the HTTP server (the v1.5 behavior) so existing setups are unchanged.
Linux (pip only)
CI publishes no Linux binary. On Linux/BSD, install the wheel: pipx install sassymcp (or pip install --user sassymcp). (The standalone executable is Windows-only; macOS ships a universal2 binary — see sassymcp-macos on the release page.) ./build.sh builds a native binary on any of them.
POSIX launchers mirror the .bat files and are plain /bin/sh, so they run on Debian/Kali/Ubuntu, Fedora/RHEL, Arch, openSUSE, Alpine, the BSDs and macOS:
Script | Purpose |
| stdio mode (point your MCP client here) |
| HTTP on localhost or LAN; prompts, or set |
| HTTP under |
| HTTP bridge + |
| start at login: systemd user unit (Linux), LaunchAgent (macOS), or an |
| package |
Each launcher finds SassyMCP in this order: ./sassymcp, dist/sassymcp, .venv/bin/python -m sassymcp.server, sassymcp on PATH, then python3 -m sassymcp.server.
MSI installer (manual builds only)
No MSI is published by CI — build-msi.ps1 exists for manual MSI builds (WiX 3.x) from a staged sassymcp.exe, and installer.wxs is a manual-build reference template, not a maintained installer.
Activating a license key
There is no separate "licensed download" and nothing to unlock — everyone runs the same fully-unlocked binary from the GitHub releases. Personal use needs no key. If you use SassyMCP for work, buy a commercial license (or, as an individual, an optional supporter license) at sassyconsultingllc.com/store and activate it to register your seat (what counts as commercial use):
# from your AI agent:
sassy_setup_license action=activate key=XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX
# or from a terminal — interactive menu, choose "Activate license":
sassymcp.exe setupThe license registers this machine as a LemonSqueezy instance (seat);
sassy_setup_license action=deactivate frees the seat to move to another machine.
From source
git clone https://github.com/sassyconsultingllc/SassyMCP.git
cd SassyMCP
uv sync
# Optional dependencies:
uv pip install pytesseract playwright
playwright install chromiumCloudflare Tunnel (remote access)
Want to drive SassyMCP from a remote MCP client (Claude Web, another machine)? Install cloudflared, then use the start-tunnel.bat launcher from this repo (deploy/start-tunnel.bat or the copy next to a standalone sassymcp.exe). Full step-by-step is in docs/TUNNEL.md; the short version:
winget install Cloudflare.cloudflared # one-time
cloudflared tunnel login # authenticate against your CF account
cloudflared tunnel create sassymcp # create a named tunnel
cloudflared tunnel route dns sassymcp mcp.<your-domain>.tld
# Write ~/.cloudflared/config.yml with the ingress block (see TUNNEL.md)
[Environment]::SetEnvironmentVariable("SASSYMCP_AUTH_TOKEN", "<your token>", "User")
[Environment]::SetEnvironmentVariable(
"SASSYMCP_ALLOWED_HOSTS",
"mcp.<your-domain>.tld,localhost,127.0.0.1", "User")
cd D:\Tools\SassyMCP # wherever you extracted
.\start-tunnel.bat sassymcp # tunnel name as arg, or set SASSYMCP_TUNNEL_NAMEstart-tunnel.bat launches the HTTP bridge on 127.0.0.1:21001 and runs cloudflared tunnel run <name> in the foreground. Nothing in the script is vendor-specific — you supply the tunnel name and the hostname. Clients send Authorization: Bearer <SASSYMCP_AUTH_TOKEN> against https://mcp.<your-domain>.tld/mcp.
For hosted-Claude clients that require OAuth 2.1 DCR/PKCE instead of a static bearer, deploy the optional Worker under sassymcp-oauth/ — copy wrangler.toml.example to wrangler.toml, fill in your hostname and KV id, and wrangler deploy. See docs/TUNNEL.md for the full OAuth section.
MCP Client Config
SassyMCP speaks standard MCP. Anything that connects works — no client-side modifications required. Ready-to-edit templates live under deploy/*_config.template.json in this repo. Pick the row for your client, copy the template, replace REPLACE_WITH_PATH with the absolute path to sassymcp.exe, and save it where the client expects.
Client | Transport | Config file location | Template |
Claude Desktop | stdio |
|
|
Cursor | stdio |
|
|
Windsurf | stdio |
|
|
Cline (VS Code) | stdio | VS Code settings → | use |
Continue.dev | stdio |
|
|
Grok Desktop | HTTP | Grok Desktop MCP settings |
|
Any other MCP client | stdio or HTTP | client's MCP config | use the closest template; the |
Standard mcpServers shape (Claude Desktop, Cursor, Windsurf, Cline)
Using the exe:
{
"mcpServers": {
"sassymcp": {
"command": "C:\\path\\to\\sassymcp.exe",
"env": {
"SASSYMCP_LOAD_ALL": "1",
"GITHUB_TOKEN": "ghp_your_token_here"
}
}
}
}From source:
{
"mcpServers": {
"sassymcp": {
"command": "uv",
"args": ["--directory", "C:\\path\\to\\SassyMCP", "run", "sassymcp"],
"env": {
"SASSYMCP_LOAD_ALL": "1",
"GITHUB_TOKEN": "ghp_your_token_here"
}
}
}
}Continue.dev shape (different schema)
{
"experimental": {
"modelContextProtocolServers": [
{
"transport": {
"type": "stdio",
"command": "C:\\path\\to\\sassymcp.exe"
}
}
]
}
}HTTP / Grok Desktop / custom HTTP clients
Run the server in HTTP mode (sassymcp.exe --http, default 127.0.0.1:21001) and point your client at http://127.0.0.1:21001/mcp/. Set SASSYMCP_AUTH_TOKEN if the bind is non-loopback.
{
"mcpServers": {
"sassymcp": {
"url": "http://127.0.0.1:21001/mcp/"
}
}
}What's actually Claude-flavored (cosmetic only)
A few docstrings and the legacy .claude/skills/sassymcp-update.md slash-command target Claude Code specifically. Other clients ignore them and use sassy_update_* tools directly. No tool, transport, or auth path requires Claude — the server doesn't know which LLM is on the other end.
Transport Modes
Mode | Command | Use Case |
Stdio |
| Claude Desktop, Cursor (direct pipe) |
HTTP |
| Grok Desktop, Windsurf (localhost:21001) |
HTTP LAN |
| Multi-device (requires auth token) |
HTTPS |
| Encrypted (auto-generates self-signed cert) |
SSE |
| Legacy transport |
Running Multiple Instances (Dual Session)
Two SassyMCP processes on the same machine — for example, a local stdio instance for Claude Desktop and a remote HTTPS instance behind a Cloudflare Tunnel for Claude Web — can clobber each other's state if they share ~/.sassymcp/. The fix is one env var per instance.
Conflicts to resolve per-instance
Resource | Default | How to give each instance its own |
HTTP port |
|
|
Crosslink HTTP port |
|
|
Auth token | env | Set per-process in launcher's env |
Per-user state dir |
|
|
SSL cert/key |
| Auto-isolated when |
Example: local stdio + remote tunnel side-by-side
Instance A — local stdio for Claude Desktop (claude_desktop_config.json):
{
"mcpServers": {
"sassymcp-local": {
"command": "C:\\Tools\\SassyMCP\\sassymcp.exe",
"env": {
"SASSYMCP_LOAD_ALL": "1",
"SASSYMCP_HOME": "C:\\Users\\<you>\\.sassymcp-local"
}
}
}
}Instance B — remote HTTPS via Cloudflare Tunnel (start-tunnel.bat + a wrapper that sets the env):
set SASSYMCP_HOME=C:\Users\<you>\.sassymcp-remote
set SASSYMCP_AUTH_TOKEN=<token-for-remote>
set PORT=21002
"%~dp0sassymcp.exe" --http --host 127.0.0.1 --port %PORT%Then cloudflared tunnel run <name> forwards https://<your-tunnel>/mcp to 127.0.0.1:21002.
What's isolated when SASSYMCP_HOME differs
Each instance gets its own:
persona.md— different profiles per sessionconfig.json— different runtime config (allowed dirs, blocked commands, etc.)tokens.json— different scoped auth tokenslicense.json— separate license activationaudit.log/audit.jsonl— no interleaved writescrosslink.db— separate cross-session message queuesmemory.db— separate persistent memoriestool_state.db/tool_usage.json— separate per-tool state and usage analyticsserver.crt/server.key— separate self-signed certsThe
_securityprotected-paths check honorsSASSYMCP_HOMEtoo — neither instance cansassy_safe_deleteinto the other's home
What's still shared between instances
The repo source tree (always protected from delete/overwrite by
_security)%LOCALAPPDATA%\SassyMCP\updates\— the updater download stage (harmless; tagged by version under it)The bundled tools in the portable zip (
adb,nmap,cloudflared, etc.) — read-only from both instances
Putting it in the OS (so both start at boot)
The legacy personal/autostart-bridge.bat + personal/register-autostart.ps1 template is gitignored — copy it, tweak the paths and the SASSYMCP_HOME for each instance, then Register-ScheduledTask once per instance.
Environment Variables
Variable | Purpose |
| Load every tool group |
| Load specific groups |
| Bearer token for HTTP auth |
| Enable live reload (dev mode) |
| Disable the startup update check (no GitHub API call) |
| Override the per-user state dir (default |
| Override the auto-detected repo root in |
| GitHub API access |
| Remote Linux hostname/IP |
| Remote Linux username |
| Remote Linux password |
External Tools
All bundled in the beta zip package. Install separately only if using the standalone exe.
Tool | Used By | Bundled | Install (if needed) |
ADB | All | Yes | |
nmap |
| Yes | |
plink |
| Yes | |
scrcpy |
| Yes | |
Tesseract |
| Yes | |
Chrome |
| No |
Run sassy_setup_check_tools to verify all tools are detected.
Requirements
Windows 10/11, macOS 12+, or Linux — one source, routed at the head (
sassymcp._platform) to the right command per host. See Cross-platform below.Python 3.11+ (only if running from source; the standalone binary is self-contained — built per OS, since PyInstaller can't cross-compile)
Cross-platform
The same SassyMCP source runs on Windows, macOS, and Linux. The host OS is
resolved once at import; every tool then routes to the host-appropriate
command — shells (PowerShell / zsh|bash), clipboard (Get-Clipboard / pbpaste),
event log (Get-WinEvent / log show / journald), firewall (netsh /
socketfilterfw / ufw, firewalld, nftables, iptables, pf), Wi-Fi, Bluetooth,
window control (pywinauto / AppleScript System Events / wmctrl or xdotool),
SSH (plink / native ssh), package installs, and more.
On Linux and BSD, SassyMCP finds the native package manager (apt, dnf, yum,
pacman, zypper, apk, xbps, emerge, pkg, pkg_add, pkgin, or Homebrew) and uses
that distro's package names. When it isn't running as root it calls
sudo -n, so a password prompt fails at once with a hint instead of
hanging. When a tool is missing on a minimal install, SassyMCP uses
another one: ss or ip neigh for net-tools, dig/host/getent for
nslookup, tracepath for traceroute, and syslog files when there is no
journald. The clipboard uses wl-clipboard on Wayland and xclip/xsel on X11.
If pwsh is installed, shell="powershell" runs PowerShell 7 on Linux and macOS.
Linux window control works on X11 and on apps running under XWayland (install
wmctrlorxdotool, plusxrandr). Native Wayland compositors don't let one app control another app's windows, so those tools give a clear error there.Build:
build.bat(Windows) orbuild.sh(macOS/Linux). Build each binary on its own OS.macOS permissions: window-control and screenshot tools need Accessibility and Screen Recording permission for the app running SassyMCP (System Settings → Privacy & Security).
A handful of concepts are Windows-only by nature (raw Registry read/write/export); those report a clear message and point to the native equivalent (
defaults, launchd). Forensic persistence (sassy_autorun_entries) IS cross-platform (Run keys / LaunchAgents / systemd+cron).
License
Free for personal and educational use; commercial use requires a license. Source-available, not open source. See LICENSING.md for the plain-English terms and LICENSE for the binding text.
Copyright (c) 2026 Sassy Consulting LLC. All rights reserved.
Available Tools
101 toolssassy_audit_clearA
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..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.
Inputs: confirm. Returns: result
sassy_audit_false_positivesARead-onlyIdempotent
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.
Inputs: count, include_bypasses. Returns: result
sassy_audit_logARead-onlyIdempotent
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.
Inputs: count. Returns: result
sassy_audit_searchARead-onlyIdempotent
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.
Inputs: keyword (required), count. Returns: result
sassy_batchADestructive
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.
Inputs: operations (required), stop_on_error, max_concurrent, timeout_seconds. Returns: failed, results, requested, succeeded, +2 more
sassy_clickADestructive
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.
Inputs: x (required), y (required), button, clicks. Returns: result
sassy_context_estimateARead-onlyIdempotent
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.
Inputs: no named parameters. Returns: object
sassy_copyAIdempotent
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.
Inputs: source (required), destination (required). Returns: result
sassy_desktop_stateARead-onlyIdempotent
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.
Inputs: include_taskbar. Returns: result
sassy_diffARead-onlyIdempotent
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.
Inputs: path_a (required), path_b (required), context_lines. Returns: object
sassy_edit_blockADestructive
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.
Inputs: path (required), new_text (required), old_text (required). Returns: result
sassy_edit_multiADestructive
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.
Inputs: path (required), edits (required). Returns: result
sassy_env_getARead-onlyIdempotent
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.
Inputs: name (required). Returns: object
sassy_env_listARead-onlyIdempotent
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.
Inputs: filter_str. Returns: object
sassy_env_setAIdempotent
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.
Inputs: name (required), value (required). Returns: object
sassy_file_infoARead-onlyIdempotent
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.
Inputs: path (required). Returns: result
sassy_get_configARead-onlyIdempotent
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.
Inputs: no named parameters. Returns: object
sassy_ghq_getARead-onlyIdempotent
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.
Inputs: path (required), repo (required), owner (required), ref. Returns: result
sassy_ghq_issueA
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.
Inputs: repo (required), owner (required), title (required), body, +1 more. Returns: result
sassy_ghq_issuesARead-onlyIdempotent
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.
Inputs: repo (required), owner (required), page, state. Returns: result
sassy_ghq_prA
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.
Inputs: base (required), head (required), repo (required), owner (required), +2 more. Returns: result
sassy_ghq_protectAIdempotent
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.
Inputs: repo (required), owner (required), branch. Returns: result
sassy_ghq_pushADestructive
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.
Inputs: repo (required), files (required), owner (required), branch (required), +1 more. Returns: result
sassy_hooks_activateAIdempotent
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.
Inputs: hook_name (required). Returns: object
sassy_hooks_deactivateAIdempotent
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.
Inputs: hook_name. Returns: object
sassy_hooks_listARead-onlyIdempotent
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.
Inputs: no named parameters. Returns: object
sassy_hooks_suggestARead-onlyIdempotent
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.
Inputs: user_text (required). Returns: object
sassy_hotkeyADestructive
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.
Inputs: keys (required). Returns: result
sassy_httpADestructive
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.
Inputs: url (required), body, method, headers, +2 more. Returns: object
sassy_http_pingARead-onlyIdempotent
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.
Inputs: urls (required). Returns: object
sassy_list_dirARead-onlyIdempotent
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.
Inputs: path (required), depth. Returns: result
sassy_memory_contextARead-onlyIdempotent
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.
Inputs: project. Returns: blockers, critical, patterns, milestones, +4 more
sassy_memory_forgetADestructive
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.
Inputs: key (required). Returns: key, error, forgotten
sassy_memory_handoffA
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___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.
Inputs: task (required), status, project, blockers, +4 more. Returns: memory_key, next_session, handoff_saved, crosslink_posted, +1 more
sassy_memory_logA
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.
Inputs: event (required), tags, project. Returns: logged, project
sassy_memory_milestonesARead-onlyIdempotent
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.
Inputs: limit, project. Returns: count, milestones
sassy_memory_recallARead-onlyIdempotent
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.
Inputs: key (required). Returns: error, found, memory
sassy_memory_rememberAIdempotent
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_state, pattern, blocker, decision 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.
Inputs: key (required), value (required), tags, project, +1 more. Returns: key, action
sassy_memory_searchARead-onlyIdempotent
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.
Inputs: tags, limit, query, project, +1 more. Returns: count, results
sassy_memory_statsARead-onlyIdempotent
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.
Inputs: no named parameters. Returns: projects, milestones, by_priority, total_memories
sassy_minify_testARead-onlyIdempotent
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.
Inputs: sample_json (required). Returns: object
sassy_mkdirAIdempotent
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.
Inputs: path (required). Returns: result
sassy_moveA
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.
Inputs: source (required), destination (required). Returns: result
sassy_observability_healthARead-onlyIdempotent
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.
Inputs: no named parameters.
sassy_observability_metricsARead-onlyIdempotent
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.
Inputs: no named parameters.
sassy_observability_tool_statsARead-onlyIdempotent
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.
Inputs: no named parameters.
sassy_offline_commandsARead-onlyIdempotent
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.
Inputs: group, verbose. Returns: object
sassy_offline_handoffA
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__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.
Inputs: task (required), channel, next_steps, start_node. Returns: object
sassy_offline_statusARead-onlyIdempotent
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.
Inputs: probe. Returns: object
sassy_panelAIdempotent
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.
Inputs: action. Returns: object
sassy_permissionAIdempotent
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.
Inputs: mode, path, rule, action, +1 more. Returns: result
sassy_persona_capabilitiesARead-onlyIdempotent
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.
Inputs: no named parameters. Returns: result
sassy_persona_contextARead-onlyIdempotent
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.
Inputs: no named parameters. Returns: result
sassy_persona_decisionsARead-onlyIdempotent
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.
Inputs: no named parameters. Returns: result
sassy_persona_fullARead-onlyIdempotent
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.
Inputs: no named parameters. Returns: object
sassy_persona_observabilityARead-onlyIdempotent
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.
Inputs: no named parameters. Returns: result
sassy_persona_practicesARead-onlyIdempotent
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.
Inputs: no named parameters. Returns: result
sassy_persona_styleARead-onlyIdempotent
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.
Inputs: no named parameters. Returns: result
sassy_read_fileARead-onlyIdempotent
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.
Inputs: path (required), length, offset. Returns: result
sassy_read_multipleARead-onlyIdempotent
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.
Inputs: paths (required). Returns: result
sassy_recent_tool_callsARead-onlyIdempotent
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.
Inputs: tool_name, max_results, since_minutes. Returns: object
sassy_safe_deleteAIdempotent
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.
Inputs: path (required). Returns: result
sassy_screen_infoARead-onlyIdempotent
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.
Inputs: no named parameters. Returns: object
sassy_screenshotAIdempotent
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.
Inputs: path, region, monitor. Returns: result
sassy_search_filesARead-onlyIdempotent
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.
Inputs: path (required), pattern (required), ignore_case, max_results, +3 more. Returns: result
sassy_self_checkARead-onlyIdempotent
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.
Inputs: no named parameters. Returns: object
sassy_session_listARead-onlyIdempotent
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.
Inputs: no named parameters. Returns: object
sassy_session_readARead-only
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.
Inputs: name (required). Returns: object
sassy_session_sendADestructive
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.
Inputs: name (required), input_text (required). Returns: object
sassy_session_startADestructive
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.
Inputs: name (required), shell, command. Returns: object
sassy_session_stopADestructiveIdempotent
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.
Inputs: name (required). Returns: object
sassy_session_stop_allADestructiveIdempotent
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.
Inputs: no named parameters. Returns: object
sassy_set_configAIdempotent
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.
Inputs: key (required), value (required). Returns: result
sassy_setup_check_toolsARead-onlyIdempotent
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.
Inputs: no named parameters. Returns: object
sassy_setup_generate_tokenADestructive
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 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.
Inputs: scopes, client_id. Returns: object
sassy_setup_githubAIdempotent
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.
Inputs: token, action. Returns: object
sassy_setup_licenseADestructive
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.
Inputs: key, action. Returns: object
sassy_setup_sshAIdempotent
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.
Inputs: key, host, user, action, +2 more. Returns: object
sassy_setup_statusARead-onlyIdempotent
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.
Inputs: no named parameters. Returns: object
sassy_setup_toolsADestructive
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.
Inputs: action, tool_name. Returns: object
sassy_setup_wizardADestructive
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).
Inputs: role, notes, systems, projects, +9 more. Returns: object
sassy_shellADestructive
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.
Inputs: command (required), shell, allow_pattern, timeout_seconds. Returns: result
sassy_shell_confirmADestructive
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.
Inputs: token (required), confirm_phrase. Returns: result
sassy_state_clearADestructiveIdempotent
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.
Inputs: confirm, tool_name. Returns: result
sassy_state_getARead-onlyIdempotent
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.
Inputs: key (required), tool_name (required). Returns: object
sassy_state_setAIdempotent
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.
Inputs: key (required), value (required), tool_name (required). Returns: result
sassy_tarADestructiveIdempotent
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.
Inputs: source (required), output, compress. Returns: object
sassy_toastA
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.
Inputs: title (required), message (required), duration. Returns: object
sassy_tool_catalogARead-onlyIdempotent
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.
Inputs: group, query. Returns: object
sassy_tool_groupsARead-onlyIdempotent
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.
Inputs: no named parameters. Returns: object
sassy_tool_group_toggleAIdempotent
Mutating: sets a tool group's always_load flag so the group loads (enable=true, default) or stays unloaded (enable=false) on the NEXT server start. Module loading is resolved once at startup, so this cannot add or remove tools from a running session — restart the server process for the change to take effect. 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 takes_effect (next server restart). 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.
Inputs: group (required), enable. Returns: object
sassy_tool_usageARead-onlyIdempotent
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.
Inputs: no named parameters. Returns: object
sassy_type_textADestructive
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.
Inputs: text (required), interval, target_x, target_y. Returns: result
sassy_untarADestructiveIdempotent
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.
Inputs: archive (required), destination. Returns: object
sassy_unzipADestructiveIdempotent
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.
Inputs: archive (required), password, destination. Returns: object
sassy_update_applyAIdempotent
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). A SHA-256 sidecar is required: on mismatch or if no sidecar is published the staged file is deleted and the tool errors. 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.
Inputs: asset_name (required), tag, dest_dir.
sassy_update_changelogARead-onlyIdempotent
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.
Inputs: tag.
sassy_update_checkARead-onlyIdempotent
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.
Inputs: force.
sassy_update_listARead-onlyIdempotent
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.
Inputs: tag.
sassy_write_fileADestructive
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..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.
Inputs: path (required), content (required), mode, encoding, +1 more. Returns: result
sassy_zipADestructiveIdempotent
Mutating: writes a new zip archive to disk. Creates a zip from a file or directory in source; directories are walked recursively and files are stored with paths relative to the source root, while a single file is stored under its basename. compression (default deflated) accepts deflated, stored, bzip2, or lzma, and unrecognized values fall back to deflated. output defaults to source plus .zip, replacing the extension for files. 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, file count, original and zip byte sizes, and a compression ratio percentage. Use it to package files for sharing; use sassy_unzip to extract what it creates.
Inputs: source (required), output, compression. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 101 tools
The descriptions are unusually diligent about pointing at the right sibling tool (e.g. audit_log vs audit_search vs recent_tool_calls, tool_catalog vs tool_groups vs context_estimate), which rescues many near-neighbors. But with 101 tools there are still numerous overlapping clusters — four audit readers, three usage/introspection stats tools, six persona document tools, five memory query tools, and parallel 'ghq' vs 'gh' GitHub families — so an agent must read cross-references carefully to avoid misselection.
Nearly everything is snake_case under a uniform sassy_ prefix with a predictable group/module segment (memory_, audit_, session_, setup_, update_, persona_, tool_, observability_). Minor deviations exist: bare noun names like sassy_permission, sassy_panel, sassy_batch, sassy_hotkey, sassy_toast, and the get_/set_ pair (get_config/set_config) sit beside verb-first names, but the scheme remains readable and largely mechanical.
101 registered tools is far beyond what a coherent tool surface should expose in one session; the server itself ships sassy_context_estimate, pruning suggestions, and group toggles as damage control for its own size. Even accounting for intentional lazy-loaded groups, the presented surface is an extreme over-extension of scope for any single MCP server.
Coverage is broad and lifecycle-complete for most areas: file read/write/edit/copy/move/safe-delete/diff/archive, shell plus persistent sessions, config get/set, memory and state CRUD, audit reading, setup/update flows, GitHub file/issue/PR paths, and desktop control. Gaps remain — no true unlink (deletion is staged, by design), and several referenced tools (screen_glance/watch/capture, phone_*, crosslink_*, gh_* full family) are absent from the live list, leaving some dead-end pointers that assume dormant groups.
Maintenance
Related MCP Connectors
8 MCP servers, 104+ tools: memory, social, PDF, email, images, calendar, scheduler, files.
One MCP server for all your MCP servers: code mode, per-tool permissions, approvals and audit.
Screenshots, PDFs, image editing, QR codes, email validation and more through one hosted MCP server.
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
Related MCP Servers
- FlicenseNot gradedqualityNot gradedmaintenanceA feature-rich Model Context Protocol server built with FastMCP that provides various tools including basic utilities, network services, file operations, encryption tools, and system information functions.1-
- AlicenseNot gradedqualityDmaintenanceA lightweight Windows-native MCP server providing a consolidated suite of 14 tools for shell execution, file operations, and interactive process management. It optimizes efficiency through batch file operations and smart process handling to minimize context window overhead.2 npm4MIT
- FlicenseNot gradedqualityDmaintenanceA production-ready, modular MCP server with 40+ tools across 8 categories, featuring dynamic auto-loading and sandboxed security for file system, database, and network operations.-
- FlicenseNot gradedqualityDmaintenanceA powerful filesystem MCP server for AI agents with extensive system access, including filesystem operations, shell execution, Windows tools, reverse engineering, code intelligence, and agent orchestration.1-