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