Ultra MCP

Instructions

Implementation Reference

• src/handlers/advanced-tools.ts:653-757 (handler)

  Main execution logic for the 'ultra-docs' tool. Handles multi-step documentation generation workflow: parses input with DocsSchema, selects AI provider, constructs step-specific prompts based on step number, generates documentation text using the provider, formats the response with workflow metadata, and supports continuation across steps.

    async handleDocs(args: unknown): Promise<HandlerResponse> {
      const params = DocsSchema.parse(args);
      const { provider: requestedProvider, model: requestedModel, stepNumber, totalSteps, nextStepRequired, task, files, format, findings, includeExamples, includeTypes } = 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) {
          const formatInstructions = {
            markdown: 'Use clear Markdown formatting with headers, lists, and code blocks',
            comments: 'Generate inline code comments following language conventions',
            'api-docs': 'Create API documentation with endpoints, parameters, and responses',
            readme: 'Write a comprehensive README with setup, usage, and examples',
            jsdoc: 'Generate JSDoc comments for functions and classes',
          };
          
          context = `You are generating ${format} documentation.
          
  Task: ${task}
  ${files ? `Files to document: ${files.join(', ')}` : ''}
  
  Requirements:
  - ${formatInstructions[format]}
  - ${includeExamples ? 'Include practical code examples' : 'Focus on descriptions without examples'}
  - ${includeTypes ? 'Include type information and signatures' : 'Omit type details'}
  
  Begin by:
  1. Understanding what needs to be documented
  2. Analyzing the code structure and purpose
  3. Planning the documentation structure`;
  
          requiredActions = [
            'Analyze the code or system to document',
            'Understand the target audience',
            'Plan documentation structure and sections',
            'Identify key concepts to explain',
            'Gather examples if needed',
          ];
        } else {
          context = `Complete the documentation based on your analysis:
  
  ${findings}
  
  Finalize by:
  - Ensuring completeness and accuracy
  - Adding examples and use cases
  - Checking formatting and readability
  - Including any necessary warnings or notes`;
  
          requiredActions = [
            'Review documentation for completeness',
            'Add missing sections or details',
            'Ensure examples are working and clear',
            'Check for consistency in style',
            'Add helpful notes and tips',
          ];
        }
  
        const prompt = `${context}\n\nGenerate documentation for step ${stepNumber} of ${totalSteps}.`;
        
        const fullResponse = await provider.generateText({
          prompt,
          model: requestedModel,
          temperature: 0.3,
          systemPrompt: `Generate high-quality ${format} documentation that is clear, accurate, and helpful.`,
          useSearchGrounding: false,
        });
  
        // TODO: Implement tracking
        // await trackUsage({
        //   tool: 'ultra-docs',
        //   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('Documentation generation failed:', error);
        throw error;
      }
    }

• src/handlers/advanced-tools.ts:134-154 (schema)

  Zod validation schema for 'ultra-docs' tool inputs, defining parameters like task, files, format (markdown/comments/etc.), provider/model, workflow steps (stepNumber, totalSteps, findings), and doc-specific options (includeExamples, includeTypes).

  // Documentation Tool Schema
  export const DocsSchema = z.object({
    task: z.string().describe('What to document (e.g., "API endpoints", "setup instructions")'),
    files: z.array(z.string()).optional().describe('File paths to document (optional)'),
    format: z.enum(['markdown', 'comments', 'api-docs', 'readme', 'jsdoc']).default('markdown')
      .describe('Documentation format'),
    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 documentation workflow'),
    totalSteps: z.number().min(1).default(2).describe('Estimated total steps needed'),
    findings: z.string().default('').describe('Accumulated documentation content'),
    nextStepRequired: z.boolean().default(true).describe('Whether another step is needed'),
    
    // Doc-specific fields
    includeExamples: z.boolean().default(true).describe('Include code examples in documentation'),
    includeTypes: z.boolean().default(true).describe('Include type information for TypeScript/Flow'),
  });

• src/server.ts:435-443 (registration)

  Registers the 'ultra-docs' MCP tool on the server, providing metadata (title, description), input schema from DocsSchema, and execution handler that dynamically imports and instantiates AdvancedToolsHandler to call handleDocs.

  server.registerTool("ultra-docs", {
    title: "Ultra Docs",
    description: "Generate comprehensive documentation with step-by-step workflow",
    inputSchema: DocsSchema.shape,
  }, async (args) => {
    const { AdvancedToolsHandler } = await import("./handlers/advanced-tools");
    const handler = new AdvancedToolsHandler();
    return await handler.handleDocs(args);
  });

• src/handlers/advanced-tools.ts:24-45 (helper)

  Utility function used by all advanced tools (including ultra-docs) to format multi-step workflow responses with step headers, status, required actions list, and instructions for next step.

  function formatWorkflowResponse(
    stepNumber: number,
    totalSteps: number,
    nextStepRequired: boolean,
    content: string,
    requiredActions?: string[]
  ): string {
    const header = `## Step ${stepNumber} of ${totalSteps}`;
    const status = nextStepRequired 
      ? `\n**Status**: Investigation in progress - more analysis needed`
      : `\n**Status**: Investigation complete - ready for final analysis`;
    
    const actions = requiredActions && requiredActions.length > 0
      ? `\n\n### Required Actions Before Next Step:\n${requiredActions.map(a => `- ${a}`).join('\n')}`
      : '';
    
    const nextStep = nextStepRequired
      ? `\n\n**Next Step**: Call this tool again with step_number=${stepNumber + 1} after completing the required actions.`
      : '';
    
    return `${header}${status}\n\n${content}${actions}${nextStep}`;
  }