mcp-adr-analysis-server 2.1.9 → 2.1.19

package/dist/src/utils/server-context-generator.js

@@ -0,0 +1,666 @@
+/**
+ * Server Context Generator
+ *
+ * Generates a human-readable context file that LLMs can @ reference
+ * to instantly understand the server's state, memory, and capabilities.
+ *
+ * This bridges the gap between internal memory systems (JSON in /tmp)
+ * and LLM working context by creating a markdown file that can be
+ * @ mentioned in conversations.
+ */
+import * as fs from 'fs/promises';
+import * as path from 'path';
+import { loadConfig } from './config.js';
+import { EnhancedLogger } from './enhanced-logging.js';
+import { listAllPatterns } from './validated-pattern-definitions.js';
+export class ServerContextGenerator {
+    logger;
+    config;
+    constructor() {
+        this.logger = new EnhancedLogger();
+        this.config = loadConfig();
+    }
+    /**
+     * Generate the complete server context markdown file
+     */
+    async generateContext(kgManager, memoryManager, conversationManager, options = {}) {
+        const { maxRecentItems = 5 } = options;
+        const sections = [];
+        // Header
+        sections.push(this.generateHeader());
+        // Server Quick Reference
+        sections.push(this.generateServerInfo());
+        // Validated Deployment Patterns
+        sections.push(this.generateValidatedPatternsSection());
+        // MCP Resources
+        sections.push(this.generateMcpResourcesSection());
+        // Memory & Knowledge Graph Status
+        sections.push(await this.generateMemoryStatus(kgManager, memoryManager, conversationManager, maxRecentItems));
+        // Analytics
+        sections.push(await this.generateAnalytics(kgManager));
+        // Recent Deployment Activity
+        sections.push(await this.generateDeploymentActivitySection(kgManager));
+        // Patterns
+        sections.push(await this.generatePatterns(memoryManager));
+        // Recommendations
+        sections.push(await this.generateRecommendations(memoryManager));
+        // Usage guide
+        sections.push(this.generateUsageGuide());
+        // Footer
+        sections.push(this.generateFooter());
+        return sections.join('\n\n---\n\n');
+    }
+    /**
+     * Write context to file
+     */
+    async writeContextFile(kgManager, memoryManager, conversationManager, filePath) {
+        const outputPath = filePath || path.join(this.config.projectPath, '.mcp-server-context.md');
+        const content = await this.generateContext(kgManager, memoryManager, conversationManager);
+        await fs.writeFile(outputPath, content, 'utf-8');
+        this.logger.info('Server context file updated', 'ServerContextGenerator', {
+            path: outputPath,
+            size: content.length,
+        });
+    }
+    generateHeader() {
+        return `# MCP Server Context & Memory
+
+> **Purpose**: \`@\` reference this file to give LLMs instant context about the MCP ADR Analysis Server's state, capabilities, and recent activity.
+>
+> **Auto-generated**: This file is automatically updated by the server's memory systems.
+>
+> **Last Updated**: ${new Date().toISOString()}`;
+    }
+    generateServerInfo(toolList) {
+        // Generate tool list from actual registered tools or use complete default list
+        const tools = toolList || [
+            // ADR Management (14 tools)
+            {
+                name: 'analyze_project_ecosystem',
+                description: 'Analyze complete project ecosystem including dependencies, technologies, and architecture',
+            },
+            {
+                name: 'get_architectural_context',
+                description: 'Retrieve architectural context and decisions for a project',
+            },
+            {
+                name: 'generate_adrs_from_prd',
+                description: 'Generate ADRs from Product Requirements Document',
+            },
+            {
+                name: 'compare_adr_progress',
+                description: 'Compare ADR implementation progress against requirements',
+            },
+            {
+                name: 'suggest_adrs',
+                description: 'Suggest new ADRs based on project context and analysis',
+            },
+            {
+                name: 'generate_adr_from_decision',
+                description: 'Generate ADR from a specific architectural decision',
+            },
+            { name: 'generate_adr_bootstrap', description: 'Bootstrap ADR structure for a project' },
+            {
+                name: 'discover_existing_adrs',
+                description: 'Discover and index existing ADRs in project',
+            },
+            { name: 'validate_adr', description: 'Validate individual ADR content and structure' },
+            { name: 'validate_all_adrs', description: 'Validate all ADRs in project' },
+            {
+                name: 'review_existing_adrs',
+                description: 'Review and analyze existing ADRs for quality and completeness',
+            },
+            {
+                name: 'interactive_adr_planning',
+                description: 'Interactive ADR creation with guided workflow',
+            },
+            {
+                name: 'generate_rules',
+                description: 'Generate architectural rules from ADRs and code patterns',
+            },
+            { name: 'create_rule_set', description: 'Create comprehensive rule set for validation' },
+            // Content Security (6 tools)
+            {
+                name: 'analyze_content_security',
+                description: 'Analyze content for security vulnerabilities and sensitive data',
+            },
+            {
+                name: 'generate_content_masking',
+                description: 'Generate content masking for detected sensitive information',
+            },
+            {
+                name: 'configure_custom_patterns',
+                description: 'Configure custom security patterns for content analysis',
+            },
+            {
+                name: 'apply_basic_content_masking',
+                description: 'Apply basic content masking to protect sensitive data',
+            },
+            {
+                name: 'validate_content_masking',
+                description: 'Validate effectiveness of content masking',
+            },
+            {
+                name: 'configure_output_masking',
+                description: 'Configure masking patterns for tool outputs',
+            },
+            // Research & Analysis (6 tools)
+            {
+                name: 'perform_research',
+                description: 'Perform comprehensive architectural research on specific questions',
+            },
+            {
+                name: 'generate_research_questions',
+                description: 'Generate context-aware research questions from project analysis',
+            },
+            {
+                name: 'incorporate_research',
+                description: 'Incorporate research findings into ADRs and documentation',
+            },
+            {
+                name: 'create_research_template',
+                description: 'Create structured research templates for investigations',
+            },
+            {
+                name: 'expand_analysis_section',
+                description: 'Retrieve and expand tiered analysis sections from memory',
+            },
+            {
+                name: 'request_action_confirmation',
+                description: 'Request user confirmation for critical actions',
+            },
+            // Deployment & Infrastructure (6 tools)
+            {
+                name: 'deployment_readiness',
+                description: 'Assess deployment readiness with zero-tolerance validation',
+            },
+            {
+                name: 'generate_deployment_guidance',
+                description: 'Generate deployment guidance and recommendations',
+            },
+            {
+                name: 'analyze_deployment_progress',
+                description: 'Analyze deployment progress and identify blockers',
+            },
+            {
+                name: 'check_ai_execution_status',
+                description: 'Check AI execution mode and capabilities',
+            },
+            {
+                name: 'analyze_environment',
+                description: 'Analyze project environment and system configuration',
+            },
+            {
+                name: 'bootstrap_validation_loop',
+                description: 'Bootstrap self-learning validation and deployment workflow',
+            },
+            // Development Workflow (4 tools)
+            {
+                name: 'smart_git_push',
+                description: 'Intelligent git operations with validation and safety checks',
+            },
+            {
+                name: 'troubleshoot_guided_workflow',
+                description: 'Guided troubleshooting for deployment and validation issues',
+            },
+            {
+                name: 'get_workflow_guidance',
+                description: 'Get workflow guidance for specific development tasks',
+            },
+            {
+                name: 'get_development_guidance',
+                description: 'Get development guidance and best practices',
+            },
+            // File System Operations (5 tools)
+            { name: 'list_roots', description: 'List available filesystem roots for operations' },
+            { name: 'read_directory', description: 'Read directory contents and metadata' },
+            { name: 'read_file', description: 'Read file contents from filesystem' },
+            { name: 'write_file', description: 'Write content to filesystem' },
+            { name: 'list_directory', description: 'List directory contents with filtering' },
+            // Memory & Context (8 tools)
+            {
+                name: 'memory_loading',
+                description: 'Load and manage memory entities from various sources',
+            },
+            {
+                name: 'expand_memory',
+                description: 'Retrieve and expand stored content from tiered responses',
+            },
+            {
+                name: 'query_conversation_history',
+                description: 'Search and retrieve conversation sessions',
+            },
+            {
+                name: 'get_conversation_snapshot',
+                description: 'Get current conversation context snapshot',
+            },
+            { name: 'get_memory_stats', description: 'Get statistics about stored conversation memory' },
+            {
+                name: 'get_server_context',
+                description: 'Generate comprehensive server context for LLM awareness',
+            },
+            { name: 'validate_rules', description: 'Validate architectural rules against code' },
+            { name: 'manage_cache', description: 'Manage multi-level caching system' },
+            // Cloud & Database (3 tools)
+            { name: 'llm_web_search', description: 'Search web for contextual information using LLM' },
+            { name: 'llm_cloud_management', description: 'Manage cloud resources and infrastructure' },
+            { name: 'llm_database_management', description: 'Manage database operations and queries' },
+            // Other (3 tools)
+            {
+                name: 'smart_score',
+                description: 'Score code quality and architecture (0-100) with detailed analysis',
+            },
+            {
+                name: 'tool_chain_orchestrator',
+                description: 'AI-powered dynamic tool sequencing and workflow coordination',
+            },
+            { name: 'mcp_planning', description: 'Plan and manage MCP workflows and project phases' },
+        ];
+        // Group tools by category for better organization
+        const categories = this.categorizeTools(tools);
+        let toolsSection = '### Available Tools by Category\n\n';
+        for (const [category, categoryTools] of Object.entries(categories)) {
+            toolsSection += `**${category}**\n`;
+            categoryTools.forEach((tool, idx) => {
+                toolsSection += `${idx + 1}. \`${tool.name}\` - ${tool.description}\n`;
+            });
+            toolsSection += '\n';
+        }
+        return `## 🎯 Server Quick Reference
+
+**Name**: mcp-adr-analysis-server
+**Purpose**: AI-powered architectural decision analysis and ADR management
+**Project Path**: \`${this.config.projectPath}\`
+**ADR Directory**: \`${this.config.adrDirectory}\`
+
+${toolsSection}
+📖 Full tool schemas available via MCP protocol • Total: ${tools.length} tools`;
+    }
+    /**
+     * Categorize tools for better organization
+     */
+    categorizeTools(tools) {
+        const categories = {
+            'ADR Management': [],
+            'Content Security': [],
+            'Research & Analysis': [],
+            'Deployment & Infrastructure': [],
+            'Development Workflow': [],
+            'File System Operations': [],
+            'Memory & Context': [],
+            'Cloud & Database': [],
+            Other: [],
+        };
+        tools.forEach(tool => {
+            const name = tool.name.toLowerCase();
+            if (name.includes('adr') ||
+                name.includes('rule') ||
+                name.includes('ecosystem') ||
+                name.includes('architectural')) {
+                categories['ADR Management']?.push(tool);
+            }
+            else if (name.includes('security') ||
+                name.includes('masking') ||
+                name.includes('content_masking')) {
+                categories['Content Security']?.push(tool);
+            }
+            else if (name.includes('research') ||
+                name.includes('expand_analysis') ||
+                name.includes('confirmation')) {
+                categories['Research & Analysis']?.push(tool);
+            }
+            else if (name.includes('deploy') ||
+                name.includes('environment') ||
+                name.includes('readiness')) {
+                categories['Deployment & Infrastructure']?.push(tool);
+            }
+            else if (name.includes('git') ||
+                name.includes('todo') ||
+                name.includes('troubleshoot') ||
+                name.includes('bootstrap') ||
+                name.includes('workflow') ||
+                name.includes('guidance')) {
+                categories['Development Workflow']?.push(tool);
+            }
+            else if (name.includes('file') ||
+                name.includes('directory') ||
+                name.includes('list_roots') ||
+                name.includes('read_file') ||
+                name.includes('write_file')) {
+                categories['File System Operations']?.push(tool);
+            }
+            else if (name.includes('memory') ||
+                name.includes('conversation') ||
+                name.includes('context') ||
+                name.includes('cache')) {
+                categories['Memory & Context']?.push(tool);
+            }
+            else if (name.includes('cloud') || name.includes('database') || name.includes('llm')) {
+                categories['Cloud & Database']?.push(tool);
+            }
+            else {
+                categories['Other']?.push(tool);
+            }
+        });
+        // Remove empty categories
+        Object.keys(categories).forEach(key => {
+            if (categories[key]?.length === 0) {
+                delete categories[key];
+            }
+        });
+        return categories;
+    }
+    async generateMemoryStatus(kgManager, memoryManager, conversationManager, maxRecent) {
+        // Get knowledge graph data
+        const kg = await kgManager.loadKnowledgeGraph();
+        const activeIntents = await kgManager.getActiveIntents();
+        const completedIntents = await kgManager.getIntentsByStatus('completed');
+        // Get memory entity data
+        const entityQuery = await memoryManager.queryEntities({ limit: 1000 });
+        const intelligence = await memoryManager.getIntelligence();
+        // Get conversation data
+        let sessionInfo = 'None';
+        let turnCount = 0;
+        let sessionDuration = '0m';
+        try {
+            const stats = await conversationManager.getStats();
+            if (stats.activeSessions > 0) {
+                sessionInfo = `${stats.activeSessions} active`;
+                turnCount = stats.totalTurns;
+                // Use average session duration if available
+                sessionDuration =
+                    stats.activeSessions > 0
+                        ? `${Math.floor(stats.totalTurns / stats.activeSessions)}t`
+                        : '0m';
+            }
+        }
+        catch {
+            // Conversation manager not initialized
+        }
+        // Recent intents
+        const recentIntents = kg.intents
+            .slice(-maxRecent)
+            .reverse()
+            .map(intent => `- **${intent.humanRequest.substring(0, 60)}...** - ${intent.currentStatus} - ${new Date(intent.timestamp).toLocaleString()}`)
+            .join('\n');
+        // Entity breakdown
+        const entityBreakdown = Object.entries(entityQuery.aggregations?.byType || {})
+            .map(([type, count]) => `- ${type}: ${count}`)
+            .join('\n');
+        const avgConfidence = Math.round((entityQuery.entities.reduce((sum, e) => sum + e.confidence, 0) /
+            (entityQuery.entities.length || 1)) *
+            100);
+        return `## 🧠 Memory & Knowledge Graph Status
+
+### Active Intents
+
+**Total Intents**: ${kg.intents.length}
+**Active**: ${activeIntents.length} | **Completed**: ${completedIntents.length}
+
+**Recent Intents** (Last ${maxRecent}):
+${recentIntents || '- No recent intents'}
+
+### Memory Entities
+
+**Total Entities**: ${entityQuery.totalCount}
+**Relationships**: ${entityQuery.relationships.length}
+**Average Confidence**: ${avgConfidence}%
+
+**Entity Breakdown**:
+${entityBreakdown || '- No entities yet'}
+
+**Recent Activity** (Last 24h):
+- Knowledge Gaps: ${intelligence.adaptiveRecommendations.knowledgeGaps.length} identified
+
+### Conversation Context
+
+**Active Session**: ${sessionInfo}
+**Conversation Turns**: ${turnCount}
+**Session Duration**: ${sessionDuration}`;
+    }
+    async generateAnalytics(kgManager) {
+        const kg = await kgManager.loadKnowledgeGraph();
+        const trends = await kgManager.getProjectScoreTrends();
+        // Tool usage from analytics
+        const toolUsage = kg.analytics.mostUsedTools
+            .slice(0, 5)
+            .map((t, i) => `${i + 1}. **${t.toolName}**: ${t.usageCount} calls`)
+            .join('\n');
+        return `## 📊 Recent Analytics
+
+### Tool Usage (Most Used)
+${toolUsage || '- No tool usage yet'}
+
+### Score Trends
+- **Current Project Score**: ${Math.round(trends.currentScore)}/100
+- **Average Improvement per Intent**: ${Math.round(trends.averageImprovement)}
+
+### Top Impacting Intents
+${trends.topImpactingIntents
+            .slice(0, 3)
+            .map(i => `- **${i.humanRequest.substring(0, 50)}...**: ${i.scoreImprovement > 0 ? '+' : ''}${Math.round(i.scoreImprovement)} points`)
+            .join('\n')}`;
+    }
+    async generatePatterns(memoryManager) {
+        const intelligence = await memoryManager.getIntelligence();
+        const patterns = intelligence.patternRecognition.discoveredPatterns
+            .slice(0, 5)
+            .map(p => `- **${p.pattern}**: ${Math.round((p.confidence || 0) * 100)}% confidence`)
+            .join('\n');
+        const suggestions = intelligence.relationshipInference.suggestedRelationships
+            .slice(0, 3)
+            .map(s => `- ${s.sourceId.substring(0, 8)} → ${s.targetId.substring(0, 8)}: **${s.type}** (${Math.round((s.confidence || 0) * 100)}%)`)
+            .join('\n');
+        return `## 🔍 Discovered Patterns
+
+### Architectural Patterns
+${patterns || '- No patterns discovered yet'}
+
+### Suggested Relationships
+${suggestions || '- No relationship suggestions yet'}
+
+**Emergent Behaviors**: ${intelligence.patternRecognition.emergentBehaviors.length} detected`;
+    }
+    async generateRecommendations(memoryManager) {
+        const intelligence = await memoryManager.getIntelligence();
+        const nextActions = intelligence.adaptiveRecommendations.nextActions
+            .slice(0, 3)
+            .map(a => `${a.priority}. **${a.action}** - ${a.reasoning}`)
+            .join('\n');
+        const knowledgeGaps = intelligence.adaptiveRecommendations.knowledgeGaps
+            .slice(0, 3)
+            .map(gap => `- ${gap}`)
+            .join('\n');
+        const opportunities = intelligence.adaptiveRecommendations.optimizationOpportunities
+            .slice(0, 3)
+            .map(opp => `- ${opp}`)
+            .join('\n');
+        return `## 🎯 Recommendations for This Session
+
+### Next Actions
+${nextActions || '- No specific actions recommended'}
+
+### Knowledge Gaps
+${knowledgeGaps || '- No knowledge gaps identified'}
+
+### Optimization Opportunities
+${opportunities || '- No optimization opportunities identified'}`;
+    }
+    generateValidatedPatternsSection() {
+        const patterns = listAllPatterns();
+        const patternList = patterns
+            .map(p => `- **${p.name}** (${p.platformType})
+  - Version: ${p.version}
+  - Dependencies: ${p.billOfMaterials.dependencies.filter(d => d.required).length} required
+  - Deployment Phases: ${p.deploymentPhases.length}
+  - Validation Checks: ${p.validationChecks.filter(v => v.severity === 'critical').length} critical
+  - Base Code: ${p.baseCodeRepository.url}`)
+            .join('\n\n');
+        return `## 🚀 Validated Deployment Patterns
+
+The server provides ${patterns.length} pre-validated deployment patterns for different platforms.
+Each pattern includes bill of materials, deployment phases, validation checks, and authoritative sources.
+
+### Available Patterns
+
+${patternList}
+
+### How to Access
+
+Use MCP resources to get pattern details:
+- \`adr://validated_patterns\` - Complete catalog
+- \`adr://validated_pattern/{platform}\` - Specific pattern (openshift, kubernetes, docker, nodejs, python, mcp, a2a)
+- \`adr://pattern_sources/{platform}\` - Authoritative documentation sources
+- \`adr://pattern_base_code/{platform}\` - Base code repository integration
+
+### Related Tools
+
+- \`bootstrap_validation_loop\` - Deploy with DAG-based infrastructure automation
+- \`deployment_readiness\` - Validate deployment readiness
+- \`generate_deployment_guidance\` - Get platform-specific deployment recommendations`;
+    }
+    generateMcpResourcesSection() {
+        const resources = [
+            {
+                uri: 'adr://validated_patterns',
+                name: 'Validated Patterns Catalog',
+                description: 'Complete catalog of all deployment patterns',
+            },
+            {
+                uri: 'adr://validated_pattern/{platform}',
+                name: 'Pattern by Platform',
+                description: 'Individual pattern with BOM, phases, validations',
+            },
+            {
+                uri: 'adr://pattern_sources/{platform}',
+                name: 'Authoritative Sources',
+                description: 'Prioritized documentation sources for LLM research',
+            },
+            {
+                uri: 'adr://pattern_base_code/{platform}',
+                name: 'Base Code Repository',
+                description: 'Framework code integration instructions',
+            },
+            {
+                uri: 'adr://architectural_knowledge_graph',
+                name: 'Knowledge Graph',
+                description: 'Complete architectural relationships and decisions',
+            },
+            {
+                uri: 'adr://deployment_status',
+                name: 'Deployment Status',
+                description: 'Current deployment state and health checks',
+            },
+            {
+                uri: 'adr://project_metrics',
+                name: 'Project Metrics',
+                description: 'Code metrics and quality scores',
+            },
+        ];
+        const resourceList = resources
+            .map(r => `- **${r.uri}**\n  ${r.name}: ${r.description}`)
+            .join('\n\n');
+        return `## 📦 MCP Resources
+
+The server exposes ${resources.length} key resources (+ 16 more) for read-only access.
+
+### Featured Resources
+
+${resourceList}
+
+**Total**: 23 resources available via MCP protocol
+See full list with \`ListResources\` MCP request`;
+    }
+    async generateDeploymentActivitySection(kgManager) {
+        try {
+            const kg = await kgManager.loadKnowledgeGraph();
+            // Find deployment-related intents
+            const deploymentIntents = kg.intents.filter(intent => {
+                const toolNames = intent.toolChain.map(tc => tc.toolName);
+                return (intent.humanRequest.toLowerCase().includes('deploy') ||
+                    intent.humanRequest.toLowerCase().includes('bootstrap') ||
+                    intent.humanRequest.toLowerCase().includes('infrastructure') ||
+                    toolNames.some(name => [
+                        'bootstrap_validation_loop',
+                        'deployment_readiness',
+                        'generate_deployment_guidance',
+                    ].includes(name)));
+            });
+            const recentDeployments = deploymentIntents
+                .slice(-3)
+                .reverse()
+                .map(intent => {
+                const toolNames = intent.toolChain.map(tc => tc.toolName).join(', ');
+                return `- **${intent.humanRequest.substring(0, 60)}...**
+  - Status: ${intent.currentStatus}
+  - Tools: ${toolNames || 'None'}
+  - Time: ${new Date(intent.timestamp).toLocaleString()}`;
+            })
+                .join('\n\n');
+            // Check for bootstrap loop executions
+            const bootstrapExecutions = deploymentIntents.filter(intent => intent.toolChain.some(tc => tc.toolName === 'bootstrap_validation_loop'));
+            const dagExecutions = bootstrapExecutions.length;
+            const successfulDeployments = deploymentIntents.filter(intent => intent.currentStatus === 'completed').length;
+            return `## 🏗️ Recent Deployment Activity
+
+**Deployment Intents**: ${deploymentIntents.length}
+**DAG Executions**: ${dagExecutions}
+**Successful Deployments**: ${successfulDeployments}
+
+### Recent Activity (Last 3)
+
+${recentDeployments || '- No recent deployment activity'}
+
+### Deployment Capabilities
+
+- **Hybrid DAG Architecture**: Infrastructure deployment runs once, application iterates with auto-fix
+- **Platform Support**: OpenShift, Kubernetes, Docker, Node.js, Python, MCP, A2A
+- **Validation**: Zero-tolerance validation with automatic remediation
+- **Cleanup**: Full teardown support via \`deploymentCleanupRequested\` parameter`;
+        }
+        catch {
+            return `## 🏗️ Recent Deployment Activity
+
+_Deployment activity tracking unavailable_`;
+        }
+    }
+    generateUsageGuide() {
+        return `## 📝 How to Use This Context
+
+**When starting a conversation**:
+\`\`\`
+@.mcp-server-context.md I need to understand our current architectural decisions
+\`\`\`
+
+**When resuming work**:
+\`\`\`
+@.mcp-server-context.md What were we working on? Show me the active intents
+\`\`\`
+
+**When making decisions**:
+\`\`\`
+@.mcp-server-context.md What patterns have we discovered that relate to [topic]?
+\`\`\`
+
+**When checking progress**:
+\`\`\`
+@.mcp-server-context.md How has our architecture score changed recently?
+\`\`\``;
+    }
+    generateFooter() {
+        return `## 🔄 Context Refresh
+
+This file is automatically updated:
+- After every tool execution
+- When memory entities change
+- When conversation sessions start/end
+- On server restart
+
+To manually refresh: Use the MCP tool \`get_server_context\` or restart the server
+
+---
+
+_This context file bridges the gap between the server's persistent memory systems and your working conversation context._`;
+    }
+}
+//# sourceMappingURL=server-context-generator.js.map