coderide

Instructions

Implementation Reference

• src/tools/next-task.ts:150-218 (handler)

  Core handler function that executes the tool logic: validates input, calls SecureApiClient to GET /task/number/{number}/next, processes response, handles errors, and returns structured data about current/next task and sequence.

  async execute(input: NextTaskInput): Promise<unknown> {
    logger.info('Executing next-task tool', input);
  
    try {
      // Use the injected API client to get next task
      if (!this.apiClient) {
        throw new Error('API client not available - tool not properly initialized');
      }
  
      const url = `/task/number/${input.number.toUpperCase()}/next`;
      logger.debug(`Making GET request to: ${url}`);
      
      const responseData = await this.apiClient.get<NextTaskApiResponse>(url) as unknown as NextTaskApiResponse;
      
      if (!responseData) {
        logger.warn(`No next task found for ${input.number} from ${url}`);
        return {
          isError: true,
          content: [{ type: "text", text: `No next task found after '${input.number}'` }]
        };
      }
      
      // Extract project slug and calculate sequence info
      const currentProjectSlug = input.number.toUpperCase().split('-')[0];
      const currentNumber = parseInt(input.number.split('-')[1]);
      const nextNumber = currentNumber + 1;
      
      // Return formatted next task details
      return {
        currentTask: {
          number: input.number.toUpperCase(),
          projectSlug: currentProjectSlug,
          sequenceNumber: currentNumber
        },
        nextTask: {
          number: responseData.number,
          title: responseData.title,
          description: responseData.description,
          status: responseData.status,
          priority: responseData.priority,
          sequenceNumber: nextNumber,
          hasContext: !!responseData.context,
          hasInstructions: !!responseData.instructions
        },
        sequenceInfo: {
          projectSlug: currentProjectSlug,
          progression: `${input.number.toUpperCase()} → ${responseData.number}`,
          increment: 1
        }
      };
    } catch (error) {
      const errorMessage = (error instanceof Error) ? error.message : 'An unknown error occurred';
      logger.error(`Error in next-task tool: ${errorMessage}`, error instanceof Error ? error : undefined);
      
      // Provide more specific error messages based on common scenarios
      let userFriendlyMessage = errorMessage;
      if (errorMessage.includes('not found')) {
        const projectSlug = input.number.toUpperCase().split('-')[0];
        const currentNumber = parseInt(input.number.split('-')[1]);
        const expectedNext = `${projectSlug}-${currentNumber + 1}`;
        userFriendlyMessage = `Next task '${expectedNext}' not found. This might be the last task in the project or the next task hasn't been created yet.`;
      }
      
      return {
        isError: true,
        content: [{ type: "text", text: userFriendlyMessage }]
      };
    }
  }

• src/tools/next-task.ts:14-19 (schema)

  Zod schema defining the input structure: requires 'number' string matching pattern ^[A-Za-z]{3}-\d+$ (e.g., CDB-23).

  const NextTaskSchema = z.object({
    // Task number (e.g., "CDB-23")
    number: z.string({
      required_error: "Task number is required"
    }).regex(/^[A-Za-z]{3}-\d+$/, { message: "Task number must be in the format ABC-123 (e.g., CDB-23 or cdb-23). Case insensitive." }),
  }).strict();

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

  Imports NextTaskTool, instantiates it with SecureApiClient dependency injection in production server (line 324), and registers it to the MCP Server via BaseTool's register method in the forEach loop.

  import { NextTaskTool } from './tools/next-task.js';
  
  // Configuration schema for Smithery
  export const configSchema = z.object({
    CODERIDE_API_KEY: z.string().describe("CodeRide API key for authentication")
  });
  
  /**
   * Create mock server for development/testing
   */
  function createMockServer() {
    logger.info('Creating mock CodeRide MCP server for development');
    
    const server = new Server(
      {
        name: 'CodeRide-Mock',
        version: '0.9.2',
      },
      {
        capabilities: {
          tools: {},
        },
      }
    );
  
    // Mock tools with professional descriptions matching production
    const mockTools = [
      {
        name: 'start_project',
        description: "Retrieves the project details and the prompt for the very first task of a specified project using the project's unique slug (e.g., 'CRD'). This is useful for initiating work on a new project or understanding its starting point.",
        inputSchema: {
          type: 'object',
          properties: {
            slug: { type: 'string', pattern: '^[A-Za-z]{3}$' }
          },
          required: ['slug']
        },
        handler: async (args: any) => ({
          project: { slug: args.slug, name: `CodeRide Project ${args.slug}` },
          task: { number: `${args.slug}-1`, title: 'Initialize Project Architecture', prompt: 'Set up the foundational architecture and development environment for this CodeRide project. Review project requirements and establish coding standards.' }
        })
      },
      {
        name: 'get_prompt',
        description: "Retrieves the specific instructions or prompt for a given task, identified by its unique task number (e.g., 'CRD-1'). This is typically used to understand the detailed requirements or context for an AI agent to work on the task.",
        inputSchema: {
          type: 'object',
          properties: {
            number: { type: 'string', pattern: '^[A-Za-z]{3}-\\d+$' }
          },
          required: ['number']
        },
        handler: async (args: any) => ({
          taskPrompt: `Implement the core functionality for task ${args.number}. Focus on clean, maintainable code following CodeRide best practices. Ensure proper error handling and comprehensive testing coverage.`
        })
      },
      {
        name: 'get_task',
        description: "Retrieves detailed information for a specific task using its unique task number (e.g., 'CRD-1').",
        inputSchema: {
          type: 'object',
          properties: {
            number: { type: 'string', pattern: '^[A-Za-z]{3}-\\d+$' }
          },
          required: ['number']
        },
        handler: async (args: any) => ({
          number: args.number,
          title: `Implement Feature Component`,
          description: 'Develop and integrate a new feature component following CodeRide architecture patterns and design system guidelines.',
          status: 'to-do',
          priority: 'high',
          agent: 'AI Development Assistant',
          agent_prompt: 'Focus on clean code architecture and comprehensive testing',
          context: 'Part of the core platform development initiative',
          instructions: 'Follow CodeRide coding standards and ensure proper documentation'
        })
      },
      {
        name: 'get_project',
        description: "Retrieves detailed information about a specific project using its unique 'slug' (three uppercase letters, e.g., 'CRD').",
        inputSchema: {
          type: 'object',
          properties: {
            slug: { type: 'string', pattern: '^[A-Za-z]{3}$' }
          },
          required: ['slug']
        },
        handler: async (args: any) => ({
          slug: args.slug,
          name: `CodeRide ${args.slug} Platform`,
          description: 'AI-native task management and development workflow platform designed for modern software teams.',
          projectKnowledge: { 
            components: ['task-engine', 'ai-integration', 'workflow-automation'], 
            technologies: ['TypeScript', 'React', 'Node.js', 'MCP'],
            architecture: 'microservices',
            patterns: ['dependency-injection', 'event-driven']
          },
          projectDiagram: 'graph TD\n  A[AI Agent] --> B[Task Engine]\n  B --> C[CodeRide API]\n  C --> D[Project Management]\n  D --> E[Workflow Automation]'
        })
      },
      {
        name: 'list_projects',
        description: "Lists all projects in the user workspace. No input parameters required as the workspace is automatically determined from the API key authentication.",
        inputSchema: { type: 'object', properties: {}, required: [] },
        handler: async () => ({
          projects: [
            { id: '1', slug: 'CRD', name: 'CodeRide Core Platform', description: 'Main CodeRide platform development' },
            { id: '2', slug: 'MCP', name: 'MCP Integration Suite', description: 'Model Context Protocol integration tools' },
            { id: '3', slug: 'API', name: 'CodeRide API Gateway', description: 'Unified API gateway and authentication system' }
          ],
          totalCount: 3
        })
      },
      {
        name: 'list_tasks',
        description: "Lists all tasks within a project using the project slug (e.g., 'CDB'). Returns tasks organized by status columns with their order and current status.",
        inputSchema: {
          type: 'object',
          properties: {
            slug: { type: 'string', pattern: '^[A-Za-z]{3}$' }
          },
          required: ['slug']
        },
        handler: async (args: any) => ({
          project: { slug: args.slug, name: `CodeRide ${args.slug} Platform` },
          taskSummary: { totalTasks: 4 },
          tasksByStatus: [
            {
              status: 'to-do',
              tasks: [
                { number: `${args.slug}-1`, title: 'Initialize Project Architecture', status: 'to-do' },
                { number: `${args.slug}-2`, title: 'Implement Core API Endpoints', status: 'to-do' }
              ]
            },
            {
              status: 'in-progress',
              tasks: [
                { number: `${args.slug}-3`, title: 'Develop User Authentication', status: 'in-progress' }
              ]
            },
            {
              status: 'completed',
              tasks: [
                { number: `${args.slug}-4`, title: 'Setup Development Environment', status: 'completed' }
              ]
            }
          ]
        })
      },
      {
        name: 'next_task',
        description: "Retrieves the next task in sequence based on the current task number (e.g., CDB-23 → CDB-24). This is useful for finding the next task that needs to be done in a project workflow.",
        inputSchema: {
          type: 'object',
          properties: {
            number: { type: 'string', pattern: '^[A-Za-z]{3}-\\d+$' }
          },
          required: ['number']
        },
        handler: async (args: any) => {
          const [slug, num] = args.number.split('-');
          const nextNum = parseInt(num) + 1;
          return {
            currentTask: { number: args.number },
            nextTask: { 
              number: `${slug}-${nextNum}`, 
              title: `Implement Advanced Features`, 
              status: 'to-do',
              description: 'Build advanced functionality and optimization features for the CodeRide platform.'
            }
          };
        }
      },
      {
        name: 'update_task',
        description: "Updates an existing task's 'description' and/or 'status'. The task is identified by its unique 'number' (e.g., 'CRD-1'). At least one of 'description' or 'status' must be provided for an update.",
        inputSchema: {
          type: 'object',
          properties: {
            number: { type: 'string', pattern: '^[A-Za-z]{3}-\\d+$' },
            description: { type: 'string' },
            status: { type: 'string', enum: ['to-do', 'in-progress', 'done'] }
          },
          required: ['number']
        },
        handler: async (args: any) => ({
          number: args.number,
          title: `CodeRide Task ${args.number}`,
          description: args.description || 'Updated task with enhanced functionality and improved implementation approach.',
          status: args.status || 'in-progress',
          updateConfirmation: `Successfully updated task ${args.number} in CodeRide platform`
        })
      },
      {
        name: 'update_project',
        description: "Updates a project's knowledge graph data and/or its structure diagram (in Mermaid.js format). The project is identified by its unique 'slug'. At least one of 'project_knowledge' or 'project_diagram' must be provided for an update to occur.",
        inputSchema: {
          type: 'object',
          properties: {
            slug: { type: 'string', pattern: '^[A-Za-z]{3}$' },
            project_knowledge: { type: 'object' },
            project_diagram: { type: 'string' }
          },
          required: ['slug']
        },
        handler: async (args: any) => ({
          slug: args.slug,
          name: `CodeRide ${args.slug} Platform`,
          project_knowledge: args.project_knowledge || { 
            updated: true, 
            components: ['enhanced-ai-engine', 'advanced-workflow'], 
            technologies: ['TypeScript', 'React', 'Node.js', 'MCP', 'AI/ML'] 
          },
          project_diagram: args.project_diagram || 'graph TD\n  A[Enhanced AI Engine] --> B[Smart Task Management]\n  B --> C[CodeRide Platform]\n  C --> D[Advanced Analytics]',
          updateConfirmation: `Successfully updated CodeRide project ${args.slug} with enhanced architecture`
        })
      }
    ];
  
    // Register list-tools handler
    server.setRequestHandler(ListToolsRequestSchema, async () => ({
      tools: mockTools.map(tool => ({
        name: tool.name,
        description: tool.description,
        inputSchema: tool.inputSchema
      }))
    }));
  
    // Register call-tool handler
    server.setRequestHandler(CallToolRequestSchema, async (request) => {
      const toolName = request.params.name;
      const mockTool = mockTools.find(t => t.name === toolName);
  
      if (!mockTool) {
        throw new McpError(ErrorCode.MethodNotFound, `Mock tool '${toolName}' not found`);
      }
  
      try {
        const result = await mockTool.handler(request.params.arguments || {});
        return {
          content: [{ type: 'text', text: JSON.stringify(result) }]
        };
      } catch (error) {
        logger.error(`Error in mock tool ${toolName}`, error as Error);
        return {
          content: [{ type: 'text', text: JSON.stringify({ 
            success: false, 
            error: `Mock error: ${(error as Error).message}` 
          }) }],
          isError: true
        };
      }
    });
  
    return server;
  }
  
  /**
   * Create production server with real API integration
   */
  function createProductionServer(smitheryConfig: z.infer<typeof configSchema>) {
    logger.info('Creating production CodeRide MCP server');
    
    // Create clean API configuration
    const apiConfig = createApiConfig(smitheryConfig);
    
    // Create secure API client with dependency injection
    const secureApiClient = createSecureApiClient(apiConfig);
  
    const server = new Server(
      {
        name: 'CodeRide',
        version: '0.9.2',
      },
      {
        capabilities: {
          tools: {},
        },
      }
    );
  
    // Initialize real tools with dependency injection
    const tools: any[] = [
      new StartProjectTool(secureApiClient),
      new GetPromptTool(secureApiClient),
      new GetTaskTool(secureApiClient),
      new GetProjectTool(secureApiClient),
      new UpdateTaskTool(secureApiClient),
      new UpdateProjectTool(secureApiClient),
      new ListProjectsTool(secureApiClient),
      new ListTasksTool(secureApiClient),
      new NextTaskTool(secureApiClient),
    ];
  
    // Register each tool with the server
    tools.forEach(tool => {
      tool.register(server);
    });

• src/tools/next-task.ts:127-145 (schema)

  MCP-compatible tool definition including inputSchema matching Zod schema, used for list-tools response.

  getMCPToolDefinition(): MCPToolDefinition {
    return {
      name: this.name,
      description: this.description,
      annotations: this.annotations,
      inputSchema: {
        type: "object",
        properties: {
          number: {
            type: "string",
            pattern: "^[A-Za-z]{3}-\\d+$",
            description: "The current task number to find the next task for (e.g., 'CDB-23' or 'cdb-23'). Case insensitive - will be converted to uppercase."
          }
        },
        required: ["number"],
        additionalProperties: false
      }
    };
  }

• src/tools/next-task.ts:56-122 (helper)

  Generates agent instructions based on tool result, recommending next tools like get_task, get_prompt, and handling workflow phases.

  generateAgentInstructions(input: any, result: any): AgentInstructions {
    const hasNextTask = result && !result.isError && result.number;
    
    const baseInstructions: AgentInstructions = {
      immediateActions: [
        'Next task in sequence identified',
        'Prepare for seamless task transition'
      ],
      nextRecommendedTools: ['get_task', 'get_prompt'],
      workflowPhase: 'discovery',
      prerequisiteValidation: {
        required: ['get_project'],
        onMissing: 'Project context required for task sequence management'
      },
      criticalReminders: [
        'Maintain workflow continuity between tasks',
        'Ensure project context remains current'
      ]
    };
  
    if (hasNextTask) {
      baseInstructions.immediateActions = [
        `Next task found: ${result.number}`,
        'Begin analysis of next task requirements',
        'Maintain project context for seamless transition'
      ];
      baseInstructions.nextRecommendedTools = ['get_task', 'get_prompt', 'update_task'];
      baseInstructions.workflowCorrection = {
        correctSequence: ['next_task', 'get_task', 'get_prompt', 'update_task'],
        redirectMessage: 'Continue with standard task workflow: get_task → get_prompt → update_task to "in-progress"'
      };
      baseInstructions.criticalReminders = [
        'Start next task immediately to maintain momentum',
        'Follow standard workflow: get_task → get_prompt → update_task',
        'Update task status to "in-progress" when ready to begin'
      ];
    } else {
      baseInstructions.immediateActions = [
        'No next task found in sequence',
        'Review project task list for available work',
        'Consider project completion or new task creation'
      ];
      baseInstructions.nextRecommendedTools = ['list_tasks'];
      baseInstructions.workflowPhase = 'completion';
      baseInstructions.criticalReminders = [
        'End of task sequence reached',
        'Review overall project status',
        'Consider if project goals are complete'
      ];
    }
  
    // Add sequence management automation hints
    baseInstructions.automationHints = {
      sequenceManagement: [
        'Always call next_task after completing a task',
        'Maintain task dependencies and logical order',
        'Update project knowledge before moving to next task'
      ],
      workflowContinuity: [
        'Preserve project context across task transitions',
        'Ensure consistent status management',
        'Document progress between tasks'
      ]
    };
  
    return baseInstructions;
  }