Ultra MCP

Instructions

Implementation Reference

• src/handlers/ai-tools.ts:718-874 (handler)

  Core handler function that executes the planner tool logic. Uses AI providers to generate step-by-step planning responses with support for revisions, branching, and deep thinking phases.

    async handlePlanner(params: z.infer<typeof PlannerSchema>) {
      const providerName = params.provider || (await this.providerManager.getPreferredProvider(['openai', 'gemini', 'azure']));
      const provider = await this.providerManager.getProvider(providerName);
      
      // Track planning state for step-by-step guidance
      const isFirstStep = params.stepNumber === 1;
      const isComplexPlan = params.totalSteps >= 5;
      const needsDeepThinking = isComplexPlan && params.stepNumber <= 3;
      
      // Build planning-specific system prompt based on step and complexity
      let systemPrompt = `You are an expert planner and strategic thinker. Your role is to break down complex tasks into manageable, sequential steps while considering dependencies, risks, and alternatives.
  
  CURRENT PLANNING CONTEXT:
  - Step ${params.stepNumber} of ${params.totalSteps} (${params.scope} scope)
  - ${isFirstStep ? "INITIAL PLANNING" : isComplexPlan && params.stepNumber <= 3 ? "STRATEGIC PHASE" : "TACTICAL PHASE"}
  - ${params.isRevision ? `REVISING previous step ${params.revisingStep}` : ""}
  - ${params.isBranching ? `EXPLORING alternative from step ${params.branchingFrom} (${params.branchId})` : ""}
  
  PLANNING GUIDELINES:`;
  
      if (isFirstStep) {
        systemPrompt += `
  STEP 1 - FOUNDATION SETTING:
  - Thoroughly understand the complete scope and complexity
  - Consider multiple high-level approaches and their trade-offs
  - Identify key stakeholders, constraints, and success criteria
  - Think about resource requirements and potential challenges
  - Establish the overall strategy before diving into tactics`;
      } else if (needsDeepThinking) {
        systemPrompt += `
  STRATEGIC PLANNING PHASE (Complex Plan):
  - Build upon previous steps with deeper analysis
  - Consider interdependencies and critical decision points
  - Evaluate risks, assumptions, and validation needs
  - Think through resource allocation and timeline implications
  - Focus on strategic decisions before tactical implementation`;
      } else {
        systemPrompt += `
  TACTICAL PLANNING PHASE:
  - Develop specific, actionable steps
  - Consider implementation details and practical constraints
  - Sequence activities logically with clear dependencies
  - Think about coordination, communication, and progress tracking
  - Prepare for execution with concrete next steps`;
      }
  
      systemPrompt += `
  
  RESPONSE FORMAT:
  Provide a structured planning response that includes:
  1. **Current Step Analysis**: ${isFirstStep ? "Complete scope understanding" : "Step-specific planning focus"}
  2. **Key Considerations**: Important factors, constraints, or dependencies
  3. **Planning Decision**: Specific step content or strategic direction
  4. **Next Steps Guidance**: What should be planned in subsequent steps
  ${needsDeepThinking ? "5. **Deep Thinking Required**: Areas requiring further reflection" : ""}
  
  ${params.requirements ? `\nREQUIREMENTS TO CONSIDER:\n${params.requirements}` : ""}`;
  
      // Build the planning prompt
      let prompt = `Planning Task: ${params.task}`;
      
      if (!isFirstStep) {
        prompt += `\n\nThis is step ${params.stepNumber} in a ${params.totalSteps}-step planning process.`;
        if (params.isRevision) {
          prompt += ` I'm revising step ${params.revisingStep} based on new insights.`;
        }
        if (params.isBranching) {
          prompt += ` I'm exploring an alternative approach (${params.branchId}) branching from step ${params.branchingFrom}.`;
        }
      }
  
      prompt += `\n\nProvide the planning analysis for this step with specific, actionable guidance.`;
  
      try {
        const response = await provider.generateText({
          prompt,
          systemPrompt,
          temperature: 0.6, // Balanced temperature for creative yet structured planning
          reasoningEffort: (providerName === "openai" || providerName === "azure" || providerName === "grok") ? "high" : undefined,
          useSearchGrounding: providerName === "gemini" && params.scope === "comprehensive",
          toolName: 'planner',
        });
  
        // Build structured response
        const planningStep = {
          stepNumber: params.stepNumber,
          totalSteps: params.totalSteps,
          stepContent: response.text,
          scope: params.scope,
          isRevision: params.isRevision || false,
          revisingStep: params.revisingStep,
          isBranching: params.isBranching || false,
          branchingFrom: params.branchingFrom,
          branchId: params.branchId,
          requirements: params.requirements,
        };
  
        // Determine if more steps are needed and provide guidance
        const isLastStep = params.stepNumber >= params.totalSteps;
        const nextStepGuidance = isLastStep 
          ? "Planning complete. Present the final plan with clear implementation guidance."
          : needsDeepThinking 
          ? `MANDATORY PAUSE: This is a complex plan requiring deep thinking. Before step ${params.stepNumber + 1}, reflect on strategic decisions, alternatives, and critical dependencies.`
          : `Continue with step ${params.stepNumber + 1}. Focus on ${params.stepNumber >= params.totalSteps - 2 ? "implementation details and concrete actions" : "detailed planning and dependencies"}.`;
  
        const result = {
          currentStep: planningStep,
          planningComplete: isLastStep,
          nextStepRequired: !isLastStep,
          nextStepNumber: isLastStep ? null : params.stepNumber + 1,
          planningGuidance: nextStepGuidance,
          deepThinkingRequired: needsDeepThinking && !isLastStep,
          plannerStatus: {
            phase: isFirstStep ? "foundation" : needsDeepThinking ? "strategic" : "tactical",
            complexity: isComplexPlan ? "complex" : "standard",
            totalSteps: params.totalSteps,
            currentStep: params.stepNumber,
            remainingSteps: params.totalSteps - params.stepNumber,
          },
        };
  
        return {
          content: [
            {
              type: "text",
              text: JSON.stringify(result, null, 2),
            },
          ],
          metadata: {
            toolName: "planner",
            stepNumber: params.stepNumber,
            totalSteps: params.totalSteps,
            scope: params.scope,
            provider: providerName,
            model: response.model,
            planningPhase: result.plannerStatus.phase,
            usage: response.usage,
            ...response.metadata,
          },
        };
      } catch (error) {
        return {
          content: [
            {
              type: "text",
              text: JSON.stringify({
                error: "Planning step failed",
                message: error instanceof Error ? error.message : "Unknown error",
                stepNumber: params.stepNumber,
                totalSteps: params.totalSteps,
              }, null, 2),
            },
          ],
          isError: true,
        };
      }
    }

• src/server.ts:354-362 (registration)

  Registers the 'planner' tool with the MCP server, specifying title, description, input schema, and handler invocation.

  // Register planner tool
  server.registerTool("planner", {
    title: "Planner",
    description: "Multi-step planning with revisions and branches",
    inputSchema: PlannerSchema.shape,
  }, async (args) => {
    const aiHandlers = await getHandlers();
    return await aiHandlers.handlePlanner(args);
  });

• src/server.ts:83-95 (schema)

  Zod schema defining the input parameters for the planner tool, including task, step numbers, scope, revision/branching flags, and provider selection.

  const PlannerSchema = z.object({
    task: z.string().describe("The task or problem to plan. For the first step, describe the complete planning challenge in detail. For subsequent steps, provide the specific planning step content, revisions, or branch explorations."),
    stepNumber: z.number().min(1).describe("Current step number in the planning sequence (starts at 1)"),
    totalSteps: z.number().min(1).describe("Current estimate of total steps needed (can be adjusted as planning progresses)"),
    scope: z.enum(["minimal", "standard", "comprehensive"]).default("standard").describe("Planning scope and depth"),
    requirements: z.string().optional().describe("Specific requirements, constraints, or success criteria"),
    isRevision: z.boolean().optional().default(false).describe("True if this step revises a previous step"),
    revisingStep: z.number().optional().describe("If isRevision is true, which step number is being revised"),
    isBranching: z.boolean().optional().default(false).describe("True if exploring an alternative approach from a previous step"),
    branchingFrom: z.number().optional().describe("If isBranching is true, which step number to branch from"),
    branchId: z.string().optional().describe("Identifier for this planning branch (e.g., 'approach-A', 'microservices-path')"),
    provider: z.enum(["openai", "gemini", "azure", "grok"]).optional().default("gemini").describe("AI provider to use for planning assistance"),
  });

• src/handlers/ai-tools.ts:87-99 (schema)

  Duplicate Zod schema for planner used internally in the handler function for type inference.

  const PlannerSchema = z.object({
    task: z.string().describe("The task or problem to plan. For the first step, describe the complete planning challenge in detail. For subsequent steps, provide the specific planning step content, revisions, or branch explorations."),
    stepNumber: z.number().min(1).describe("Current step number in the planning sequence (starts at 1)"),
    totalSteps: z.number().min(1).describe("Current estimate of total steps needed (can be adjusted as planning progresses)"),
    scope: z.enum(["minimal", "standard", "comprehensive"]).default("standard").describe("Planning scope and depth"),
    requirements: z.string().optional().describe("Specific requirements, constraints, or success criteria"),
    isRevision: z.boolean().optional().default(false).describe("True if this step revises a previous step"),
    revisingStep: z.number().optional().describe("If isRevision is true, which step number is being revised"),
    isBranching: z.boolean().optional().default(false).describe("True if exploring an alternative approach from a previous step"),
    branchingFrom: z.number().optional().describe("If isBranching is true, which step number to branch from"),
    branchId: z.string().optional().describe("Identifier for this planning branch (e.g., 'approach-A', 'microservices-path')"),
    provider: z.enum(["openai", "gemini", "azure", "grok"]).optional().default("gemini").describe("AI provider to use for planning assistance"),
  });

• src/server.ts:721-746 (registration)

  Registers the prompt template for the planner tool, used for natural language invocation.

  server.registerPrompt("planner", {
    title: "Multi-Step Planning",
    description: "Create detailed multi-step plans with revisions and branching support",
    // String-only schema
    argsSchema: {
      task: z.string(),
      stepNumber: z.string(),
      totalSteps: z.string(),
      scope: z.string().optional(),
      requirements: z.string().optional(),
      isRevision: z.string().optional(),
      revisingStep: z.string().optional(),
      isBranching: z.string().optional(),
      branchingFrom: z.string().optional(),
      branchId: z.string().optional(),
      provider: z.string().optional(),
    },
  }, (args) => ({
    messages: [{
      role: "user",
      content: {
        type: "text",
        text: `Create a detailed plan for: ${args.task} (Step ${args.stepNumber} of ${args.totalSteps})${args.scope ? ` (scope: ${args.scope})` : ''}${args.requirements ? `\n\nRequirements: ${args.requirements}` : ''}${args.isRevision ? `\n\nThis is a revision of step ${args.revisingStep}` : ''}${args.isBranching ? `\n\nThis branches from step ${args.branchingFrom} as ${args.branchId}` : ''}${args.provider ? ` (using ${args.provider} provider)` : ''}`
      }
    }]
  }));