Skip to main content

Architectural Decision Records (ADRs)

This directory contains the Architectural Decision Records for the DocuMCP project - an intelligent MCP server for GitHub Pages documentation deployment.

ADR Index​

ADRTitleStatusDateSummary
001MCP Server Architecture using TypeScript SDKAccepted2025-01-14Core server architecture decision using TypeScript MCP SDK with modular, stateless design
002Multi-Layered Repository Analysis Engine DesignAccepted2025-01-14Comprehensive repository analysis through multiple layers: file system, language ecosystem, content, metadata, and complexity assessment
003Static Site Generator Recommendation Engine DesignAccepted2025-01-14Multi-criteria decision analysis framework for intelligent SSG recommendations with confidence scoring
004Diataxis Framework Integration for Documentation StructureAccepted2025-01-14Integration of Diataxis framework as foundational information architecture for all generated documentation
005GitHub Pages Deployment Automation ArchitectureAccepted2025-01-14Comprehensive deployment orchestration with SSG-specific workflows, security best practices, and performance optimization
006MCP Tools API Design and Interface SpecificationAccepted2025-01-14Six core MCP tools providing comprehensive documentation workflow coverage with robust validation and error handling
007MCP Prompts and Resources Integration for AI AssistanceAccepted2025-01-14Native MCP prompts and resources for guided workflows and content access, leveraging built-in protocol capabilities (Implemented 2025-12-12)
008Intelligent Content Population Engine for Diataxis DocumentationAccepted2025-01-23Project-aware content generation engine that transforms repository analysis into contextually relevant Diataxis documentation (Fully Implemented, Verified 2026-01-16)
009Content Accuracy and Validation Framework for Generated DocumentationAccepted (Phase 2.5 superseded by ADR-014)2025-01-14Comprehensive accuracy assurance system with confidence scoring, reality-check validation, and interactive correction workflows. Phase 2.5 (LLM-enhanced semantic analysis) superseded by ADR-014 in favor of MCP Sampling.
010MCP Resource Pattern RedesignAccepted2025-01-14Redesigned resource patterns for improved efficiency and context management
011CE-MCP CompatibilityAccepted2025-01-14Compatibility with CE-MCP directive for improved token efficiency
012Priority Scoring System for Documentation Drift DetectionAccepted2025-01-14Multi-factor priority scoring system for documentation drift that considers complexity, usage, change magnitude, coverage, staleness, and feedback
013Release Pipeline and Package Distribution ArchitectureAccepted2025-01-14Automated release pipeline with npm publishing, conventional commits, automated changelog generation, and quality gates (Implemented)
014Removal of Server-Side LLM Dependency in Favor of MCP SamplingAccepted2026-04-30Removes the bundled LLM client and DOCUMCPLLM* env vars; defers semantic features to MCP Sampling. Supersedes Phase 2.5 of ADR-009. Tracks #106-#110 in milestone v0.6.0.
015Multi-Language AST Analysis via Tree-sitter Parser RegistryAccepted2026-04-30Lazy-loaded tree-sitter parser registry covering Python, Go, Rust, Java, Ruby, Bash, and YAML. Extends ADR-002. Tracks #112 in milestone v0.7.0.
016SSG Adapter Plugin Pattern for Recommendation, Configuration, and DeploymentAccepted2026-04-30Pluggable SSGAdapter interface replacing hard-coded enums in recommend-ssg, generate-config, and deploy-pages. Extends ADR-003. Tracks #122, #123 in milestone v1.0.0.
017Standalone CLI Surface for Non-MCP WorkflowsAccepted2026-04-30Adds documcp-cli binary mirroring tool names; thin transport over the existing handlers. Tracks #126 in milestone v1.0.0.
018Deploy Target Adapter Pattern for GitHub Pages, Vercel, Netlify, and Cloudflare PagesAccepted (revisits ADR-005 alternatives)2026-04-30Pluggable DeployTargetAdapter interface symmetric to ADR-016; medium depth (config + opt-in CLI). Vercel ships first; Netlify and Cloudflare Pages are help-wanted. Tracks D1-D4 in milestone v1.0.0.

ADR Process​

This project follows the Architectural Decision Record (ADR) process as defined by Michael Nygard. Each ADR documents a significant architectural decision made during the project's development.

ADR Template​

Each ADR follows a consistent structure:

  • Status: Proposed, Accepted, Deprecated, or Superseded
  • Context: The situation and requirements that led to the decision
  • Decision: The actual architectural decision made
  • Alternatives Considered: Other options that were evaluated
  • Consequences: Positive and negative outcomes of the decision
  • Implementation Details: Technical specifics and code examples where relevant

Decision Categories​

Our ADRs are organized into the following categories:

Foundation Architecture (ADRs 001-002)​

  • Core server architecture and technology choices
  • Repository analysis engine design

Intelligence & Recommendation (ADRs 003)​

  • Static site generator recommendation algorithms
  • Decision-making frameworks

Content & Structure (ADRs 004, 008, 009)​

  • Documentation framework integration
  • Information architecture decisions
  • Intelligent content population and generation
  • Content accuracy and validation frameworks

Deployment & Integration (ADRs 005-006)​

  • GitHub Pages deployment automation
  • MCP tools API design

AI & Assistance (ADR 007)​

  • MCP prompts and resources for guided workflows

Key Architectural Principles​

Based on our ADRs, DocuMCP follows these core architectural principles:

1. Methodological Pragmatism​

  • Evidence-based decision making with explicit confidence scoring
  • Systematic verification processes for all recommendations
  • Clear acknowledgment of limitations and uncertainty

2. Standards Compliance​

  • Full adherence to MCP specification requirements
  • Industry best practices for static site generation
  • Proven frameworks like Diataxis for information architecture

3. Modular Design​

  • Clear separation of concerns between analysis, recommendation, generation, and deployment
  • Extensible architecture supporting future enhancements
  • Stateless operation for consistency and reliability

4. Intelligent Automation​

  • Deep repository analysis for informed decision making
  • Context-aware configuration generation
  • Performance-optimized deployment workflows

5. Developer Experience​

  • Intuitive MCP tools API with comprehensive validation
  • Clear error messages and troubleshooting guidance
  • Progressive complexity from simple to advanced use cases

Decision Timeline​

The ADRs were developed during the planning phase of DocuMCP, establishing the architectural foundation before implementation. The decisions build upon each other:

  1. Foundation (ADR-001): Established TypeScript/MCP SDK as the core platform
  2. Analysis (ADR-002): Defined multi-layered repository analysis approach
  3. Intelligence (ADR-003): Specified recommendation engine architecture
  4. Structure (ADR-004): Integrated Diataxis framework for quality documentation
  5. Deployment (ADR-005): Designed automated GitHub Pages deployment system
  6. Interface (ADR-006): Specified comprehensive MCP tools API

Confidence and Validation​

Each ADR includes confidence assessments and validation strategies:

  • High Confidence Decisions: Technology choices with strong ecosystem support (TypeScript/MCP SDK)
  • Medium Confidence Decisions: Framework integrations with proven track records (Diataxis)
  • Validated Assumptions: Architectural patterns tested through prototype development
  • Risk Mitigation: Explicit identification and mitigation strategies for each decision

Future Considerations​

Our ADRs acknowledge areas for future evolution:

  • Machine Learning Integration: Potential for AI-powered content analysis and recommendations
  • Performance Optimization: WebAssembly modules for intensive analysis operations
  • Extended SSG Support: Community-contributed static site generator profiles
  • Advanced Deployment: Multi-environment and blue-green deployment capabilities

References​

Last Updated: April 30, 2026
Total ADRs: 18
Status: ADRs 001-013 Accepted and Implemented; ADRs 014-018 Accepted and pending implementation (tracked under milestones v0.6.0 / v0.7.0 / v1.0.0)
Latest Verification: ADR-008 DevOps templates verified 2026-01-16; ADRs 014-018 added 2026-04-30