coderide

Instructions

Implementation Reference

• src/tools/list-tasks.ts:96-168 (handler)

  The main handler function that executes the list_tasks tool. It fetches tasks for a given project slug from the API, processes the response, sorts tasks by number, and returns formatted project and task information or handles errors.

  async execute(input: ListTasksInput): Promise<unknown> {
    logger.info('Executing list-tasks tool', input);
  
    try {
      // Use the injected API client to get task list
      if (!this.apiClient) {
        throw new Error('API client not available - tool not properly initialized');
      }
  
      const url = `/task/project/slug/${input.slug.toUpperCase()}`;
      logger.debug(`Making GET request to: ${url}`);
      
      const responseData = await this.apiClient.get<TaskListApiResponse>(url) as unknown as TaskListApiResponse;
      
      if (!responseData) {
        logger.warn(`No project found or invalid response format from ${url}`);
        return {
          isError: true,
          content: [{ type: "text", text: `Project with slug '${input.slug}' not found` }]
        };
      }
      
      // Calculate total task count across all columns
      const totalTasks = responseData.columns?.reduce((total, column) => total + (column.tasks?.length || 0), 0) || 0;
      
      // Return formatted task list with project info and organized tasks
      return {
        project: {
          id: responseData.id,
          name: responseData.name,
          slug: responseData.slug,
          status: responseData.status
        },
        taskSummary: {
          totalTasks,
          statusBreakdown: responseData.columns?.map(column => ({
            status: column.id,
            name: column.name,
            count: column.tasks?.length || 0
          })) || []
        },
        tasksByStatus: responseData.columns?.map(column => ({
          status: column.id,
          name: column.name,
          tasks: column.tasks?.map(task => ({
            number: task.number,
            title: task.title,
            description: task.description,
            status: task.status,
            priority: task.priority,
            position: task.position,
            hasContext: !!task.context,
            hasInstructions: !!task.instructions
          })).sort((a, b) => {
            // Sort tasks by their number (e.g., CDB-1, CDB-2, CDB-3, etc.)
            const getTaskNumber = (taskNumber: string) => {
              const match = taskNumber.match(/^[A-Z]{3}-(\d+)$/);
              return match ? parseInt(match[1], 10) : 0;
            };
            return getTaskNumber(a.number) - getTaskNumber(b.number);
          }) || []
        })) || []
      };
    } catch (error) {
      const errorMessage = (error instanceof Error) ? error.message : 'An unknown error occurred';
      logger.error(`Error in task-list tool: ${errorMessage}`, error instanceof Error ? error : undefined);
      
      return {
        isError: true,
        content: [{ type: "text", text: errorMessage }]
      };
    }
  }

• src/tools/list-tasks.ts:14-20 (schema)

  Zod schema defining the input parameters for the list_tasks tool, specifically requiring a three-letter project slug.

  const ListTasksSchema = z.object({
    // Project slug (URL-friendly identifier)
    slug: z.string({
      required_error: "Project slug is required"
    })
      .regex(/^[A-Za-z]{3}$/, { message: "Project slug must be three letters (e.g., CDB or cdb). Case insensitive." }),
  }).strict();

• src/index.ts:328-330 (registration)

  Registration loop that calls register() on all tool instances, including ListTasksTool, to register them with the MCP server.

  tools.forEach(tool => {
    tool.register(server);
  });

• src/index.ts:323-323 (registration)

  Instantiation of the ListTasksTool class with dependency-injected SecureApiClient, added to the tools array for subsequent registration.

  new ListTasksTool(secureApiClient),

• src/tools/list-tasks.ts:73-91 (helper)

  Helper method that generates agent instructions after executing list_tasks, providing guidance on next steps and workflow recommendations.

  protected generateAgentInstructions(input: ListTasksInput, result: any): AgentInstructions {
    return {
      immediateActions: [
        "Review available tasks and their current status",
        "Help user select appropriate task to work on",
        "Consider task status (to-do, in-progress, completed) for workflow planning"
      ],
      nextRecommendedTools: ["get_project", "get_task"],
      workflowPhase: 'discovery',
      criticalReminders: [
        "Always establish project context before starting selected task",
        "Follow optimal workflow: get_project → get_task → get_prompt"
      ],
      automationHints: {
        taskSelection: "Guide user to select tasks based on priority and dependencies",
        workflowGuidance: "Ensure project context is established before task work begins"
      }
    };
  }