# ziruiwang1996/ai-agent-mcp architecture

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

- Interactive diagram: https://gitdiagram.com/ziruiwang1996/ai-agent-mcp
- Repository: https://github.com/ziruiwang1996/ai-agent-mcp

## Overview

##### Project Type and Purpose
- This is a full-stack, modular AI agent framework.
- Frontend: Streamlit web UI.
- Backend: FastAPI service exposing chatbot endpoints.
- LLM Host: Gemini (and future HuggingFace) chatbot wrappers.
- Tool/Service Layer: A set of MCP microservices (arXiv, OpenFDA, ClinicalTrials, PDB, filesystem, etc.).
- Purpose: Enable tool-augmented reasoning by combining LLMs + external data sources via the Model Context Protocol.

##### Main Components
A. Streamlit Frontend
– File: streamlit_app/home_page.py
– Role: User interacts via a browser; sends chat messages.
B. FastAPI Backend
– File: src/fastapi_app.py
– Role: HTTP API gateway between UI and chatbot host.
C. Chatbot Host Layer
– Files: src/host/gemini_chatbot.py (and future HuggingFace_LLM.py)
– Role: Wraps LLM calls, manages conversation state.
D. Chatbot Client/Tool Manager
– File: src/client/gemini_client.py & server_config.json
– Role: Reads MCP server configuration; launches/manages subprocesses for each tool.
E. MCP Microservices
– Directory: src/mcp-server/
– Servers: arxiv_server.py, clinicaltrials_server.py, openfda_server.py, pdb_server.py (plus future rdkit, pubmed, filesystem via Node.js)
– Role: Provide external data/tool functionality via a simple protocol.
F. External Dependencies & Config
– .env (API keys), requirements.txt, Dockerfile (optional containerization), etc/jupyter and share/jupyter (Jupyter extensions)

##### Relationships & Data Flows
- User → Streamlit UI: user submits query.
- Streamlit UI → FastAPI: REST call (e.g. POST /chat).
- FastAPI → Host Chatbot: passes user message to gemini_chatbot.
- Host → Client/Tool Manager: invokes MCP tools via subprocesses per server_config.json.
- Client → MCP Servers: starts subprocesses (Python scripts or npx commands).
- MCP Servers → External APIs/Data Sources: each microservice queries its designated API or filesystem.
- Results flow back: MCP Servers → Client → Host → FastAPI → Streamlit → User.

##### Architectural Patterns & Design Principles
- Layered Architecture: UI / API / Host / Tool Manager / Microservices
- Plugin-style / Microservices: each MCP server is a self-contained process.
- Configuration-driven: server_config.json drives tool instantiation.
- Separation of concerns: LLM logic separated from tool logic.
- Incremental streaming: both Streamlit and FastAPI can stream partial responses for a responsive UX.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Frontend Layer
    subgraph "Frontend Layer"
        Streamlit["Streamlit UI\n(Python + Streamlit)"]:::ui
    end

    %% API Layer
    subgraph "API Layer"
        FastAPIApp["FastAPI App\n(Python + Uvicorn)"]:::api
    end

    %% Host Layer
    subgraph "Host Layer"
        GeminiChatbot["Gemini Chatbot Host\n(LLM API)"]:::host
    end

    %% Tool Manager Layer
    subgraph "Tool Manager Layer"
        ToolManager["MCP Tool Manager\n(JSON config, subprocess)"]:::tool
        ServerConfig["server_config.json"]:::config
    end

    %% Microservices Layer
    subgraph "MCP Microservices"
        arxiv["arXiv Server"]:::micro
        clinicaltrials["ClinicalTrials Server"]:::micro
        openfda["OpenFDA Server"]:::micro
        pdbServer["PDB Server"]:::micro
    end

    %% External Systems
    subgraph "External Systems"
        ExternalAPIs["External APIs / Filesystem"]:::external
        Dockerfile["Dockerfile"]:::config
        Requirements["requirements.txt"]:::config
        JupyterEtc["etc/jupyter"]:::config
        JupyterShare["share/jupyter"]:::config
    end

    %% Connections
    Streamlit -->|"POST/chat"| FastAPIApp
    FastAPIApp -->|"invokeChatbot"| GeminiChatbot
    GeminiChatbot -->|"readsConfig & spawn"| ToolManager
    ServerConfig -.->|"readBy"| ToolManager
    ToolManager -->|"spawn subprocess"| arxiv
    ToolManager -->|"spawn subprocess"| clinicaltrials
    ToolManager -->|"spawn subprocess"| openfda
    ToolManager -->|"spawn subprocess"| pdbServer

    arxiv -->|"queryExternal"| ExternalAPIs
    clinicaltrials -->|"queryExternal"| ExternalAPIs
    openfda -->|"queryExternal"| ExternalAPIs
    pdbServer -->|"queryExternal"| ExternalAPIs

    ExternalAPIs -->|"returnData"| arxiv
    ExternalAPIs -->|"returnData"| clinicaltrials
    ExternalAPIs -->|"returnData"| openfda
    ExternalAPIs -->|"returnData"| pdbServer

    arxiv -->|"toolResult"| ToolManager
    clinicaltrials -->|"toolResult"| ToolManager
    openfda -->|"toolResult"| ToolManager
    pdbServer -->|"toolResult"| ToolManager

    ToolManager -->|"toolOutput"| GeminiChatbot
    GeminiChatbot -->|"streamResponse"| FastAPIApp
    FastAPIApp -->|"streamResponse"| Streamlit

    %% Click Events
    click Streamlit "https://github.com/ziruiwang1996/ai-agent-mcp/blob/main/streamlit_app/home_page.py"
    click FastAPIApp "https://github.com/ziruiwang1996/ai-agent-mcp/blob/main/src/fastapi_app.py"
    click GeminiChatbot "https://github.com/ziruiwang1996/ai-agent-mcp/blob/main/src/host/gemini_chatbot.py"
    click ToolManager "https://github.com/ziruiwang1996/ai-agent-mcp/blob/main/src/client/gemini_client.py"
    click ServerConfig "https://github.com/ziruiwang1996/ai-agent-mcp/blob/main/src/client/server_config.json"
    click arxiv "https://github.com/ziruiwang1996/ai-agent-mcp/blob/main/src/mcp-server/arxiv_server.py"
    click clinicaltrials "https://github.com/ziruiwang1996/ai-agent-mcp/blob/main/src/mcp-server/clinicaltrials_server.py"
    click openfda "https://github.com/ziruiwang1996/ai-agent-mcp/blob/main/src/mcp-server/openfda_server.py"
    click pdbServer "https://github.com/ziruiwang1996/ai-agent-mcp/blob/main/src/mcp-server/pdb_server.py"
    click Dockerfile "https://github.com/ziruiwang1996/ai-agent-mcp/tree/main/Dockerfile"
    click Requirements "https://github.com/ziruiwang1996/ai-agent-mcp/blob/main/requirements.txt"
    click JupyterEtc "https://github.com/ziruiwang1996/ai-agent-mcp/tree/main/etc/jupyter"
    click JupyterShare "https://github.com/ziruiwang1996/ai-agent-mcp/tree/main/share/jupyter"

    %% Styles
    classDef ui fill:#87CEFA,stroke:#333,stroke-width:1px;
    classDef api fill:#98FB98,stroke:#333,stroke-width:1px;
    classDef host fill:#2ECC71,stroke:#333,stroke-width:1px;
    classDef tool fill:#F39C12,stroke:#333,stroke-width:1px;
    classDef micro fill:#F1C40F,stroke:#333,stroke-width:1px;
    classDef config fill:#D35400,stroke:#333,stroke-width:1px;
    classDef external fill:#95A5A6,stroke:#333,stroke-width:1px;
```
