docs/STRUCTURE.md

EcoMCP Project Structure

Overview

EcoMCP has been reorganized into a clean, modular architecture with clear separation of concerns.

ecomcp/
 src/                          # Main source code
    __init__.py
    ui/                       # Gradio UI components
       __init__.py
       app.py               # Main Gradio application
       components.py        # Reusable UI components and handlers
    server/                  # MCP server implementation
       __init__.py
       mcp_server.py        # JSON-RPC MCP server
    clients/                 # Client implementations
       __init__.py
       mcp_client.py        # JSON-RPC client for server communication
    core/                    # Shared business logic (future)
        __init__.py

 run_ui.py                    # Entry point: Launch Gradio UI
 run_server.py                # Entry point: Launch MCP server standalone
 archive/                     # Old/deprecated files
 STRUCTURE.md                 # This file

Module Breakdown

src/ui/ - User Interface

• app.py: Main Gradio application with all tabs and interface
• components.py: Reusable UI components including:
  • ToolCallHandler: Handles all MCP tool calls with streaming
  • create_sentiment_chart_html(): HTML visualization for sentiment
  • create_pricing_tiers_html(): HTML visualization for pricing

src/server/ - MCP Server

• mcp_server.py: Implements JSON-RPC 2.0 MCP protocol
  • EcoMCPServer: Main server class
  • Tool implementations: analyze_product, analyze_reviews, generate_listing, price_recommendation

src/clients/ - Client Communication

• mcp_client.py: JSON-RPC client for communicating with MCP server
  • MCPClient: Handles server startup and message routing

src/core/ - Shared Logic

• Reserved for future shared utilities, data models, and business logic

Running the Application

Option 1: UI Only (Recommended)

python run_ui.py

Launches Gradio interface at http://localhost:7860 Automatically starts the MCP server as a subprocess

Option 2: Standalone Server

python run_server.py

Runs the MCP server listening for JSON-RPC messages on stdin/stdout

Option 3: Separate Processes

Terminal 1:

python run_server.py

Terminal 2:

python run_ui.py
# Update src/clients/mcp_client.py to use server socket instead of subprocess

Key Design Decisions

1. Modular Structure: Clear separation between UI, server, and client
2. Async Throughout: Uses asyncio for non-blocking I/O
3. Type Hints: All functions have type annotations for clarity
4. Reusable Components: UI components can be imported and reused
5. JSON-RPC 2.0: Industry-standard protocol for MCP communication

Adding New Tools

1. Add tool definition in EcoMCPServer._init_tools()
2. Implement tool handler method (e.g., _my_new_tool())
3. Add case in call_tool() method
4. Add UI method in src/ui/components.py ToolCallHandler
5. Add tab in src/ui/app.py

Migration from Old Structure

Old app files have been moved to archive/:

• app.py → archive/app.py
• app_enhanced.py → archive/app_enhanced.py
• ecomcp_app.py → archive/ecomcp_app.py
• etc.

The old files are kept for reference but should not be used.

Environment Variables

• OPENAI_API_KEY: Optional. For AI-powered analysis (defaults to smart fallback)
• GRADIO_SERVER_PORT: Gradio server port (default: 7860)

Next Steps

1. Extract database logic to src/core/database.py
2. Create src/core/prompts.py for all AI prompts
3. Add logging configuration to src/core/logging.py
4. Create test suite under tests/
5. Add configuration management to src/core/config.py