MCP Task

Instructions

Implementation Reference

• src/serve.ts:1076-1147 (handler)

  Handler function that executes the list_tasks tool. Retrieves all tasks from TaskManager, applies optional filters (status_filter, batch_id, recent_only), computes summaries and stats, and returns formatted JSON response.

  case 'list_tasks': {
      let allTasks = taskManager.getAllTasks();
  
      // Apply recent_only filter (last 2 hours)
      if (args.recent_only) {
          const twoHoursAgo = Date.now() - 2 * 60 * 60 * 1000;
          allTasks = allTasks.filter(
              t => t.createdAt.getTime() > twoHoursAgo
          );
      }
  
      // Apply batch_id filter
      if (args.batch_id) {
          allTasks = allTasks.filter(
              t => t.batchId === args.batch_id
          );
      }
  
      // Apply status filter
      const filteredTasks = args.status_filter
          ? allTasks.filter(t => t.status === args.status_filter)
          : allTasks;
  
      const taskSummaries = filteredTasks.map(t => ({
          id: t.id,
          status: t.status,
          task: t.task.substring(0, 100),
          model: t.model || t.modelClass,
          batchId: t.batchId,
          readOnly: t.readOnly,
          createdAt: t.createdAt,
          completedAt: t.completedAt,
      }));
  
      // Calculate stats for filtered tasks
      const stats = {
          total: filteredTasks.length,
          pending: filteredTasks.filter(t => t.status === 'pending')
              .length,
          running: filteredTasks.filter(t => t.status === 'running')
              .length,
          completed: filteredTasks.filter(
              t => t.status === 'completed'
          ).length,
          failed: filteredTasks.filter(t => t.status === 'failed')
              .length,
          cancelled: filteredTasks.filter(
              t => t.status === 'cancelled'
          ).length,
      };
  
      return {
          content: [
              {
                  type: 'text',
                  text: JSON.stringify(
                      {
                          stats,
                          tasks: taskSummaries,
                          filters_applied: {
                              batch_id: args.batch_id || null,
                              status: args.status_filter || null,
                              recent_only: args.recent_only || false,
                          },
                      },
                      null,
                      2
                  ),
              },
          ],
      };
  }

• src/serve.ts:286-324 (schema)

  Tool schema definition including name, description, annotations, and inputSchema for parameters: status_filter (enum), batch_id (string), recent_only (boolean).

  const LIST_TASKS_TOOL: Tool = {
      name: 'list_tasks',
      description: 'List all tasks with their current status.',
      annotations: {
          title: 'List All Tasks',
          readOnlyHint: true, // Only reads task list
          destructiveHint: false, // Doesn't modify or destroy data
          idempotentHint: false, // Task list may change between calls
          openWorldHint: false, // Only queries local task state
      },
      inputSchema: {
          type: 'object',
          properties: {
              status_filter: {
                  type: 'string',
                  description: 'Optional: Filter tasks by status',
                  enum: [
                      'pending',
                      'running',
                      'completed',
                      'failed',
                      'cancelled',
                  ],
              },
              batch_id: {
                  type: 'string',
                  description:
                      'Optional: Filter tasks by batch ID to only show tasks from a specific batch',
              },
              recent_only: {
                  type: 'boolean',
                  description:
                      'Optional: Only show tasks from the last 2 hours (default: false)',
                  default: false,
              },
          },
          required: [], // All parameters are optional
      },
  };

• src/serve.ts:558-579 (registration)

  Registers the list_tasks tool by including LIST_TASKS_TOOL in the array returned by the ListToolsRequestHandler.

  server.setRequestHandler(ListToolsRequestSchema, async () => {
      if (process.env.MCP_MODE !== 'true') {
          logger.debug('Received ListTools request');
      }
      const response = {
          tools: [
              RUN_TASK_TOOL,
              CHECK_TASK_STATUS_TOOL,
              GET_TASK_RESULT_TOOL,
              CANCEL_TASK_TOOL,
              WAIT_FOR_TASK_TOOL,
              LIST_TASKS_TOOL,
          ],
      };
      if (process.env.MCP_MODE !== 'true') {
          logger.debug(
              'Returning tools:',
              response.tools.map(t => t.name)
          );
      }
      return response;
  });

• src/utils/task-manager.ts:316-318 (helper)

  Helper method in TaskManager that returns the complete list of all current tasks, used by the list_tasks handler.

  public getAllTasks(): TaskInfo[] {
      return Array.from(this.tasks.values());
  }