Ultra MCP

Instructions

Implementation Reference

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

  Registration of the ultra-review tool, specifying metadata and delegating to AdvancedToolsHandler.handleCodeReview
  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:47-70 (schema)

  Zod input schema for the ultra-review tool defining parameters like task, files, focus areas, provider/model selection, and multi-step workflow state (stepNumber, findings, confidence, etc.)
  // Code Review Tool Schema 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:164-291 (handler)

  Primary handler function for ultra-review: parses input, selects AI provider, constructs dynamic prompts based on workflow step and confidence, invokes AI generation, and returns formatted multi-step response using formatWorkflowResponse
  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:24-44 (helper)

  Helper utility that formats the AI response into a structured multi-step workflow output with progress indicators, action lists, and continuation instructions
  function formatWorkflowResponse( stepNumber: number, totalSteps: number, nextStepRequired: boolean, content: string, requiredActions?: string[] ): string { const header = `## Step ${stepNumber} of ${totalSteps}`; const status = nextStepRequired ? `\n**Status**: Investigation in progress - more analysis needed` : `\n**Status**: Investigation complete - ready for final analysis`; const actions = requiredActions && requiredActions.length > 0 ? `\n\n### Required Actions Before Next Step:\n${requiredActions.map(a => `- ${a}`).join('\n')}` : ''; const nextStep = nextStepRequired ? `\n\n**Next Step**: Call this tool again with step_number=${stepNumber + 1} after completing the required actions.` : ''; return `${header}${status}\n\n${content}${actions}${nextStep}`;
• src/handlers/advanced-tools.ts:759-776 (handler)

  Dispatch handler method in AdvancedToolsHandler class that routes 'ultra-review' calls to the specific handleCodeReview implementation based on the method string
  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}`); } }