Skip to main content

🔬 Research Integration Guide

Learn how to integrate research findings and external knowledge into your architectural decisions.

📋 Overview​

The MCP ADR Analysis Server includes powerful research integration capabilities that help you:

  • Gather relevant research and best practices
  • Integrate findings into ADRs automatically
  • Track research sources and citations
  • Build knowledge-driven architectural decisions

🎯 Prerequisites​

  • MCP ADR Analysis Server installed and configured
  • Basic understanding of ADRs
  • Access to research tools (optional: Firecrawl API)

🚀 Quick Start​

1. Generate Research Questions​

Use the perform_research tool to generate relevant research questions for your project:

await mcp.callTool('perform_research', {
  topic: 'microservices architecture',
  depth: 'comprehensive',
  includeExamples: true,
});

2. Integrate Research into ADRs​

The server automatically suggests research-backed decisions:

await mcp.callTool('research_integration_tool', {
  adrPath: './docs/adrs/001-architecture.md',
  researchTopics: ['scalability', 'performance'],
  autoApply: false,
});

📖 Step-by-Step Guide​

Step 1: Set Up Research Tools​

Configure your environment for research integration:

# .env file
FIRECRAWL_API_KEY=your_api_key_here  # Optional but recommended
RESEARCH_CACHE_DIR=./.documcp/research

Step 2: Perform Initial Research​

Generate research questions for your domain:

const research = await mcp.callTool('research_question_tool', {
  projectPath: './',
  domain: 'backend-services',
  focusAreas: ['architecture', 'security', 'performance'],
});

Step 3: Review Research Findings​

The server stores research in .documcp/research/:

.documcp/research/
├── perform_research_001.md
├── perform_research_002.md
└── index.json

Step 4: Integrate into ADRs​

Apply research findings to your decisions:

await mcp.callTool('interactive_adr_planning_tool', {
  includeResearch: true,
  researchIntensity: 'high',
});

💡 Advanced Techniques​

Custom Research Templates​

Create custom research templates for your domain:

const template = {
  domain: 'machine-learning',
  questions: [
    'What are best practices for ML model deployment?',
    'How to handle model versioning?',
    'What monitoring strategies work best?',
  ],
  sources: ['arxiv', 'industry-blogs', 'documentation'],
};

Automated Research Updates​

Set up periodic research updates:

# Add to your CI/CD pipeline
npm run research:update -- --topics architecture,security

Research-Driven ADR Generation​

Generate ADRs directly from research:

await mcp.callTool('generate_adrs_from_prd', {
  prdPath: './docs/requirements.md',
  includeResearch: true,
  researchDepth: 'comprehensive',
});

🔗 Integration Workflows​

Workflow 1: New Project Setup​

  1. Analyze project requirements
  2. Generate research questions
  3. Perform research
  4. Create ADRs with research backing
  5. Review and refine

Workflow 2: Existing Project Enhancement​

  1. Review existing ADRs
  2. Identify research gaps
  3. Perform targeted research
  4. Update ADRs with findings
  5. Track improvements

Workflow 3: Continuous Learning​

  1. Monitor industry trends
  2. Perform periodic research
  3. Update decision records
  4. Maintain knowledge base
  5. Share insights with team

📊 Best Practices​

1. Balance Research Depth​

  • Light: Quick validation of decisions (5-10 min)
  • Standard: Comprehensive analysis (20-30 min)
  • Deep: Thorough investigation (1-2 hours)

2. Cite Sources Properly​

Always include source attribution in ADRs:

## Context

Based on research from [Source Name](URL), we found that...

**Research References**:

- [Paper Title](link) - Key finding
- [Blog Post](link) - Implementation details

3. Keep Research Current​

Update research findings regularly:

# Re-run research quarterly
npm run research:refresh -- --older-than 90d

4. Organize Research Findings​

Structure your research directory:

docs/research/
├── architecture/
│   ├── microservices.md
│   └── serverless.md
├── security/
│   ├── authentication.md
│   └── encryption.md
└── performance/
    ├── caching.md
    └── optimization.md

🛠️ Troubleshooting​

Research Not Generating​

Issue: perform_research tool returns empty results

Solutions:

  1. Check Firecrawl API key configuration
  2. Verify internet connectivity
  3. Try different search topics
  4. Use depth: 'standard' instead of 'quick'

Integration Failing​

Issue: Research integration tool fails to update ADRs

Solutions:

  1. Verify ADR file format
  2. Check file permissions
  3. Ensure valid markdown structure
  4. Review error logs in .documcp/logs/

Slow Research Performance​

Issue: Research takes too long to complete

Solutions:

  1. Use depth: 'quick' for faster results
  2. Limit number of research questions
  3. Cache research results locally
  4. Consider parallel processing

📚 Related Documentation​

🎯 Examples​

Example 1: Architecture Research​

// Generate architecture research
const archResearch = await mcp.callTool('perform_research', {
  topic: 'event-driven architecture',
  depth: 'comprehensive',
  outputPath: './docs/research/architecture/event-driven.md',
});

// Apply to ADR
await mcp.callTool('research_integration_tool', {
  adrPath: './docs/adrs/005-event-architecture.md',
  researchSource: archResearch.outputPath,
  sections: ['context', 'decision', 'consequences'],
});

Example 2: Security Research​

// Research security patterns
const secResearch = await mcp.callTool('research_question_tool', {
  projectPath: './',
  domain: 'security',
  focusAreas: ['authentication', 'authorization', 'encryption'],
});

// Generate security ADRs
await mcp.callTool('generate_adrs_from_prd', {
  prdPath: './docs/security-requirements.md',
  includeResearch: true,
  researchResults: secResearch,
});

💬 Need Help?​

Last Updated: 2025-10-12