# 🔬 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:
```typescript
await mcp.callTool('perform_research', {
topic: 'microservices architecture',
depth: 'comprehensive',
includeExamples: true,
});
```
### 2. Integrate Research into ADRs
The server automatically suggests research-backed decisions:
```typescript
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:
```bash
# .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:
```typescript
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:
```typescript
await mcp.callTool('interactive_adr_planning_tool', {
includeResearch: true,
researchIntensity: 'high',
});
```
---
## 💡 Advanced Techniques
### Custom Research Templates
Create custom research templates for your domain:
```typescript
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:
```bash
# Add to your CI/CD pipeline
npm run research:update -- --topics architecture,security
```
### Research-Driven ADR Generation
Generate ADRs directly from research:
```typescript
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:
```markdown
## 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:
```bash
# 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
- **[Perform Research Tool](../reference/generation-tools.md#perform-research)** - Tool reference
- **[Interactive ADR Planning](./interactive-adr-planning.md)** - ADR workflows
- **[Firecrawl Setup](./firecrawl-setup.md)** - API configuration
- **[Research Architecture](../explanation/research-architecture.md)** - System design
---
## 🎯 Examples
### Example 1: Architecture Research
```typescript
// 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
```typescript
// 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?
- **Questions?** → [Open an Issue](https://github.com/tosin2013/mcp-adr-analysis-server/issues)
- **Documentation** → [Full API Reference](../reference/api-reference.md)
- **Troubleshooting** → [Troubleshooting Guide](./troubleshooting.md)
---
_Last Updated: 2025-10-12_