Todokan

---

name: todokan version: 1.3.2 description: "Manage tasks, boards, thoughts, and reviews in Todokan via MCP" homepage: https://todokan.com metadata: {"category":"productivity","tags":["tasks","kanban","mcp","planning","review"],"requires":{"env":["TODOKAN_API_KEY","TODOKAN_MCP_URL"],"mcp":true},"openclaw":{"homepage":"https://todokan.com","requires":{"env":["TODOKAN_API_KEY","TODOKAN_MCP_URL"]}}}

---

Todokan — Kanban Task Management

Todokan is a kanban-style task manager. You can manage the user's tasks, boards, and projects through MCP tools.

Prerequisites

A Todokan MCP server must be available (see README for setup)

Required env vars: TODOKAN_API_KEY, TODOKAN_MCP_URL (declared in skill metadata)

---

Trigger — When to Activate This Skill

Activate the Todokan skill when the user has one of the following intents:

| Intent | Example | |--------|---------| | Create / edit / delete a task | "Create a task: review PR" | | Show boards or tasks | "Show me my tasks", "What's on the dev board?" | | Change status | "Mark task X as done" | | Save research results | "Save this as a task / document in Todokan" | | Briefing / summary from tasks | "Give me a briefing of my open tasks" | | Attach a document to a task | "Write a note on task X" | | Search topics across boards | "What did I note about the investor meeting?" | | Retrieve changes since last check | "What's new since this morning?" |

Do not activate when the user is just talking about tasks in general without referencing Todokan.

---

Tool Ordering

Follow this order to achieve consistent results:

Reading (always orient first)

1. list_habitats            → Which workspaces exist?
2. list_boards              → Which boards exist? (note the IDs)
3. list_tasks               → Tasks on a board (with filters)
4. search_across_habitats   → Full-text search across boards/habitats
5. get_events_since         → Retrieve changes since a timestamp
6. list_board_labels        → Available labels + usage counts
7. list_task_documents      → Documents attached to a task
8. read_document            → Content of a document

Writing (only after orientation + confirmation)

9.  create_task / create_board / create_habitat
10. update_task / update_task_by_title
11. create_document / add_document_to_task
12. delete_task              → Only after explicit confirmation

AI-Assisted (optional)

13. propose_task_variants    → Generate 2-3 variants
14. confirm_task_fields      → Review fields before creation

Golden rule: Never write blindly. Always call list_boards first to discover IDs — never guess UUIDs.

---

Mandatory Checks

Before executing write actions, clarify the following:

Before create_task

[ ] Board: Which board? (If unclear → show list_boards, let the user choose)

[ ] Title: Short, precise, imperative (max 80 characters)

[ ] Priority: low / normal / high — default to normal if unclear

[ ] Due date: Only set if mentioned by the user

Before update_task

[ ] Correct task? State the title + board for confirmation

[ ] Which fields? Only change the fields the user requested

Before delete_task

[ ] Always ask for explicit confirmation — "Should I permanently delete task '[Title]' on board '[Board]'? This cannot be undone."

Before create_document

[ ] Clarify format: markdown, text, or html

[ ] Link: Attach to which task (or standalone)?

---

Guardrails

No Hallucination

Use only real data from MCP tool responses. Never fabricate task IDs, board names, or content.

If a tool call fails or returns empty data: inform the user, do not improvise.

When in doubt, show the actual results and ask.

No Sensitive Data

Do not store passwords, API keys, tokens, or personal data in task titles or descriptions.

If the user mentions sensitive information, warn them: "This may contain sensitive data — should I really store it in Todokan?"

Source Attribution

When storing content from external research (web, files, other tools) in Todokan, note the source in the task description or document:

  Source: [URL or filename]
  Created by: Agent on [date]
  

Scope Awareness

Worker endpoint (/mcp-worker): Read-only + comments (add_comment). No task/board CUD, no document creation.

Planner endpoint (/mcp): Full access. Still ask before destructive actions.

On scope errors: explain to the user that the current endpoint does not have the required permissions.

Idempotency

On network errors: do not blindly retry the same action. First check whether the action was already performed (list_tasks).

---

Output Format

Briefing (summary of existing tasks)

## Briefing: [Board Name] — [Date]
Open (todo): X tasks
In progress (doing): Y tasks
Completed (done): Z tasks
Urgent (high priority)
[ ] [Task Title] — due [Date]
[ ] [Task Title] — due [Date]
In Progress
[~] [Task Title] — since [Date]
Next Steps
[1-2 sentences recommendation based on the data]

Draft (preview before task creation)

## Task Draft
| Field       | Value                         |
|-------------|-------------------------------|
| Board       | [Board Name]                  |
| Title       | [Title, max 80 chars]         |
| Description | [Description, max 500 chars]  |
| Status      | todo                          |
| Priority    | [low / normal / high]         |
| Due         | [YYYY-MM-DD or —]             |
| Labels      | [label1, label2]              |
Should I create this task?

Document Draft

## Document Draft
Title: [Title]
Format: markdown
Linked to: [Task Title] on [Board Name]

[Document content]
Should I create this document?

---

Data Model

Habitat (workspace/project)
  └── Board (kanban board, type: "task" or "thought")
       └── Task (individual item with status, priority, labels, due date)
            └── Document (attached notes/docs in markdown, text, or html)

Habitats group boards. A user can have multiple habitats.

Boards are kanban boards. Type task for actionable items, thought for ideas/notes.

Tasks live on a board and move through status columns.

Documents are rich text attached to tasks.

Status Values

| Status | Meaning | |--------|---------| | todo | Not started | | doing | In progress | | done | Completed |

Priority Values

| Priority | Meaning | |----------|---------| | low | Low priority | | normal | Default priority | | high | High/urgent priority |

Available MCP Tools

Reading Data

list_habitats — List all workspaces

list_boards — List all boards (returns id, name, version)

list_tasks — List tasks with filters: boardId, status, label/labels, limit, cursor

search_across_habitats — Full-text search over habitats/boards/tasks in one call

get_events_since — Unified feed since timestamp (task events + comments + documents)

list_board_labels — Get unique labels on a board with usage counts

list_task_documents — Get documents attached to a task

read_document — Read a document's content

list_task_comments — List comments on a task

Creating & Modifying (Planner endpoint only)

create_habitat — Create a new workspace (name)

create_board — Create a new board (name, optional habitatId, boardType)

create_task — Create a task (title, boardId or boardName, optional description, dueDate, priority, labels)

update_task — Update a task by ID (taskId, plus fields to change)

update_task_by_title — Update a task by exact title match (titleExact, boardId or boardName)

delete_task — Permanently delete a task (taskId)

create_document — Create a document (optional relatedTaskId to attach)

add_document_to_task — Attach a new document to a task

add_comment — Add a comment to a task

AI-Assisted Creation

propose_task_variants — Generate 2-3 task variants (short/standard/detailed) from a rough description

confirm_task_fields — Preview a variant's fields before creating it

AI Visibility Gate

By default, the MCP server only returns tasks where aiEnabled: true. Tasks with aiEnabled: false are invisible to MCP agents — they will not appear in list_tasks, search_across_habitats, get_events_since, or get_task.

Users control this via a "Send to AI" button on each task card. When clicked, it sets aiEnabled: true, assignee: 'ai', and status: 'doing'.

To see only AI-assigned tasks: list_tasks { "assignee": "ai" }

To see all AI-enabled tasks: list_tasks {} (default — only AI-enabled tasks are returned)

To explicitly include non-AI tasks: list_tasks { "aiEnabled": false } (override, useful for reporting)

OAuth & Authentication

OAuth 2.1 with PKCE (RS256 JWT)

Token lifetime: 30 days, no refresh token

Planner (/mcp): Full CRUD access — all scopes

Worker (/mcp-worker): boards:read, tasks:read, labels:read, docs:read, comments:read, comments:write

No rate limiting — still be conservative with calls

Activity logging: Every tool call is logged server-side

Common Workflows

List all tasks on a board

1. list_boards to find the board ID 2. list_tasks with boardId to get tasks

Create a task

create_task { "title": "Review PR #42", "boardName": "Development", "priority": "high", "dueDate": "2026-03-01" }

Move a task to done

update_task { "taskId": "", "status": "done" }

Add labels to a task

update_task { "taskId": "", "labels": ["bug", "frontend"] }

Find tasks by label

list_tasks { "boardId": "", "labels": ["bug"] }

Search across all habitats

search_across_habitats { "query": "investor meeting", "limit": 20 }

Poll event feed (agent loop)

get_events_since { "since": "2026-02-24T08:00:00Z", "limit": 200 }

Tips

Always call list_boards first to discover available board IDs — don't guess UUIDs.

Use boardName instead of boardId when the user refers to boards by name.

Due dates use YYYY-MM-DD format.

Task titles are max 80 characters, descriptions max 500 characters.

Labels are free-form strings (max 10 per task).

The update_task tool requires the task's UUID. Use list_tasks to find it, or update_task_by_title if you only know the title.

A Todokan MCP server must be available (see README for setup)

Required env vars: TODOKAN_API_KEY, TODOKAN_MCP_URL (declared in skill metadata)

---

Always call list_boards first to discover available board IDs — don't guess UUIDs.

Use boardName instead of boardId when the user refers to boards by name.

Due dates use YYYY-MM-DD format.

Task titles are max 80 characters, descriptions max 500 characters.

Labels are free-form strings (max 10 per task).

The update_task tool requires the task's UUID. Use list_tasks to find it, or update_task_by_title if you only know the title.