# MCP ADR Analysis Server Architecture

## Overview

The MCP ADR Analysis Server is an intelligent architectural analysis platform that provides LLM clients with comprehensive ADR (Architectural Decision Record) analysis capabilities. The server has evolved from a prompt-only system to a hybrid architecture that combines actual file system operations with intelligent AI processing.

## High-Level Communication Flow

```mermaid
graph TB
    subgraph "Client Environment"
        Claude[Claude AI]
        Gemini[Google Gemini] 
        OpenAI[OpenAI GPT]
        Other[Other LLM Clients]
    end
    
    subgraph "MCP Protocol Layer"
        Protocol[MCP Protocol<br/>stdin/stdout]
    end
    
    subgraph "MCP ADR Server"
        subgraph "Core Server"
            Index[index.ts<br/>Server Entry Point]
            Tools[Tool Registry<br/>23 MCP Tools]
            Resources[Resource Registry<br/>3 MCP Resources]
            Prompts[Prompt Registry<br/>AI Templates]
        end
        
        subgraph "New File System Layer"
            ReadFile[read_file tool]
            WriteFile[write_file tool] 
            ListDir[list_directory tool]
            Security[Path Security<br/>Validation]
        end
        
        subgraph "Utility Layer"
            ADRDisc[adr-discovery.js<br/>Actual ADR Reading]
            FileOps[actual-file-operations.js<br/>Project Scanning]
            ContentMask[content-masking.js<br/>Security Analysis]
            ResearchInt[research-integration.js<br/>Research Processing]
        end
        
        subgraph "AI Processing Layer"
            PromptExec[prompt-execution.js<br/>Internal AI Engine]
            KnowledgeGen[knowledge-generation.js<br/>GKP Enhancement]
            AIFallback[AI Fallback Strategy]
        end
        
        subgraph "Cache & Config"
            Cache[.mcp-adr-cache/<br/>Result Caching]
            Config[Environment Config<br/>PROJECT_PATH, etc.]
        end
    end
    
    subgraph "Target Project"
        ProjectFiles[Project Files]
        ADRs[././adrs/<br/>ADR Files]
        Research[./research/<br/>Research Files]
        Config2[Configuration Files]
        Scripts[Build Scripts]
    end
    
    %% Communication Flow
    Claude -->|MCP Calls| Protocol
    Gemini -->|MCP Calls| Protocol
    OpenAI -->|MCP Calls| Protocol
    Other -->|MCP Calls| Protocol
    
    Protocol <-->|JSON-RPC| Index
    
    Index --> Tools
    Index --> Resources
    Index --> Prompts
    
    Tools --> ReadFile
    Tools --> WriteFile
    Tools --> ListDir
    
    ReadFile --> Security
    WriteFile --> Security
    ListDir --> Security
    
    Security --> ADRDisc
    Security --> FileOps
    Security --> ContentMask
    Security --> ResearchInt
    
    ADRDisc -->|Read Files| ProjectFiles
    FileOps -->|Scan Structure| ProjectFiles
    ContentMask -->|Analyze Content| ProjectFiles
    ResearchInt -->|Process Research| Research
    
    Tools --> PromptExec
    PromptExec --> KnowledgeGen
    PromptExec --> AIFallback
    
    PromptExec --> Cache
    Tools --> Config
    
    %% Data Flow
    ProjectFiles -.->|File Content| ADRs
    ProjectFiles -.->|File Content| Research
    ProjectFiles -.->|File Content| Config2
    ProjectFiles -.->|File Content| Scripts
```

## Detailed Tool Communication Pattern

```mermaid
sequenceDiagram
    participant Client as LLM Client
    participant MCP as MCP Server
    participant FileSystem as File System Tools
    participant Utils as Utility Layer
    participant AI as Internal AI
    participant Project as Target Project
    
    Note over Client,Project: Example: discover_existing_adrs tool call
    
    Client->>MCP: discover_existing_adrs(adrDirectory)
    MCP->>FileSystem: list_directory(adrDirectory)
    FileSystem->>Utils: Security validation
    Utils->>Project: Read directory contents
    Project-->>Utils: File list
    
    loop For each ADR file
        Utils->>FileSystem: read_file(adrPath)
        FileSystem->>Project: Read ADR content
        Project-->>FileSystem: ADR content
        FileSystem-->>Utils: Validated content
    end
    
    Utils->>Utils: Parse ADR metadata & content
    Utils->>AI: Generate analysis prompt + actual data
    
    alt Internal AI Available
        AI->>AI: Process prompt with file content
        AI-->>Utils: Intelligent analysis results
        Utils-->>MCP: Formatted AI insights
    else AI Unavailable (Fallback)
        Utils-->>MCP: Raw prompt + file content
    end
    
    MCP-->>Client: Analysis results or prompt for external processing
    
    Note over Client,Project: Client gets either AI insights or raw data to process
```

## Before vs After Architecture Comparison

```mermaid
graph LR
    subgraph "BEFORE: Prompt-Only Mode"
        B1[LLM Client] -->|Call Tool| B2[MCP Server]
        B2 --> B3[Generate Prompt Template]
        B3 --> B4[Return Template]
        B4 --> B1
        B1 --> B5[Client must process<br/>externally]
        
        style B3 fill:#ffcccc
        style B5 fill:#ffcccc
    end
    
    subgraph "AFTER: Hybrid Mode"
        A1[LLM Client] -->|Call Tool| A2[MCP Server]
        A2 --> A3[Read Actual Files]
        A3 --> A4[Internal AI Processing]
        A4 --> A5{AI Available?}
        A5 -->|Yes| A6[Return AI Analysis]
        A5 -->|No| A7[Return Prompt + Data]
        A6 --> A1
        A7 --> A1
        
        style A3 fill:#ccffcc
        style A4 fill:#ccffcc
        style A6 fill:#ccffcc
    end
```

## Core Components

### 1. MCP Server Core (`src/index.ts`)
- **Entry Point**: Main server initialization and protocol handling
- **Tool Registry**: 31 MCP tools for comprehensive ADR analysis and project management
- **Resource Registry**: 3 MCP resources for structured data access
- **Prompt Registry**: AI-ready templates for analysis tasks
- **Knowledge Graph**: Advanced intent tracking and TODO synchronization

### 2. File System Layer (New)
Three new fundamental tools that enable universal LLM compatibility:

#### `read_file` Tool
```typescript
{
  name: 'read_file',
  description: 'Read contents of a file',
  inputSchema: {
    type: 'object',
    properties: {
      path: { type: 'string', description: 'Path to file' }
    },
    required: ['path']
  }
}
```

#### `write_file` Tool
```typescript
{
  name: 'write_file',
  description: 'Write content to a file',
  inputSchema: {
    type: 'object',
    properties: {
      path: { type: 'string', description: 'Path to file' },
      content: { type: 'string', description: 'Content to write' }
    },
    required: ['path', 'content']
  }
}
```

#### `list_directory` Tool
```typescript
{
  name: 'list_directory',
  description: 'List contents of a directory',
  inputSchema: {
    type: 'object',
    properties: {
      path: { type: 'string', description: 'Path to directory' }
    },
    required: ['path']
  }
}
```

### 3. Utility Layer
Provides actual file operations and intelligent processing:

#### ADR Discovery (`src/utils/adr-discovery.js`)
- **Function**: `discoverAdrsInDirectory()`
- **Purpose**: Actually read and parse ADR files + initialize `.mcp-adr-cache` infrastructure
- **Output**: Structured ADR data with content
- **Note**: Always initializes cache infrastructure, regardless of ADR presence

#### File Operations (`src/utils/actual-file-operations.js`)
- **Function**: `scanProjectStructure()`
- **Purpose**: Comprehensive project analysis
- **Features**: Shell script detection, content masking, pattern matching

#### Content Masking (`src/utils/content-masking.js`)
- **Function**: `analyzeSensitiveContent()`
- **Purpose**: Security analysis and data protection
- **Features**: Pattern detection, confidence scoring, masking strategies

#### Research Integration (`src/utils/research-integration.js`)
- **Function**: `monitorResearchDirectory()`
- **Purpose**: Research file processing and ADR impact analysis
- **Features**: Topic extraction, impact evaluation, update suggestions

### 4. AI Processing Layer

#### Internal AI Engine (`src/utils/prompt-execution.js`)
```typescript
// Enhanced analysis with actual file content
const result = await discoverAdrsInDirectory(adrDirectory, true, projectPath);
const analysisPrompt = generatePrompt(result.actualContent);
const aiResult = await executePromptWithFallback(analysisPrompt);
```

#### AI-Powered Tool Orchestration
- **OpenRouter.ai Integration**: Advanced AI planning through external LLM services
- **Dynamic Tool Sequencing**: AI generates optimal tool execution sequences
- **Hallucination Detection**: Reality checks prevent AI confusion and loops
- **Human Override Patterns**: Predefined workflows bypass AI confusion

#### Generated Knowledge Prompting (GKP)
- **Enhanced Analysis**: Leverages architectural knowledge for better insights
- **Context-Aware**: Understands project-specific patterns and technologies
- **Confidence Scoring**: Provides reliability metrics for recommendations

#### Intelligent Workflow Management
```typescript
// AI-powered tool orchestration
const plan = await generateToolPlan(userIntent, availableTools);
const sequence = await validateToolSequence(plan.tools);
const execution = await executeWithFallback(sequence);
```

#### Fallback Strategy
```typescript
if (executionResult.isAIGenerated) {
  // Return smart analysis
  return formatMCPResponse({...});
} else {
  // Return raw data for external processing
  return { content: [...] };
}
```

## Key Architectural Improvements

### 1. Universal LLM Compatibility
- **Before**: Worked only with Claude (had file access)
- **After**: Works with all LLM providers through internal file operations

### 2. Intelligent Fallback Strategy
The server provides both AI-enhanced analysis and raw data depending on capabilities:
- **AI Available**: Smart insights with confidence scores
- **AI Unavailable**: Structured prompts with actual file content

### 3. Security-First File Access
- **Path Validation**: Absolute paths required, security sandboxing
- **Content Masking**: Automatic sensitive data detection and protection
- **Access Control**: Configurable project boundaries

### 4. Performance Optimization
- **Caching System**: Results cached in `.mcp-adr-cache/` with TTL
- **Lazy Loading**: Utilities loaded on-demand
- **Intelligent Filtering**: Content-aware file processing

### 5. Enhanced AI Capabilities
- **Generated Knowledge Prompting**: Domain expertise enhancement
- **Context Awareness**: Project-specific analysis
- **Risk Assessment**: Confidence scoring and impact evaluation

### 6. Advanced Project Management Tools
- **Smart Scoring System**: Dynamic project health assessment across all dimensions
- **TODO Lifecycle Management**: Complete task tracking with status transitions
- **AI-Powered Troubleshooting**: Systematic failure analysis with test plan generation
- **Intelligent Tool Orchestration**: Dynamic workflow automation based on user intent
- **Human Override System**: Force planning when LLMs get confused or stuck
- **Smart Git Operations**: Release readiness analysis with sensitive content filtering

### 7. Knowledge Graph Integration
- **Intent Tracking**: Comprehensive tracking of human requests and AI responses
- **Tool Execution History**: Complete audit trail of all tool executions
- **TODO Synchronization**: Bidirectional sync between TODO.md and knowledge graph
- **Analytics Generation**: Real-time project insights and completion metrics

## Communication Protocols

### MCP Protocol Integration
The server communicates with LLM clients via the Model Context Protocol:
- **Transport**: stdin/stdout JSON-RPC
- **Format**: Structured tool calls and responses
- **Validation**: Zod schema validation for all inputs/outputs

### Tool Execution Flow
1. **Client Request**: LLM client calls MCP tool
2. **Security Validation**: Path and content validation
3. **File Operations**: Read actual project files
4. **AI Processing**: Internal analysis or prompt generation
5. **Response**: Structured insights or prompts for external processing

## File System Security

### Path Security
```typescript
// Absolute path requirement
if (!path.isAbsolute(filePath)) {
  throw new McpAdrError('File path must be absolute', 'INVALID_PATH');
}

// Project boundary validation
const projectPath = process.env.PROJECT_PATH || process.cwd();
if (!filePath.startsWith(projectPath)) {
  throw new McpAdrError('Access denied: file outside project', 'ACCESS_DENIED');
}
```

### Content Masking
- **Automatic Detection**: API keys, tokens, passwords, secrets
- **Configurable Patterns**: Project-specific sensitive data patterns
- **Masking Strategies**: Full, partial, placeholder, environment-based

## Deployment Architecture

### Environment Configuration
```bash
PROJECT_PATH=/path/to/target/project
ADR_DIRECTORY=./adrs
LOG_LEVEL=INFO
CACHE_ENABLED=true
```

### Cache Management
- **Location**: `.mcp-adr-cache/`
- **TTL**: Configurable time-to-live
- **Invalidation**: Automatic on file changes
- **Structure**: Organized by tool and query parameters

## Integration Examples

### Claude Code Integration
```typescript
// Claude automatically uses internal file tools
const adrAnalysis = await mcpClient.call('discover_existing_adrs', {
  adrDirectory: './adrs'
});
// Returns intelligent analysis with actual ADR content
```

### Gemini/OpenAI Integration
```typescript
// Gemini/OpenAI get actual file content through MCP file tools
const adrAnalysis = await mcpClient.call('discover_existing_adrs', {
  adrDirectory: './adrs'
});
// Returns structured data they can process independently
```

## Tool Categories and Advanced Features

### Core Analysis Tools (Original)
- `discover_existing_adrs` - ADR discovery and cataloging
- `analyze_project_ecosystem` - Technology stack analysis
- `suggest_adrs` - Implicit decision identification
- `generate_adrs_from_prd` - Requirements-driven ADR generation

### Enhanced TDD and TODO Management
- `generate_adr_todo` - Two-phase TDD task generation with ADR linking
- `manage_todo` - Advanced TODO.md lifecycle management
- `compare_adr_progress` - Implementation validation with mock detection

### AI-Powered Orchestration and Planning
- `tool_chain_orchestrator` - Dynamic tool sequencing based on user intent
- `troubleshoot_guided_workflow` - Systematic failure analysis with test plans

### Project Health and Operations
- `smart_score` - Cross-tool project health scoring coordination
- `smart_git_push` - Release readiness analysis with content security
- `generate_deployment_guidance` - AI-driven deployment guidance generation

### Knowledge Graph and Analytics
- Comprehensive intent tracking and execution history
- Real-time TODO.md synchronization and change detection
- Cross-ADR dependency validation and analytics
- Project completion metrics and velocity tracking

## Future Enhancements

### Planned Improvements
1. **Real-time File Watching**: Automatic updates on file changes
2. **Distributed Caching**: Multi-project cache sharing
3. **Enhanced Security**: Role-based access control
4. **Performance Metrics**: Analysis timing and resource usage
5. **Plugin Architecture**: Extensible tool framework
6. **Advanced AI Integration**: More sophisticated hallucination detection
7. **Multi-Repository Support**: Cross-repository architectural analysis

### Integration Opportunities
- **CI/CD Pipelines**: Automated ADR compliance checking
- **IDE Extensions**: Real-time architectural guidance
- **Documentation Systems**: Automated documentation generation
- **Compliance Tools**: Regulatory requirement tracking
- **Team Collaboration**: Shared knowledge graphs and scoring metrics

## Conclusion

The MCP ADR Analysis Server architecture represents a significant evolution from a prompt-only system to an intelligent architectural analysis platform. By combining actual file system operations with AI-enhanced processing, the server provides universal LLM compatibility while delivering sophisticated architectural insights.

The hybrid approach ensures that all LLM providers can benefit from the server's capabilities, whether through direct AI analysis or by processing structured data and prompts. This architecture makes the server a true architectural intelligence platform rather than just a prompt generator.