Logwork Helper

npm version npm downloads license

Local MCP server and terminal CLI for Resource Optimiser logwork and Jira self-hosted worklogs.

Logwork Helper lets Cursor, Codex, Google Antigravity, GitHub Copilot / VS Code, Claude Code, and other MCP clients work with Resource Optimiser from your machine. It can query logged work, reconcile RO and Jira by day, preview and submit approved Resource Optimiser logwork, preview and submit approved Jira worklogs, map ticket prefixes to Resource Optimiser projects, keep a sanitized local apply history, schedule native OS reminders, and run a guided terminal flow through logwork.

Credentials stay local. Resource Optimiser passwords and 2FA codes, and Jira Personal Access Tokens, are entered in Terminal only, never in MCP config or AI chat.

Install

Requirements:

• macOS or Windows 10/11
• Node.js 20+
• npm

Install globally:

npm install -g logwork-helper

Prepare the local runtime used by MCP configs:

logwork-helper setup-user

This creates the local Logwork Helper runtime (~/.logwork-helper on macOS, %USERPROFILE%\.logwork-helper on Windows), installs runtime dependencies there, links the terminal commands, and prints copy-ready MCP config snippets using your real local path.

Update

Check npm for a newer release:

logwork-helper update check

Install the latest release after an interactive confirmation:

logwork-helper update install

The logwork terminal UI also shows a short notice when a newer release is available. Checks are cached for 24 hours and network errors never block logwork. Updating preserves OS credentials, project mappings, drafts, and apply history. Restart the terminal session and reconnect MCP clients after an update.

Authenticate

Log in to Resource Optimiser from Terminal:

logwork-helper auth login

Follow the prompts for email, password, 2FA device, and 2FA code. The helper stores only the final Resource Optimiser session in your OS credential store: macOS Keychain on macOS, or Windows Credential Manager on Windows.

Check auth status:

logwork-helper auth status

For Jira self-hosted worklogs, create a Jira Personal Access Token in Jira, then save it from Terminal:

logwork-helper jira login

The default Jira URL is https://jira-vnv.vinova.sg. Override it with:

logwork-helper jira login --base-url https://jira.example.com

Check or delete Jira auth without printing the token:

logwork-helper jira status
logwork-helper jira logout

Set Up MCP

The easiest way to get the right config is from the terminal UI:

logwork

Then type:

/mcp

Choose your MCP client and copy the printed config. Supported clients:

• Cursor
• Google Antigravity
• GitHub Copilot / VS Code
• Claude Code
• Codex

You can also jump directly:

/mcp cursor
/mcp antigravity
/mcp copilot
/mcp claude-code
/mcp codex

After saving the config, restart or reload your IDE MCP tools.

MCP assistants can use check_for_updates, then call apply_update only after showing the exact version and receiving explicit approval. A successful MCP update requires reconnecting the MCP server.

Reminder

Enable a smart native notification at 17:00, Monday-Friday:

logwork-helper reminder enable

Test and inspect it:

logwork-helper reminder test
logwork-helper reminder status

The default target is Both. Resource Optimiser compares today's logged and booked hours; Jira checks whether the current user has any worklog today. Complete days stay silent. macOS uses a user launchd agent and Windows uses Task Scheduler; neither schedule stores credentials.

Customize or disable it:

logwork-helper reminder enable --time 18:00 --target ro
logwork-helper reminder disable

Reconcile RO And Jira

Compare Resource Optimiser and Jira without writing either system:

logwork-helper reconcile this-week
logwork-helper reconcile last-month --json

The report shows booked, RO, and Jira hours by day. It also flags daily or issue-level mismatches. A correction suggestion is included only when an RO task contains exactly one Jira issue key; applying a suggestion still requires the normal target-specific preview and approval flow.

Inside logwork, run /reconcile to pick a period or use /reconcile this-week directly. MCP clients can call the read-only reconcile_logwork tool.

Verify from your assistant:

Check my logwork for this week.

Full client examples are in docs/mcp-setup.md.

Daily Use

Ask your assistant:

Check whether I have logged anything today.

Preview this logwork and ask for my approval before submitting:
Monday, 01 Jun 2026
+2 Maintenance mode management and status UI (SCB-213)

Preview this Jira worklog and ask for my approval before submitting:
Monday, 01 Jun 2026
+2 Maintenance mode management and status UI (SCB-213)

Set up the SCB ticket mapping to project 2621A-SIT-HTML BUILDER-PRJ.

To log work directly from Terminal:

logwork

Inside the terminal UI, /logwork opens a target picker. Use /logwork ro for Resource Optimiser, /logwork jira for Jira worklogs, or /logwork both to preview/apply both with separate approvals.

Useful terminal commands:

/query today
/query yesterday
/query this-week
/query last-week
/query this-month
/query last-month
/reconcile
/reconcile this-week
/logwork
/logwork ro
/logwork jira
/logwork both
/mcp
/projects
/projects 5234
/map SCB 5234
/history
/diagnostics

More Docs

• Integrated operations guide: complete CLI/MCP feature matrix, RO/Jira/Both processing examples, mapping, reconciliation, history, reminders, updates, release flow, and OS validation.
• MCP setup: full client configs, exposed tools, verification prompts, and common MCP workflows.
• Security and auth: Keycloak flow, Jira PAT flow, OS credential storage, stored files, and safety model.
• Advanced usage: environment overrides, manual REPL details, updates, troubleshooting, legacy git hook, and release checks.
• Quick recipes: copy-ready RO, Jira, Both, auth recovery, duplicate handling, mapping, and history workflows.
• Release checklist: publish and manual verification checklist.

License

This project is proprietary and not open source. See LICENSE.