mcp-adr-analysis-server

Instructions

Implementation Reference

• src/tools/research-integration-tool.ts:11-357 (handler)

  Primary handler for 'incorporate_research' tool. Dispatches to specialized analysis modes (monitor, extract_topics, evaluate_impact, generate_updates, comprehensive) using helper functions from research-integration utils. Returns structured content blocks with prompts and instructions for AI agents.
  export async function incorporateResearch(args: { researchPath?: string; adrDirectory?: string; analysisType?: | 'monitor' | 'extract_topics' | 'evaluate_impact' | 'generate_updates' | 'comprehensive'; existingTopics?: string[]; researchTopics?: Array<{ id: string; title: string; category: string; keyFindings: string[]; relevanceScore: number; }>; adrId?: string; updateType?: 'content' | 'status' | 'consequences' | 'alternatives' | 'deprecation'; researchFindings?: Array<{ finding: string; evidence: string[]; impact: string; }>; }): Promise<any> { const { researchPath = 'docs/research', adrDirectory = 'docs/adrs', analysisType = 'comprehensive', existingTopics, researchTopics, adrId, updateType, researchFindings, } = args; try { const { monitorResearchDirectory, extractResearchTopics, evaluateResearchImpact, generateAdrUpdateSuggestions, } = await import('../utils/research-integration.js'); switch (analysisType) { case 'monitor': { const result = await monitorResearchDirectory(researchPath); return { content: [ { type: 'text', text: `# Research Directory Monitoring ${result.instructions} ## Monitoring Status ${result.monitoringPrompt} ## Next Steps 1. **Extract research topics** using \`incorporate_research\` with \`analysisType: "extract_topics"\` 2. **Evaluate ADR impact** using \`analysisType: "evaluate_impact"\` 3. **Generate specific updates** using \`analysisType: "generate_updates"\` ## Automation Recommendations - Set up file system watchers for real-time monitoring - Schedule periodic research integration reviews - Establish research file templates and conventions - Create notification systems for new research findings `, }, ], }; } case 'extract_topics': { const result = await extractResearchTopics(researchPath, existingTopics); return { content: [ { type: 'text', text: `# Research Topic Extraction ${result.instructions} ## AI Analysis Prompt ${result.extractionPrompt} ## Next Steps 1. **Submit the prompt** to an AI agent for comprehensive topic extraction 2. **Review the extracted topics** for architectural relevance and quality 3. **Use the topics** with \`analysisType: "evaluate_impact"\` to assess ADR implications 4. **Store the topics** for future reference and tracking ## Expected Output The AI will provide: - **Extracted Topics**: Detailed research topics with findings and evidence - **Research Summary**: Quality assessment and completeness evaluation - **Key Insights**: Major findings that require immediate attention - **Recommendations**: Specific actions for incorporating research - **Gaps**: Areas needing additional research ## Integration Workflow After topic extraction, proceed with impact evaluation: \`\`\`json { "tool": "incorporate_research", "args": { "analysisType": "evaluate_impact", "researchTopics": [extracted topics from AI response] } } \`\`\` `, }, ], }; } case 'evaluate_impact': { if (!researchTopics || researchTopics.length === 0) { throw new McpAdrError( 'Research topics are required for impact evaluation. Use extract_topics first.', 'INVALID_INPUT' ); } // Convert to full ResearchTopic format const fullResearchTopics = researchTopics.map(topic => ({ ...topic, description: `Research topic: ${topic.title}`, sourceFiles: [], evidence: topic.keyFindings, confidence: topic.relevanceScore, lastUpdated: new Date().toISOString().split('T')[0] || '', tags: [topic.category], })); const result = await evaluateResearchImpact(fullResearchTopics, adrDirectory); return { content: [ { type: 'text', text: `# Research Impact Evaluation ${result.instructions} ## AI Evaluation Prompt ${result.evaluationPrompt} ## Next Steps 1. **Submit the prompt** to an AI agent for comprehensive impact analysis 2. **Review the impact assessments** and prioritize based on urgency and impact level 3. **Generate specific updates** for high-impact ADRs using \`analysisType: "generate_updates"\` 4. **Plan implementation** of recommended changes ## Expected Output The AI will provide: - **Impact Analysis**: Detailed assessment of how research affects each ADR - **Update Recommendations**: Specific suggestions for ADR modifications - **New ADR Suggestions**: Recommendations for new ADRs based on research - **Deprecation Suggestions**: ADRs that should be deprecated or superseded - **Overall Assessment**: Summary and action priorities ## Implementation Workflow For high-priority updates, use the update generation tool: \`\`\`json { "tool": "incorporate_research", "args": { "analysisType": "generate_updates", "adrId": "target-adr-id", "updateType": "content", "researchFindings": [relevant findings from analysis] } } \`\`\` `, }, ], }; } case 'generate_updates': { if (!adrId || !updateType || !researchFindings) { throw new McpAdrError( 'ADR ID, update type, and research findings are required for update generation', 'INVALID_INPUT' ); } const result = await generateAdrUpdateSuggestions( adrId, researchFindings, updateType, adrDirectory ); return { content: [ { type: 'text', text: `# ADR Update Generation ${result.instructions} ## AI Update Prompt ${result.updatePrompt} ## Next Steps 1. **Submit the prompt** to an AI agent for detailed update suggestions 2. **Review the proposed changes** for accuracy and completeness 3. **Request confirmation** using the action confirmation process 4. **Apply the updates** to the ADR file with proper version control 5. **Notify stakeholders** of the changes and implementation plan ## Expected Output The AI will provide: - **Update Suggestion**: Overall assessment and metadata - **Proposed Changes**: Specific modifications to make - **New Content**: Complete updated ADR content - **Migration Guidance**: Implementation and rollback plans - **Quality Checks**: Assessment of update quality - **Review Recommendations**: Suggested approval process ## Implementation Checklist Before applying updates: - [ ] Review all proposed changes carefully - [ ] Verify research evidence supports changes - [ ] Check impact on dependent systems - [ ] Ensure proper backup and version control - [ ] Plan stakeholder communication - [ ] Schedule implementation timeline `, }, ], }; } case 'comprehensive': { const monitorResult = await monitorResearchDirectory(researchPath); const extractResult = await extractResearchTopics(researchPath, existingTopics); return { content: [ { type: 'text', text: `# Comprehensive Research Integration This comprehensive analysis will integrate research findings into your architectural decision-making process. ## Research Directory Status ${monitorResult.instructions} ## Topic Extraction Analysis ${extractResult.instructions} ## AI Analysis Prompt ${extractResult.extractionPrompt} ## Comprehensive Workflow ### 1. **Topic Extraction** (Current Step) Submit the prompt above to extract research topics and insights ### 2. **Impact Evaluation** Use the extracted topics to evaluate impact on existing ADRs: \`\`\`json { "tool": "incorporate_research", "args": { "analysisType": "evaluate_impact", "researchTopics": [topics from step 1] } } \`\`\` ### 3. **Update Generation** Generate specific updates for affected ADRs: \`\`\`json { "tool": "incorporate_research", "args": { "analysisType": "generate_updates", "adrId": "target-adr-id", "updateType": "content", "researchFindings": [findings from step 2] } } \`\`\` ### 4. **Implementation** - Review and approve proposed changes - Apply updates with proper version control - Communicate changes to stakeholders - Monitor implementation results ## Expected Outcomes This comprehensive integration will help you: - **Identify research insights** that impact architectural decisions - **Prioritize ADR updates** based on research findings - **Generate high-quality updates** with proper justification - **Maintain architectural consistency** with latest research - **Improve decision quality** through evidence-based updates ## Quality Assurance All research integration follows these principles: - **Evidence-based**: All suggestions backed by solid research - **Impact-assessed**: Changes prioritized by architectural impact - **Stakeholder-aware**: Considers impact on all relevant parties - **Version-controlled**: Maintains proper change tracking - **Reversible**: Includes rollback plans for all changes `, }, ], }; } default: throw new McpAdrError(`Unknown analysis type: ${analysisType}`, 'INVALID_INPUT'); } } catch (error) { throw new McpAdrError( `Failed to incorporate research: ${error instanceof Error ? error.message : String(error)}`, 'RESEARCH_INTEGRATION_ERROR' ); } }
• src/tools/research-integration-tool.ts:11-35 (schema)

  Input schema (TypeScript interface) defining parameters for the incorporateResearch handler, including analysisType enum and structured research data types.
  export async function incorporateResearch(args: { researchPath?: string; adrDirectory?: string; analysisType?: | 'monitor' | 'extract_topics' | 'evaluate_impact' | 'generate_updates' | 'comprehensive'; existingTopics?: string[]; researchTopics?: Array<{ id: string; title: string; category: string; keyFindings: string[]; relevanceScore: number; }>; adrId?: string; updateType?: 'content' | 'status' | 'consequences' | 'alternatives' | 'deprecation'; researchFindings?: Array<{ finding: string; evidence: string[]; impact: string; }>; }): Promise<any> {
• src/utils/research-integration.ts:56-249 (helper)

  Helper function called by handler for 'monitor' analysisType. Scans research directory, reads file contents, generates AI prompts for analysis.
  export async function monitorResearchDirectory( researchPath: string = 'docs/research' ): Promise<{ monitoringPrompt: string; instructions: string; actualData?: any }> { try { // Use actual file operations to scan research directory const fs = await import('fs/promises'); const path = await import('path'); const projectPath = process.cwd(); const fullResearchPath = path.resolve(projectPath, researchPath); const researchFiles: ResearchFile[] = []; try { // Check if research directory exists await fs.access(fullResearchPath); // Scan for research files const scanDirectory = async (dirPath: string): Promise<void> => { const entries = await fs.readdir(dirPath, { withFileTypes: true }); for (const entry of entries) { const fullPath = path.join(dirPath, entry.name); if (entry.isDirectory()) { await scanDirectory(fullPath); } else if (entry.isFile()) { const ext = path.extname(entry.name).toLowerCase(); const supportedExts = ['.md', '.txt', '.pdf', '.doc', '.docx']; if (supportedExts.includes(ext)) { try { const stats = await fs.stat(fullPath); let content = ''; // Only read text-based files if (['.md', '.txt'].includes(ext)) { content = await fs.readFile(fullPath, 'utf-8'); } else { content = `[${ext.toUpperCase()} file - content not readable]`; } researchFiles.push({ filename: entry.name, content, lastModified: stats.mtime.toISOString(), size: stats.size, path: path.relative(projectPath, fullPath), }); } catch { // Skip files that can't be read } } } } }; await scanDirectory(fullResearchPath); } catch { // Research directory doesn't exist or is not accessible } const monitoringPrompt = ` # Research Directory Monitoring Based on actual file system analysis, here are the research files found: ## Research Directory Status - **Research Path**: ${researchPath} - **Full Path**: ${fullResearchPath} - **Files Found**: ${researchFiles.length} research files - **Directory Exists**: ${researchFiles.length > 0 ? 'Yes' : 'No (may need to be created)'} ## Discovered Research Files ${ researchFiles.length > 0 ? researchFiles .map( (file, index) => ` ### ${index + 1}. ${file.filename} - **Path**: ${file.path} - **Size**: ${file.size} bytes - **Last Modified**: ${file.lastModified} #### Content: \`\`\` ${file.content.slice(0, 1000)}${file.content.length > 1000 ? '\n... (truncated)' : ''} \`\`\` --- ` ) .join('\n') : '**No research files found.** You may need to:\n- Create the research directory: `mkdir -p docs/research`\n- Add research files in supported formats (.md, .txt, .pdf, .doc, .docx)\n- Use the research template tool to create structured research documents' } ## Analysis Requirements For each research file discovered: 1. Extract key architectural insights and findings from **actual file content** 2. Identify potential impacts on existing ADRs 3. Assess relevance to current project decisions 4. Categorize research by topic and priority 5. Generate recommendations for ADR updates 6. Monitor for new research files and changes ## Required Output Format Please provide research monitoring analysis in JSON format with: - File inventory with metadata - Key insights and findings extraction - Impact assessment on existing ADRs - Recommendations for integration `; const instructions = ` # Research Directory Monitoring Instructions This analysis provides **actual research file contents** for comprehensive architectural insights and findings. ## Monitoring Scope - **Research Path**: ${researchPath} - **Files Found**: ${researchFiles.length} research files - **Readable Files**: ${researchFiles.filter(f => f.content && !f.content.includes('content not readable')).length} files - **File Types**: Markdown, Text, PDF, Word documents - **Analysis Focus**: Architectural insights, ADR impacts, integration opportunities ## Discovered Files Summary ${researchFiles.map(f => `- **${f.filename}** (${f.size} bytes, modified: ${f.lastModified.split('T')[0]})`).join('\n')} ## Next Steps 1. **Submit the monitoring prompt** to an AI agent for analysis of **actual file content** 2. **Extract research topics** using the topic extraction tool 3. **Analyze impact on existing ADRs** using the impact evaluation tool 4. **Generate update suggestions** for affected ADRs 5. **Monitor for new research** files and changes ## Monitoring Recommendations - Set up file system watchers for automatic detection - Establish research file naming conventions - Create research templates for consistent structure - Schedule regular research integration reviews ## Getting Started ${ researchFiles.length === 0 ? `To begin using research integration: 1. Create the research directory: \`mkdir -p ${researchPath}\` 2. Add research files (markdown, text, or documents) 3. Use the \`incorporate_research\` tool to analyze findings 4. Review suggested ADR updates and implementations` : `Research files are already available for analysis. Proceed with topic extraction and impact evaluation.` } ## Expected AI Response Format The AI will return a JSON object with: - \`researchInventory\`: File inventory with metadata and analysis - \`keyInsights\`: Major architectural insights from actual content - \`impactAssessment\`: Potential impacts on existing ADRs - \`integrationRecommendations\`: Specific recommendations for incorporating findings ## Usage Example \`\`\`typescript const result = await monitorResearchDirectory(researchPath); // Submit result.monitoringPrompt to AI agent // Parse AI response for research insights and recommendations \`\`\` `; return { monitoringPrompt, instructions, actualData: { researchFiles, summary: { totalFiles: researchFiles.length, readableFiles: researchFiles.filter( f => f.content && !f.content.includes('content not readable') ).length, directoryExists: researchFiles.length > 0, lastModified: researchFiles.length > 0 ? Math.max(...researchFiles.map(f => new Date(f.lastModified).getTime())) : null, }, }, }; } catch (error) { throw new McpAdrError( `Failed to monitor research directory: ${error instanceof Error ? error.message : String(error)}`, 'MONITORING_ERROR' ); } }
• src/utils/research-integration.ts:254-374 (helper)

  Helper for 'extract_topics' mode. Extracts topics from actual research file contents using AI prompts.
  export async function extractResearchTopics( researchPath: string = 'docs/research', existingTopics?: string[] ): Promise<{ extractionPrompt: string; instructions: string; actualData?: any }> { try { // Reuse the actual file monitoring to get research files const monitoringResult = await monitorResearchDirectory(researchPath); const researchFiles = monitoringResult.actualData?.researchFiles || []; // Filter to only text-based files for topic extraction const textFiles = researchFiles.filter( (f: ResearchFile) => f.content && !f.content.includes('content not readable') ); const extractionPrompt = ` # Research Topic Extraction Based on actual research file analysis, here are the files with extractable content: ## Research Files for Topic Extraction ${ textFiles.length > 0 ? textFiles .map( (file: ResearchFile, index: number) => ` ### ${index + 1}. ${file.filename} - **Path**: ${file.path} - **Size**: ${file.size} bytes - **Last Modified**: ${file.lastModified.split('T')[0]} #### Full Content: \`\`\`markdown ${file.content} \`\`\` --- ` ) .join('\n') : '**No text-based research files found for topic extraction.**\n\nTo extract topics, you need:\n- Research files in .md or .txt format\n- Files with readable content\n- Research content that contains architectural insights' } ## Existing Topics Context ${ existingTopics ? ` ### Current Topics (${existingTopics.length}) ${existingTopics.map((topic, index) => `${index + 1}. ${topic}`).join('\n')} ` : 'No existing topics provided.' } ## Topic Extraction Requirements For each research file with **actual content** shown above: 1. Extract key architectural insights and findings from the **actual file content** 2. Identify potential impacts on existing decisions 3. Categorize topics by relevance and priority 4. Generate actionable recommendations 5. Assess integration opportunities with current ADRs `; const instructions = ` # Research Topic Extraction Instructions This analysis provides **actual research file contents** to extract key topics and findings that could impact architectural decisions. ## Research Analysis - **Research Path**: ${researchPath} - **Total Research Files**: ${researchFiles.length} files - **Text-Based Files**: ${textFiles.length} files with extractable content - **Existing Topics**: ${existingTopics?.length || 0} topics - **Analysis Focus**: Topic extraction from actual content, impact assessment, integration opportunities ## Discovered Text Files ${textFiles.map((f: ResearchFile) => `- **${f.filename}** (${f.size} bytes)`).join('\n')} ## Next Steps 1. **Submit the extraction prompt** to an AI agent for topic analysis based on **actual file content** 2. **Parse the JSON response** to get extracted topics and insights 3. **Review the research findings** for architectural relevance 4. **Use the impact evaluation tool** to assess ADR implications ## Expected AI Response Format The AI will return a JSON object with: - \`extractedTopics\`: Array of research topics with findings and evidence based on actual content - \`researchSummary\`: Overall assessment of research quality and completeness - \`keyInsights\`: Major insights that require action derived from actual files - \`recommendations\`: Specific recommendations for incorporating findings - \`gaps\`: Areas where additional research is needed ## Usage Example \`\`\`typescript const result = await extractResearchTopics(researchPath, existingTopics); // Submit result.extractionPrompt to AI agent // Parse AI response for research topics and insights based on actual content \`\`\` `; return { extractionPrompt, instructions, actualData: { researchFiles, textFiles, summary: { totalFiles: researchFiles.length, textFiles: textFiles.length, existingTopics: existingTopics?.length || 0, }, }, }; } catch (error) { throw new McpAdrError( `Failed to extract research topics: ${error instanceof Error ? error.message : String(error)}`, 'EXTRACTION_ERROR' ); } }
• src/utils/research-integration.ts:379-513 (helper)

  Helper for 'evaluate_impact' mode. Analyzes impact of research topics on actual ADR contents.
  export async function evaluateResearchImpact( researchTopics: ResearchTopic[], adrDirectory: string = 'docs/adrs' ): Promise<{ evaluationPrompt: string; instructions: string; actualData?: any }> { try { // Use actual ADR discovery instead of prompts const { discoverAdrsInDirectory } = await import('./adr-discovery.js'); // Actually read ADR files const discoveryResult = await discoverAdrsInDirectory(adrDirectory, process.cwd(), { includeContent: true, includeTimeline: false, }); const evaluationPrompt = ` # Research Impact Evaluation Based on actual ADR file analysis and research topics, analyze how research findings impact existing ADRs: ## Discovered ADRs (${discoveryResult.totalAdrs} total) ${ discoveryResult.adrs.length > 0 ? discoveryResult.adrs .map( (adr, index) => ` ### ${index + 1}. ${adr.title} - **File**: ${adr.filename} - **Status**: ${adr.status} - **Path**: ${adr.path} ${adr.metadata?.number ? `- **Number**: ${adr.metadata.number}` : ''} #### ADR Content: \`\`\`markdown ${adr.content || 'Content not available'} \`\`\` --- ` ) .join('\n') : 'No ADRs found in the specified directory.' } ## Research Topics Analysis Please evaluate the following research topics for their impact on the **actual ADR content** above: ${researchTopics .map( (topic, index) => ` ### ${index + 1}. ${topic.title} - **Category**: ${topic.category} - **Relevance Score**: ${topic.relevanceScore} - **Confidence**: ${topic.confidence} - **Key Findings**: ${topic.keyFindings.join(', ')} - **Evidence**: ${topic.evidence.join(', ')} - **Source Files**: ${topic.sourceFiles.join(', ')} - **Description**: ${topic.description} - **Tags**: ${topic.tags.join(', ')} ` ) .join('')} ## Impact Assessment Requirements For each research topic and each ADR with **actual content**: 1. Identify affected ADRs based on actual content analysis 2. Assess the severity of impact (low, medium, high, critical) 3. Determine required updates or new decisions 4. Prioritize changes based on business impact and evidence strength 5. Generate specific update recommendations with references to actual ADR sections `; const instructions = ` # Research Impact Evaluation Instructions This analysis provides **actual ADR content and research topics** to evaluate how research findings impact existing ADRs. ## Impact Analysis - **Research Topics**: ${researchTopics.length} topics - **ADR Directory**: ${adrDirectory} - **ADRs Found**: ${discoveryResult.totalAdrs} files - **ADRs with Content**: ${discoveryResult.adrs.filter(adr => adr.content).length} ADRs - **High Relevance Topics**: ${researchTopics.filter(t => t.relevanceScore > 0.7).length} topics ## Discovered ADR Summary ${discoveryResult.adrs.map(adr => `- **${adr.title}** (${adr.status})`).join('\n')} ## Research Topic Summary ${researchTopics.map(topic => `- **${topic.title}** (Relevance: ${topic.relevanceScore}, Confidence: ${topic.confidence})`).join('\n')} ## Next Steps 1. **Submit the evaluation prompt** to an AI agent for impact analysis based on **actual ADR content** 2. **Parse the JSON response** to get impact assessments and recommendations 3. **Review suggested updates** and prioritize based on impact level 4. **Use the update suggestion tool** for specific ADR modifications ## Expected AI Response Format The AI will return a JSON object with: - \`impactAnalysis\`: Detailed impact assessment for each ADR based on actual content - \`updateRecommendations\`: Specific update suggestions with justifications and content references - \`newAdrSuggestions\`: Recommendations for new ADRs based on research findings - \`deprecationSuggestions\`: ADRs that should be deprecated based on research evidence - \`overallAssessment\`: Summary of findings and action priorities ## Usage Example \`\`\`typescript const result = await evaluateResearchImpact(researchTopics, adrDirectory); // Submit result.evaluationPrompt to AI agent // Parse AI response for impact analysis based on actual ADR content \`\`\` `; return { evaluationPrompt, instructions, actualData: { discoveryResult, researchTopics, summary: { totalAdrs: discoveryResult.totalAdrs, adrsWithContent: discoveryResult.adrs.filter(adr => adr.content).length, totalTopics: researchTopics.length, highRelevanceTopics: researchTopics.filter(t => t.relevanceScore > 0.7).length, }, }, }; } catch (error) { throw new McpAdrError( `Failed to evaluate research impact: ${error instanceof Error ? error.message : String(error)}`, 'EVALUATION_ERROR' ); } }