Ultra MCP

Instructions

Implementation Reference

• src/server.ts:395-403 (registration)

  Registers the 'ultra-review' MCP tool, specifying title, description, input schema from CodeReviewSchema, and handler instantiation.

  server.registerTool("ultra-review", {
    title: "Ultra Review", 
    description: "Comprehensive code review with step-by-step workflow analysis",
    inputSchema: CodeReviewSchema.shape,
  }, async (args) => {
    const { AdvancedToolsHandler } = await import("./handlers/advanced-tools");
    const handler = new AdvancedToolsHandler();
    return await handler.handleCodeReview(args);
  });

• src/handlers/advanced-tools.ts:164-291 (handler)

  Core handler function executing the 'ultra-review' tool logic: parses input, selects AI provider, builds workflow context based on step, generates analysis, formats multi-step response.

    async handleCodeReview(args: unknown): Promise<HandlerResponse> {
      const params = CodeReviewSchema.parse(args);
      const { provider: requestedProvider, model: requestedModel, stepNumber, totalSteps, nextStepRequired, confidence, findings, files, focus, task, filesChecked, issuesFound } = 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 {
        // Build context based on step
        let context = '';
        let requiredActions: string[] = [];
        
        if (stepNumber === 1) {
          context = `You are performing a comprehensive code review focused on ${focus}.
          
  Task: ${task}
  ${files ? `Files to review: ${files.join(', ')}` : 'Review all relevant files in the codebase'}
  
  Please begin your systematic code review by:
  1. Understanding the code structure and purpose
  2. Identifying the main components and their interactions
  3. Looking for ${focus === 'all' ? 'any issues including bugs, security vulnerabilities, performance problems, and code quality issues' : `${focus}-related issues`}
  4. Documenting your initial findings
  
  Remember to be thorough and consider:
  - Obvious issues and bugs
  - Security implications  
  - Performance considerations
  - Code maintainability and readability
  - Architectural decisions
  - Over-engineering or unnecessary complexity`;
  
          requiredActions = [
            'Read and analyze the specified files or codebase',
            'Understand the overall architecture and design patterns',
            'Identify main components and their responsibilities',
            'Note any immediate concerns or issues',
            'Document initial observations about code quality',
          ];
        } else if (confidence === 'exploring' || confidence === 'low') {
          context = `Continue your code review investigation. You've made initial observations:
  
  ${findings}
  
  Files checked so far: ${filesChecked.join(', ')}
  Issues found: ${issuesFound.length}
  
  Now dive deeper into:
  - Specific code sections that raised concerns
  - ${focus === 'security' ? 'Security vulnerabilities like injection, XSS, authentication flaws' : ''}
  - ${focus === 'performance' ? 'Performance bottlenecks, inefficient algorithms, resource usage' : ''}
  - ${focus === 'architecture' ? 'Architectural issues, coupling, missing abstractions' : ''}
  - Edge cases and error handling
  - Code that could be simplified or refactored`;
  
          requiredActions = [
            'Examine problematic code sections in detail',
            'Verify security best practices are followed',
            'Check for performance optimization opportunities',
            'Analyze error handling and edge cases',
            'Look for code duplication and refactoring opportunities',
          ];
        } else {
          context = `Complete your code review. You've thoroughly analyzed the code:
  
  ${findings}
  
  Files reviewed: ${filesChecked.join(', ')}
  Total issues found: ${issuesFound.length}
  
  Now finalize your review by:
  - Summarizing all findings by severity
  - Providing specific recommendations for each issue
  - Highlighting any positive aspects of the code
  - Suggesting priority order for fixes`;
  
          requiredActions = [
            'Verify all identified issues are documented',
            'Ensure recommendations are actionable and specific',
            'Double-check no critical issues were missed',
            'Prepare final summary with prioritized fixes',
          ];
        }
  
        const prompt = `${context}\n\nProvide your analysis for step ${stepNumber} of ${totalSteps}.`;
        
        const fullResponse = await provider.generateText({
          prompt,
          model: requestedModel,
          temperature: 0.3,
          systemPrompt: 'Provide detailed, actionable code review feedback.',
          useSearchGrounding: false,
        });
  
  
        // TODO: Implement tracking
        // await trackUsage({
        //   tool: 'ultra-review',
        //   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('Code review failed:', error);
        throw error;
      }
    }

• src/handlers/advanced-tools.ts:48-70 (schema)

  Zod input schema for 'ultra-review' tool, defining parameters like task, focus areas, provider, and multi-step workflow state (stepNumber, findings, confidence, etc.).

  export const CodeReviewSchema = z.object({
    task: z.string().describe('What to review in the code'),
    files: z.array(z.string()).optional().describe('File paths to review (optional)'),
    focus: z.enum(['bugs', 'security', 'performance', 'style', 'architecture', 'all']).default('all')
      .describe('Review focus area'),
    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 review workflow'),
    totalSteps: z.number().min(1).default(3).describe('Estimated total steps needed'),
    findings: z.string().default('').describe('Accumulated findings from the review'),
    nextStepRequired: z.boolean().default(true).describe('Whether another step is needed'),
    confidence: z.enum(['exploring', 'low', 'medium', 'high', 'very_high', 'almost_certain', 'certain'])
      .optional().describe('Confidence level in findings'),
    filesChecked: z.array(z.string()).default([]).describe('Files examined during review'),
    issuesFound: z.array(z.object({
      severity: z.enum(['critical', 'high', 'medium', 'low']),
      description: z.string(),
      location: z.string().optional(),
    })).default([]).describe('Issues identified during review'),
  });

• src/handlers/advanced-tools.ts:759-776 (handler)

  AdvancedToolsHandler.handle() method dispatches 'ultra-review' method calls to the specific handleCodeReview implementation.

  async handle(request: { method: string; params: { arguments: unknown } }): Promise<CallToolResult> {
    const { method, params } = request;
  
    switch (method) {
      case 'ultra-review':
        return await this.handleCodeReview(params.arguments);
      case 'ultra-analyze':
        return await this.handleCodeAnalysis(params.arguments);
      case 'ultra-debug':
        return await this.handleDebug(params.arguments);
      case 'ultra-plan':
        return await this.handlePlan(params.arguments);
      case 'ultra-docs':
        return await this.handleDocs(params.arguments);
      default:
        throw new Error(`Unknown method: ${method}`);
    }
  }