Ultra MCP

Instructions

Implementation Reference

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

  The core handler function `handleDebug` that implements the ultra-debug tool. It parses input with DebugSchema, builds step-specific debugging prompts based on workflow state, calls the configured AI provider to generate analysis, formats the multi-step response, and handles errors.
  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 input schema for the ultra-debug tool, defining parameters like issue, symptoms, files, provider, and multi-step workflow state (stepNumber, findings, confidence, etc.).
  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)

  MCP server registration of the 'ultra-debug' tool, including title, description, DebugSchema input validation, and handler instantiation that delegates to AdvancedToolsHandler.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/handlers/advanced-tools.ts:759-776 (handler)

  The dispatch handler method in AdvancedToolsHandler class that routes 'ultra-debug' calls to the specific handleDebug implementation via switch-case.
  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:852-870 (registration)

  Optional MCP prompt registration for 'ultra-debug' that provides a default message template for conversational invocation.
  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})` } }] }));