Ultra MCP

Instructions

Implementation Reference

• src/handlers/advanced-tools.ts:388-513 (handler)

  The core handler function that implements the ultra-debug tool logic. Parses arguments using DebugSchema, constructs step-specific prompts for systematic debugging workflow, generates AI response using the selected provider, and formats the multi-step workflow response.

    async handleDebug(args: unknown): Promise<HandlerResponse> {
      const params = DebugSchema.parse(args);
      const { provider: requestedProvider, model: requestedModel, stepNumber, totalSteps, nextStepRequired, confidence, findings, issue, files, symptoms, hypothesis } = params;
      
      const config = await this.configManager.getConfig();
      const providerName = requestedProvider || await this.providerManager.getPreferredProvider();
      const provider = await this.providerManager.getProvider(providerName);
      
      if (!provider) {
        throw new Error('No AI provider configured. Please run: bunx ultra-mcp config');
      }
  
      try {
        let context = '';
        let requiredActions: string[] = [];
        
        if (stepNumber === 1) {
          context = `You are debugging an issue in the codebase.
          
  Issue: ${issue}
  ${symptoms ? `Symptoms: ${symptoms}` : ''}
  ${files ? `Relevant files: ${files.join(', ')}` : ''}
  
  Begin your systematic debugging by:
  1. Understanding the reported issue and symptoms
  2. Identifying potential root causes
  3. Forming initial hypotheses
  4. Planning your investigation approach`;
  
          requiredActions = [
            'Reproduce or understand the issue',
            'Examine error logs and stack traces',
            'Identify the code paths involved',
            'Form initial hypotheses about root cause',
            'Plan systematic investigation steps',
          ];
        } else if (stepNumber === 2) {
          context = `Continue debugging based on initial investigation:
  
  ${findings}
  ${hypothesis ? `Current hypothesis: ${hypothesis}` : ''}
  
  Now investigate deeper:
  - Test your hypotheses
  - Trace through the code execution
  - Check for common pitfalls in this area
  - Look for related issues`;
  
          requiredActions = [
            'Test current hypothesis with evidence',
            'Trace execution flow step by step',
            'Check for race conditions or timing issues',
            'Verify assumptions about data and state',
            'Look for similar patterns elsewhere',
          ];
        } else if (confidence === 'high' || confidence === 'very_high') {
          context = `You're close to identifying the root cause:
  
  ${findings}
  ${hypothesis ? `Working hypothesis: ${hypothesis}` : ''}
  
  Verify your findings and prepare the solution:
  - Confirm the root cause
  - Identify the fix
  - Consider side effects
  - Plan testing approach`;
  
          requiredActions = [
            'Confirm root cause with concrete evidence',
            'Design the fix or workaround',
            'Consider potential side effects',
            'Plan how to test the fix',
            'Document the issue for future reference',
          ];
        } else {
          context = `Finalize your debugging investigation:
  
  ${findings}
  
  Provide:
  - Confirmed root cause
  - Recommended fix with code examples
  - Testing strategy
  - Prevention recommendations`;
  
          requiredActions = [];
        }
  
        const prompt = `${context}\n\nProvide your debugging analysis for step ${stepNumber} of ${totalSteps}.`;
        
        const fullResponse = await provider.generateText({
          prompt,
          model: requestedModel,
          temperature: 0.2,
          systemPrompt: 'Focus on systematic debugging and root cause analysis.',
          useSearchGrounding: false,
        });
  
        // TODO: Implement tracking
        // await trackUsage({
        //   tool: 'ultra-debug',
        //   model: provider.getActiveModel(),
        //   provider: provider.getName(),
        //   input_tokens: 0,
        //   output_tokens: 0,
        //   cache_tokens: 0,
        //   total_tokens: 0,
        //   has_credentials: true,
        // });
  
        const formattedResponse = formatWorkflowResponse(
          stepNumber,
          totalSteps,
          nextStepRequired && confidence !== 'certain',
          fullResponse.text,
          requiredActions
        );
  
        return {
          content: [{ type: 'text', text: formattedResponse }],
        };
      } catch (error) {
        logger.error('Debug failed:', error);
        throw error;
      }
    }

• src/handlers/advanced-tools.ts:92-108 (schema)

  Zod schema defining the input validation for the ultra-debug tool, including core fields like issue, symptoms, files, provider/model selection, and workflow state management fields.

  export const DebugSchema = z.object({
    issue: z.string().describe('The issue or error to debug'),
    files: z.array(z.string()).optional().describe('Relevant file paths (optional)'),
    symptoms: z.string().optional().describe('Error symptoms or behavior observed'),
    provider: z.enum(['openai', 'gemini', 'azure', 'grok']).optional()
      .describe('AI provider to use'),
    model: z.string().optional().describe('Specific model to use'),
    
    // Workflow fields
    stepNumber: z.number().min(1).default(1).describe('Current step in the debug workflow'),
    totalSteps: z.number().min(1).default(4).describe('Estimated total steps needed'),
    findings: z.string().default('').describe('Accumulated findings from debugging'),
    nextStepRequired: z.boolean().default(true).describe('Whether another step is needed'),
    hypothesis: z.string().optional().describe('Current theory about the issue'),
    confidence: z.enum(['exploring', 'low', 'medium', 'high', 'very_high', 'almost_certain', 'certain'])
      .optional().describe('Confidence level in findings'),
  });

• src/server.ts:415-423 (registration)

  Registers the ultra-debug tool on the MCP server with metadata (title, description), input schema, and execution handler that dynamically imports AdvancedToolsHandler and invokes handleDebug.

  server.registerTool("ultra-debug", {
    title: "Ultra Debug",
    description: "Systematic debugging with step-by-step root cause analysis",
    inputSchema: DebugSchema.shape,
  }, async (args) => {
    const { AdvancedToolsHandler } = await import("./handlers/advanced-tools");
    const handler = new AdvancedToolsHandler();
    return await handler.handleDebug(args);
  });

• src/server.ts:852-870 (registration)

  Registers a prompt variant for ultra-debug, providing a simplified message template for step-by-step debugging interactions.

  server.registerPrompt("ultra-debug", {
    title: "Ultra Debug Analysis",
    description: "Systematic step-by-step debugging with root cause analysis",
    argsSchema: {
      issue: z.string(),
      files: z.string().optional(),
      symptoms: z.string().optional(),
      stepNumber: z.string(),
      totalSteps: z.string(),
    },
  }, (args) => ({
    messages: [{
      role: "user",
      content: {
        type: "text",
        text: `Debug this issue systematically: ${args.issue}${args.files ? `\n\nRelevant files: ${args.files}` : ''}${args.symptoms ? `\n\nSymptoms: ${args.symptoms}` : ''} (Step ${args.stepNumber} of ${args.totalSteps})`
      }
    }]
  }));