Documentation Generator MCP Server

{ "feature_name": "Universal Quickref Generator", "version": "proposed", "category": "documentation_generation", "type": "workflow", "overview": { "description": "AI-assisted workflow to generate scannable quickref guides for ANY application (web apps, CLI tools, APIs, desktop software, libraries)", "problem": "Traditional documentation is verbose and hard to scan. Users need action-oriented, minimal reference guides that show WHAT, HOW, and WHERE in <200 lines", "solution": "Natural language workflow that interviews user about their app and generates structured quickref.md following proven pattern from docs-mcp", "benefits": [ "10x faster to scan than traditional docs", "Action-oriented (commands → workflows → outputs)", "Universal pattern works for any software type", "Generated in minutes vs hours of manual writing", "Consistent format across all applications" ] }, "slash_command": { "command": "/generate-quickref", "aliases": ["/quickref", "/qr"], "usage": "User types: /generate-quickref", "behavior": "AI interviews user to gather app info, then generates quickref.md" }, "workflow": { "description": "Interactive AI-driven workflow using natural language", "steps": [ { "step": 1, "name": "Initiate", "user_action": "Type: /generate-quickref", "ai_response": "Start interview: 'I'll help you create a quickref guide. What application are we documenting?'" }, { "step": 2, "name": "Gather Basic Info", "ai_questions": [ "What is the app name?", "Brief description (one sentence)?", "What type of software is it? (CLI/Web App/API/Desktop/Library)" ], "user_provides": "Answers in natural language" }, { "step": 3, "name": "Identify Core Capabilities", "ai_questions": [ "What are the 4-5 main things this app does?", "What problems does it solve?" ], "example_user_response": "1. Generates documentation, 2. Manages changelogs, 3. Audits code consistency, 4. Validates plans" }, { "step": 4, "name": "List Actions/Commands", "ai_questions": [ "What actions/commands are available?", "For each: What does it do? How long does it take?" ], "format_expected": "Table format with action, purpose, speed/time" }, { "step": 5, "name": "Define Features/Tools", "ai_questions": [ "What are the main features/tools?", "How should they be grouped? (by category)" ], "user_provides": "Categories and tools within each" }, { "step": 6, "name": "Common Workflows", "ai_questions": [ "What are 3-5 common use cases?", "Walk me through the steps for each" ], "format_expected": "Numbered step-by-step sequences" }, { "step": 7, "name": "Outputs/Results", "ai_questions": [ "Where do outputs go? (files, directories, screens)", "What gets created/modified?" ], "format_expected": "Table of output types and locations" }, { "step": 8, "name": "Key Concepts", "ai_questions": [ "Are there 2-4 important patterns/concepts users should know?", "Any unique workflows or design patterns?" ], "optional": true }, { "step": 9, "name": "Generate & Save", "ai_action": "Generate quickref.md following universal pattern", "output_location": "{project_path}/coderef/quickref.md", "confirmation": "Show preview and ask: 'Review this quickref. Any changes needed?'" } ] }, "universal_pattern": { "description": "The proven structure that works for any application", "sections": [ { "section": "At a Glance", "content": "4-5 core capabilities with icons/emojis", "format": "Bullet list" }, { "section": "Actions/Commands", "content": "What user can DO", "format": "Table: action | purpose | time/speed", "variations": { "cli": "Commands table", "web_app": "Pages/features table", "api": "Endpoints table", "desktop": "Menu items/shortcuts table" } }, { "section": "Features/Tools", "content": "Available functionality grouped by category", "format": "Category headers with tables" }, { "section": "Common Workflows", "content": "Step-by-step numbered sequences for common tasks", "format": "Numbered lists in code blocks" }, { "section": "Reference Format", "content": "Copy-paste examples", "format": "Code blocks with actual usage" }, { "section": "Output Locations", "content": "Where results/files are stored", "format": "Table: type | location | files" }, { "section": "Key Concepts", "content": "Important patterns/workflows (2-4)", "format": "Bold headers with brief explanations" }, { "section": "Summary", "content": "Total counts and links to detailed docs", "format": "Table or bullet list" } ], "target_length": "150-250 lines", "design_principles": [ "Scannable: Tables over paragraphs", "Hierarchical: Category → Feature → Details", "Actionable: Every line = something user can do", "Minimal: Remove all fluff, keep only essentials", "Performance: Show speed/time where relevant" ] }, "implementation": { "mcp_tool": { "name": "generate_quickref_interactive", "type": "meta-tool", "description": "Returns interview questions for AI to ask user, not direct generation", "inputs": { "project_path": "Where to save quickref.md", "app_type": "CLI/Web/API/Desktop/Library (optional, can be inferred)" }, "outputs": { "interview_script": "JSON with questions AI should ask", "template_structure": "Quickref template adapted to app type" }, "workflow_type": "conversational" }, "slash_command_file": { "path": ".claude/commands/generate-quickref.md", "content_outline": [ "Trigger interactive quickref generation workflow", "AI asks questions to gather app information", "User responds in natural language", "AI generates quickref.md following universal pattern", "Saves to coderef/quickref.md" ] }, "generator_module": { "path": "generators/quickref_generator.py", "class": "QuickrefGenerator", "methods": [ "get_interview_questions(app_type)", "parse_user_responses(responses)", "generate_quickref(app_info)", "format_section(section_name, content)", "validate_completeness(quickref)" ] } }, "example_usage": { "scenario": "User wants quickref for their CLI tool", "conversation": [ { "user": "/generate-quickref", "ai": "I'll help you create a quickref guide. What application are we documenting?" }, { "user": "A CLI tool called 'deploy-bot' that automates deployment workflows", "ai": "Great! What type of software is this? (CLI/Web App/API/Desktop/Library)" }, { "user": "CLI tool", "ai": "Perfect. What are the 4-5 main things deploy-bot does?" }, { "user": "1. Builds Docker images, 2. Pushes to registry, 3. Deploys to Kubernetes, 4. Monitors rollout status", "ai": "Excellent. What commands are available? For each, tell me: command name, what it does, approximate time" }, { "user": "deploy build - Builds Docker image (2-5 min), deploy push - Pushes to registry (1-2 min), deploy rollout - Deploys to k8s (30s), deploy status - Shows deployment status (instant)", "ai": "Got it. What are 2-3 common workflows users follow?" }, { "user": "1. Full deployment: build → push → rollout, 2. Quick update: build → rollout, 3. Check status: status command", "ai": "Where do outputs go? Any files created or logs generated?" }, { "user": "Logs go to ~/.deploy-bot/logs/, config in ~/.deploy-bot/config.yaml, deployment manifests in ./k8s/", "ai": "Any important concepts or patterns users should know?" }, { "user": "Yes - rollback workflow if deployment fails, and the multi-environment pattern (dev/staging/prod)", "ai": "Perfect! I'll generate your quickref now... [generates quickref.md] Here's your quickref. Review and let me know if any changes are needed." } ], "generated_output": "quickref.md with all sections filled, ~180 lines, ready to use" }, "variations_by_app_type": { "cli_tool": { "actions_section": "Commands Table", "emphasis": "Command syntax, flags, piping workflows" }, "web_app": { "actions_section": "Pages/Features Table", "emphasis": "Navigation paths, user flows, form inputs" }, "api": { "actions_section": "Endpoints Table", "emphasis": "HTTP methods, auth, response formats, rate limits" }, "desktop_app": { "actions_section": "Menu Items/Shortcuts Table", "emphasis": "Keyboard shortcuts, UI workflows, file operations" }, "library": { "actions_section": "Functions/Classes Table", "emphasis": "Import statements, code examples, parameters" } }, "benefits_analysis": { "time_savings": { "traditional_docs": "4-8 hours to write comprehensive docs", "with_quickref_workflow": "15-30 minutes interview + 2 minutes generation", "reduction": "90-95% time savings" }, "user_experience": { "traditional_docs": "Users search, read paragraphs, piece together info", "quickref": "Users scan table → find action → see example → do it", "improvement": "10x faster time-to-action" }, "maintenance": { "traditional_docs": "Multiple pages need updates, easy to miss sections", "quickref": "Single file, update one table/workflow", "improvement": "Easier to keep current" } }, "future_enhancements": { "auto_detection": "Scan app files to auto-suggest capabilities and commands", "interactive_preview": "Show quickref sections as they're built, allow inline editing", "multi_format": "Generate HTML/PDF versions from same data", "templates_by_domain": "Pre-built templates for common app types (e.g., REST APIs, CLIs)", "versioning": "Track quickref versions as app evolves" }, "related_docs": { "pattern_source": "coderef/quickref.md (docs-mcp's own quickref)", "user_guide_section": "To be added: 'Generating Quickref Guides'", "slash_command_def": ".claude/commands/generate-quickref.md (to be created)" }, "status": "proposed", "priority": "medium", "effort_estimate": "4-6 hours implementation", "dependencies": [ "generators/base_generator.py (existing)", "Natural language interview pattern (similar to update_changelog meta-tool)" ], "success_metrics": { "adoption": "Users generate quickrefs for 50%+ of their projects", "quality": "Generated quickrefs are scannable in <30 seconds", "completeness": "90%+ of quickrefs need zero manual edits", "reusability": "Pattern works for all 5 app types (CLI/Web/API/Desktop/Library)" }, "notes": [ "This workflow generalizes the quickref pattern to ANY software, not just MCP servers", "Uses natural language interview approach (similar to update_changelog meta-tool)", "AI drives conversation, user just answers questions in plain English", "Output follows proven scannable format from docs-mcp's own quickref.md", "Universal applicability = massive value for documentation across entire software ecosystem" ] }