Ultra MCP

Instructions

Implementation Reference

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

  Implementation of the planner tool handler in AIToolHandlers class. Generates structured multi-step planning responses using AI providers, with support for revisions, branching, and deep thinking pauses for complex plans.
  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)

  MCP server registration of the 'planner' tool, specifying title, description, input schema, and handler delegation to aiHandlers.handlePlanner
  // 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 definition for planner tool input validation, used in tool registration.
  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)

  MCP prompt registration for the 'planner' tool, providing a default user message template.
  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)` : ''}` } }] }));
• src/handlers/ai-tools.ts:87-99 (schema)

  Zod schema definition for planner tool input validation, used in the handler 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"), });