tidy-mcp

✨ Features

• 📁 Any folder, any repo — not locked to one tool. Point Tidy at a folder + a git remote and it handles the rest.

• ⏰ Per-repo schedules, many times — one folder can back up at 08:00, 12:30, 18:00 — add as many as you like.

• 🔄 True two-way sync — fetch → pull --rebase → commit → push. Edits from other devices merge cleanly.

• 🍞 Tray mini-panel — right-click the tray icon for a tiny control panel. No window needed for quick actions.

• 🎨 5 pixel themes — Neon Grid, CRT Terminal, Game Boy, Watermelon, Paper Desk. Switch live.

• 🖥️ Desktop app + headless CLI/TUI — same engine, two faces. Runs 24/7 on your laptop or a VPS.

• 🤖 MCP server + CLI — Claude, Cursor, Cline, and pi can control Tidy with natural language.

• 📦 One install script + AppImage — install.sh (laptop or --server VPS mode) and a portable AppImage.

Related MCP server: duplicati-mcp

🚀 Quickstart

Desktop (laptop)

bash install.sh
tidy-gui

Headless (VPS, 24/7)

bash install.sh --server
tidy add /srv/notes --at 18:00
systemctl --user enable --now tidy

AppImage

Download tidy-<version>.AppImage, make it executable, double-click:

chmod +x tidy-0.1.0.AppImage
./tidy-0.1.0.AppImage

🖥️ CLI & TUI

tidy status              # state of all repos (human + --json)
tidy add ~/Notes --at 18:00      # register a folder + schedule
tidy remove ~/Notes
tidy schedule ~/Notes --at 21:00 # add another time to a repo
tidy backup all          # push everything now
tidy pull ~/Notes
tidy serve               # daemon mode → 24/7 engine, no GUI
tidy tui                 # interactive full-screen terminal UI
tidy gui                 # desktop pixel GUI (window + system tray mini-panel)
tidy-gui                 # same as `tidy gui` (direct entry point)

🖥️ Desktop GUI (Phase 5)

tidy gui (or tidy-gui) opens a pywebview window with the pixel dashboard:

• Repo cards — path, remote status, schedule chips (click ✕ to remove, ＋ ADD TIME for another slot)

• Actions — BACKUP + PUSH ALL, PULL ALL, per-repo ▶ PUSH, ＋ ADD REPO (native folder dialog)

• Theme switcher — live pixel theme dots (Neon Grid, CRT Terminal, Game Boy, Watermelon, Paper Desk)

• Activity log — live tail of the JSONL log (polls every 4s)

• System tray — right-click mini-panel: status line, per-repo push, backup/pull all, theme menu, show window, quit

The tray is skipped automatically when no display is available (headless VPS).

🤖 MCP for AI agents

Tidy exposes an MCP server so AI agents can control backups:

Register it with Claude Desktop:

{
  "mcpServers": {
    "tidy": { "command": "tidy-mcp", "args": [] }
  }
}

Run the server with tidy-mcp (or python -m tidy.mcp). A ready sample is in docs/mcp-claude.json; full setup (Claude Desktop, Cursor, Cline, pi) is in docs/MCP.md.

For pi the same power is exposed as a tidy skill (installed at ~/.agents/skills/tidy/, versioned in skills/tidy/SKILL.md) that drives the tidy CLI directly.

🎨 Themes

Five built-in pixel themes, switchable live from the GUI, CLI, or MCP:

Design mockups live in designs/.

🛠️ Development

git clone https://github.com/Twarga/Tidy
cd Tidy
./dev.sh            # pretty launcher — GUI / TUI / daemon / shell
./dev.sh gui        # straight to the desktop GUI

dev.sh bootstraps the venv (with --system-site-packages so PyGObject/webkit work for the GUI), installs the editable package + extras with a spinner, detects whether a display is available, and drops you into a menu:

python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
tidy status

This repo ships a devcontainer — open it in GitHub Codespaces or VS Code for a secure, configured development environment with everything preinstalled.

Docs

Testing

pytest            # 105 tests — unit + integration against real git pairs
ruff check .      # lint
ruff format .     # format

Structure

Tidy/
├── src/tidy/          # the engine + CLI + GUI + MCP
├── designs/           # 5 pixel theme mockups
├── packaging/         # systemd units, AppImage build, PyInstaller spec
├── docs/              # CLI/MCP/manual-test reference
├── skills/            # pi skill (installed to ~/.agents/skills/tidy)
├── install.sh         # one-command setup (laptop / --server)
├── pyproject.toml     # package metadata (tidy, tidy-gui, tidy-mcp)
└── .devcontainer/     # Codespaces dev environment

📄 License

MIT © 2025 Twarga