Design Decisions

Key architectural and design decisions made in documcp MCP server.

MCP vs Traditional CLI Architecture

Why Model Context Protocol?

We chose MCP over traditional CLI tools for:

AI-Native Integration: Seamless interaction with AI assistants like Claude Desktop
Natural Language Interface: Users describe intent rather than memorizing commands
Intelligent Orchestration: AI handles complex workflow coordination automatically
Context Preservation: Analysis results flow naturally between tool calls
Future-Proof Design: Built for the emerging AI-assisted development ecosystem

Traditional CLI Limitations

Traditional documentation tools require manual orchestration:

# Manual workflow coordination required
./analyze --path ./project > analysis.json
./recommend --input analysis.json > recommendation.json  
./configure --ssg docusaurus --name "MyProject"
./deploy --config docs/docusaurus.config.js

Problems:

Users must understand tool sequence and dependencies
Manual parameter passing between tools
No intelligent error recovery
Steep learning curve for complex workflows

MCP Advantages

With MCP, AI assistants handle orchestration:

// Natural language intent → AI orchestrates tools
"Analyze my repository and set up complete documentation with deployment"
// AI automatically: analyze → recommend → configure → deploy

Benefits:

Zero workflow orchestration burden on users
Intelligent parameter flow between tools
Natural language interface
AI-powered error recovery and guidance

Static Site Generator Selection Logic

Multi-Criteria Decision Framework

Our SSG recommendation engine evaluates:

Project Characteristics (40% weight)

Language Ecosystem: Match SSG to primary project language
Project Size: Small projects favor simplicity, large projects need performance
Complexity: Simple sites use Jekyll, complex docs use Docusaurus
Existing Infrastructure: Leverage current tooling and knowledge

Team Capabilities (30% weight)

Technical Skills: Match SSG complexity to team expertise
Maintenance Capacity: Consider long-term maintenance requirements
Learning Appetite: Balance new technology adoption with productivity

Performance Requirements (20% weight)

Build Speed: Hugo for large sites requiring fast builds
Site Performance: Static generation vs client-side rendering trade-offs
Scalability: Consider future growth and content volume

Integration Needs (10% weight)

GitHub Pages Compatibility: Native Jekyll support vs GitHub Actions
Existing Tooling: CI/CD pipeline integration requirements
Deployment Complexity: Balance features with deployment simplicity

SSG Decision Matrix

SSG	Best For	Strengths	Trade-offs
Jekyll	Simple sites, GitHub-native	Zero-config GitHub Pages, Ruby ecosystem	Limited theming, slower builds
Hugo	Large sites, performance-critical	Extremely fast builds, powerful templating	Go templates learning curve
Docusaurus	Technical docs, interactive content	React ecosystem, rich features	Complex setup, heavier builds
MkDocs	API docs, Python projects	Clean themes, simple configuration	Limited customization
Eleventy	Custom designs, JAMstack	Template flexibility, JavaScript ecosystem	More configuration required

Tool Design Philosophy

Stateless Tool Architecture

Each MCP tool is independent and idempotent:

Benefit: Consistent behavior across different AI clients
Trade-off: Parameters must be passed between tools
Rationale: Aligns with MCP protocol principles and enables reliable AI orchestration

Progressive Complexity

Tools support simple to advanced use cases:

Basic Mode: Minimal parameters, intelligent defaults
Advanced Mode: Full customization and control
Expert Mode: Raw configuration access and overrides

Example:

// Simple: analyzeRepository({ repositoryPath: "./project" })
// Advanced: analyzeRepository({ 
//   repositoryPath: "./project",
//   analysisDepth: "deep",
//   focusAreas: ["security", "performance"]
// })

Comprehensive Validation

All tool inputs use Zod schemas for validation:

Runtime Safety: Catch invalid parameters before processing
Clear Error Messages: Actionable guidance for parameter fixes
Type Safety: Compile-time and runtime type checking
Schema Documentation: Automatic JSON schema generation for MCP clients

Content Intelligence Decisions

Diataxis Framework Adoption

We chose the Diataxis framework for documentation structure:

Proven Methodology: Battle-tested approach to technical documentation
User-Centered Design: Addresses different user needs and contexts
Scalable Structure: Works for projects of all sizes
Industry Standard: Widely adopted by successful documentation projects

Intelligent Content Population

Rather than empty templates, we generate contextual content:

Technology-Specific Examples: Code samples match detected languages
Project-Aware Guidance: Instructions tailored to actual project structure
Progressive Enhancement: Basic structure with intelligent placeholders
Maintenance Guidance: Ongoing documentation improvement recommendations

Performance and Scalability Decisions

Memory-Efficient Analysis

For large repository handling:

Streaming Processing: Avoid loading entire files into memory
Chunked Analysis: Process repositories in manageable segments
Intelligent Sampling: Focus analysis on representative files
Garbage Collection: Explicit cleanup of temporary objects

Caching Strategy

Multi-level caching for performance:

Analysis Results: Cache repository analysis for repeated operations
Template Generation: Reuse generated configurations for similar projects
Recommendation Logic: Cache decision matrices for common scenarios
File System Operations: Minimize redundant disk I/O

Security and Quality Decisions

Type Safety First

Comprehensive TypeScript usage:

Strict Mode: Maximum type checking enabled
No Any Types: Explicit typing throughout codebase
Runtime Validation: Zod schemas for all external inputs
Compile-Time Guarantees: Catch errors before deployment

Minimal Dependencies

Focused dependency management:

Core Dependencies: Only essential MCP, validation, and TypeScript tools
Trusted Sources: Well-maintained packages with active communities
Regular Updates: Automated dependency vulnerability scanning
Supply Chain Security: Lock file usage and audit processes

Future Architecture Considerations

Plugin System Evolution

Planned extensibility improvements:

Dynamic Tool Loading: Runtime tool registration and discovery
Custom SSG Support: User-defined static site generator integration
Workflow Extensions: Custom multi-tool orchestration patterns
Community Contributions: Open ecosystem for tool development

AI Integration Enhancement

Leveraging advancing AI capabilities:

Content Generation: AI-powered documentation writing assistance
Quality Analysis: Automated content review and improvement suggestions
Predictive Workflows: Anticipating user needs based on project patterns
Intelligent Debugging: AI-assisted troubleshooting and error resolution

MCP vs Traditional CLI Architecture​

Why Model Context Protocol?​

Traditional CLI Limitations​

MCP Advantages​

Static Site Generator Selection Logic​

Multi-Criteria Decision Framework​

Project Characteristics (40% weight)​

Team Capabilities (30% weight)​

Performance Requirements (20% weight)​

Integration Needs (10% weight)​

SSG Decision Matrix​

Tool Design Philosophy​

Stateless Tool Architecture​

Progressive Complexity​

Comprehensive Validation​

Content Intelligence Decisions​

Diataxis Framework Adoption​

Intelligent Content Population​

Performance and Scalability Decisions​

Memory-Efficient Analysis​

Caching Strategy​

Security and Quality Decisions​

Type Safety First​

Minimal Dependencies​

Future Architecture Considerations​

Plugin System Evolution​

AI Integration Enhancement​