mcp-adr-analysis-server

Instructions

Implementation Reference

• src/tools/tool-catalog.ts:361-379 (registration)

  Registration and input schema definition for the analyze_adr_timeline tool in the central tool catalog. Includes metadata, description, token cost estimates, related tools, and input schema.
  TOOL_CATALOG.set('analyze_adr_timeline', { name: 'analyze_adr_timeline', shortDescription: 'Analyze ADR evolution over time', fullDescription: 'Analyzes the timeline of ADR decisions to understand architectural evolution.', category: 'adr', complexity: 'moderate', tokenCost: { min: 1500, max: 3000 }, hasCEMCPDirective: true, // Phase 4.3: Moderate tool - timeline analysis relatedTools: ['discover_existing_adrs', 'compare_adr_progress'], keywords: ['adr', 'timeline', 'history', 'evolution'], requiresAI: true, inputSchema: { type: 'object', properties: { startDate: { type: 'string', description: 'Start date for analysis' }, endDate: { type: 'string', description: 'End date for analysis' }, }, }, });
• src/utils/adr-timeline-extractor.ts:57-376 (helper)

  Core timeline extraction logic that analyzes ADR creation/update dates using git history, content parsing, or filesystem metadata with intelligent caching and conditional extraction. This is the primary helper function for ADR timeline analysis.
  export async function extractBasicTimeline( adrPath: string, adrContent: string, options: TimelineExtractionOptions = {} ): Promise<BasicTimeline> { const { useCache = true, cacheTTL = 3600, // 1 hour default forceExtract = false, } = options; // Check if extraction can be skipped (unless forced) if (!forceExtract) { const decision = await shouldExtractTimeline(adrPath, adrContent); if (!decision.shouldExtract && decision.useExisting) { // Use existing date from content return createTimelineFromContent(adrContent, decision.useExisting, decision.reason); } if (!decision.shouldExtract && !decision.useExisting) { // Use cached data const cached = getCachedTimeline(`timeline:${adrPath}`); if (cached) { return cached as BasicTimeline; } } // Log extraction reason for debugging // NOTE: All console output goes to stderr to preserve stdout for MCP JSON-RPC if (decision.shouldExtract) { console.error(`[Timeline] Extracting for ${adrPath}: ${decision.reason}`); } } // Perform extraction using priority order: git → content → filesystem let timeline: Partial<BasicTimeline> | null = null; // Try git extraction first timeline = await tryGitExtraction(adrPath); // Fallback to content parsing if (!timeline || !timeline.created_at) { const contentDate = extractDateFromContent(adrContent); if (contentDate) { timeline = { created_at: contentDate, updated_at: contentDate, extraction_method: 'content', }; } } // Final fallback to filesystem if (!timeline || !timeline.created_at) { timeline = await fallbackToFilesystem(adrPath); } // Calculate derived fields const stats = await stat(adrPath); const ageDays = calculateAgeDays(timeline.created_at!); const daysSinceUpdate = calculateAgeDays(timeline.updated_at!); const fullTimeline: BasicTimeline = { created_at: timeline.created_at!, updated_at: timeline.updated_at!, age_days: ageDays, days_since_update: daysSinceUpdate, staleness_warnings: generateBasicWarnings(ageDays, daysSinceUpdate), extraction_method: timeline.extraction_method as 'git' | 'content' | 'filesystem', }; // Cache result with file modification time for future checks if (useCache) { setCachedTimeline( `timeline:${adrPath}`, { ...fullTimeline, _fileModifiedAt: stats.mtime.toISOString(), _cachedAt: new Date().toISOString(), }, cacheTTL ); } return fullTimeline; } /** * Determine if timeline extraction should run */ async function shouldExtractTimeline( adrPath: string, adrContent: string ): Promise<{ shouldExtract: boolean; reason: string; useExisting?: string; }> { // Check if ADR content has a date field const dateInContent = extractDateFromContent(adrContent); // Check file modification time const stats = await stat(adrPath); const fileModifiedAt = stats.mtime; // Check cache const cacheKey = `timeline:${adrPath}`; const cached = getCachedTimeline(cacheKey); // CONDITION 1: No date in content → MUST extract if (!dateInContent) { return { shouldExtract: true, reason: 'No timestamp found in ADR content', }; } // CONDITION 2: Has date + cached + file unchanged → SKIP if (cached && cached._fileModifiedAt) { const cachedModTime = new Date(cached._fileModifiedAt); if (fileModifiedAt <= cachedModTime) { return { shouldExtract: false, reason: 'File unchanged since last extraction', useExisting: dateInContent, }; } } // CONDITION 3: Has date + file modified recently → RE-EXTRACT const daysSinceModification = (Date.now() - fileModifiedAt.getTime()) / (1000 * 60 * 60 * 24); if (daysSinceModification < 7) { // Modified within last week return { shouldExtract: true, reason: `File modified ${Math.floor(daysSinceModification)} days ago`, }; } // CONDITION 4: Has date + old file → USE CONTENT DATE return { shouldExtract: false, reason: 'File has valid date and is stable (not recently modified)', useExisting: dateInContent, }; } /** * Extract date from ADR content using regex */ function extractDateFromContent(content: string): string | null { const dateMatch = content.match(/(?:##?\s*date|date:|\*\*date\*\*:)\s*(.+?)(?:\n|$)/i); if (dateMatch && dateMatch[1]) { const dateStr = dateMatch[1].trim(); try { // Validate it's a parseable date const date = new Date(dateStr); if (!isNaN(date.getTime())) { return date.toISOString(); } } catch { // Invalid date format } } return null; } /** * Create timeline from ADR content date (no git extraction needed) */ function createTimelineFromContent( _content: string, dateStr: string, reason: string ): BasicTimeline { let decisionDate: Date; try { decisionDate = new Date(dateStr); } catch { // Fallback to current time if parsing fails decisionDate = new Date(); } const isoDate = decisionDate.toISOString(); const ageDays = calculateAgeDays(isoDate); return { created_at: isoDate, updated_at: isoDate, // Assume same as creation age_days: ageDays, days_since_update: ageDays, staleness_warnings: generateBasicWarnings(ageDays, ageDays), extraction_method: 'content', extraction_skipped: true, skip_reason: reason, }; } /** * Try to extract timeline from git history */ async function tryGitExtraction(adrPath: string): Promise<Partial<BasicTimeline> | null> { try { // Creation date (first commit) const { stdout: created } = await execAsync( `git log --diff-filter=A --follow --format=%aI -- "${adrPath}" | tail -1`, { timeout: 5000 } ); // Last modification date const { stdout: updated } = await execAsync(`git log -1 --format=%aI -- "${adrPath}"`, { timeout: 5000, }); if (!created.trim() || !updated.trim()) { return null; } return { created_at: created.trim(), updated_at: updated.trim(), extraction_method: 'git', }; } catch (error) { // Git not available, not a git repo, or command failed console.warn(`[Timeline] Git extraction failed for ${adrPath}:`, error); return null; } } /** * Fallback to filesystem timestamps */ async function fallbackToFilesystem(adrPath: string): Promise<Partial<BasicTimeline>> { try { const stats = await stat(adrPath); return { created_at: stats.birthtime.toISOString(), updated_at: stats.mtime.toISOString(), extraction_method: 'filesystem', }; } catch { // Last resort: use current time const now = new Date().toISOString(); return { created_at: now, updated_at: now, extraction_method: 'filesystem', }; } } /** * Calculate age in days from ISO timestamp */ function calculateAgeDays(isoTimestamp: string): number { const date = new Date(isoTimestamp); const now = new Date(); const diffMs = now.getTime() - date.getTime(); return Math.floor(diffMs / (1000 * 60 * 60 * 24)); } /** * Generate basic staleness warnings */ function generateBasicWarnings(ageDays: number, daysSinceUpdate: number): string[] { const warnings: string[] = []; // Warning: Old ADR if (ageDays > 180) { warnings.push(`ADR is ${ageDays} days old (>6 months)`); } // Warning: No recent updates if (daysSinceUpdate > 365) { warnings.push(`No updates in ${daysSinceUpdate} days (>1 year)`); } // Warning: Very old dormant ADR if (daysSinceUpdate > 730) { warnings.push(`Dormant for ${Math.floor(daysSinceUpdate / 365)} years - may be obsolete`); } return warnings; } /** * Helper to extract keywords from ADR content for implementation tracking */ export function extractKeywordsFromAdr(title: string, decision?: string): string[] { const text = `${title} ${decision || ''}`.toLowerCase(); const keywords: string[] = []; // Extract technology names const techPatterns = [ /\b(redis|postgres|mongodb|mysql|kafka|rabbitmq|docker|kubernetes|aws|gcp|azure)\b/gi, /\b(react|vue|angular|node|express|fastapi|django|flask|spring)\b/gi, /\b(graphql|rest|grpc|websocket|oauth|jwt|saml)\b/gi, ]; techPatterns.forEach(pattern => { const matches = text.match(pattern); if (matches) { keywords.push(...matches.map(m => m.toLowerCase())); } }); // Extract quoted terms (likely important concepts) const quoted = text.match(/"([^"]+)"/g); if (quoted) { keywords.push(...quoted.map(q => q.replace(/"/g, '').toLowerCase())); } // Remove duplicates return [...new Set(keywords)]; }
• src/utils/adr-timeline-types.ts:5-25 (helper)

  Type definitions for ADR timeline data structures used by the timeline extractor and analyzer.
  */ /** * Basic timeline information for an ADR * Extracted automatically from git history, content, or filesystem */ export interface BasicTimeline { /** When the ADR was created (ISO timestamp) */ created_at: string; /** When the ADR was last updated (ISO timestamp) */ updated_at: string; /** Age of the ADR in days */ age_days: number; /** Days since last update */ days_since_update: number; /** Staleness warnings based on basic timeline analysis */ staleness_warnings: string[]; /** How the timeline was extracted */ extraction_method: 'git' | 'content' | 'filesystem'; /** Whether extraction was skipped due to smart detection */ extraction_skipped?: boolean;
• src/utils/adr-discovery.ts:210-220 (helper)

  Usage of the timeline extractor in ADR discovery utility, demonstrating integration point for timeline analysis.
  const { extractBasicTimeline } = await import('./adr-timeline-extractor.js'); adr.timeline = await extractBasicTimeline(filePath, content, timelineOptions); } catch (error) { console.warn(`[Timeline] Failed to extract timeline for ${filename}:`, error); // Continue without timeline data } } discoveredAdrs.push(adr); } } catch (error) {