LocalFileHandler

Overview

LocalFileHandler replaces manual file operations with an intelligent MCP server that enforces naming conventions, auto-categorises files, and accepts plain-English or voice commands. It exposes 17 tools over POST /invoke covering core CRUD, bulk organisation, undo, AI-enhanced NL commands, smart categorisation, duplicate detection, offline voice control (4 STT backends), and a directory watchdog. A vanilla JS web dashboard and a Docker multi-arch image (amd64 + arm64) make it deployable on a laptop or a Raspberry Pi with a single command.

Key Features

• Naming rules engine enforces YYYY-MM-DD-{slug}.{ext} conventions on every create/rename/move
• nlcommandtool parses plain-English commands via LLM (Anthropic, Ollama, or llama.cpp) into {tool, payload} before executing — user confirms before action runs
• Push-to-talk voice control in the browser: base64 WAV → voicetool → STT transcription → NL command panel
• 4 STT backends: faster-whisper (recommended), openai-whisper, Vosk (40 MB, ideal for Pi), whisper.cpp
• Directory watchdog auto-organises files dropped into a watched folder via inotify or polling fallback
• Docker Compose with three profiles: minimal (~120 MB), full (AI + STT, ~1.2 GB), rpi (Vosk, ~280 MB)

Technical Decisions

The NL command flow deliberately shows the resolved {tool, payload} to the user before execution — the LLM parses intent but never acts autonomously — keeping the user in control of destructive operations like delete or bulk move. Vosk was included as a supported STT backend specifically because its 40 MB model fits comfortably on a Raspberry Pi Zero 2W where faster-whisper would be too slow or too large. The bare-metal installer (deploy/install.sh) creates a filebot system user and a systemd service so the server survives reboots without Docker.