LocalHero Org

Helping Organisations get organised!

MCP abilities

Part of LH Tasks

Add Note

lh-tasks/add-note

Adds a note to the progress log of a task without claiming it, so context can be added to a task you are not working on. Does not change status, claim or assignment, and works on any status, including finished tasks. The note shows in the progress_log returned by get-task as event “note” with the time and who added it. Requires edit_others_posts.

Parameter Type Required Default Description
task_id integer Yes The task to add the note to.
note string Yes Plain text, up to 4000 characters. Line breaks are kept; HTML is stripped.

Claim Next Task

lh-tasks/claim-next-task

Atomically claims the next available task on behalf of the calling account: highest priority first (urgent, high, normal, low), then oldest, optionally narrowed to a queue and/or task type. Tasks still waiting on a blocked_by prerequisite are skipped. If task_id is given, atomically claims that specific task instead. A candidate is eligible if it is unassigned, or hard-assigned to the calling account – tasks assigned to someone else are skipped, not errored. Returns claimed:false with a reason when nothing was claimed – safe to poll repeatedly. Returns a claim_token that must be passed to complete-task/fail-task/reassign-task/renew-claim for this task. Requires edit_others_posts.

Parameter Type Required Default Description
queue string No Queue/lane slug to claim from. Omit to claim from any queue. Ignored if task_id is given.
task_type string No Only claim tasks of this task type slug, e.g. “bug_fix“. Omit for any type. Ignored if task_id is given.
task_id integer No Claim this specific task instead of the next eligible one. Still goes through the same atomic claim, assigned_to and blocked checks – returns claimed:false with a reason rather than an error if the task is not currently claimable.

Complete Task

lh-tasks/complete-task

Marks a claimed task as Resolved and stores an optional result payload. Needs the claim_token returned by claim-next-task for this task – fails if the caller does not currently hold the claim. Requires edit_others_posts.

Parameter Type Required Default Description
task_id integer Yes The claimed task to mark Resolved.
claim_token string Yes The claim_token returned by claim-next-task when you claimed this task.
result object No Optional structured result to store against the task.

Create Task

lh-tasks/create-task

Creates a new task in the queue with status New. Accepts an optional machine-readable payload for agent-executable tasks, a queue/lane slug for routing, priority, due date, blocking task IDs, and an optional hard assignment. Requires edit_others_posts.

Parameter Type Required Default Description
title string Yes Task title.
description string No Human-readable description, written as markdown by default (see description_format). Stored as canonical HTML in post_content either way.
description_format string No "markdown" How description is written: markdown (default) or html. It is stored as HTML either way. One of: markdown, html.
payload object No Machine-actionable spec for agent tasks, e.g. {“ability”: “lh-email/send-broadcast”, “params”: {…}}.
queue string No Queue/lane slug for routing, e.g. “email-triage”.
task_type string No Task type slug classifying what kind of work this is, e.g. “github_triage“. Distinct from queue – queue is about routing, task_type is about classification.
post_status string No "active" Visibility. active (default) is immediately visible/claimable. Use draft or pending for a task that should not be visible or claimable yet – e.g. an AI-drafted task awaiting human review before it is surfaced. One of: draft, pending, active.
assigned_to integer No WP user ID this task must be actioned by. Omit to leave the task open, claimable by anyone polling the queue.
priority string No urgent, high, normal or low; claim-next-task takes higher priorities first. Defaults to normal. One of: low, normal, high, urgent.
due_date string No MySQL datetime, e.g. 2026-07-10 09:00:00.
scheduled_for string No MySQL datetime (site local time). If in the future, the task stays hidden from claim-next-task until this time, then automatically activates to New. Omit to make the task claimable immediately.
blocked_by array of integer No Task IDs that must be finished (Resolved, Closed or Cancelled) before this task can be claimed. Each must be an existing, untrashed task; otherwise nothing is created and the error names the bad IDs. If a prerequisite is later cancelled, trashed or deleted, this task moves to Pending for a human to check.
max_retries integer No How many times to auto-requeue on failure before leaving Blocked for triage.
source_plugin string No Slug of the plugin that created this task, e.g. lh-crm.
source_post_id integer No ID of the originating post in the source plugin.

Edit Task

lh-tasks/edit-task Destructive Idempotent

Unconditional queue-management override for staff – changes assignment, releases a stuck claim, and/or changes workflow status or queue without needing to hold the current claim. Distinct from reassign-task, which is a self-service action for whoever currently holds the claim; use this for cleanup (stuck claims, wrong assignment) rather than routine handoffs. Requires edit_others_posts.

Parameter Type Required Default Description
task_id integer Yes The task to change.
assigned_to integer No New hard assignment. Pass 0 to explicitly clear assignment (open to anyone). Omit this field entirely to leave assignment unchanged.
release_claim boolean No Release the current claim (if any) without changing assignment or status.
status string No New workflow status key, e.g. lh_tasks-new_task. Omit to leave unchanged.
queue string No New queue/lane slug. Omit to leave unchanged.
note string No Logged alongside the change for audit purposes.

Fail Task

lh-tasks/fail-task

Marks a claimed task as failed. Needs the claim_token returned by claim-next-task for this task. reason_type “retryable” (default) requeues to New if retries remain, else Blocked. reason_type “needs_human” skips retries entirely and hands the task off via reassignment instead – use this when the work itself is fine but something outside your authority/ability is needed to finish it. Requires edit_others_posts.

Parameter Type Required Default Description
task_id integer Yes The claimed task that failed.
claim_token string Yes The claim_token returned by claim-next-task when you claimed this task.
error_message string No What went wrong, or what is still needed. Stored as the task result and, for needs_human, as the handoff note.
reason_type string No "retryable" retryable (default): requeue to New while retries remain, then Blocked. needs_human: skip retries and hand the task off (see new_assigned_to and new_queue). One of: retryable, needs_human.
new_assigned_to integer No needs_human only. WP user ID of the specific person this should go to, if known. Omit to return it to the open queue.
new_queue string No needs_human only. Move to a different queue/lane, e.g. a human-review lane.

Get Task

lh-tasks/get-task Read-only Idempotent

Retrieves a single task by ID, including status, meta fields, queue, result, its blocked_by prerequisites and whether any of them are still holding it back. Requires edit_others_posts.

Parameter Type Required Default Description
task_id integer Yes The task to retrieve.

List Tasks

lh-tasks/list-tasks Read-only Idempotent

Returns a paginated list of tasks. Supports filtering by status, queue, assignee (current claim holder), and assigned_to (hard assignment). Requires edit_others_posts.

Parameter Type Required Default Description
status string No Filter by a single workflow status key, e.g. lh_tasks-new_task. Omit for all open (non-terminal) statuses.
queue string No Filter by queue/lane slug.
task_type string No Filter by task type slug.
assignee integer No Filter to tasks currently claimed by this WP user ID.
assigned_to integer No Filter to tasks hard-assigned to this WP user ID.
page integer No 1 Page number, from 1.
per_page integer No 20 Tasks per page, up to 100. Defaults to 20.

Reassign Task

lh-tasks/reassign-task

Hands a task off to someone else – releases the current claim, optionally hard-assigns it to a specific account (only that account, or edit-task, can claim/act on it next), and logs a note describing what is done and what is left. Needs the claim_token returned by claim-next-task for this task – reassigning is an action available to whoever currently holds the claim. Use this for partial-completion handoffs; use fail-task for something that went wrong. Requires edit_others_posts.

Parameter Type Required Default Description
task_id integer Yes The claimed task to hand off.
claim_token string Yes The claim_token returned by claim-next-task when you claimed this task.
new_assigned_to integer No WP user ID this task must be actioned by next. Omit to just return it to the open queue for anyone to claim.
new_queue string No Move the task to a different queue/lane.
new_status string No Defaults to New (immediately claimable). Use the Pending status key for a handoff to a human who is not actively polling.
note string Yes What has been done so far and what is left – the next assignee will see this.

Renew Claim

lh-tasks/renew-claim

Extends a held claim’s clock – pushes claimed_at forward to now, so a still-live long-running task stays ahead of the automatic stale-claim sweep (releases claims older than the configured cutoff, default 10 minutes) instead of being auto-released mid-work. Does not change status or assignee. Needs the claim_token returned by claim-next-task for this task – fails if the caller does not currently hold the claim. Call periodically from a long-running task. Optionally logs a progress note alongside the heartbeat, the same way reassign-task logs its note. Requires edit_others_posts.

Parameter Type Required Default Description
task_id integer Yes The claimed task whose claim to extend.
claim_token string Yes The claim_token returned by claim-next-task when you claimed this task.
note string No Optional progress note, logged alongside the heartbeat – lets a renewal double as a lightweight progress trail. Omit for a bare heartbeat with no side effects beyond extending the claim.

Update Task

lh-tasks/update-task Idempotent

Changes the content of a task after it was created: title, description, payload, priority, due date, schedule, task type, max retries and blocked_by. Only the fields you pass change; an empty value clears payload, due_date, task_type or blocked_by. Everything is checked before anything is written, so an invalid blocked_by (missing, trashed, the task itself, or a loop) changes nothing. Works on claimed tasks too, and every call adds an “updated” entry to the progress log listing the fields changed. Status, queue, assignment and the claim are not changed here: use edit-task or the claim-token abilities. Requires edit_others_posts.

Parameter Type Required Default Description
task_id integer Yes The task to change.
title string No New title. Cannot be empty.
description string No Replaces the description. Written as markdown by default (see description_format).
description_format string No "markdown" How description is written: markdown (default) or html. It is stored as HTML either way. One of: markdown, html.
payload object No Replaces the whole payload. An empty object clears it.
priority string No New priority: urgent, high, normal or low. One of: low, normal, high, urgent.
due_date string No MySQL datetime, e.g. 2026-07-10 09:00:00. Empty string clears it.
scheduled_for string No New activation time (site local MySQL datetime, in the future). Only for a task that is still scheduled.
task_type string No Task type slug. Empty string clears it.
max_retries integer No How many times to auto-requeue on failure before leaving the task Blocked for triage.
blocked_by array of integer No Replaces the whole list of prerequisite task IDs. Empty array clears it.
note string No Why it changed; logged with the update.

If you like this plugin please consider making a donation to further development