ARCHITECTURE.md

EcoMCP Architecture Guide

Project Structure

ecomcp/
├── src/
│   ├── __init__.py
│   ├── config.py              # Centralized configuration
│   ├── constants.py           # Constants and enums
│   ├── errors.py              # Custom exceptions
│   ├── logger.py              # Logging configuration
│   │
│   ├── server/                # MCP Server
│   │   ├── __init__.py
│   │   └── mcp_server.py      # JSON-RPC MCP server
│   │
│   ├── ui/                    # Gradio UI Layer
│   │   ├── __init__.py
│   │   ├── app.py             # Main Gradio application
│   │   ├── components.py      # UI handlers & callbacks
│   │   └── formatters.py      # HTML/Markdown formatters
│   │
│   ├── clients/               # MCP Client
│   │   ├── __init__.py
│   │   └── mcp_client.py      # JSON-RPC client
│   │
│   └── core/                  # Business Logic
│       ├── __init__.py
│       ├── knowledge_base.py  # LlamaIndex KB
│       ├── llama_integration.py # KB integration
│       ├── document_loader.py # Document handling
│       ├── vector_search.py   # Semantic search
│       ├── response_models.py # Response schemas
│       ├── validators.py      # Input validation
│       ├── examples.py        # Usage examples
│       └── async_knowledge_base.py # Async KB
│
├── app/                       # Optional app deployment
├── tests/                     # Test suite
├── docs/                      # Documentation
├── scripts/                   # Utility scripts
├── config.yaml               # YAML configuration
├── requirements.txt          # Python dependencies
├── .env.example             # Environment template
├── Dockerfile               # Container image
├── Makefile                 # Build commands
└── README.md               # Project readme

Module Responsibilities

Core Application

src/config.py - Configuration Management

• Centralized config with environment variable support
• Pydantic validation for all settings
• Singleton pattern for global access
• Easy override for testing

src/constants.py - Application Constants

• Enums for categories, styles, search types
• Tool names and MCP constants
• Validation constraints
• Error codes

src/errors.py - Error Handling

• Custom exception hierarchy
• Structured error responses
• Error formatting utilities
• Detailed error tracking

src/logger.py - Logging

• Colored console output
• File logging support
• Module-level loggers
• Centralized configuration

Server Layer

src/server/mcp_server.py - MCP Server Implementation

• JSON-RPC 2.0 protocol handler
• Tool registration and dispatching
• Input validation integration
• OpenAI API integration
• Knowledge base integration

src/clients/mcp_client.py - MCP Client

• Subprocess-based server communication
• JSON-RPC message handling
• Async request/response handling
• Automatic server startup

UI Layer

src/ui/app.py - Gradio Application

• Tab-based interface layout
• Responsive design with CSS
• Example inputs and outputs
• Knowledge search integration
• About page with feature showcase

src/ui/components.py - UI Handlers

• Tool call handlers
• Sync/async bridge for Gradio
• Input validation and feedback
• Response formatting
• Error handling and display

src/ui/formatters.py - Output Formatting

• HTML sentiment charts
• Pricing tier visualizations
• Markdown formatting helpers
• Responsive design utilities

Core Business Logic

src/core/knowledge_base.py - Knowledge Base Core

• LlamaIndex integration
• Document indexing pipeline
• Vector store management
• Retrieval and query engines
• Persistence layer

src/core/llama_integration.py - High-Level KB API

• Simplified knowledge base interface
• Document loading orchestration
• Search and query wrappers
• Global instance management

src/core/document_loader.py - Document Processing

• Multi-format support (MD, TXT, JSON, PDF)
• Product document creation
• URL document loading
• Metadata extraction

src/core/vector_search.py - Search Engine

• Semantic similarity search
• Hierarchical search across types
• Weighted result combination
• Contextual filtering
• Recommendation engine

src/core/response_models.py - API Schemas

• Pydantic response models
• Consistent API contracts
• Type safety and validation
• Helper functions

src/core/validators.py - Input Validation

• Tool-specific validators
• Pydantic-based validation
• Constraint enforcement
• Detailed error messages

Data Flow

User Request → Response

UI (Gradio)
    ↓
components.py (Handler)
    ↓
mcp_client.py (JSON-RPC)
    ↓
mcp_server.py (Server)
    ├→ validators.py (Validation)
    ├→ OpenAI API / Knowledge Base (Processing)
    └→ response_models.py (Format)
    ↓
mcp_client.py (Response)
    ↓
formatters.py (HTML/Markdown)
    ↓
UI (Gradio Display)

Tool Execution Flow

Tool Request
    ↓
Input Validation (validators.py)
    ↓ (if valid)
Tool Dispatch (mcp_server.call_tool)
    ↓
Tool Handler (_analyze_product, etc.)
    ├→ Prepare prompt/args
    ├→ Call OpenAI API or KB
    ├→ Format response
    └→ Return result
    ↓
Success Response

Key Design Patterns

1. Centralized Configuration

• All settings in config.py
• Environment variable driven
• Easy for deployment and testing
• Singleton access pattern

2. Input Validation

• Pydantic-based validators
• Tool-specific validation rules
• Early rejection of invalid input
• Detailed error feedback

3. Error Handling

• Custom exception hierarchy
• Structured error responses
• Consistent error format
• Detailed logging

4. Async/Sync Bridge

• Async server and client
• Sync Gradio UI
• Helper for bridging contexts
• Non-blocking I/O throughout

5. Modular Organization

• Clear separation of concerns
• Single responsibility principle
• Easy to test and maintain
• Reusable components

Integration Points

OpenAI API

• Configured via environment variable
• Used by all analysis tools
• JSON streaming for responses
• Error handling with retries

LlamaIndex Knowledge Base

• Optional integration (graceful degradation)
• Supports multiple vector stores (in-memory, Pinecone)
• Document ingestion pipeline
• Semantic search and Q&A

Gradio UI

• Web-based interface
• Real-time updates
• Example inputs
• Responsive design

Environment Setup

Required Variables

OPENAI_API_KEY          # OpenAI API key

Optional Variables

PINECONE_API_KEY        # For Pinecone vector store
USE_PINECONE            # Enable Pinecone backend
OPENAI_MODEL            # Model name (default: gpt-5)
LOG_LEVEL               # Logging level (default: INFO)

Configuration Override

Via .env file

OPENAI_API_KEY=sk-...
OPENAI_MODEL=gpt-5

Via Environment

export OPENAI_API_KEY=sk-...
python run_ui.py

Via Code

from src.config import AppConfig, initialize_config

config = AppConfig(
    openai_api_key="sk-...",
    openai_model="gpt-5"
)
initialize_config(config)

Testing Strategy

Unit Tests

• Validators: test constraint enforcement
• Formatters: test HTML/Markdown output
• Components: test handler logic

Integration Tests

• Server: test tool execution
• Client: test request/response
• UI: test callbacks and formatting

End-to-End Tests

• Full request flow
• Knowledge base integration
• Error handling

Deployment Considerations

Docker

• See Dockerfile for containerization
• Environment variables passed at runtime
• Port mapping for Gradio (7860)

Scaling

• Stateless design allows horizontal scaling
• Knowledge base can use Pinecone for scale
• OpenAI API for distributed inference

Monitoring

• Structured logging for all operations
• Error tracking and logging
• Performance metrics via logging timestamps

Future Enhancements

1. Database Integration - Store results and history
2. Authentication - User and API key management
3. Rate Limiting - Handle API quotas
4. Caching - Cache responses for repeated queries
5. Webhooks - Async processing callbacks
6. Batch Processing - Handle multiple requests
7. Advanced Analytics - Track usage and metrics