ARCHITECTURE.md

MCP Architecture Documentation

Overview

This document explains the Model Context Protocol (MCP) architecture used in the Competitive Analysis Agent system.

What is the Model Context Protocol?

MCP is a standardized protocol designed to enable seamless integration of:

• AI Models (Claude, GPT-4, etc.) with
• External Tools & Services (web search, databases, APIs, etc.)
• Custom Business Logic (analysis, validation, report generation)

Why MCP?

1. Modularity: Tools are isolated and reusable
2. Scalability: Add tools without modifying core agent code
3. Standardization: Common protocol across different AI systems
4. Separation of Concerns: Clear boundaries between reasoning and action
5. Production Ready: Built for enterprise-grade AI applications

---

System Architecture

Three-Tier Architecture

┌─────────────────────────────────────────────────────┐
│          PRESENTATION LAYER - Gradio UI             │
│  • User input (company name, API key)               │
│  • Report display (formatted Markdown)              │
│  • Error handling and validation                    │
└──────────────────┬──────────────────────────────────┘
                   │ HTTP/REST
                   ▼
┌─────────────────────────────────────────────────────┐
│         APPLICATION LAYER - MCP Client              │
│  • OpenAI Agent (GPT-4)                            │
│  • Strategic reasoning and planning                 │
│  • Tool orchestration and sequencing               │
│  • Result synthesis                                 │
└──────────────────┬──────────────────────────────────┘
                   │ MCP Protocol
                   ▼
┌─────────────────────────────────────────────────────┐
│         SERVICE LAYER - MCP Server (FastMCP)        │
│  Tools:                                             │
│  • validate_company()                              │
│  • identify_sector()                               │
│  • identify_competitors()                          │
│  • browse_page()                                   │
│  • generate_report()                               │
│                                                     │
│  External Services:                                │
│  • DuckDuckGo API                                 │
│  • HTTP/BeautifulSoup scraping                    │
│  • OpenAI API (GPT-4)                             │
└─────────────────────────────────────────────────────┘

---

Component Details

1. Presentation Layer (app.py)

Gradio Interface

• User-friendly web UI
• Input validation
• Output formatting
• Error messaging

# Example flow
User Input: "Tesla"
    ↓
Validate inputs
    ↓
Call MCP Client.analyze_company()
    ↓
Display Markdown report

2. Application Layer (mcp_client.py)

MCP Client with OpenAI Agent

The client implements:

• System Prompt: Defines agent role and goals
• Message History: Maintains conversation context
• Tool Calling: Translates agent decisions to MCP calls
• Response Synthesis: Compiles results into reports

system_prompt = """
You are a competitive analysis expert.
Use available tools to:
1. Validate the company
2. Identify sector
3. Find competitors
4. Gather strategic data
5. Generate insights
"""

# Agent workflow:
messages = [
    {"role": "system", "content": system_prompt},
    {"role": "user", "content": "Analyze Sony"}
]

response = client.chat.completions.create(
    model="gpt-4",
    messages=messages
)
# OpenAI returns tool calls, which we execute

Key Features:

• Graceful fallback to simple analysis when MCP unavailable
• Handles API errors and timeouts
• Synthesizes multiple tool results

3. Service Layer (mcp_server.py)

FastMCP Server with Tools

Tools Overview

Tool	Purpose	Returns
validate_company(name)	Check if company exists	Bool + evidence
identify_sector(name)	Find industry classification	Sector name
identify_competitors(sector, company)	Discover top 3 rivals	"Comp1, Comp2, Comp3"
browse_page(url, instructions)	Extract webpage content	Relevant text
generate_report(company, context)	Create analysis report	Markdown report

Tool Implementation Pattern

@mcp.tool()
def validate_company(company_name: str) -> str:
    """
    Docstring: Describes tool purpose and parameters
    """
    # Implementation
    try:
        results = web_search_tool(f"{company_name} company")
        evidence_count = analyze_search_results(results)
        return validation_result
    except Exception as e:
        return f"Error: {str(e)}"

Web Search Integration

from duckduckgo_search import DDGS

def web_search_tool(query: str) -> str:
    """Unified search interface for all tools"""
    with DDGS() as ddgs:
        results = list(ddgs.text(query, max_results=5))
    return format_results(results)

---

Message Flow

Complete Analysis Request

1. USER INTERFACE (Gradio)
   │
   ├─ Company: "Apple"
   └─ OpenAI Key: "sk-..."
   
2. GRADIO → MCP CLIENT
   │
   ├─ analyze_competitor_landscape("Apple", api_key)
   │
   └─ Creates CompetitiveAnalysisAgent instance
   
3. MCP CLIENT → OPENAI
   │
   ├─ System: "You are a competitive analyst..."
   ├─ User: "Analyze Apple's competitors"
   │
   ├─ OpenAI responds with:
   │  └─ "Call validate_company('Apple')"
   
4. MCP CLIENT → MCP SERVER
   │
   ├─ Calls: validate_company("Apple")
   ├─ Calls: identify_sector("Apple")
   ├─ Calls: identify_competitors("Technology", "Apple")
   │
   └─ Receives results for each tool
   
5. MCP SERVER
   │
   ├─ validate_company()
   │  └─ Web search → DuckDuckGo API → Parse results
   │
   ├─ identify_sector()
   │  └─ Multi-stage search → Keyword analysis → Return sector
   │
   ├─ identify_competitors()
   │  └─ Industry search → Competitor extraction → Ranking
   │
   └─ generate_report()
      └─ Format results → Markdown template → Return report
   
6. MCP CLIENT SYNTHESIS
   │
   ├─ Compile all tool results
   ├─ Add OpenAI insights
   └─ Return complete report
   
7. GRADIO DISPLAY
   │
   └─ Render Markdown report to user

---

Data Flow Diagram

USER INPUT
    │
    ├─ company_name: "Company X"
    └─ api_key: "sk-xxx"
    │
    ▼
┌──────────────────────┐
│   Input Validation   │
│  (Length, Format)    │
└──────────┬───────────┘
           │
           ▼
┌──────────────────────────────┐
│   OpenAI Agent Planning      │
│  (System + User Messages)    │
└──────────┬───────────────────┘
           │
           ├─────────────────────────────┬─────────────────────────┬──────────────┐
           │                             │                         │              │
           ▼                             ▼                         ▼              ▼
    ┌────────────────┐         ┌──────────────────┐      ┌──────────────┐   ┌─────────┐
    │ validate_      │         │ identify_        │      │ identify_    │   │ browse_ │
    │ company()      │         │ sector()         │      │ competitors()│   │ page()  │
    └────────┬───────┘         └────────┬─────────┘      └──────┬───────┘   └────┬────┘
             │                         │                       │                  │
             ▼                         ▼                       ▼                  ▼
       ┌──────────────┐         ┌─────────────┐         ┌────────────┐     ┌──────────┐
       │ Web Search   │         │ Web Search  │         │ Web Search │     │ HTTP Get │
       │ DuckDuckGo   │         │ Multi-stage │         │ Industry   │     │ Parse    │
       │ + Analysis   │         │             │         │ Leaders    │     │ HTML     │
       └──────┬───────┘         └──────┬──────┘         └─────┬──────┘     └────┬─────┘
              │                       │                      │                  │
              ▼                       ▼                      ▼                  ▼
         VALIDATION  →  SECTOR ID  →  COMPETITORS  →  ADDITIONAL DATA
              │              │              │                  │
              └──────────────┴──────────────┴──────────────────┘
                             │
                             ▼
                    ┌─────────────────────┐
                    │  generate_report()  │
                    │  (Compile results)  │
                    └────────┬────────────┘
                             │
                             ▼
                    ┌─────────────────────┐
                    │  OpenAI Final       │
                    │  Synthesis          │
                    └────────┬────────────┘
                             │
                             ▼
                     FINAL REPORT
                    (Markdown format)

---

Tool Implementation Details

Tool 1: validate_company()

# Multi-stage validation
search_results = web_search_tool("Tesla company business official site")

# Evidence signals:
✓ Official website found (.com/.io)
✓ "Official site" or "official website" mention
✓ Company + sector description
✓ Business terminology present
✓ Wikipedia/news mentions

# Result: Evidence count >= 2 → Valid company

Tool 2: identify_sector()

# Three search strategies:
1. "What does Tesla do?" → Extract sector keywords
2. "Tesla industry type" → Direct classification
3. "Tesla sector news" → Financial/news sources

# Sector patterns:
{
  "Technology": ["software", "hardware", "cloud", "ai", ...],
  "Finance": ["banking", "fintech", "insurance", ...],
  "Manufacturing": ["automotive", "industrial", ...],
  ...
}

# Weighted voting to determine primary sector

Tool 3: identify_competitors()

# Search strategy:
1. "Top technology companies" → Market leaders
2. "Tesla competitors" → Direct rivals
3. "EV industry leaders" → Sector players

# Extraction methods:
- Pattern matching for company names
- List parsing (comma-separated, bulleted)
- Frequency analysis and ranking

# Returns: Top 3 ranked competitors

Tool 4: browse_page()

# Content extraction workflow:
requests.get(url) 
  → BeautifulSoup parsing
  → Remove scripts/styles/headers/footers
  → Extract main content divs/articles/paragraphs
  → Keyword matching against instructions
  → Return top N relevant sentences

# Safety: Timeout=10s, max_content=5000 chars

Tool 5: generate_report()

# Template-based report generation
report = f"""
# Competitive Analysis Report: {company_name}

## Executive Summary
[Synthesized findings]

## Competitor Comparison
| Competitor | Strategy | Pricing | Products | Market |
|------------|----------|---------|----------|--------|
| [extracted competitors] | - | - | - | - |

## Strategic Insights
[Recommendations]
"""

---

Error Handling Strategy

Layered Error Handling

Layer 1: Input Validation (Gradio)
  └─ Check company name length
  └─ Validate API key format
  └─ Return user-friendly error

Layer 2: Tool Execution (MCP Server)
  └─ Try/except on each tool
  └─ Timeout protection (10s requests)
  └─ Graceful degradation
  └─ Log detailed errors

Layer 3: Agent Logic (MCP Client)
  └─ API timeout handling
  └─ Rate limit handling
  └─ Fallback to simple analysis
  └─ Return partial results

Layer 4: User Feedback (Gradio)
  └─ Display error with context
  └─ Suggest remediation
  └─ Allow retry

---

Performance Optimization

Caching Strategy

# Web search results cached for 5 minutes
# Sector identify, re-used across tools
# Competitor list, reused in reports

Parallel Tool Execution

# Future enhancement: Run independent tools in parallel
validate_company() (parallel)
identify_sector()  (parallel)
identify_competitors() (sequential, depends on sector)

Rate Limiting

# DuckDuckGo: 2.0 second delays between searches
# OpenAI: Batched requests, monitoring quota
# HTTP: 10-second timeout, connection pooling

---

Security Considerations

API Key Handling

# Keys accepted via:
✓ UI input field (temporary in memory)
✗ NOT stored in files
✗ NOT logged in output
✗ NOT persisted in database

# Environment variables optional:
Optional: Load from .env via python-dotenv

Data Privacy

# Web search results: Temporary, discarded after analysis
# Company data: Not cached or stored
# User queries: Not logged or tracked
# Report generation: All local processing

Web Scraping Safety

# User-Agent provided (genuine browser identification)
# Robots.txt respected (DuckDuckGo + BeautifulSoup)
# Timeout protection (10 seconds)
# Error handling for blocked requests

---

Extension Points

Adding New Tools

@mcp.tool()
def custom_tool(param1: str, param2: int) -> str:
    """
    Your custom tool description.
    Args:
        param1: Parameter 1 description
        param2: Parameter 2 description
    Returns:
        str: Result description
    """
    try:
        # Implementation
        result = some_operation(param1, param2)
        return result
    except Exception as e:
        return f"Error: {str(e)}"

Modifying Agent Behavior

# In mcp_client.py, edit system_prompt:
system_prompt = """
Updated instructions for agent behavior
"""

# Or add initial human message:
messages.append({
    "role": "user",
    "content": "Additional analysis request..."
})

Customizing Report Generation

# In mcp_server.py, edit generate_report() template:
report = f"""
# Custom Report Format

Your custom structure here...
"""

---

Testing

Manual Testing

# Test MCP Server
python mcp_server.py

# Test MCP Client functions
python -c "from mcp_client import analyze_competitor_landscape; print(analyze_competitor_landscape('Microsoft', 'sk-...'))"

# Test Gradio UI
python app.py
# Navigate to http://localhost:7860

Validation Tests

# Test validate_company()
assert "VALID" in validate_company("Google")
assert "NOT" in validate_company("FakeCompanyXYZ123")

# Test identify_sector()
assert "Technology" in identify_sector("Microsoft")
assert "Finance" in identify_sector("JPMorgan")

# Test competitor discovery
competitors = identify_competitors("Technology", "Google")
assert len(competitors) <= 3

---

Future Enhancements

1. Real-time Market Data: Integrate financial APIs (Alpha Vantage, etc.)
2. Sentiment Analysis: Analyze news sentiment about companies
3. Patent Analysis: Include R&D insights from patents
4. Social Media: Monitor competitor social media activity
5. Pricing Intelligence: Track price changes over time
6. SWOT Matrix: Generate structured SWOT analysis
7. Visualization: Create charts and graphs
8. PDF Export: Generate PDF reports
9. Multi-company Batch: Analyze multiple companies
10. Integration APIs: Connect to Slack, Salesforce, etc.

---

Conclusion

The MCP architecture provides:

• ✅ Modularity and extensibility
• ✅ Clear separation of concerns
• ✅ Robust error handling
• ✅ Scalability for future enhancements
• ✅ Production-ready design
• ✅ Easy tool management

This design enables rapid development, maintenance, and deployment of AI-powered competitive analysis systems.

---

Document Version: 1.0
Last Updated: March 2026