6.0 KiB
name, description
| name | description |
|---|---|
| dingtalk-approval | Use the protected DingTalk Approval MCP to list, inspect, summarize, approve, reject, return, or create the signed-in user's DingTalk OA and XFT approvals, including approvals the user handled or submitted. Trigger for approval todos or history, expense review, reimbursement details, explicit approval actions, or requests to start and submit a new approval. |
DingTalk Approval
Use only the dingtalk-approval MCP tools. DingTalk OA and XFT use the same gateway-authenticated DingTalk user. Never ask for AppKey, Secret, userId, employee ID, cookies, or raw access tokens.
Login and first run
After installation or update, handle the installer's postInstall result immediately instead of waiting for the user's first approval request. If it contains authChallenge.directUrl, copy that complete clickable URL into the current user-facing reply. After the user authorizes, call approval_login, then make one read-only approval_list_todos call with source=all to verify both DingTalk OA and XFT. If login preparation was temporarily unavailable, keep the installation and call approval_login after the MCP is loaded. If the installation link expires before the MCP can load, execute the returned loginCommand and show its new authChallenge.directUrl; never rerun installation just to renew a link.
When a successful response contains onboarding.firstRun=true, show its short examples and write-safety note to the user once. Do not execute an example automatically. The same onboarding may be returned directly in postInstall when an existing login is reused.
On first use, expired authorization, or an expired login link, call approval_login again. It checks the existing session and creates a fresh link when necessary; never reinstall for this purpose. The tool does not send or push the login link through another channel. Copy the clickable URL from content.text verbatim into the current user-facing reply; when available, authChallenge.directUrl and the resource_link contain the same URL. Never merely claim that a link was generated or pushed, never read bridge state files to recover it, and never render QR images as ASCII. One successful login covers both approval sources.
Review and process
- Call
approval_list_todosfirst. TreatapprovalId,selectionId,targetId, reference availability, call limits, and batching as internal tool details: never mention or explain them to the user. When the user only asks to review approvals, report only relevant business information and do not proactively discuss how writes would be performed. Internally useapprovalIdfor one or some items; when the user explicitly asks to process the entire returned result set and aselectionIdis present, prefer it because the gateway binds it to that exact live set. - For ordinary review call
approval_get_detailwithview=summary; for expenses useview=expense. Use filteredrawpaging only when a required field is missing. - Approve and reject do not require per-item
approval_get_actionscalls: the gateway revalidates every item immediately before writing.allowed=truemeans the pending-task preflight passed;guaranteed=falsemeans DingTalk may still enforce a signature or another business rule at execution. Only before return, callapproval_get_actionsand copy a returnedtargetIdexactly. - Call
approval_process_batchonly after the user explicitly requests a write action. One call accepts at most 20 items. For an entire eligible listed group passselectionIdand an emptyitemslist; for a subset pass itsapprovalIditems. Never combine both. If one confirmed list contains more than 20 requested items, split only those originalapprovalIdvalues into internal groups of at most 20; do not relist between groups or mix newly appeared todos into the authorization. The user's request must cover every group, but do not add a redundant confirmation when it already clearly does. Never tell the user about the 20-item limit, internal grouping, or reference fields; simply carry out the authorized business action and report the business results. - The gateway validates every
approvalIdandtargetIdbefore the first write. If any reference is invalid, the result ispreflight_failed,writesStarted=false, and the entire call writes zero items. Relist, show the refreshed targets, and obtain confirmation again; never compensate or retry automatically. - Report every item result from the compact tool text.
failedmeans the operation was rejected and did not take effect; do not retry unless the user explicitly asks after reviewing the reason.succeededmeans the node was submitted;completedmeans the current user has no remaining node.outcome_uncertainmeans a write was submitted but not confirmed: never retry it automatically; wait and list todos again. If follow-up is required, list todos again. If a DingTalk template requires handwriting or another client-only action, send its client link to the user instead of retrying.
Review history
Call approval_list_history with scope=handled for approvals the current user already processed, or scope=submitted for approvals the current user initiated. The default window is the most recent 30 days. Use optional startDate and endDate for a specific window of at most 120 days; YYYY-MM-DD is interpreted in Asia/Shanghai, the end date is inclusive, and timezone-aware ISO 8601 timestamps are also accepted. Use source, query, and limit to narrow the live result. Historical approvalId values are user-bound, short-lived, and read-only: use them only with approval_get_detail. Never pass them to approval_get_actions or approval_process_batch; the gateway rejects them before any write. Historical results intentionally have no selectionId or available actions.
Create an approval
Before creating, submitting, revoking, or reconciling a newly initiated approval, read references/create-approval.md completely and follow it. Do not use that reference for ordinary todo review, history lookup, or processing someone else's pending approval.