WorkWall MCP Server

A wall you can think on

Workwall brings the freedom of a physical planning wall to a local desktop app. Arrange work across editable stages and task-type swimlanes, move and resize notes naturally, and keep the whole project visible without turning it into another rigid issue tracker.

Related MCP server: vibeops

Highlights

• Tactile Kanban wall — layered 2D paper, natural curls and shadows, handwritten fonts, flexible stage widths, and adjustable swimlane heights.

• Independent projects — create, rename, colour, duplicate, archive, restore, or recoverably delete workspaces without mixing their board data.

• AI card partner — stream replies into a real conversation, optionally inspect provider reasoning while it is running, and preserve the visible discussion with each card.

• Review before write — the assistant can propose a task, next action, notes, category, and stage, but it changes the card only after explicit approval.

• Local-first persistence — atomic workspace files, browser-cache fallback, per-project undo history, and no required Workwall cloud account.

• Multilingual workspace — switch the interface among nine languages and keep translated card copies without overwriting the original text.

• Agent-ready automation — inspect and update projects, cards, categories, stages, and layout through the local API or MCP adapter.

AI collaboration that stays conversational

The card assistant is designed for discussion, not one-shot generation. Ask questions, refine intent, and request a structured fill proposal when the card is ready. The proposal remains separate until you approve it; rejecting it returns you to the conversation for another iteration.

Visible replies stream as they arrive. When a compatible provider supplies reasoning increments, the current reasoning panel can be expanded or collapsed and closes automatically after completion. Workwall retains up to 40 visible user and assistant messages per card, while provider keys and reasoning text never enter board files.

Download

Download the newest Windows installer from GitHub Releases. The packaged desktop app includes its Python sidecar, so end users do not need to install Python separately.

Workwall is currently an early desktop release for Windows x64. Keep a backup of important workspace files before testing a new release.

Windows normally provides the required WebView2 runtime. If the app cannot create its window, install the current Microsoft Edge WebView2 Runtime.

Run from source

The local web service uses the Python standard library. Python 3.11 or newer is recommended.

./manage-workwall.ps1 -Action Start -NoPause

Open http://127.0.0.1:4177/ and check readiness at http://127.0.0.1:4177/api/health. On Windows, you can also double-click manage-workwall.cmd for the start, stop, restart, and status menu.

For the native desktop development shell:

npm install
npm run desktop:dev

Create a Windows installer with:

npm run desktop:build

Board controls

Local-first by design

Workspace data stays outside the Git repository:

• Windows: %LOCALAPPDATA%\Workwall\state\<workspace-id>.json

• Other platforms: ~/.workwall/state/<workspace-id>.json

Replacing or updating the application does not intentionally replace these board files. Project deletion moves the selected JSON file into a timestamped trash directory rather than erasing it immediately.

AI provider metadata is stored separately. On Windows, API keys are encrypted for the current user with DPAPI and are never returned by the API or written to board state, exports, MCP payloads, or logs. AI features contact only the public HTTPS provider configured by the user; the board itself remains usable without a provider or network connection.

MCP and local API

Install the MCP adapter dependency:

python -m pip install -r requirements-mcp.txt

The repository includes .codex/config.toml, which registers mcp_server.py against the running loopback service. Restart Codex or open a new task from this repository after changing MCP configuration.

Every MCP board operation requires an explicit workspace_id; there is no implicit current board. The adapter does not read workspace files directly and never exposes arbitrary HTTP requests or provider keys.

• MCP tools and safety boundaries

• Loopback API reference

Architecture

Tauri / WebView2 desktop UI ──┐
Browser UI ──────────────────┼──> Python loopback service ──> local workspace JSON
Trusted coding agent ─> MCP ─┘                └─────────────> configured AI provider (optional)

Production sticky-note rendering remains Canvas/2D based. Three.js and GLB experiments are isolated in the sticky-shape research lab and are not loaded by the main board.

Validation

python -m unittest discover -s tests -v
python scripts/validate_sticky_assets.py

After layout or rendering changes, also verify the board at desktop size and exercise card editing, panning, zooming, lane changes, and restart persistence.

Documentation

Project status

Workwall 0.1.3 includes the multi-project local board, Tauri desktop shell, packaged Python loopback sidecar, Windows installer, persistent AI provider settings, encrypted API keys, streaming card conversations, and review-before-write proposals. Clean-machine acceptance and broader distributable packaging remain active work.

License

Workwall is free software released under the GNU General Public License, version 3.