ToolBox MCP Server

Implementation Reference

• src/tools/schedule_tool.ts:213-353 (handler)

  Main handler function implementing the logic for scheduling, canceling, listing, and managing recurring tasks by executing other tools at specified times.
  export default async (request: any) => { const action = request.params.arguments?.action; const toolName = request.params.arguments?.toolName; const toolArgs = request.params.arguments?.toolArgs; const id = request.params.arguments?.id; const messages = { taskCreated: (id: string) => `Scheduled task created. ID: ${id}`, taskCanceled: (id: string) => `Task canceled. ID: ${id}`, allOnceTasksCleared: "All one-time tasks cleared", allRecurringCleared: "All recurring tasks cleared", invalidTime: "Scheduled time must be in the future", missingParams: "Missing required parameters: time/delaySeconds/interval", invalidAction: "Invalid action type" }; switch (action) { case "create": let newTask: ScheduledTask; const { time, delaySeconds, interval } = request.params.arguments; if (time && time.startsWith('every@')) { newTask = { id: uuidv4(), toolName: toolName, toolArgs: toolArgs, executed: false, creationTime: new Date().toISOString(), type: 'recurring', interval: time, }; } else if (time) { const targetTime = new Date(time); const timeDiff = targetTime.getTime() - Date.now(); if (timeDiff <= 0) { throw new Error("Scheduled time must be in the future"); } newTask = { id: uuidv4(), toolName: toolName, toolArgs: toolArgs, executed: false, creationTime: new Date().toISOString(), type: 'once_absolute', time: time, }; } else if (delaySeconds) { newTask = { id: uuidv4(), toolName: toolName, toolArgs: toolArgs, executed: false, creationTime: new Date().toISOString(), type: 'once_relative', delaySeconds: delaySeconds, }; } else if (interval) { newTask = { id: uuidv4(), toolName: toolName, toolArgs: toolArgs, executed: false, creationTime: new Date().toISOString(), type: 'recurring', interval: interval, }; } else { throw new Error("Missing required parameters: time/delaySeconds/interval"); } await createTask(newTask); return { content: [ { type: "text", text: JSON.stringify(messages.taskCreated(newTask.id), null, 2), }, ], }; case "cancel": if (!id) { throw new Error("Missing parameter: id"); } cancelTask(id); return { content: [ { type: "text", text: JSON.stringify(messages.taskCanceled(id), null, 2), }, ], }; case "list": const tasksWithoutTimerId = scheduledTasks.map(task => { const { timerId, ...taskWithoutTimerId } = task; return taskWithoutTimerId; }); return { content: [ { type: "text", text: JSON.stringify(tasksWithoutTimerId, null, 2), }, ], }; case "cancel_all_once": scheduledTasks.forEach(task => { if ((task.type === 'once_absolute' || task.type === 'once_relative') && task.timerId) { clearTimeout(task.timerId); } }); scheduledTasks = scheduledTasks.filter(task => task.type !== 'once_absolute' && task.type !== 'once_relative'); saveTasks(); return { content: [ { type: "text", text: JSON.stringify(messages.allOnceTasksCleared, null, 2), }, ], }; case "cancel_all_recurring": scheduledTasks.forEach(task => { if (task.type === 'recurring' && task.timerId) { clearTimeout(task.timerId); } }); scheduledTasks = scheduledTasks.filter(task => task.type !== 'recurring'); saveTasks(); return { content: [ { type: "text", text: JSON.stringify(messages.allRecurringCleared, null, 2), }, ], }; default: throw new Error(messages.invalidAction); } };
• src/tools/schedule_tool.ts:161-196 (schema)

  Input schema defining the structure and validation for schedule_tool parameters, including actions and scheduling options.
  export const schema = { name: "schedule_tool", description: "Manage scheduled tasks (create/cancel/list)", type: "object", properties: { action: { type: "string", enum: ["create", "cancel", "list", "cancel_all_once", "cancel_all_recurring"], description: "Action type (create/cancel/list)" }, time: { type: "string", description: "Absolute execution time (YYYY-MM-DD HH:mm:ss)" }, delaySeconds: { type: "number", description: "Delay execution by N seconds" }, interval: { type: "string", description: "Recurring interval pattern (e.g. 'every@5m')" }, toolName: { description: "Tool to execute (e.g. 'time_tool')" }, toolArgs: { type: "object", description: "Parameters for the target tool" }, id: { type: "string", description: "Task ID (required for cancel)" } }, required: ["action"] };
• src/handler/ToolHandler.ts:91-139 (registration)

  Dynamic registration of all tools, including 'schedule_tool', by scanning the tools directory, importing modules, extracting schema/handler/destroy, and populating global tools and handlers registries.
  export async function loadTools(reload: boolean = false): Promise<{ [key: string]: (request: ToolRequest) => Promise<ToolResponse> }> { // 如果是初始加载且已加载，则直接返回 if (!reload && isLoaded) return; // 如果是重新加载，则重置状态 if (reload) { for (const tool of tools) { await tool?.destroy?.(); delete handlers[tool.name]; } tools.length = 0; isLoaded = false; } // 获取所有工具文件 const toolFiles = fs.readdirSync(toolsDir).filter(file => file.endsWith('.js') || file.endsWith('.ts')); // 加载每个工具 for (const file of toolFiles) { const toolPath = path.join(toolsDir, file); try { // 如果是重新加载，清除模块缓存 if (reload) clearModuleCache(toolPath); // 导入模块，重新加载时添加时间戳防止缓存 const importPath = 'file://' + toolPath + (reload ? `?update=${Date.now()}` : ''); const { default: tool, schema, destroy } = await import(importPath); const toolName = path.parse(toolPath).name; // 注册工具 tools.push({ name: toolName, description: tool.description, inputSchema: schema, destroy: destroy }); // 注册处理函数 handlers[toolName] = async (request: ToolRequest) => { return await tool(request); }; } catch (error) { console.error(`Failed to ${reload ? 'reload' : 'load'} tool ${file}:`, error); } } isLoaded = true; if (reload) console.log(`Successfully reloaded ${tools.length} tools`); return handlers; }
• src/tools/schedule_tool.ts:98-155 (helper)

  Core helper function that sets up timers for scheduled tasks based on their type (absolute time, relative delay, or recurring interval).
  async function scheduleTask(task: ScheduledTask) { switch (task.type) { case 'once_absolute': const targetTime = new Date(task.time); const delay = targetTime.getTime() - Date.now(); if (delay > 0) { task.timerId = setTimeout(async () => { await executeTask(task); }, delay); } break; case 'once_relative': const delaySeconds = task.delaySeconds; const delayMs = delaySeconds * 1000; task.timerId = setTimeout(async () => { await executeTask(task); }, delayMs); break; case 'recurring': const intervalStr = task.interval; const num = parseInt(intervalStr.substring(6)); const unit = intervalStr.slice(String(num).length + 6); let intervalMs = 0; if (unit === 's') { intervalMs = num * 1000; } else if (unit === 'm') { intervalMs = num * 60 * 1000; } else if (unit === 'h') { intervalMs = num * 60 * 60 * 1000; } else if (unit === 'd') { intervalMs = num * 24 * 60 * 60 * 1000; } if (intervalMs <= 0) { console.error(`Invalid interval for task ${task.id}: ${task.interval}`); return; } const scheduleRecurring = async () => { await executeTask(task); // Schedule next execution task.timerId = setTimeout(scheduleRecurring, intervalMs); }; let initialDelay = 0; if (task.startTime) { const startTime = new Date(task.startTime); initialDelay = startTime.getTime() - Date.now(); if (initialDelay < 0) { initialDelay = 0; } } task.timerId = setTimeout(scheduleRecurring, initialDelay); break; } }
• src/tools/schedule_tool.ts:90-96 (helper)

  Helper function that executes the scheduled tool call and updates task status.
  async function executeTask(task: ScheduledTask) { await callToolHandler({ params: { name: task.toolName, arguments: task.toolArgs } }, 'schedule_tool_' + task.id); task.executed = true; task.lastExecutionTime = new Date().toISOString(); saveTasks(); }