Skip to main content

Documentation Update Plan: Research-Driven Architecture

Overview​

This plan outlines the documentation updates needed to communicate the new research-driven architecture direction for the MCP ADR Analysis Server.

Priority: HIGH 🔴​

The research-driven architecture is a major paradigm shift from traditional RAG approaches and needs comprehensive documentation.

Phase 1: Core Documentation (Week 1)​

1.1 Main README.md Updates​

File: ../../README.md`

Changes Needed:

  1. Add Research-Driven Section (after "Features")

    ## Research-Driven Architecture

    Unlike traditional RAG systems, this MCP server answers questions by querying **live environment resources**:

    - 📁 **Project Files** (configs, code, ADRs)
    - 🧠 **Knowledge Graph** (ADR relationships)
    - 🔧 **Environment Resources** (Kubernetes, Docker, OS metrics)
    - 🌐 **Web Search** (fallback only)

    **Why Not RAG?** Your infrastructure changes constantly. Live queries ensure accuracy.

    [Learn more →](./RESEARCH-DRIVEN-ARCHITECTURE.md)

  2. Update Tool List (add perform_research)

    ### New: Research Tools

    - `perform_research` - Answer questions using cascading sources
    - `generate_research_questions` - Generate context-aware research questions

  3. Add Red Hat Section

    ## Red Hat Support

    First-class support for Red Hat ecosystem:
    - ✅ OpenShift (`oc` CLI)
    - ✅ Podman (containers & pods)
    - ✅ Ansible (inventories, playbooks)

    Auto-detects available tools and provides live data.

  4. Update Quick Start (add research example)

    ## Quick Start

    ### Perform Research

    Ask questions about your project using live data:

    ```json
    {
      "tool": "perform_research",
      "args": {
        "question": "What container orchestration are we using?"
      }
    }

    The server cascades through project files → knowledge graph → environment → web search.

Priority: 🔴 CRITICAL - Users need to understand the new paradigm

Estimated Time: 2 hours

1.2 Architecture Documentation​

File: /./ARCHITECTURE.md (NEW or update existing)

Content Structure:

# Architecture Overview

## Research-Driven Design

### Cascading Source Hierarchy
[Diagram showing the cascade]

### Component Architecture
- ResearchOrchestrator
- EnvironmentCapabilityRegistry
- Knowledge Graph Integration

### Why Not RAG?
- Real-time data vs stale documents
- Lower maintenance overhead
- Perfect for infrastructure decisions

Priority: 🟡 HIGH - Important for technical understanding

Estimated Time: 3 hours

1.3 API Documentation Updates​

File: /./API.md or /./TOOLS.md

Changes Needed:

  1. Add perform_research tool documentation
  2. Update generate_research_questions with new capabilities
  3. Add environment capability examples

Example Entry:

## perform_research

Answer research questions using cascading sources.

### Input Schema

```json
{
  "question": string,           // Required: Research question
  "projectPath": string,        // Optional: Project path
  "confidenceThreshold": number // Optional: 0-1, default 0.6
}

Example​

{
  "tool": "perform_research",
  "args": {
    "question": "What deployment strategy do we use?",
    "confidenceThreshold": 0.7
  }
}

Response​

Returns:

  • Sources consulted (project files, knowledge graph, environment)
  • Confidence score
  • Synthesized answer
  • Web search recommendation (if needed)

**Priority**: 🟡 **HIGH**

**Estimated Time**: 2 hours

---

## Phase 2: Integration Guides (Week 2)

### 2.1 Red Hat Integration Guide

**File**: `/./RED-HAT-INTEGRATION.md` (NEW)

**Content**:
```markdown
# Red Hat Integration Guide

## Supported Tools

### OpenShift
- Installation requirements
- Configuration
- Example queries
- Common patterns

### Podman
- Podman vs Docker differences
- Pod management
- Example queries

### Ansible
- Inventory setup
- Playbook discovery
- Integration patterns

## Auto-Detection

How the system detects Red Hat tools...

## Configuration

Environment variables and settings...

## Examples

Real-world usage examples...

## Troubleshooting

Common issues and solutions...

Priority: 🟢 MEDIUM - Important for Red Hat users

Estimated Time: 4 hours

2.2 Environment Setup Guide​

File: /./ENVIRONMENT-SETUP.md (NEW)

Content:

# Environment Setup Guide

## Overview

The MCP server auto-detects environment capabilities.

## Supported Environments

### Kubernetes
- kubectl installation
- Context configuration
- Permissions needed

### Docker/Podman
- Installation
- Socket permissions
- Rootless configuration

### Operating System
- Supported platforms
- Required permissions

## Verification

How to verify capabilities are detected...

## Troubleshooting

Common detection issues...

Priority: 🟢 MEDIUM

Estimated Time: 3 hours

Phase 3: Tutorial Content (Week 3)​

3.1 Research Workflow Tutorial​

File: /./tutorials/RESEARCH-WORKFLOW.md (NEW)

Content:

# Research Workflow Tutorial

## Introduction

Learn how to use the research-driven architecture...

## Scenario 1: Discovering Container Setup

Step-by-step guide...

## Scenario 2: Investigating Deployment Strategy

Step-by-step guide...

## Scenario 3: OpenShift Route Analysis

Step-by-step guide...

## Advanced: Custom Research Patterns

How to structure complex research questions...

Priority: 🟢 MEDIUM

Estimated Time: 4 hours

3.2 Migration Guide (RAG to Research-Driven)​

File: /./MIGRATION-FROM-RAG.md (NEW)

Content:

# Migrating from RAG to Research-Driven

## Why Migrate?

Benefits of research-driven over RAG...

## Conceptual Differences

| RAG | Research-Driven |
|-----|-----------------|
| ... | ... |

## Migration Steps

1. Remove vector database dependencies
2. Configure environment tools
3. Update queries
4. Test cascading sources

## Examples

Before (RAG): ...
After (Research): ...

Priority: 🔵 LOW - Nice to have

Estimated Time: 2 hours

Phase 4: Video & Visual Content (Week 4)​

4.1 Architecture Diagrams​

Files: Various .png or .svg in /./diagrams/

Needed Diagrams:

  1. Cascading source hierarchy (flow diagram)
  2. Component architecture (system diagram)
  3. Environment capability detection (sequence diagram)
  4. Research flow with confidence scores (decision tree)

Tools: Mermaid, draw.io, or Excalidraw

Priority: 🟢 MEDIUM

Estimated Time: 6 hours

4.2 Demo Video/GIF​

File: demo.gif or link to video

Content:

  • Show research query execution
  • Demonstrate environment detection
  • Show confidence scoring
  • Illustrate web search fallback

Priority: 🔵 LOW - Great for engagement

Estimated Time: 4 hours

Phase 5: Blog Posts & Announcements (Ongoing)​

5.1 Announcement Blog Post​

Platform: GitHub Discussions, Medium, Dev.to

Content:

# Introducing Research-Driven Architecture for MCP Servers

Why we moved away from RAG...

How it works...

Benefits for smaller LLMs...

Try it yourself...

Priority: 🟢 MEDIUM

Estimated Time: 3 hours

5.2 Technical Deep Dive​

Platform: Blog or documentation site

Content:

  • Implementation details
  • Performance benchmarks
  • Comparison with RAG
  • Future roadmap

Priority: 🔵 LOW

Estimated Time: 5 hours

Summary: Documentation Deliverables​

Critical (Phase 1)​

  • Update README.md with research-driven section
  • Add Red Hat support section
  • Update tool list
  • Create ARCHITECTURE.md
  • Update API documentation

High Priority (Phase 2)​

  • Create RED-HAT-INTEGRATION.md
  • Create ENVIRONMENT-SETUP.md
  • Add troubleshooting guides

Medium Priority (Phase 3)​

  • Create tutorial content
  • Add architecture diagrams
  • Create example projects

Nice to Have (Phase 4+)​

  • Migration guide from RAG
  • Demo videos/GIFs
  • Blog posts
  • Technical deep dives

Estimated Total Time​

  • Phase 1 (Critical): 7 hours
  • Phase 2 (High): 7 hours
  • Phase 3 (Medium): 6 hours
  • Phase 4 (Low): 10 hours
  • Phase 5 (Ongoing): 8 hours

Total: ~38 hours (1 week full-time)

Success Metrics​

Documentation Quality​

  • All new tools documented
  • Examples for each capability
  • Troubleshooting sections complete
  • Architecture clearly explained

User Understanding​

  • Users understand RAG vs Research-Driven
  • Red Hat users can set up easily
  • Clear migration path provided
  • Confidence scoring explained

Community Engagement​

  • GitHub stars increase
  • Issues/questions about features decrease
  • Positive feedback on new direction
  • External blog posts/mentions

Maintenance Plan​

Regular Updates (Monthly)​

  • Update capability list as new tools are added
  • Add community-contributed examples
  • Refresh troubleshooting with new issues
  • Update performance benchmarks

Version Updates (Per Release)​

  • Update API schemas
  • Add new tool documentation
  • Update compatibility matrix
  • Refresh examples

Review & Approval Process​

  1. Draft → Technical review by maintainers
  2. Review → User testing & feedback
  3. Revise → Incorporate feedback
  4. Publish → Deploy to documentation site
  5. Announce → Share in community channels

Questions to Address in Documentation​

Users will likely ask:

  1. "Why not use RAG?" → Answer in README and ARCHITECTURE.md
  2. "How do I install Red Hat tools?" → RED-HAT-INTEGRATION.md
  3. "What if tools aren't detected?" → ENVIRONMENT-SETUP.md + troubleshooting
  4. "Can I use this without environment tools?" → Yes, project files + knowledge graph
  5. "How accurate is this vs RAG?" → Benchmarks in blog post
  6. "What happens when confidence is low?" → API docs + examples
  7. "Does this work with small LLMs?" → Benefits section in README

Next Steps (Immediate)​

  1. ✅ Create this plan document
  2. 🔴 Update README.md (highest priority)
  3. 🔴 Create ARCHITECTURE.md
  4. 🟡 Update API documentation
  5. 🟡 Create RED-HAT-INTEGRATION.md

Owner: Documentation team / maintainers Timeline: Start immediately, complete Phase 1 in 1 week