cupbox

Chores in, done out. One package that installs as a CLI for humans and as an MCP server for AI agents (Claude Desktop / Cursor / Cline) — 13 everyday dev chores, zero config.

📖 中文文档：README.zh-CN.md

Why another toolbox?

• You type it, or your AI does. Every capability ships twice: cupbox organize for the terminal, organize_files for your AI client. Same engine, same safety rules.

• AI-safe by design. Destructive operations default to dry-run previews when driven by an AI; command execution sits behind an allowlist; killing a process requires PID and name to match. Your agent can be helpful without being dangerous.

• No batteries to install. OCR uses Windows' built-in engine (or tesseract if you have it), zips use the system tar, clipboard/screenshot use native APIs. Only two runtime dependencies in total.

• Cross-platform. Windows / macOS / Linux, Node ≥ 18.17.

Related MCP server: Uten Agent Terminal MCP

What's inside (13 tools)

Every CLI command accepts --json for scripting.

Install

npm install -g cupbox      # global CLI
# or try it without installing:
npx cupbox help

CLI quick tour

# Preview a folder cleanup, then apply it
cupbox organize ~/Downloads --mode category --dry-run
cupbox organize ~/Downloads --mode category

#  📋 report.pdf  →  Documents/report.pdf
#  📋 photo.png   →  Images/photo.png
#  📋 预览完毕（未执行），共 2 项将移动。去掉 --dry-run 执行。

# Number your holiday photos safely
cupbox rename ./photos --template "{n}-{name}" --ext *.jpg --dry-run

# Find every TODO in a repo (skips node_modules/.git)
cupbox search ./src -c "TODO" --glob *.ts

# Timestamps, hashes, codecs — the boring stuff done right
cupbox time 1700000000
cupbox hash --text "hello" --algo sha256,md5
cupbox codec b64e "你好，世界"

# OCR a screenshot (Windows built-in engine, Chinese supported)
cupbox ocr ./截图.png --lang zh-Hans

# Kill a process only if the name matches too
cupbox proc kill --pid 1234 --name node

Connect it to your AI (MCP)

Add to your MCP client config (e.g. claude_desktop_config.json):

{
  "mcpServers": {
    "cupbox": {
      "command": "cupbox",
      "args": ["mcp"]
    }
  }
}

No global install? Use npx -y cupbox mcp instead — see examples/npx-mcp-config.json.

Then just talk to your agent:

"Organize my Downloads folder by file type — show me a preview first." "Rename these screenshots with running numbers, don't touch the originals until I confirm."

The agent will call organize_files / batch_rename, which default to dry-run, hand you the preview, and only execute when you say so.

Guardrails

Documentation

• cupbox help — full command reference in your terminal

• 中文文档

• MCP config examples: examples/

Development

git clone https://github.com/beizilaoshi/cupbox.git
cd cupbox
npm ci
npm test        # builds + runs the full suite (unit, CLI smoke, MCP over in-memory transport)
npm run dev     # tsc watch mode

Project layout: src/core (features) · src/util (platform/process/fs helpers) · src/index.ts (CLI) · src/mcp.ts (MCP server) · test/ (vitest).

CI runs the suite on Windows + Ubuntu × Node 18/20/22.

Contributing

Issues and PRs welcome — especially platform-specific edge cases (paths, encodings, tool availability). Please keep npm test green.

License

MIT