sassyconsultingllc/SassyMCP
GitHub: sassyconsultingllc/SassyMCP
一个整合 270 个工具的统一 MCP 服务器，以单一可执行文件替代 75+ 个独立 MCP server，解决 AI agent 工具链碎片化与 context window 浪费问题。
Stars: 4 | Forks: 2
# SassyMCP
**一个 MCP server 统治一切。**
**270 个工具 | 35 个模块 | 18 个工具组 | 替代 75+ MCP server | 34MB 独立 exe**
*最后更新：2026-06-18 — v1.8.0 | 一次性永久授权 (免费 / 专业 / 取证)*
兼容 Claude Desktop, Grok Desktop, Cursor, Windsurf 以及任何 MCP client。
## 为什么选择 SassyMCP？
MCP 生态系统非常碎片化。需要文件操作？安装 Filesystem server。需要终端？Desktop Commander。GitHub？又一个 server。Android？又一个。截图？又一个。你最终会装上 6-10 个独立的 MCP server，每一个都在消耗 context window，每一个都有自己的配置、bug 和更新周期。
SassyMCP 用一个 34MB 的 exe 取代了 **75+ 个独立的 MCP server** —— 包括 [Desktop Commander](https://github.com/wonderwhy-er/DesktopCommanderMCP) (5.9k stars)、[Windows-MCP](https://github.com/CursorTouch/Windows-MCP) (5k stars)、[GitHub MCP Server](https://github.com/github/github-mcp-server) (28.6k stars)、Anthropic 官方的 [Filesystem](https://github.com/modelcontextprotocol/servers/tree/main/src/filesystem) 和 [Memory](https://github.com/modelcontextprotocol/servers/tree/main/src/memory) server、[mobile-mcp](https://github.com/mobile-next/mobile-mcp) (4.4k stars)，以及更多。
**核心差异化优势：**
- **智能工具加载** — 仅加载你使用的工具组。默认将 context window 开销从约 25K tokens 减少到约 5K tokens。
- **动态视觉** — 桌面和 Android 的实时屏幕监控与变化检测。告别盲拍。
- **Android 交互** — 通过 UI accessibility tree 实现完整的手机控制：点击、滑动、输入，并自动检测敏感上下文（身份验证/支付屏幕自动拦截）。
- **暂停/恢复** — 用户接管手机执行手动步骤（登录、2FA、选择账户），AI 观察并学习，然后自主恢复。
- **使用追踪** — 对工具调用进行 ML-lite 评分并采用指数衰减。你最常用的工具会优先加载。
- **上下文估算** — 内置工具，用于测量工具定义占用了你 200K context window 中的多少。
- **响应压缩** — 剥离 GitHub API 响应中冗余的 URL metadata（缩小 40-70%）。
- **安全删除** — 跨所有 shell 拦截删除命令（`rm`, `del`, `Remove-Item` 等）。目标不会被销毁，而是被移动到同目录下的 `_DELETE_/` 暂存文件夹中供人工审查 —— 防范 AI 幻觉。
- **自我修改** — 无需重启即可热重载模块，发生语法错误时通过 git 回滚。
- **引导式设置** — 向导引导你完成 persona、GitHub token、SSH 凭据以及可选的工具发现。
## 替代了什么
| 领域 | SassyMCP 模块 | 替代了 | 顶级替代方案 |
|--------|----------------|----------|----------------|
| 文件操作 | FileOps, Editor | 11 个 filesystem/editor MCP server | [Filesystem](https://github.com/modelcontextprotocol/servers/tree/main/src/filesystem) (Anthropic 官方) |
| Shell / 终端 | Shell, Session | 5 个 shell MCP server | [Desktop Commander](https://github.com/wonderwhy-er/DesktopCommanderMCP) (5.9k stars) |
| 桌面自动化 | UIAutomation, Vision | 9 个桌面 MCP server | [Windows-MCP](https://github.com/CursorTouch/Windows-MCP) (5k stars) |
| GitHub / Git | GitHub Quick, GitHub Full | 5 个 GitHub/Git MCP server | [GitHub MCP Server](https://github.com/github/github-mcp-server) (28.6k stars) |
| Android / 手机 | ADB, PhoneScreen | 9 个移动端 MCP server | [mobile-mcp](https://github.com/mobile-next/mobile-mcp) (4.4k stars) |
| 网络扫描 | NetworkAudit | 8 个 nmap/安全 MCP server | [mcp-for-security](https://github.com/cyproxio/mcp-for-security) (601 stars) |
| 安全审计 | SecurityAudit | 8 个安全 MCP server | [mcp-security-hub](https://github.com/FuzzingLabs/mcp-security-hub) (509 stars) |
| SSH / 远程 Linux | Linux | 7 个 SSH MCP server | [ssh-mcp](https://github.com/tufantunc/ssh-mcp) (365 stars) |
| 记忆 / 状态 | Memory, StateManager | 7 个 memory MCP server | [mcp-memory-service](https://github.com/doobidoo/mcp-memory-service) (1.6k stars) |
| OCR / 屏幕阅读 | Vision | 7 个 OCR/视觉 MCP server | [PaddleOCR MCP](https://paddlepaddle.github.io/PaddleOCR/) |
| Web 检查 | WebInspector, Utility | 7 个 web/fetch MCP server | [Fetch](https://github.com/modelcontextprotocol/servers/tree/main/src/fetch) (Anthropic 官方) |
| Windows 系统 | Registry, ProcessManager, Clipboard, EventLog, Bluetooth | 13 个 Windows MCP server | [Windows-MCP](https://github.com/CursorTouch/Windows-MCP) (5k stars) |
| 热重载 | SelfMod | 3 个重载 MCP server | [mcp-reloader](https://github.com/mizchi/mcp-reloader) |
**此外，还有一些没有对应 MCP server 的功能：** 手机暂停/恢复及敏感上下文检测（在登录/支付屏幕自动拦截）、操作钩子（14 个专家 playbook）、安全删除拦截、Windows autorun 取证、Android+Windows 剪贴板同步、基于使用频率的智能加载。
## 授权与版本
SassyMCP 通过 [LemonSqueezy](https://sassyconsultingllc.com/sassymcp) 以**一次性永久授权**（非订阅）方式销售。免费版开箱即用，无需密钥 —— 付费版可解锁额外的工具组。一次购买，终身拥有；退款将自动撤销授权。
| 版本 | 解锁内容 | 获得功能 |
|---|---|---|
| **免费版** | core, meta, github_quick, persona, setup, infrastructure, utility, selfmod, memory, updater, prompts, combos | 文件操作、shell、桌面自动化、日常驱动 GitHub、持久化 memory、精准编辑、审计日志、多客户端安装 —— 足以将 SassyMCP 作为日常驱动工具，只是不包含重量级自动化接口。 |
| **专业版** | 免费版 + `github_full`, `android`, `v020`, `linux`, `system` | 完整的 GitHub API（80 个工具）、Android 手机控制 + 动态视觉、OCR、应用启动器、web inspector、crosslink、远程 Linux SSH、系统监控、剪贴板同步、事件日志。 |
| **取证版** *(附加项)* | `forensics` 组：`security_audit`, `registry` | 在免费版或专业版基础上叠加。APK 检查、证书验证、哈希 + 权限审计、Defender / 防火墙状态、注册表读取/写入/导出、autorun 取证。 |
**激活流程：**
1. 在 `https://sassyconsultingllc.com/sassymcp` 购买 —— LemonSqueezy 会通过电子邮件发送给你一个密钥（`XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX`）。
2. 从你的 AI agent 处激活：`sassy_setup_license action=activate key=...`
3. 或者从终端激活：`sassymcp.exe setup` 会打开交互式菜单。
4. SassyMCP 调用 LS 将该机器注册为一个实例，生成本地 HMAC 签名的 payload，并在下一次 server 重启时解锁付费组。
**离线运行：** 一旦激活，本地 HMAC payload 即可让 SassyMCP 完全离线运行。每周针对 LS 的权威复查会检测退款和取消行为；针对 SassyMCP 计费预言机的更快启动检查将退款到撤销的延迟缩短至几秒钟。
**安全故障模式：** 缺失、过期、被篡改或损坏的授权文件会静默降级为免费版 —— 产品绝不会变砖。激活或重新验证期间的网络错误会保留本地授权。
**开发者逃生舱：** 设置 `SASSYMCP_LICENSE_BYPASS=1` 可无视授权状态解锁所有组。专用于上游代码库开发、CI 和物理隔离支持场景。以 WARNING 级别记录日志。
## 运行托管模式 (`sassymcp supervise`)
对于常驻 / 远程部署，请在 SassyMCP 内置的监督程序下运行，而不是使用简单的启动脚本：
```
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 stop
```
监督程序掌控 runtime tree，使其具备自我修复能力且**防止孤儿进程**：
- **绝不会出现孤儿进程。** 强制杀死监督程序（崩溃、`kill -9`、`taskkill /f`）会连带杀死所有子进程 —— 在 Windows 上通过 Job Object (`KILL_ON_JOB_CLOSE`) 实现，在 Linux 上通过进程组 + `PR_SET_PDEATHSIG` 实现。不会有残留的桥接进程占用死锁的 SQLite/WAL 锁，而这正是旧的基于 `taskkill` 的脚本所导致的问题。
- **自我修复。** 崩溃的子进程将以指数退避算法重启（并且在崩溃循环后干净地放弃，而不是死循环）。
- **捕获卡死。** HTTP 就绪探针会回收*卡死但仍存活*的桥接进程 —— 这是 Windows 计划任务永远无法检测到的故障。
- **在崩溃中存活的控制。** `$SASSYMCP_HOME` 下的 pidfile + 磁盘注册表意味着，即使桥接进程宕机，`supervise status`/`stop` 也能正常工作，因此操作员或 agent 可以恢复死锁的系统。
`start-supervised.bat` 将此封装为推荐的 Windows 启动器。stdio 模式（Claude Desktop 管道）由客户端掌控，因此特意不被监督。
## 模块
| 模块 | 工具 | 组 | 描述 |
|--------|-------|-------|-------------|
| **Meta** | 9 | meta | 上下文估算、工具使用分析、组管理 |
| **FileOps** | 10 | core | 读取、写入、搜索、移动、复制、编辑、mkdir、文件信息、安全删除 |
| **Shell** | 2 | core | PowerShell, CMD, WSL 执行，带语法规范化和删除拦截 |
| **UIAutomation** | 6 | core | 桌面状态、点击、输入、热键、截图、屏幕信息 |
| **Editor** | 2 | core | 精准查找/替换、多重编辑 |
| **Audit** | 4 | core | 审计日志读取、搜索、清除、误报追踪 |
| **Session** | 6 | core | 持久化终端会话（启动、读取、发送、停止） |
| **GitHub Quick** | 6 | github_quick | 日常驱动：push_files, get_file, issue, PR, protect |
| **Persona** | 7 | persona | 专家模式指令、决策框架、工程标准 |
| **Utility** | 11 | utility | 环境变量、toast、zip/tar/unzip/untar、HTTP 请求、文件 diff |
| **SelfMod** | 8 | selfmod | 自编辑、热重载、重启、回滚、状态 |
| **Setup** | 8 | setup | 设置向导、GitHub token 指南、SSH 设置、工具检查器、授权激活 |
| **ToolsManager** | 1 | setup | 外部工具引导和检测 |
| **Observability** | 3 | infrastructure | 健康、指标、工具统计 |
| **StateManager** | 3 | infrastructure | 跨会话的持久化键值状态 |
| **RuntimeConfig** | 3 | infrastructure | 运行时配置、最近的工具调用 |
| **Memory** | 9 | memory | 跨会话的持久化记忆、里程碑、任务交接、模式学习 |
| **Updater** | 4 | updater | 版本检查、更新日志、自我更新 (Kali 风格) |
| **GitHub Full** | 80 | github_full | 完整的 GitHub API：repos, issues, PRs, actions, security, gists |
| **ADB** | 10 | android | Android shell、包、文件传输、logcat、屏幕截图 |
| **PhoneScreen** | 14 | android | UI tree 读取器、手机概览/监控、点击/滑动/输入/按键、暂停/恢复、scrcpy |
| **NetworkAudit** | 7 | system | netstat, ARP, WiFi 扫描、端口扫描、DNS、traceroute |
| **ProcessManager** | 5 | system | Windows + Android 进程列表/杀掉、系统信息 |
| **SecurityAudit** | 7 | forensics | 哈希、权限、证书、APK、防火墙、Defender — *需要 Forensics 附加组件* |
| **Registry** | 4 | forensics | 读取、写入、导出、autorun 取证 — *需要 Forensics 附加组件* |
| **Bluetooth** | 3 | system | Windows + Android BT 枚举 |
| **EventLog** | 3 | system | Windows Event Log + Android logcat |
| **Clipboard** | 4 | system | + Android 剪贴板同步 |
| **Vision** | 8 | v020 | 屏幕捕获、OCR、动态概览/监控/差异对比 |
| **AppLauncher** | 6 | v020 | 启动应用、聚焦/关闭/调整大小/吸附窗口 |
| **WebInspector** | 5 | v020 | 安全标头、URL 截图、技术栈检测 |
| **Crosslink** | 7 | v020 | 通过 HTTP API + SQLite 进行跨会话消息传递 |
| **Linux** | 1 | linux | 通过 plink 执行远程 SSH |
| **Combos** | 4 | combos | 一步调用执行多步骤工作流：PR 审查、手机观察、代码库 grep |
| **Prompts** | 0 | prompts | MCP 斜杠菜单快捷方式 (pr-review, phone-status, resume, brain-status, setup-sassy) |
## 动态视觉
### 桌面 (Vision 模块)
传统的 MCP 截图是盲目的 —— 你捕获一帧并祈祷它是正确的。SassyMCP 的动态视觉改变了这一点：
| 工具 | 用途 |
|------|---------|
| `sassy_screen_glance` | 以约 3-6KB 的大小进行快速灰度捕获。重复调用以“监视”屏幕。 |
| `sassy_screen_watch` | 监控 N 秒，**仅返回内容发生变化的帧**（像素差异阈值）。 |
| `sassy_screen_diff` | 前/后对比 —— 拍下一帧，等待，再拍一帧，返回两帧图片以及一张突出显示变化的差异图。 |
这三个工具都使用灰度 + 高强度 JPEG 压缩，以将 context 消耗降至最低。一次概览约为 2KB，而全彩捕获约为 14KB。
### Android (PhoneScreen 模块)
手机不仅仅是一个摄像头目标 —— SassyMCP 会读取其 UI accessibility tree：
| 工具 | 用途 |
|------|---------|
| `sassy_phone_ui` | 读取**每一个可见的 UI 元素** —— 文本、描述、坐标、可点击/聚焦/选中状态。返回的是结构化数据，而不是像素。 |
| `sassy_phone_state` | 前台应用、屏幕开/关、电量、WiFi、通知数量。 |
| `sassy_phone_glance` | 通过直接管道获取低分辨率灰度手机屏幕截图（约 4-8KB）。 |
| `sassy_phone_watch` | 监控持续时间内 UI tree 的变化。仅在元素发生变化时返回快照。 |
## 手机交互
通过 ADB 进行完整的触摸输入 —— AI 可以操作手机：
| 工具 | 用途 |
|------|---------|
| `sassy_phone_tap` | 点击屏幕坐标 |
| `sassy_phone_swipe` | 在两点之间滑动 |
| `sassy_phone_type` | 在聚焦的输入框中输入文本 |
| `sassy_phone_key` | 发送按键事件 (HOME, BACK, ENTER, VOLUME 等) |
| `sassy_phone_open` | 通过包名启动应用 |
### 敏感上下文检测
所有交互工具（点击、滑动、输入）在执行前都会自动扫描 UI tree。如果它们检测到**登录屏幕、支付表单、账户选择器、2FA 提示或权限对话框**，该工具将**拒绝执行**，并返回它看到的内容。然后 AI 会向你描述屏幕并询问该怎么做。在用户明确批准后，传入 `confirmed=True`。
## 安全删除（删除拦截）
AI agent 可能会产生破坏性命令的幻觉。SassyMCP 拦截了跨所有 shell 和所有工具入口点的**所有**删除系列命令，然后将目标移动到 `_DELETE_/` 暂存文件夹中，而不是销毁它们。每次拦截都会将原始命令、解析出的目标和移动结果写入审计日志。
**覆盖范围 —— 每个破坏性路径都已设防：**
| 工具 | 防护措施 |
|------|-------|
| `sassy_shell` | 拦截删除命令，将目标暂存到 `_DELETE_/` |
| `sassy_session_send` / `sassy_session_start` | 相同的拦截器 —— 持久化终端无法绕过 |
| `sassy_linux_exec` | 拒绝在远程主机上执行破坏性命令 |
| `sassy_adb_shell` | 拒绝在 Android 设备上执行破坏性命令（使用 `allow_destructive=True` 覆盖） |
| `sassy_safe_delete` | 显式暂存工具 —— 以符号链接形式移动符号链接（移动路径中不使用 `resolve()`） |
| `sassy_write_file` (重写模式) | 覆盖前将现有文件快照保存到 `_DELETE_/` |
| `sassy_edit_block` / `sassy_edit_multi` | 拒绝受保护路径，在应用前将现有内容快照保存到 `_DELETE_/.pre-edit.` |
| `sassy_copy` | 拒绝现有目标（不静默覆盖），拒绝受保护的源/目标 |
| `sassy_move` | 拒绝静默覆盖目标，拒绝受保护的源/目标 |
| `sassy_selfmod_edit` / `sassy_selfmod_write` | 语法错误的写入会被重命名为 `.bad.`（绝不unlink） |
| `sassy_selfmod_rollback` | 需要 `confirm='YES'` —— 丢弃未提交的更改 |
| `sassy_audit_clear` | 轮换审计日志而不是删除它；需要 `confirm='YES'` |
**被拦截的命令关键词：** `rm`, `rmdir`, `unlink` (Unix/WSL), `del`, `erase`, `rd` (CMD), `Remove-Item`, `ri`, `rni` (PowerShell 别名), `sdelete` / `sdelete64` (Sysinternals)。
**同样会被捕获（除了裸关键词外）：**
- Shell 包装器 —— `powershell -c "del foo"`, `cmd /c del foo`, `bash -c "rm foo"`, `wsl -- rm foo`（payload 会被递归扫描）
- Base64 payload —— `powershell -EncodedCommand ` 会被解码 (UTF-16-LE) 并递归扫描
- `.NET` 调用 —— `[System.IO.File]::Delete(...)`, `[System.IO.Directory]::Delete(...)`
- `Clear-Content`, `Set-Content -Value ''`（仅限字面量空值 —— 正常的 `-Value "foo"` 是允许的）
- `Out-File -Force`, `New-Item -Force`（覆盖模式）
- `copy /y`, `xcopy /y` —— CMD 静默覆盖标志
- **`robocopy /MIR` 和 `robocopy /PURGE`** —— 镜像/清除模式会删除目标文件
- 通过重定向截断 —— `> file.txt`, `type foo > bar.txt`, `cmd; > file.txt`（追加 `>>` 和流 `2>` / `&>` 会被正确忽略）
- `Move-Item foo $null`
- 赋值前缀 —— `$null = ri foo` 会被正确解包
**受保护的根目录**（被每个受防护的工具拒绝，不仅仅是拦截器）：SassyMCP 源码树本身、`~/.sassymcp/`（审计 + 配置），以及任何 `_DELETE_/` 暂存文件夹（无暂存递归）。保护机制使用 `resolve()`，因此路径遍历（`..\`）、符号链接和 Windows 8.3 短文件名在检查前都能正确标准化。
| 场景 | 结果 |
|----------|--------|
| `rm -rf /` | 被常驻黑名单**强制拦截** —— 不尝试移动 |
| `rm important.txt` | 已拦截，文件被移动到 `./_DELETE_/important.txt` |
| `del /q *.log` | 已拦截，所有 `.log` 文件被移动到 `./_DELETE_/` |
| `Remove-Item -Path C:\data\old` | 已拦截，`old` 被移动到 `C:\data\_DELETE_\old` |
| `cmd /c del foo` (包装器) | 已拦截 —— payload 被解包并拦截 |
| `gci *.tmp \| ri` (PS 别名) | 已拦截 —— 匹配到 `ri` 别名 |
| 在现有文件上执行 `sassy_write_file("doc.txt", ..., "rewrite")` | 现有内容首先被快照到 `_DELETE_/doc.overwrite..txt` |
| `ls -la` | 正常执行 —— 不是删除命令 |
`_DELETE_/` 中的名称冲突会自动使用计数器后缀处理（`file.txt`, `file_1.txt`, `file_2.txt`）。在 Windows 上，带反斜杠的路径（`C:\Users\foo\bar`）会被解析器正确保留 —— 不会被 `shlex` 破坏。
### 暂停 / 恢复
适用于用户需要接管的复杂流程：
| 工具 | 用途 |
|------|---------|
| `sassy_phone_pause` | 拦截所有交互工具。观察工具 (ui, glance, watch) 仍然有效。 |
| `sassy_phone_resume` | 解除对交互的拦截。AI 会根据暂停期间观察到的所有内容，从中断的地方继续执行。 |
**工作流程：**
1. AI 自主操作手机完成日常任务
2. AI 遇到登录屏幕 → 敏感上下文自动拦截 → AI 告知用户
3. 用户说“等等” → AI 调用 `sassy_phone_pause`
4. 用户手动登录。AI 通过 `sassy_phone_ui` / `sassy_phone_glance` 进行观察
5. 用户说“完成” → AI 调用 `sassy_phone_resume`
6. AI 继续执行，此时它已知道用户登录了特定账户
## 引导式设置
首次启动时（没有 `~/.sassymcp/persona.md`），向导工具会显著显示，并通过注册的 hook 为 AI 提供一份入门 playbook。流程是对话式的 —— AI 提问，你回答，它调用工具。
### 入门流程（推荐顺序）
每一步都是独立且可跳过的。只需告诉 AI “set up SassyMCP” 或 “let's get started”，它就会引导你完成：
| # | 步骤 | 工具 | 发生了什么 |
|---|------|------|--------------|
| 0 | **授权** | `sassy_setup_license action="status"` 然后 `action="activate" key=...` | 报告当前版本。如果你有专业/取证版密钥，将激活它并解锁受限工具组。 |
| 1 | **Persona** | `sassy_setup_wizard` | 询问下面的问卷，生成 `~/.sassymcp/persona.md`，热重载 persona 模块。 |
| 2 | **GitHub** | `sassy_setup_github action="check"` → `action="open_browser"` → `action="save_token" token=...` | 验证现有的 `GITHUB_TOKEN`，或打开 [github.com/settings/tokens](https://github.com/settings/tokens?type=beta)，引导你选择权限范围，然后保存并重新验证。 |
| 3 | **SSH / Linux** | `sassy_setup_ssh action="check"` → `action="save" host=... user=... password=...` → `action="test"` | 定位 `plink`，将凭据存储在进程 env 中，运行一次 `echo` 往返测试以验证。 |
| 4 | **可选工具** | `sassy_setup_check_tools` | 扫描 `nmap`, `tesseract`, `adb`, `scrcpy`, `plink`, Chrome；报告缺失项的安装 URL。 |
| ✓ | **状态检查** | `sassy_setup_status` | 显示哪些已配置，哪些仍然缺失，以及 action_required 提示。随时可以运行。 |
| ⚙️ | **Auth 令牌** | `sassy_setup_generate_token client_id="claude-desktop"` | 为 HTTP/隧道模式生成 32 字节 URL 安全令牌，并写入 `~/.sassymcp/tokens.json`。 |
在支持的步骤中使用 `action="skip"` 跳过任何步骤 —— 配置会记录跳过操作，这样 AI 就不会再次提示。
### persona 问卷
`sassy_setup_wizard` 接受这些字段。均为可选 —— 显示的是默认值。
| 字段 | 值 / 格式 | 默认值 |
|---|---|---|
| `role` | `developer` \| `sysadmin` \| `security` \| `devops` \| `data` \| `designer` \| `manager` \| `other` | `developer` |
| `expertise_level` | `junior` \| `mid` \| `senior` \| `principal` \| `staff` | `senior` |
| `specializations` | 逗号分隔的领域 —— 例如 `"web security, cloud infra, mobile"` | 为空 |
| `languages` | 逗号分隔 —— 例如 `"Python, Rust TypeScript, Go"` | 为空 |
| `frameworks` | 逗号分隔 —— 例如 `"React, FastAPI, Cloudflare Workers"` | 为空 |
| `systems` | 换行分隔的 `主机名 — 操作系统 — 角色` 条目 | 为空 |
| `projects` | 换行分隔的 `名称 — 状态 — 描述` 条目 | 为空 |
| `communication_style` | `terse` (仅代码) \| `balanced` (简要解释) \| `verbose` (详细理由) | `terse` |
| `security_posture` | `standard` (OWASP) \| `hardened` (+ CSP/HSTS/rate-limit) \| `paranoid` (+ air-gap, cert pinning, zero trust) | `standard` |
| `mcp_clients` | 连接的 AI 工具 —— 例如 `"Claude Desktop, Cursor, Grok Desktop"` | 为空 |
| `notes` | 自由格式文本 —— AI 应该了解的关于你工作方式的任何其他信息 | 为空 |
输出将发送到 `~/.sassymcp/persona.md`（persona 模块在每次会话时读取它），运行记录将保存在 `~/.sassymcp/config.json`（`setup_complete`, `setup_timestamp`, `setup_version`）。随时重新运行 `sassy_setup_wizard` 以重新生成 —— persona 模块会使用新的配置文件进行热重载。
### 从你的客户端触发流程
入门 hook 会在类似 `"setup"`, `"first time"`, `"get started"`, `"onboard"`, `"new user"`, `"set up sassymcp"` 的短语上触发。任何与这些接近的表述都会将 playbook 拉入 AI 的上下文。如果你想手动驱动它，只需先调用 `sassy_setup_status` 查看你进行到了哪一步，然后按照上面的表格走。
## 智能加载
默认情况下，SassyMCP 仅加载常用的工具组。这使工具定义保持在 context window 的 5% 以下。
```
# 默认：加载 core, github_quick, persona, meta, utility, selfmod, setup, infrastructure
uv run sassymcp
# 加载所有内容（270 个 tools，约 22K tokens 的 context）
SASSYMCP_LOAD_ALL=1 uv run sassymcp
# 加载特定 groups
SASSYMCP_GROUPS=core,github_quick,android,v020 uv run sassymcp
```
### 可用组
| 组 | 模块 | 默认 |
|-------|---------|---------|
| `core` | fileops, shell, ui_automation, editor, audit, session | 是 |
| `meta` | meta | 是 |
| `infrastructure` | observability, state_manager, runtime_config | 是 |
| `github_quick` | github_quick (6 个精简工具) | 是 |
| `persona` | persona | 是 |
| `utility` | utility | 是 |
| `selfmod` | selfmod | 是 |
| `setup` | setup_wizard, tools_manager | 是 |
| `memory` | memory | 是 |
| `updater` | updater | 是 |
| `combos` | combos (4 个工具) | 否 |
| `prompts` | prompts (斜杠菜单快捷方式) | 是 |
| `github_full` | github_ops (80 个工具) | 否 |
| `android` | adb, phone_screen | 否 |
| `system` | network_audit, process_manager, security_audit, registry, bluetooth, eventlog, clipboard | 否 |
| `v020` | vision, app_launcher, web_inspector, crosslink | 否 |
| `linux` | linux | 否 |
## 安装
选择与你目前工作方式最匹配的入口点。所有这四种方式最终都会汇集到 `~/.sassymcp/` 的同一个共享大脑 —— 你的 persona、记忆、授权和审计日志对每个连接的 MCP client 都是可见的。
### 通过 DXT 一键安装
从[最新发布版](https://github.com/sassyconsultingllc/SassyMCP/releases/latest)下载 `sassymcp.dxt`，双击 —— Claude Desktop 会自动安装它。首次启动时，sassymcp 会自动检测你机器上的所有其他 MCP client（Cursor, VS Code Copilot, Windsurf, Continue, Cline, Zed, Grok Desktop），并修改每个客户端的配置，这样它们都能看到 SassyMCP，而你无需编辑任何 JSON。
### VS Code 扩展
从 VS Code 市场安装 **[SassyMCP](https://marketplace.visualstudio.com/items?itemName=sassyconsultingllc.sassymcp)**。该扩展会定位 `sassymcp.exe`（通过 PATH 或 `sassymcp.exePath` 设置），运行相同的自动配置 CLI，并添加一个状态栏项目以显示你的授权版本和大脑健康状态。五个命令涵盖了设置向导、重新安装配置、打开审计日志、打开 `_DELETE_` 文件夹、显示大脑状态。
### 手动自动配置 CLI
如果你已经有 `sassymcp.exe`（来自便携 zip 或 pip 安装），并希望将其注册到每个 MCP client 而无需针对每个客户端编辑 JSON：
```
sassymcp-install
```
该命令会检测 Claude Desktop, VS Code Copilot, Cursor, Windsurf, Continue, Cline, Zed 和 Grok Desktop，并以原子方式修改每个客户端的配置。重新运行是幂等的。可以先使用 `sassymcp-install --dry-run` 看看会发生什么。使用 `sassymcp-install --uninstall` 移除。CLI 在首次编辑前会对任何现有配置进行带有时间戳的备份。
### 便携包（手动配置 —— 旧路径）
**无需安装程序**，但除非你在之后运行 `sassymcp-install`，否则你需要自己编辑每个客户端的 JSON。
1. 从[最新发布版](https://github.com/sassyconsultingllc/SassyMCP/releases/latest)下载 `sassymcp-v1.3.1-portable.zip`（约 123 MB —— 包括 `sassymcp.exe`, `adb`, `nmap`, `plink`, `scrcpy`, `tesseract`, `cloudflared` 和 `start-*.bat` 启动器）。
2. 解压到任何地方 —— `D:\Tools\SassyMCP`、U盘、你的主文件夹，随便哪里。
3. 运行 `start-local.bat` (Claude Desktop), `start-lan.bat` (局域网 HTTP), 或 `start-tunnel.bat` (Cloudflare Tunnel)。
卸载：删除文件夹。升级：将新的 zip 解压覆盖旧文件夹，或解压到新文件夹并删除旧文件夹。
### 独立可执行文件（未捆绑工具）
如果你不需要捆绑的 `nmap` / `adb` / `cloudflared`（或者你的 PATH 中已经有了），只需从[最新发布版](https://github.com/sassyconsultingllc/SassyMCP/releases/latest)获取 `sassymcp.exe`（约 35 MB）。将其放在任何地方，并将你的 MCP client 指向它。
**首次运行向导：** 在全新的机器上双击 `sassymcp.exe`（或在终端中运行不带任何参数），你将看到一个交互式菜单 —— 自动检测 AI agent 并注册 SassyMCP、激活 LemonSqueezy 授权密钥、生成/列出 bearer token，或启动 HTTP server。随时运行 `sassymcp.exe setup` 重新打开菜单。一旦配置了 persona，裸调用将回退到启动 HTTP server（v1.5 的行为），因此现有设置保持不变。
### 一行 PowerShell 安装（授权受限）
针对已授权用户 —— 通过受限镜像拉取独立 exe：
```
$key = "SASSY-XXXX-XXXX-XXXX" # from https://sassyconsultingllc.com/pricing.html
$dst = "$env:LOCALAPPDATA\SassyMCP"
New-Item -Force -ItemType Directory $dst | Out-Null
Invoke-WebRequest "https://sassyconsultingllc.com/download/sassymcp/windows/sassymcp.exe?key=$key" -OutFile "$dst\sassymcp.exe"
Write-Host "Installed: $dst\sassymcp.exe"
```
### 授权受限下载
**[获取授权 →](https://sassyconsultingllc.com/pricing.html)**。结账后你将收到一个 `SASSY-...` 密钥；将其粘贴到下载 URL 中：
- `https://sassyconsultingllc.com/download/sassymcp/windows/sassymcp.exe?key=SASSY-...` — 独立 exe，约 35 MB
- `https://sassyconsultingllc.com/download/sassymcp/windows/sassymcp-v1.3.1-portable.zip?key=SASSY-...` — 完整便携包，约 123 MB
两者均不需要 Python。
### 从源码构建
```
git clone https://github.com/sassyconsultingllc/SassyMCP.git
cd SassyMCP
uv sync
# 可选 dependencies：
uv pip install pytesseract playwright
playwright install chromium
```
### Cloudflare Tunnel（远程访问）
想从远程 MCP client（Claude Web，另一台机器）驱动 SassyMCP 吗？便携包提供了一个开箱即用的启动器。完整的分步指南在 [**docs/TUNNEL.md**](docs/TUNNEL.md) 中；简短版本如下：
```
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..tld
# 将 ingress block 写入 ~/.cloudflared/config.yml（参见 TUNNEL.md）
[Environment]::SetEnvironmentVariable("SASSYMCP_AUTH_TOKEN", "", "User")
[Environment]::SetEnvironmentVariable(
"SASSYMCP_ALLOWED_HOSTS",
"mcp..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_NAME
```
`start-tunnel.bat` 在前台启动 `127.0.0.1:21001` 上的 HTTP 桥接，并运行 `cloudflared tunnel run `。脚本中没有任何内容是与特定供应商绑定的 —— 你只需提供隧道名称和主机名。客户端向 `https://mcp..tld/mcp` 发送 `Authorization: Bearer `。
对于需要 OAuth 2.1 DCR/PKCE 而不是静态 bearer 的托管型 Claude 客户端，请部署 `sassymcp-oauth/` 下的可选 Worker —— 将 `wrangler.toml.example` 复制为 `wrangler.toml`，填入你的主机名和 KV id，然后 `wrangler deploy`。完整的 OAuth 部分请参见 `docs/TUNNEL.md`。
## MCP Client 配置
SassyMCP 说着标准的 MCP。任何连接的客户端都可以工作 —— **无需客户端修改**。便携包在 `deploy/*_config.template.json` 下提供了随时可编辑的模板。选择与你客户端对应的那一行，复制模板，用 `sassymcp.exe` 的绝对路径替换 `REPLACE_WITH_PATH`，并将其保存在客户端期望的位置。
| 客户端 | 传输方式 | 配置文件位置 | 模板 |
|--------|-----------|----------------------|----------|
| **Claude Desktop** | stdio | `%APPDATA%\Claude\claude_desktop_config.json` (Win) / `~/Library/Application Support/Claude/claude_desktop_config.json` (mac) | `claude_desktop_config.template.json` |
| **Cursor** | stdio | `~/.cursor/mcp.json` (全局) 或 `/.cursor/mcp.json` (每个项目) | `cursor_mcp_config.template.json` |
| **Windsurf** | stdio | `~/.codeium/windsurf/mcp_config.json` | `windsurf_mcp_config.template.json` |
| **Cline (VS Code)** | stdio | VS Code 设置 → `cline.mcpServers` (相同的 `mcpServers` 结构) | 使用 `claude_desktop_config.template.json` |
| **Continue.dev** | stdio | `~/.continue/config.json` (在 `experimental.modelContextProtocolServers` 下合并) | `continue_mcp_config.template.json` |
| **Grok Desktop** | HTTP | Grok Desktop MCP 设置 | `grok_desktop_config.template.json` |
| **任何其他 MCP client** | stdio 或 HTTP | 客户端的 MCP 配置 | 使用最接近的模板；`mcpServers` 结构是约定俗成的 |
### 标准 `mcpServers` 结构 (Claude Desktop, Cursor, Windsurf, Cline)
使用 exe：
```
{
"mcpServers": {
"sassymcp": {
"command": "C:\\path\\to\\sassymcp.exe",
"env": {
"SASSYMCP_LOAD_ALL": "1",
"GITHUB_TOKEN": "ghp_your_token_here"
}
}
}
}
```
从源码运行：
```
{
"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 结构 (不同的 schema)
```
{
"experimental": {
"modelContextProtocolServers": [
{
"transport": {
"type": "stdio",
"command": "C:\\path\\to\\sassymcp.exe"
}
}
]
}
}
```
### HTTP / Grok Desktop / 自定义 HTTP 客户端
在 HTTP 模式下运行 server（`sassymcp.exe --http`，默认 `127.0.0.1:21001`）并将你的客户端指向 `http://127.0.0.1:21001/mcp/`。如果绑定到非回环地址，请设置 `SASSYMCP_AUTH_TOKEN`。
```
{
"mcpServers": {
"sassymcp": {
"url": "http://127.0.0.1:21001/mcp/"
}
}
}
```
### 实际上有哪些是 Claude 专属的（仅限外观）
一些 docstring 和旧版 `.claude/skills/sassymcp-update.md` 斜杠命令专门针对 Claude Code。其他客户端会忽略它们并直接使用 `sassy_update_*` 工具。没有任何工具、传输或认证路径要求必须是 Claude —— server 并不知道另一端连接的是哪个 LLM。
## 传输模式
| 模式 | 命令 | 用例 |
|------|---------|----------|
| Stdio | `sassymcp.exe` | Claude Desktop, Cursor (直接管道) |
| HTTP | `sassymcp.exe --http` | Grok Desktop, Windsurf (localhost:21001) |
| 局域网 HTTP | `sassymcp.exe --http --host 0.0.0.0` | 多设备（需要 auth token） |
| HTTPS | `sassymcp.exe --http --ssl` | 加密（自动生成自签名证书） |
| SSE | `sassymcp.exe --http --sse` | 传统传输方式 |
## 运行多个实例（双会话）
同一台机器上的两个 SassyMCP 进程 —— 例如，一个用于 Claude Desktop 的**本地 stdio** 实例和一个通过 Cloudflare Tunnel 为 Claude Web 提供服务的**远程 HTTPS** 实例 —— 如果它们共享 `~/.sassymcp/`，可能会互相干扰彼此的状态。解决方法是每个实例设置一个环境变量。
### 需要为每个实例解决的冲突
| 资源 | 默认值 | 如何为每个实例单独配置 |
|----------|---------|------------------------------------|
| HTTP 端口 | `21001` | `--port 21002` (仅限 HTTP 模式实例) |
| Crosslink HTTP 端口 | `9377` | `sassy_crosslink_register port=9378` |
| Auth token | env `SASSYMCP_AUTH_TOKEN` 在启动器的 env 中按进程设置 |
| 每用户状态目录 | `~/.sassymcp` | **`SASSYMCP_HOME=/path/to/dir`** ← 新的环境变量 (v1.3.4+) |
| SSL 证书/密钥 | `$SASSYMCP_HOME/server.{crt,key}` | 设置 `SASSYMCP_HOME` 时自动隔离；或使用 `--ssl-cert` / `--ssl-key` |
### 示例：本地 stdio + 远程隧道并行运行
**实例 A — 用于 Claude Desktop 的本地 stdio** (claude_desktop_config.json)：
```
{
"mcpServers": {
"sassymcp-local": {
"command": "C:\\Tools\\SassyMCP\\sassymcp.exe",
"env": {
"SASSYMCP_LOAD_ALL": "1",
"SASSYMCP_HOME": "C:\\Users\\\\.sassymcp-local"
}
}
}
}
```
**实例 B — 通过 Cloudflare Tunnel 的远程 HTTPS**（`start-tunnel.bat` + 一个设置 env 的包装器）：
```
set SASSYMCP_HOME=C:\Users\\.sassymcp-remote
set SASSYMCP_AUTH_TOKEN=
set PORT=21002
"%~dp0sassymcp.exe" --http --host 127.0.0.1 --port %PORT%
```
然后 `cloudflared tunnel run ` 会将 `https:///mcp` 转发到 `127.0.0.1:21002`。
### 当 SASSYMCP_HOME 不同时，哪些内容被隔离了
每个实例都有自己的：
- `persona.md` — 每个会话有不同的配置文件
- `config.json` — 不同的运行时配置（允许的目录、被拦截的命令等）
- `tokens.json` — 不同的作用域 auth token
- `license.json` — 独立的授权激活
- `audit.log` / `audit.jsonl` — 没有交错的写入
- `crosslink.db` — 独立的跨会话消息队列
- `memory.db` — 独立的持久化记忆
- `tool_state.db` / `tool_usage.json` — 独立的按工具状态和使用分析
- `server.crt` / `server.key` — 独立的自签名证书
- `_security` 受保护路径检查也遵循 `SASSYMCP_HOME` — 任何一个实例都不能对另一个实例的主目录执行 `sassy_safe_delete`
### 实例之间仍然共享的内容
- 仓库源码树（始终受 `_security` 保护，防止删除/覆盖）
- `%LOCALAPPDATA%\SassyMCP\updates\` — 更新程序下载暂存区（无害；在其下按版本标记）
- 便携 zip 中的捆绑工具（`adb`, `nmap`, `cloudflared` 等）— 两个实例均只读
### 置入操作系统（以便两者在开机时同时启动）
旧版的 `personal/autostart-bridge.bat` + `personal/register-autostart.ps1` 模板被 gitignored 忽略 —— 复制它，为每个实例调整路径和 `SASSYMCP_HOME`，然后为每个实例执行一次 `Register-ScheduledTask`。
## 环境变量
| 变量 | 用途 |
|----------|---------|
| `SASSYMCP_LOAD_ALL=1` | 加载全部 270 个工具 |
| `SASSYMCP_GROUPS=core,android` | 加载特定组 |
| `SASSYMCP_AUTH_TOKEN=xxx` | 用于 HTTP 认证的 Bearer token |
| `SASSYMCP_DEV=1` | 启用实时重载（开发者模式） |
| `SASSYMCP_NO_UPDATE_CHECK=1` | 禁用启动更新检查（不调用 GitHub API） |
| `SASSYMCP_HOME=/path/to/dir` | 覆盖每用户状态目录（默认为 `~/.sassymcp`）。在一台机器上运行多个实例时必需。 |
| `SASSYMCP_REPO=/path/to/repo` | 覆盖 `tools/mercury_audit_sassymcp.py` 中自动检测的仓库根目录（仅限开发工具） |
| `GITHUB_TOKEN=xxx` | GitHub API 访问 |
| `SSH_HOST=xxx` | 远程 Linux 主机名/IP |
| `SSH_USER=xxx` | 远程 Linux 用户名 |
| `SSH_PASS=xxx` | 远程 Linux 密码 |
## 外部工具
全部捆绑在 [beta zip 包](https://github.com/sassyconsultingllc/SassyMCP/releases)中。仅在使用独立 exe 时单独安装。
| 工具 | 使用者 | 已捆绑 | 安装（如果需要） |
|------|---------|---------|---------------------|
| ADB | 所有 `sassy_adb_*` + `sassy_phone_*` 工具 | 是 | [Android Platform Tools](https://developer.android.com/tools/releases/platform-tools) |
| nmap | `sassy_port_scan` | 是 | [nmap.org](https://nmap.org/download.html) |
| plink | `sassy_linux_exec` | 是 | [PuTTY](https://www.chiark.greenend.org.uk/~sgtatham/putty/latest.html) |
| scrcpy | `sassy_scrcpy_*` 工具 | 是 | [scrcpy 发布版](https://github.com/Genymobile/scrcpy/releases) |
| Tesseract | `sassy_screen_ocr`, `sassy_find_text_on_screen` | 是 | [tesseract-ocr](https://github.com/tesseract-ocr/tesseract) |
| Chrome | `sassy_url_screenshot` | 否 | [google.com/chrome](https://www.google.com/chrome/) |
运行 `sassy_setup_check_tools` 以验证是否检测到所有工具。
## 系统要求
- Windows 10/11
- Python 3.11+（仅在从源码运行时需要；exe 是自包含的）
## 许可证
MIT License - Sassy Consulting LLC
标签：AI代理工具, AI合规, Android自动化, MCP服务器, 桌面自动化, 系统运维, 网络安全研究, 自动化控制