Inspect first-run onboarding state without mutating tasks or config.

Use this before task creation/modification if the active schema may be the bundled minimal default rather than a user-specific taxonomy.

Return structured onboarding choices for the user/model to discuss.

Read-only: does not write config, schema, or task data.

Call after get_initialization_status confirms onboarding is required. Use this to present a structured schema-source menu rather than guessing a path. For the next step, choose one of: analyze_existing_tasks_for_schema — infer schema from tasks analyze_taxonomy_file — parse a taxonomy Markdown file list_preset_schemas / use_preset_schema — bundled presets generate_initial_schema_preview — combine taxonomy + tasks

project_dir: optional path scoping task analysis to a project subdirectory. Pass empty string (default) to analyse all tasks.

Analyse existing Taskwarrior tasks for field/schema inference.

This is read-only. It returns field occurrence ratios, likely enum values, likely required fields, projects, tags, and detected UDAs.

Parse a taxonomy Markdown file and return extracted semantics.

This is read-only. It extracts fields, descriptions, allowed values, conditional requirements, and phase transitions when possible.

Generate a reviewable schema TOML preview without writing any files.

Read-only: returns a preview string only; no files are created or modified. Call save_initial_schema only after the user approves.

The preview combines existing task analysis with an optional taxonomy Markdown file. Run analyze_existing_tasks_for_schema or analyze_taxonomy_file first to understand what the preview will contain.

taxonomy_path: absolute path to a taxonomy Markdown file; omit to infer from tasks only. project_dir: optional path scoping task analysis to a subdirectory. schema_name: optional name embedded in the schema [meta] block.

Persist an approved generated schema and optionally update config.toml.

This writes schema/config files but does not mutate Taskwarrior tasks. Call generate_initial_schema_preview first and show the user a summary before saving.

role is the MCP permission level to persist in config.toml. Pass one of CONTRIBUTOR / GENERATOR / MANAGER (see propose_initialization_options for descriptions). When omitted, CONTRIBUTOR is persisted so the server leaves onboarding mode on next restart. Without persisting a role the server stays stuck on the onboarding tool surface.

List bundled preset schemas (minimal, gtd, kanban, scrum, ...).

Read-only. Returns each preset's name, file path, version and description as parsed from the schema's [meta] block. Use this before calling use_preset_schema so the user can see what is available without you guessing the preset names.

Wire a bundled preset schema into the user's config.toml.

By default this just sets schema = "<preset_name>" in config.toml (lowest friction; keeps using the version-controlled bundled file). Pass copy=true to copy the preset into output_path (or the user config dir) and reference that copy via schema_path — use this when the user wants a personal, editable copy.

Refuses to overwrite an existing target file when copy=true unless overwrite=true.

role is the MCP permission level to persist in config.toml. Pass one of CONTRIBUTOR / GENERATOR / MANAGER (see propose_initialization_options for descriptions). When omitted, CONTRIBUTOR is persisted so the server leaves onboarding mode on next restart. Without persisting a role the server stays stuck on the onboarding tool surface.

List and filter Taskwarrior tasks. Read-only.

Returns a JSON array of matching tasks. Use Taskwarrior filter syntax: 'status:pending' — pending tasks (default without filter) 'project:work' — tasks in project 'work' 'phase:impl' — tasks where UDA phase=impl '+python' — tasks tagged 'python' '-python' — tasks NOT tagged 'python' Combine: 'status:pending project:work +urgent'

Prefer get_task when you have a UUID and need full field data. Prefer search_tasks for free-text search within a specific field. Use get_task_report for named Taskwarrior reports (next, blocked).

Get a single task by UUID and return all its fields. Read-only.

Returns full task JSON including all UDA fields and annotations. Always use UUID — local numeric IDs change as tasks complete or are filtered.

Use this over list_tasks when you have the UUID and need complete field data. Use list_tasks with filters to discover tasks.

Search tasks by matching a query against a specific field. Read-only.

Returns matching tasks as JSON. Matching is case-insensitive substring.

field defaults to 'description'. Other values: 'project', 'tags', or any UDA name (e.g. 'phase', 'scope', 'area'). The field must exist in the schema or be a Taskwarrior built-in.

Use list_tasks with filter syntax for structured queries. Use this for free-text search when filter syntax is insufficient or when searching across a UDA field.

Append a timestamped annotation to a task.

Annotations are appended to the task's annotation list — they do not replace existing annotations or modify other fields. Each annotation records the current timestamp automatically.

Annotations are the preferred way to attach narrative context, rationale, URLs, and reference links. Use modify_task to change structured fields like priority or project instead.

Supports dry_run=true to preview without writing. Requires CONTRIBUTOR role.

Modify fields on an existing task.

Args: uuid: Task UUID. fields: Field:value pairs to modify. Example: {"priority": "H", "phase": "impl"} For adding tags: {"tags_add": ["python"]} For removing tags: {"tags_remove": ["old"]}

Mark a task as active by setting its start timestamp.

Sets the Taskwarrior 'start' field, making the task appear in active-task reports. If Timewarrior is installed, also begins time tracking tagged with the task's tags.

Supports dry_run=true to preview without mutation. Does not complete or delete the task. Use stop_task to deactivate, complete_task to mark done. Requires CONTRIBUTOR role.

Deactivate a task by clearing its start timestamp.

Clears the Taskwarrior 'start' field. If Timewarrior is installed, also stops active time tracking for this task.

Supports dry_run=true to preview without mutation. Does not complete or delete the task. Pair with start_task to track work sessions. Use complete_task to mark the task done. Requires CONTRIBUTOR role.

List all project names in the Taskwarrior database. Read-only.

Returns a flat list including subproject hierarchies (e.g. 'work.acme.backend'). Use before create_task or filter queries to confirm project name spelling.

List all tags used across the Taskwarrior database. Read-only.

Returns every tag that appears on at least one task. Use before create_task, modify_task, or filter queries to confirm tag spelling and discover available tags.

Show the currently active Taskwarrior context filter. Read-only.

A context automatically applies a filter to all task queries. Returns the active context name and its filter expression, or indicates no context is active. An active context narrows the output of list_tasks and get_task_report automatically.

Get the active task schema definition.

Returns field definitions, required fields, allowed values, and conditional requirements. Use this to understand what fields are available before creating or modifying tasks.

Run a named Taskwarrior report and return its output. Read-only.

Built-in report names: 'next', 'blocked', 'overdue', 'active', 'completed', 'all', 'summary', 'burndown.daily'. Custom reports defined in .taskrc are also supported.

filters: Taskwarrior filter syntax appended to the report's own filter (e.g. 'project:work' to scope 'next' to one project).

Use list_tasks for raw JSON output. Use this tool when the formatted report view or urgency ordering is more useful.

Get a Timewarrior time-tracking summary for a period. Read-only.

Returns empty results (not an error) if Timewarrior is not installed or no time was tracked in the given period.

period accepts: ':day', ':week', ':month', ':year' — relative periods '2026-05-01 - 2026-05-25' — explicit date range 'monday - today' — Timewarrior relative syntax

Use get_time_status to check whether tracking is currently active.

Check whether Timewarrior is currently tracking time. Read-only.

Returns active tracking state, current tags, and elapsed duration, or indicates no tracking is active. Returns a clear message (not an error) if Timewarrior is not installed.

Use get_time_summary for historical aggregates. Use start_task / stop_task to control tracking via Taskwarrior hooks.

Switch the active task schema.

Exactly one of schema_name (a bundled preset such as 'minimal' / 'gtd' / 'kanban' / 'scrum') or schema_path (an absolute path to a custom TOML schema) must be provided.

Set dry_run=true to validate the inputs and preview the config write without touching config.toml — useful for confirming a preset name spells correctly or a schema_path exists before committing. Returns code="dry_run" per ADR 14.

Updates config.toml and triggers an in-process reload so the change takes effect immediately (ADR 19). Does not mutate any Taskwarrior tasks. Available at CONTRIBUTOR level and above — switching the validation lens is a horizontal move, not a privilege change (ADR 17).

Update the taxonomy file path persisted in config.toml.

The taxonomy informs the model's interpretation of task semantics. The target path must exist and be a regular file; the tool refuses non-existent or directory targets to prevent silently disabling taxonomy awareness.

Set dry_run=true to validate the path and preview the config write without touching config.toml. Returns code="dry_run" per ADR 14.

Takes effect on next MCP server restart. Available at CONTRIBUTOR level (informational input, not a capability).

Change the persisted MCP role — DOWNGRADE ONLY.

Valid roles: CONTRIBUTOR, GENERATOR, MANAGER (cumulative; see ADR 5). This tool will set the persisted role to target_role IF AND ONLY IF its level is less than or equal to the currently-loaded role.

Set dry_run=true to validate inputs (including the elevation refusal check) and preview the config write without touching config.toml. Refusal-class errors (role_elevation_forbidden) trigger regardless of dry_run — a forbidden elevation is forbidden whether or not the LLM was just "asking". Returns code="dry_run" on legitimate previews.

Self-elevation via MCP is forbidden by design (ADR 17). Attempts to elevate return a structured error with error_code='role_elevation_forbidden'. To elevate, run './dev.sh init --role ' from a shell or hand-edit ~/.config/taskchampion-mcp/config.toml and restart the MCP server.

Takes effect on next MCP server restart.

Create a new Taskwarrior task with schema validation.

Args: description: Task description (imperative, actionable). project: Project name in dot-notation (e.g. 'work.acme'). priority: H, M, or L. tags: List of tags (e.g. ["python", "docker"]). due: Due date (ISO format or Taskwarrior relative like 'eow'). extra_fields: Additional UDA fields. Example: {"scope": "personal", "phase": "impl"}

Call get_schema_info first to see required and available fields.

Create a subtask with depends: linking to a parent task.

Args: parent_uuid: UUID of the parent task this subtask depends on. description: Task description (imperative, actionable). project: Project name in dot-notation (e.g. 'work.acme'). priority: H, M, or L. tags: List of tags (e.g. ["python", "docker"]). due: Due date (ISO format or Taskwarrior relative like 'eow'). extra_fields: Additional UDA fields. Example: {"scope": "personal", "phase": "impl"}

The subtask will have a 'depends' field set to the parent UUID. Call get_schema_info first to see required and available fields.

Create multiple tasks in a single call with per-task result reporting.

Prefer this over repeated create_task calls when creating several independent tasks at once. Use create_subtask instead when tasks must be linked to a parent via depends. Requires GENERATOR role.

NON-ATOMIC: tasks are created sequentially. If task N fails, tasks 0..N-1 are already committed — there is no rollback. A rate-limit hit stops the batch early; partial results are returned with the stopping index and created/failed counts.

dry_run=true previews all entries without writing to Taskwarrior. Each preview entry confirms field validation without mutation.

Each entry in tasks accepts: description (str, required), project (str), priority (H/M/L), tags (list[str] or comma-separated str), due (ISO or TW relative e.g. eow/eom), extra_fields (dict of UDA key/value pairs).

Call get_schema_info first to confirm required and available fields.

Mark a task as done (completed).

Args: uuid: Task UUID. dry_run: If true, preview the action without executing.

Destructive operation — may require confirmation depending on server configuration.

Delete a task from Taskwarrior.

Args: uuid: Task UUID. dry_run: If true, preview the action without executing.

Destructive operation — may require confirmation depending on server configuration. Prefer completing over deleting.

Undo the most recent Taskwarrior operation.

Reverts the last change in Taskwarrior's undo log. Only one level of undo is available — cannot be chained, and there is no redo.

Supports dry_run=true to preview what would be undone without applying it. Destructive: the reverted change cannot be recovered. May require a confirm_token depending on server configuration.

Caution: after batch operations, undo reverts only the last single operation, not the whole batch. Requires MANAGER role.

Trigger a sync with the configured TaskChampion sync server.

Pushes local task changes to the sync server and pulls remote changes. Requires a TaskChampion sync server configured in .taskrc. Returns an error if no sync server is configured.

Supports dry_run=true to check connectivity without transferring data. Conflicts are resolved server-side; local changes are not lost but may be reordered. Requires MANAGER role.

Modify all tasks matching a filter expression in a single call.

Applies the same field changes to every matching task. NON-ATOMIC: tasks are modified sequentially; a failure on one task does not stop the batch. High-impact changes require a confirm_token — call with dry_run=true first to receive the token, then resubmit with confirm_token set.

filters: Taskwarrior filter syntax (required, e.g. 'project:work +urgent'). fields: field/value pairs — same format as modify_task. For tags: {"tags_add": ["label"]} or {"tags_remove": ["label"]}.

Use modify_task for targeted single-task changes. Use dry_run=true to preview affected task count before committing. Requires MANAGER.

Re-read config.toml from disk and refresh all runtime state.

Use this after hand-editing config.toml to pick up changes without restarting the IDE. Reloads: config, schema, rate limiter, audit logger, Taskwarrior/Timewarrior CLI wrappers.

Onboarding write tools (save_initial_schema, use_preset_schema) and reconfigure tools (set_active_schema, set_taxonomy_path, set_role) auto-reload on success, so you rarely need to call this directly.

Return the server's current mode, role, schema, and callable tool groups.

Call this first to understand what the server can do right now. The response tells you which tool groups are callable and which are blocked (with the reason code).