# ishwanku/mcp-agent-demo architecture

> Architecture diagram of the GitHub repository ishwanku/mcp-agent-demo, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-04). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ishwanku/mcp-agent-demo
- Repository: https://github.com/ishwanku/mcp-agent-demo

## Overview

##### Main Components
- run.py (Entry point / bootstrap)
- Demo Agent (mcp/agents/demo_agent.py)
- Core Server (mcp/core/server.py using FastAPI + Uvicorn)
- Configuration (mcp/core/config.py with Pydantic + .env)
- Tools
– Email File Tool (mcp/tools/email_file_tool.py)
– Email Tool (mcp/tools/email_tool.py)
- External System: Microsoft Outlook via COM Automation
- Client: send_email.py (HTTP client sending sample_email.txt)

##### Relationships and Data Flows
1. run.py
– Sets up virtual environment & dependencies (pyproject.toml, setup.py)
– Launches demo_agent.py
2. demo_agent.py
– Initializes Config (reads .env via config.py)
– Creates FastAPI app and Uvicorn server (via server.py)
– Registers Email File Tool and Email Tool as API endpoints (plugin pattern)
3. send_email.py (Client)
– Reads sample_email.txt
– Sends HTTP POST → FastAPI endpoint (/tools/send_email_from_file)
4. server.py (FastAPI + Uvicorn)
– Authenticates API key
– Routes request to Email File Tool handler
5. email_file_tool.py
– Parses the email file (recipients, subject, body, attachments)
– Validates data
– Calls email_tool.send_email(...)
6. email_tool.py
– Checks/starts Outlook via COM automation
– Composes email (TO/CC/BCC, attachments)
– Sends via Outlook
– Returns status/log

##### Architectural Patterns & Design Principles
- Plugin / Component registration: demo_agent dynamically registers tools as API endpoints
- Separation of concerns:
– Configuration (config.py)
– Server layer (server.py)
– Business logic: parsing vs. email composition
- Use of FastAPI for HTTP microservice interface
- Pydantic for strongly-typed configuration settings
- External integration abstracted behind tool interface

##### Relevant Technologies, Frameworks & Libraries
- Python 3.9+
- FastAPI + Uvicorn
- Pydantic (configuration management)
- python-dotenv (.env support)
- pywin32 or comtypes (Outlook COM automation)
- Standard library for file I/O and logging

##### Additional Details to Capture
- .env/config loading before server startup
- Health-check endpoint on FastAPI (e.g., GET /health)
- Logging flow: which component logs which events
- Python package installation step (pip install -e .) as part of bootstrapping (optional)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Bootstrapping Components
    run["run.py"]:::bootstrap
    pyproj["pyproject.toml"]:::bootstrap
    setup["setup.py"]:::bootstrap

    demo["mcp/agents/demo_agent.py"]:::bootstrap
    config["mcp/core/config.py"]:::config
    server["mcp/core/server.py"]:::api
    emailFile["mcp/tools/email_file_tool.py"]:::tool
    emailTool["mcp/tools/email_tool.py"]:::tool

    %% Client & Payload
    client["send_email.py"]:::client
    sample["sample_email.txt"]:::client

    %% External System
    outlook["Microsoft Outlook (COM)"]:::external

    %% Bootstrapping Flow
    pyproj -->|"dependencies"| run
    setup -->|"install script"| run
    run -->|"bootstrap & launch"| demo

    %% Agent Initialization
    demo -->|"loads .env config"| config
    demo -->|"registers tools"| server
    demo -->|"starts FastAPI"| server

    %% Configuration Usage
    config -->|"provides settings"| server

    %% Client Request Flow
    sample -->|"reads payload"| client
    client -->|"HTTP POST /tools/send_email_from_file"| server
    server -->|"authenticate API key"| server
    server -->|"dispatch request"| emailFile

    %% Tool Processing Flow
    emailFile -->|"parse & validate file"| emailTool
    emailTool -->|"COM call to Outlook"| outlook
    emailTool -->|"return status/log"| server

    %% Response Flow
    server -->|"HTTP 200 JSON"| client

    %% Click Events
    click run "https://github.com/ishwanku/mcp-agent-demo/blob/main/run.py"
    click demo "https://github.com/ishwanku/mcp-agent-demo/blob/main/mcp/agents/demo_agent.py"
    click config "https://github.com/ishwanku/mcp-agent-demo/blob/main/mcp/core/config.py"
    click server "https://github.com/ishwanku/mcp-agent-demo/blob/main/mcp/core/server.py"
    click emailFile "https://github.com/ishwanku/mcp-agent-demo/blob/main/mcp/tools/email_file_tool.py"
    click emailTool "https://github.com/ishwanku/mcp-agent-demo/blob/main/mcp/tools/email_tool.py"
    click client "https://github.com/ishwanku/mcp-agent-demo/blob/main/send_email.py"
    click sample "https://github.com/ishwanku/mcp-agent-demo/blob/main/sample_email.txt"
    click pyproj "https://github.com/ishwanku/mcp-agent-demo/blob/main/pyproject.toml"
    click setup "https://github.com/ishwanku/mcp-agent-demo/blob/main/setup.py"

    %% Styles
    classDef bootstrap fill:#FFDDC1,stroke:#E35D6A;
    classDef config fill:#D1E8E4,stroke:#2E8B57;
    classDef api fill:#CDE2FF,stroke:#1E90FF;
    classDef tool fill:#FFF4B2,stroke:#DAA520;
    classDef client fill:#F0F0F0,stroke:#808080;
    classDef external fill:#E8D1D1,stroke:#A52A2A;
```
