Ultra MCP

Instructions

Implementation Reference

• src/handlers/advanced-tools.ts:515-651 (handler)

  Main handler function for the 'ultra-plan' tool. Implements multi-step planning workflow with support for revisions and branching, using AI providers to generate structured plans.
  async handlePlan(args: unknown): Promise<HandlerResponse> { const params = PlanSchema.parse(args); const { provider: requestedProvider, model: requestedModel, stepNumber, totalSteps, nextStepRequired, task, requirements, scope, currentStep, isRevision, revisingStep, isBranching, branchingFrom, branchId } = 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 creating a ${scope} implementation plan. Task: ${task} ${requirements ? `Requirements: ${requirements}` : ''} Create a structured plan by: 1. Understanding the full scope of the task 2. Breaking it down into logical phases 3. Identifying dependencies and prerequisites 4. Considering potential challenges 5. Defining success criteria`; requiredActions = [ 'Analyze the task requirements thoroughly', 'Identify all stakeholders and dependencies', 'Break down into major phases or milestones', 'Consider technical and resource constraints', 'Define clear success metrics', ]; } else if (isRevision && revisingStep) { context = `You are revising step ${revisingStep} of your plan based on new insights. Previous step content: ${currentStep} Revise this step considering: - New information discovered - Better approaches identified - Feedback or constraints - Improved clarity or detail`; requiredActions = [ 'Review the original step content', 'Identify what needs revision and why', 'Incorporate new insights or corrections', 'Ensure consistency with other steps', 'Update dependencies if needed', ]; } else if (isBranching && branchingFrom) { context = `You are exploring an alternative approach branching from step ${branchingFrom}. Branch: ${branchId || 'Alternative Approach'} Explore a different path by: - Taking a fundamentally different approach - Using alternative technologies or methods - Addressing the same goal differently`; requiredActions = [ 'Define the alternative approach clearly', 'Explain why this branch is worth exploring', 'Outline the different steps in this path', 'Compare trade-offs with the main approach', 'Identify unique benefits or risks', ]; } else { const stepContext = stepNumber <= 3 && totalSteps >= 5 ? '\n\nIMPORTANT: This is an early planning stage. Take time to think deeply about strategic decisions, architectural choices, and long-term implications before moving to tactical details.' : ''; context = `Continue planning step ${stepNumber} of ${totalSteps}. Previous planning: ${currentStep} Develop the next aspect of your plan: - Build on previous steps - Add more detail and specificity - Address dependencies and risks - Include concrete actions${stepContext}`; requiredActions = [ 'Review previous planning steps', 'Identify the next logical planning element', 'Add specific implementation details', 'Consider risks and mitigation strategies', 'Ensure alignment with overall objectives', ]; } const prompt = `${context}\n\nProvide your planning for step ${stepNumber} of ${totalSteps}.`; const fullResponse = await provider.generateText({ prompt, model: requestedModel, temperature: 0.6, systemPrompt: scope === 'comprehensive' ? 'Provide detailed, thorough planning with multiple alternatives considered.' : scope === 'minimal' ? 'Keep planning concise and focused on essential elements only.' : 'Balance detail with clarity in your planning.', useSearchGrounding: false, }); // TODO: Implement tracking // await trackUsage({ // tool: 'ultra-plan', // 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, fullResponse.text, requiredActions ); return { content: [{ type: 'text', text: formattedResponse }], }; } catch (error) { logger.error('Planning failed:', error); throw error; } }
• src/handlers/advanced-tools.ts:111-132 (schema)

  Zod schema defining input parameters for the ultra-plan tool, including task, scope, workflow steps, and branching/revision fields.
  export const PlanSchema = z.object({ task: z.string().describe('What to plan (e.g., "add user profiles", "implement payment system")'), requirements: z.string().optional().describe('Specific requirements or constraints'), scope: z.enum(['minimal', 'standard', 'comprehensive']).default('standard') .describe('Planning scope and depth'), 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 planning workflow'), totalSteps: z.number().min(1).default(5).describe('Estimated total steps needed'), currentStep: z.string().default('').describe('Current planning step content'), nextStepRequired: z.boolean().default(true).describe('Whether another step is needed'), // Planning-specific fields isRevision: z.boolean().default(false).describe('True if this step revises a previous step'), revisingStep: z.number().optional().describe('Which step number is being revised'), isBranching: z.boolean().default(false).describe('True if exploring alternative approach'), branchingFrom: z.number().optional().describe('Which step to branch from'), branchId: z.string().optional().describe('Identifier for this planning branch'), });
• src/server.ts:425-433 (registration)

  Registers the 'ultra-plan' tool with the MCP server, linking to the AdvancedToolsHandler.handlePlan method and using PlanSchema for input validation.
  server.registerTool("ultra-plan", { title: "Ultra Plan", description: "Multi-step feature planning with revisions and branches", inputSchema: PlanSchema.shape, }, async (args) => { const { AdvancedToolsHandler } = await import("./handlers/advanced-tools"); const handler = new AdvancedToolsHandler(); return await handler.handlePlan(args); });
• src/handlers/advanced-tools.ts:769-770 (handler)

  Switch case in AdvancedToolsHandler.handle() method that routes 'ultra-plan' calls to the handlePlan implementation.
  case 'ultra-plan': return await this.handlePlan(params.arguments);
• src/server.ts:872-890 (registration)

  Registers the prompt version of 'ultra-plan' for MCP compatibility.
  server.registerPrompt("ultra-plan", { title: "Ultra Feature Planning", description: "Advanced multi-step feature planning with revisions and branches", argsSchema: { task: z.string(), requirements: z.string().optional(), scope: z.string().optional(), stepNumber: z.string(), totalSteps: z.string(), }, }, (args) => ({ messages: [{ role: "user", content: { type: "text", text: `Plan this feature comprehensively: ${args.task}${args.requirements ? `\n\nRequirements: ${args.requirements}` : ''}${args.scope ? ` (scope: ${args.scope})` : ''} (Step ${args.stepNumber} of ${args.totalSteps})` } }] }));