wecom-todo

Enterprise WeChat Todo Management Skill

wecom_mcp is an MCP tool; all operations are completed by calling this tool.

⚠️ Prerequisites: before the first call to wecom_mcp , you must follow the wecom-preflight skill to perform the prerequisite check to ensure the tool has been added to the whitelist.

Overview

wecom-todo provides complete management capabilities for Enterprise WeChat todo items, including the following functions:

Query todo list - filter by creation time and reminder time, supports pagination, and returns todo summary information
Get todo details - batch get complete information based on a list of todo IDs (including content and assignees)
Create todo - create a new todo item, and you can specify the content, assignees, and reminder time
Update todo - modify the content, assignees, status, or reminder time of an existing todo
Delete todo - delete the specified todo item
Change user todo status - change the current user's status in a todo (rejected/accepted/completed)

Command invocation method

Use the wecom_mcp tool to call wecom_mcp call todo <tool_name> '<json格式的入参>'

Behavior policy

After querying the list, you must query the details: get_todo_list only returns summary information such as todo ID and status, and does not include the actual todo content and assignees. To users, a todo list without content is useless - what they want to know is "what needs to be done", not a string of IDs. Therefore, every time after calling get_todo_list and getting the result, you must immediately use the returned todo_id list to call get_todo_detail to get the complete details (content, assignees, etc.), and then present them to the user. This is not an optional step, but a necessary part of completing the user's request.

Converting personnel IDs to names (key step): get_todo_detail In the returned results, follower_id and creator_id are both internal system IDs, and displaying them directly to the user is meaningless - users do not recognize these IDs, only names. Therefore, before presenting todo details to the user, you must first call the wecom-contact skill to get the contacts, and match all follower_id and creator_id to real names. The specific approach is:

Use the wecom_mcp tool to call wecom_mcp call contact get_userlist '{}' to get the contacts. In the returned userlist, use the userid field to match follower_id / creator_id, and take the corresponding name.

If an ID cannot be found in the contacts, simply label it as "Unknown User (ID: xxx)" when displaying.

You must remind the user when pagination has not been fully retrieved: get_todo_list The API is paginated, and it is not required to retrieve all data at once. However, if the response has has_more as true, indicating that there are still more todos that have not been returned—when presenting the current results, you must clearly tell the user "There are more todos not displayed. Would you like to continue viewing?". Users may not know that there is more data afterward; if you do not say so, they will think what they see is all there is, which will lead to missing important todos. This is an easily overlooked point with serious consequences, so be sure to do it.

Retry policy: When encountering "returned HTTP error" or "HTTP request failed", actively retry, up to three times.

Detailed command description

1. Query todo list (get_todo_list)

Query the current user's todo list, supporting time filtering and pagination. What is returned is todo summary information (excluding content and assignees).

How to call

Use wecom_mcp tool to call wecom_mcp call todo get_todo_list '<json格式的入参>'

Input parameter description

Parameter	Type	Required	Description
`create_begin_time`	string	❌	Creation start time, format:`YYYY-MM-DD HH:mm:ss`
`create_end_time`	string	❌	Creation end time, format:`YYYY-MM-DD HH:mm:ss`
`remind_begin_time`	string	❌	Reminder start time, format:`YYYY-MM-DD HH:mm:ss`
`remind_end_time`	string	❌	Reminder end time, format:`YYYY-MM-DD HH:mm:ss`
`limit`	number	❌	Maximum number returned, default 10, maximum 20
`cursor`	string	❌	Pagination cursor, do not pass it in the first request; subsequently pass the `next_cursor`

Return format

{
    "errcode": 0,
    "errmsg": "ok",
    "index_list": [
        {
            "todo_id": "TODO_ID",
            "todo_status": 1,
            "user_status": 1,
            "creator_id": "CREATOR_ID",
            "remind_time": "2025-06-01 09:00:00",
            "create_time": "2025-01-15 10:30:00",
            "update_time": "2025-01-16 14:20:00"
        }
    ],
    "next_cursor": "NEXT_CURSOR",
    "has_more": false
}

Returned field description

Field	Type	Description
`index_list`	array	Todo list
`index_list[].todo_id`	string	Todo unique ID
`index_list[].todo_status`	number	Todo status:`0`-Completed,`1`-In progress,`2`-Deleted
`index_list[].user_status`	number	User status:`0`-Rejected,`1`-Accepted,`2`-Completed
`index_list[].creator_id`	string	Creator ID
`index_list[].remind_time`	string	Reminder time
`index_list[].create_time`	string	Creation time
`index_list[].update_time`	string	Update time
`next_cursor`	string	Next page cursor
`has_more`	boolean	Whether there are more records

The list returns todo summary information (excluding content and assignees). After getting the list, you must call get_todo_detail to get the complete details before displaying them to the user.

2. Get todo details (get_todo_detail)

Batch query complete details based on a list of todo IDs, including todo content and assignee information.

How to call

Use wecom_mcp tool to call wecom_mcp call todo get_todo_detail '<json格式的入参>'

Input parameter description

Parameter	Type	Required	Description
`todo_id_list`	array	✅	Todo ID list, maximum 20

Call example

Use wecom_mcp tool to call wecom_mcp call todo get_todo_detail '{"todo_id_list": ["TODO_ID_1", "TODO_ID_2"]}'

Return format

{
    "errcode": 0,
    "errmsg": "ok",
    "data_list": [
        {
            "todo_id": "TODO_ID",
            "todo_status": 1,
            "content": "完成Q2规划文档",
            "follower_list": {
                "followers": [
                    {
                        "follower_id": "FOLLOWER_ID",
                        "follower_status": 1,
                        "update_time": "2025-01-16 14:20:00"
                    }
                ]
            },
            "creator_id": "CREATOR_ID",
            "user_status": 1,
            "remind_time": "2025-06-01 09:00:00",
            "create_time": "2025-01-15 10:30:00",
            "update_time": "2025-01-16 14:20:00"
        }
    ]
}

Returned field description

Field	Type	Description
`data_list`	array	Todo detail list, maximum 20 entries
`data_list[].todo_id`	string	Todo ID
`data_list[].todo_status`	number	Todo status:`0`-Completed,`1`-In progress,`2`-Deleted
`data_list[].content`	string	Todo content
`data_list[].follower_list.followers`	array	Assignee list
`data_list[].follower_list.followers[].follower_id`	string	Assignee ID (i.e. userid)— Before display, it must be converted to a name via wecom-contact
`data_list[].follower_list.followers[].follower_status`	number	Assignee status:`0`-Reject,`1`-Accept,`2`-Completed
`data_list[].follower_list.followers[].update_time`	string	Assignee status update time
`data_list[].creator_id`	string	Creator ID — Before display, it must be converted to a name via wecom-contact
`data_list[].user_status`	number	Current user status
`data_list[].remind_time`	string	Reminder time
`data_list[].create_time`	string	Creation time
`data_list[].update_time`	string	Update time

3. Create todo (create_todo)

Create a new todo item, with optional content, assignees, and reminder time.

How to call

Use wecom_mcp tool to call wecom_mcp call todo create_todo '<json格式的入参>'

Input parameters

Parameter	Type	Required	Description
`content`	string	✅	Todo content
`follower_list`	object	❌	Assignee list, format see note 6
`remind_time`	string	❌	Reminder time, format:`YYYY-MM-DD HH:mm:ss`

Call example

Use wecom_mcp tool to call wecom_mcp call todo create_todo '{"content": "<待办的内容>", "remind_time": "2025-06-01 09:00:00"}'

Return format

{
    "errcode": 0,
    "errmsg": "ok",
    "todo_id": "TODO_ID"
}

Return field description

Field	Type	Description
`todo_id`	string	Unique ID of the newly created todo

4. Update todo (update_todo)

Modify the content, assignees, status, or reminder time of an existing todo item.

How to call

Use wecom_mcp tool to call wecom_mcp call todo update_todo '<json格式的入参>'

Input parameters

Parameter	Type	Required	Description
`todo_id`	string	✅	Todo ID
`content`	string	❌	New todo content
`follower_list`	object	❌	New assignee list (full replacement, not append), format see note 6. To add assignees, first query the existing assignees, merge them, and submit together
`todo_status`	number	❌	New todo status:`0`-Completed,`1`-In progress,`2`-Deleted. To delete, use `delete_todo`
`remind_time`	string	❌	New reminder time

Call example

Use wecom_mcp tool to call wecom_mcp call todo update_todo '{"todo_id": "TODO_ID", "content": "<待办的内容>", "remind_time": "2025-07-01 09:00:00"}'

Return format

{
    "errcode": 0,
    "errmsg": "ok"
}

5. Delete todo (delete_todo)

Delete the specified todo item.

How to call

Use wecom_mcp tool to call wecom_mcp call todo delete_todo '<json格式的入参>'

Input parameters

Must follow the format requirements in "Notes":

Parameter	Type	Required	Description
`todo_id`	string	✅	Todo ID

Call example

Use wecom_mcp tool to call wecom_mcp call todo delete_todo '{"todo_id": "TODO_ID"}'

Return format

{
    "errcode": 0,
    "errmsg": "ok"
}

Before deleting, you must confirm with the user. Example confirmation wording: "Confirm deleting the todo 'Code Review'? It cannot be recovered after deletion." Note:delete_todo and update_todo set todo_status=2 have the same effect, prefer using delete_todo。

6. Change user todo status (change_todo_user_status)

Change the current user's status in a todo (reject/accept/completed).

How to call

Use wecom_mcp tool to call wecom_mcp call todo change_todo_user_status '<json格式的入参>'

Input parameters

Must follow the format requirements in "Notes":

Parameter	Type	Required	Description
`todo_id`	string	✅	Todo ID
`user_status`	number	✅	User status:`0`-Rejected,`1`-Accepted,`2`-Completed

Call example

Use wecom_mcp tool to call wecom_mcp call todo change_todo_user_status '{"todo_id": "TODO_ID", "user_status": 2}'

Return format

{
    "errcode": 0,
    "errmsg": "ok"
}

Return field description

Field	Type	Description
`errcode`	number	Return code,`0` indicates success
`errmsg`	string	Error message, on success `"ok"`

Typical workflows

For complete workflow steps, command examples, and display formats, see examples/workflows.md

Workflow	Applicable scenarios	Key points
Workflow 1: View todo list	"Show me my recent todos"	Standard three steps: get_todo_list → get_todo_detail → contact to convert names; check has_more for pagination
Workflow 2: Query by time range	"What todos were created this month?"	Pass create_begin_time / create_end_time to filter, then follow Workflow 1
Workflow 3: Create and assign a todo	"Help me create a todo and have Zhang San complete the requirements document"	First look up the userid via wecom-contact, then create_todo with follower_list
Workflow 4: Mark a todo as completed	"Mark this todo as completed"	Distinguish scenario A (change todo_status=0) and scenario B (change user_status=2)
Workflow 5: Update a todo	"Change the reminder time to next Friday"	First query the list + details to locate the target, then update_todo
Workflow 6: Delete a todo	"Delete that todo"	Must confirm with the user before deletion; it cannot be undone
Workflow 7: Paginated retrieval	The number of todos exceeds the single-page limit	Loop through with cursor; if not fully retrieved, must remind the user

Notes

todo_id source rule
- todo_id must come from the result returned by get_todo_list ; guessing or constructing it yourself is prohibited
- Users usually provide a todo content description rather than an ID; you should first query the list via get_todo_list and then match
- If multiple similar todos are matched, display the candidate list for the user to confirm
follower_id source rule
- follower_id is userid, and must be obtained through the wecom-contact skill's get_userlist interface
- Guessing the userid based on the user's name is prohibited
- If the search results contain multiple people with the same name, display the candidate list for the user to choose
Personnel IDs must be converted to names
- In the returned results, follower_id and creator_id are internal system identifiers that users cannot recognize
- Before displaying todo details, first use the wecom_mcp tool to call wecom_mcp call contact get_userlist '{}' to get the contacts
- Use the contacts' userid to match follower_id / creator_id, and use name for display replacement
- If an ID cannot be found in the contacts, mark it as "Unknown User (ID: xxx)" when displaying
Time Format
- All time parameters use the YYYY-MM-DD HH:mm:ss format
- When the user says relative times such as "tomorrow" or "next Monday", calculate the specific date based on the current date
Status Value Meanings
- Todo status (todo_status）：0-Completed,1-In Progress,2-Deleted
- User status (user_status）：0-Declined,1-Accepted,2-Completed
- Assignee status (follower_status）：0-Declined,1-Accepted,2-Completed

Format of follower_list(when used as an input parameter)

"follower_list": {                    // 分派人列表
    "followers": [                    // 注意里面还有一层是 "followers"，它的value才是真正的列表数组
        {
            "follower_id": "FOLLOWER_ID",      // 分派人id
            "follower_status": 1              // 分派人状态：0-拒绝, 1-接受, 2-已完成
        }
    ]
}

follower_id i.e. userid, which must be obtained by querying wecom-contact . Guessing or constructing it yourself is prohibited.

Confirmation for Destructive Operations
- Before deleting a todo (delete_todo), you must confirm with the user
- Before changing the status to "Declined" (user_status=0), it is recommended to confirm with the user
Must Check Details
- get_todo_list returns summary information (excluding content and assignee). After getting the list, you must immediately call get_todo_detail to get the full content before displaying it to the user. Do not display only the list summary
Must Remind When Pagination Is Not Complete
- If the returned has_more is true, when displaying the results to the user you must clearly state "There are more todos not displayed" and ask the user whether they need to continue viewing
Single Detail Limit
- todo_id_list can pass at most 20 IDs; if exceeded, requests must be made in batches
Error Handling
- If errcode is not 0, it indicates the API call failed. Inform the user of the error message in errmsg error message in
Contacts Query
- When an assignee is involved, you must first use the wecom-contact skill's get_userlist interface to get all contacts members, then locally filter and match by name/alias to find the corresponding userid. This interface takes no parameters and returns the list of members visible to the current user (including userid, name, alias）

About this skill

Overview

Command invocation method

Behavior policy

Detailed command description

1. Query todo list (get_todo_list)

How to call

Input parameter description

Return format

Returned field description

2. Get todo details (get_todo_detail)

How to call

Input parameter description

Call example

Return format

Returned field description

3. Create todo (create_todo)

How to call

Input parameters

Call example

Return format

Return field description

4. Update todo (update_todo)

How to call

Input parameters

Call example

Return format

5. Delete todo (delete_todo)

How to call

Input parameters

Call example

Return format

6. Change user todo status (change_todo_user_status)

How to call

Input parameters

Call example

Return format

Return field description

Typical workflows

Notes