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