Ultra MCP

Instructions

Implementation Reference

• src/handlers/advanced-tools.ts:293-386 (handler)

  Core implementation of the ultra-analyze tool: performs step-by-step code analysis using configured AI providers, workflow management, and formatted responses.

    async handleCodeAnalysis(args: unknown): Promise<HandlerResponse> {
      const params = CodeAnalysisSchema.parse(args);
      const { provider: requestedProvider, model: requestedModel, stepNumber, totalSteps, nextStepRequired, confidence, findings, files, focus, task } = 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 performing a comprehensive code analysis focused on ${focus}.
          
  Task: ${task}
  ${files ? `Files to analyze: ${files.join(', ')}` : 'Analyze the relevant parts of the codebase'}
  
  Begin your analysis by understanding:
  1. The overall architecture and design patterns
  2. ${focus === 'performance' ? 'Performance characteristics and bottlenecks' : ''}
  3. ${focus === 'security' ? 'Security posture and potential vulnerabilities' : ''}
  4. ${focus === 'architecture' ? 'Architectural decisions and their implications' : ''}
  5. ${focus === 'quality' ? 'Code quality, maintainability, and technical debt' : ''}
  6. ${focus === 'scalability' ? 'Scalability considerations and limitations' : ''}`;
  
          requiredActions = [
            'Map out the codebase structure and architecture',
            'Identify key components and their relationships',
            'Understand data flow and dependencies',
            'Note design patterns and architectural decisions',
            'Document initial observations',
          ];
        } else {
          context = `Continue your analysis based on previous findings:
  
  ${findings}
  
  Deepen your investigation into:
  - Specific areas of concern identified
  - Hidden complexities or technical debt
  - Opportunities for improvement
  - Best practices and patterns that could be applied`;
  
          requiredActions = [
            'Investigate specific concerns in detail',
            'Analyze impact of identified issues',
            'Research best practices for similar systems',
            'Evaluate alternative approaches',
            'Document detailed findings with evidence',
          ];
        }
  
        const prompt = `${context}\n\nProvide your analysis for step ${stepNumber} of ${totalSteps}.`;
        
        const fullResponse = await provider.generateText({
          prompt,
          model: requestedModel,
          temperature: 0.4,
          useSearchGrounding: false,
        });
  
        // TODO: Implement tracking
        // await trackUsage({
        //   tool: 'ultra-analyze',
        //   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 analysis failed:', error);
        throw error;
      }
    }

• src/handlers/advanced-tools.ts:73-89 (schema)

  Zod schema defining input parameters for the ultra-analyze tool, including task, focus areas, workflow steps, and AI provider configuration.

  export const CodeAnalysisSchema = z.object({
    task: z.string().describe('What to analyze in the code'),
    files: z.array(z.string()).optional().describe('File paths to analyze (optional)'),
    focus: z.enum(['architecture', 'performance', 'security', 'quality', 'scalability', 'all']).default('all')
      .describe('Analysis 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 analysis workflow'),
    totalSteps: z.number().min(1).default(3).describe('Estimated total steps needed'),
    findings: z.string().default('').describe('Accumulated findings from the analysis'),
    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'),
  });

• src/server.ts:405-413 (registration)

  MCP server registration of the ultra-analyze tool, linking schema and handler implementation.

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

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

  Dispatch handler that routes 'ultra-analyze' calls to the specific handleCodeAnalysis method.

  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}`);
    }
  }

• src/server.ts:832-850 (registration)

  MCP prompt registration for ultra-analyze, providing a natural language interface.

  server.registerPrompt("ultra-analyze", {
    title: "Ultra Code Analysis",
    description: "Deep step-by-step code analysis with architectural insights",
    argsSchema: {
      task: z.string(),
      files: z.string().optional(),
      focus: z.string().optional(),
      stepNumber: z.string(),
      totalSteps: z.string(),
    },
  }, (args) => ({
    messages: [{
      role: "user",
      content: {
        type: "text",
        text: `Perform deep code analysis: ${args.task}${args.files ? `\n\nFiles to analyze: ${args.files}` : ''}${args.focus ? ` (focus: ${args.focus})` : ''} (Step ${args.stepNumber} of ${args.totalSteps})`
      }
    }]
  }));