MCP Cron Server

Instructions

Implementation Reference

• src/index.ts:115-149 (handler)

  The main cron_add handler in CallToolRequestSchema that validates input arguments, calls scheduler.addJob() to create the job, and returns a formatted response with job ID and next run time

  case 'cron_add': {
    const inputArgs = args as {
      name: string;
      description?: string;
      schedule: any;
      payload: any;
      options?: any;
    };
    
    const job = scheduler.addJob({
      name: inputArgs.name,
      description: inputArgs.description,
      enabled: true,
      schedule: inputArgs.schedule,
      payload: inputArgs.payload,
      options: inputArgs.options,
      state: {}
    });
    
    return {
      content: [
        {
          type: 'text',
          text: JSON.stringify({
            success: true,
            job: {
              id: job.id,
              name: job.name,
              nextRun: formatNextRun(job.state.nextRunAtMs)
            }
          }, null, 2)
        }
      ]
    };
  }

• src/index.ts:26-64 (schema)

  Input schema definition for cron_add tool specifying required fields (name, schedule, payload) and optional fields (description, options) with detailed property descriptions

    name: 'cron_add',
    description: '添加定时任务',
    inputSchema: {
      type: 'object',
      properties: {
        name: { type: 'string', description: '任务名称' },
        description: { type: 'string', description: '任务描述（可选）' },
        schedule: {
          type: 'object',
          description: '调度配置',
          properties: {
            kind: { type: 'string', enum: ['at', 'every', 'cron'], description: '调度类型' },
            atMs: { type: 'number', description: '一次性任务：绝对时间戳（毫秒）' },
            everyMs: { type: 'number', description: '间隔任务：间隔毫秒数' },
            expr: { type: 'string', description: 'Cron任务：cron表达式，如 "0 8 * * *"' },
            tz: { type: 'string', description: '时区，如 "Asia/Shanghai"' },
          },
          required: ['kind']
        },
        payload: {
          type: 'object',
          description: '任务内容',
          properties: {
            kind: { type: 'string', enum: ['agentTurn', 'systemEvent'] },
            message: { type: 'string', description: 'prompt或消息内容' },
          },
          required: ['kind', 'message']
        },
        options: {
          type: 'object',
          properties: {
            deleteAfterRun: { type: 'boolean', description: '执行后删除（一次性任务）' },
            maxRetries: { type: 'number', description: '最大重试次数' }
          }
        }
      },
      required: ['name', 'schedule', 'payload']
    }
  },

• src/scheduler.ts:80-98 (handler)

  The CronScheduler.addJob() method implementation that creates a new CronJob with generated ID, timestamps, computed next run time, and stores it in the store

  addJob(input: CronJobCreate): CronJob {
    const nowMs = Date.now();
    const job: CronJob = {
      ...input,
      id: createJobId(),
      enabled: true,
      createdAtMs: nowMs,
      updatedAtMs: nowMs,
      state: {
        ...input.state,
        nextRunAtMs: computeNextRunAtMs(input.schedule, nowMs)
      }
    };
    
    this.store.addJob(job);
    console.log(`[Scheduler] Job added: ${job.name} (${job.id})`);
    
    return job;
  }

• src/types.ts:1-50 (schema)

  Type definitions for CronSchedule (at/every/cron), CronPayload, CronJob, and CronJobCreate which define the structure of job data used by cron_add

  export type CronSchedule =
    | { kind: 'at'; atMs: number }
    | { kind: 'every'; everyMs: number; anchorMs?: number }
    | { kind: 'cron'; expr: string; tz?: string };
  
  export type CronPayloadKind = 'agentTurn' | 'systemEvent';
  
  export type CronPayload = {
    kind: CronPayloadKind;
    message: string;
    deliver?: boolean;
    channel?: string;
    to?: string;
    model?: string;
  };
  
  export type CronJobOptions = {
    deleteAfterRun?: boolean;
    retry?: boolean;
    maxRetries?: number;
  };
  
  export type CronRunStatus = 'ok' | 'error' | 'skipped';
  
  export type CronJobState = {
    nextRunAtMs?: number;
    runningAtMs?: number;
    lastRunAtMs?: number;
    lastStatus?: CronRunStatus;
    lastError?: string;
    lastDurationMs?: number;
    consecutiveErrors?: number;
  };
  
  export type CronJob = {
    id: string;
    name: string;
    description?: string;
    enabled: boolean;
    createdAtMs: number;
    updatedAtMs: number;
    schedule: CronSchedule;
    payload: CronPayload;
    options?: CronJobOptions;
    state: CronJobState;
  };
  
  export type CronJobCreate = Omit<CronJob, 'id' | 'createdAtMs' | 'updatedAtMs' | 'state'> & {
    state?: Partial<CronJobState>;
  };

• src/schedule.ts:65-95 (helper)

  formatNextRun() helper function that formats the next run timestamp into human-readable format (seconds, minutes, hours, or date string) used in the cron_add response

  export function formatNextRun(nextRunAtMs: number | null | undefined): string {
    if (!nextRunAtMs) return 'N/A';
    
    const date = new Date(nextRunAtMs);
    const now = new Date();
    
    const diff = nextRunAtMs - now.getTime();
    
    if (diff < 0) {
      return 'Overdue';
    }
    
    if (diff < 60000) {
      return `${Math.floor(diff / 1000)}s`;
    }
    
    if (diff < 3600000) {
      return `${Math.floor(diff / 60000)}m`;
    }
    
    if (diff < 86400000) {
      return `${Math.floor(diff / 3600000)}h`;
    }
    
    return date.toLocaleString('zh-CN', { 
      month: 'short', 
      day: 'numeric', 
      hour: '2-digit', 
      minute: '2-digit' 
    });
  }