MCP Agentic AI Server

# 🔄 MCP Agentic AI Server - Workflow Diagrams This document contains comprehensive Mermaid diagrams illustrating all the workflows and processes in the MCP Agentic AI Server project. ## 📋 Table of Contents 1. [Overall System Workflow](#overall-system-workflow) 2. [Custom MCP Server Workflow](#custom-mcp-server-workflow) 3. [Public MCP Server Workflow](#public-mcp-server-workflow) 4. [Streamlit Dashboard Workflow](#streamlit-dashboard-workflow) 5. [Tool Integration Workflow](#tool-integration-workflow) 6. [Statistics Tracking Workflow](#statistics-tracking-workflow) 7. [Error Handling Workflow](#error-handling-workflow) 8. [User Interaction Workflow](#user-interaction-workflow) 9. [AI Processing Workflow](#ai-processing-workflow) 10. [Deployment Workflow](#deployment-workflow) --- ## 🌐 Overall System Workflow ```mermaid %%{init: {'theme': 'neo'}}%% graph TB A[👤 User] ==> B[🎨 Streamlit Dashboard] B ==> C{🔀 Server Selection} C ==> |Custom Tasks| D[🔧 Custom MCP Server<br/>Port 8000] C ==> |Direct Queries| E[🌐 Public MCP Server<br/>Port 8001] D ==> F[📋 Task Creation] F ==> G[🆔 Generate UUID] G ==> H[💾 Store Task] H ==> I[🔄 Task Execution] I ==> J{🛠️ Tools Required?} J ==> |Yes| K[🔧 Execute Tools] J ==> |No| L[🤖 Direct AI Call] K ==> L L ==> M[🧠 Google Gemini API] M ==> N[📊 Update Statistics] N ==> O[📤 Return Response] E ==> P[🤖 Direct AI Processing] P ==> M O ==> B P ==> Q[📊 Update Public Stats] Q ==> B classDef sky fill:#e1f5fe,stroke:#039be5,stroke-width:3px,color:#000 classDef purple fill:#f3e5f5,stroke:#8e24aa,stroke-width:3px,color:#000 classDef green fill:#e8f5e8,stroke:#43a047,stroke-width:3px,color:#000 classDef yellow fill:#fff3e0,stroke:#fbc02d,stroke-width:3px,color:#000 classDef rose fill:#ffebee,stroke:#d32f2f,stroke-width:3px,color:#000 class A sky class B purple class C yellow class D,F,G,H,I,J,K green class E,P,Q yellow class L,M,N,O rose ``` --- ## 🔧 Custom MCP Server Workflow ```mermaid %%{init: {'theme': 'neo'}}%% sequenceDiagram participant U as 👤 User participant D as 🎨 Dashboard participant S as 🔧 Custom Server participant C as 📋 Controller participant T as 🛠️ Tools participant AI as 🧠 Gemini API participant DB as 💾 Task Store U->>D: Enter task input & select tools D->>S: POST /task {input, tools} S->>C: create_task(input, tools) C->>DB: Generate UUID & store task C->>S: Return task_id S->>D: {task_id: "uuid"} D->>S: POST /task/{task_id}/run S->>C: run(task_id) C->>DB: Retrieve task data alt Tools specified C->>T: Execute specified tools T->>C: Return processed input end C->>AI: Generate content with processed input AI->>C: AI response C->>C: Update statistics C->>S: Return result S->>D: {task_id, output} D->>U: Display result ``` --- ## 🌐 Public MCP Server Workflow ```mermaid %%{init: {'theme': 'neo'}}%% sequenceDiagram participant U as 👤 User participant D as 🎨 Dashboard participant S as 🌐 Public Server participant AI as 🧠 Gemini API participant ST as 📊 Statistics U->>D: Enter direct query D->>S: POST /ask {query} Note over S: Start timing & session tracking S->>ST: Increment active sessions S->>AI: Generate content with query alt Success AI->>S: AI response S->>ST: Update success count else Failure AI->>S: Error response S->>ST: Update failure count end S->>ST: Update response time & query count S->>D: {response} or {error} D->>U: Display result Note over S: End timing & session tracking S->>ST: Decrement active sessions ``` --- ## 🎨 Streamlit Dashboard Workflow ```mermaid %%{init: {'theme': 'neo'}}%% flowchart TD A([🚀 App Start]):::blue B([🎨 Load CSS Styles]):::purple C([📊 Initialize Stats Containers]):::yellow D([🔄 Main Loop Start]):::green E{{📡 Fetch Stats API}}:::yellow F([📊 Update Statistics Display]):::green G([⚠️ Show Default Values]):::rose H([🎛️ Render UI Components]):::purple I([📝 Server Selection Radio]):::blue J{{🔀 Server Type?}}:::yellow K([📋 Task Input Form]):::green L([💬 Query Input Form]):::green M([🛠️ Tool Selection]):::orange N([▶️ Submit Button]):::green O{{📤 Form Submitted?}}:::yellow P([📡 API Call]):::purple Q([⏳ Wait for Input]):::blue R{{📊 API Response?}}:::yellow S([✅ Display Results]):::green T([❌ Display Error]):::rose U([🔄 Auto-refresh Stats]):::blue V([⏱️ Wait 2 seconds]):::purple A --> B B --> C C --> D D --> E E -- Success --> F E -- Failure --> G F --> H G --> H H --> I I --> J J -- Custom --> K J -- Public --> L K --> M M --> N L --> N N --> O O -- Yes --> P O -- No --> Q P --> R R -- Success --> S R -- Error --> T S --> U T --> U Q --> U U --> V V --> D classDef blue fill:#e1f5fe,stroke:#039be5,stroke-width:3px,color:#000 classDef purple fill:#f3e5f5,stroke:#8e24aa,stroke-width:3px,color:#000 classDef green fill:#e8f5e8,stroke:#43a047,stroke-width:3px,color:#000 classDef yellow fill:#fff3e0,stroke:#fbc02d,stroke-width:3px,color:#000 classDef rose fill:#ffebee,stroke:#d32f2f,stroke-width:3px,color:#000 classDef orange fill:#ffb74d,stroke:#f57c00,stroke-width:3px,color:#000 ``` --- ## 🛠️ Tool Integration Workflow ```mermaid %%{init: {'theme': 'neo'}}%% flowchart LR A[📥 Task Input] ==> B{🔍 Tools Specified?} B ==> |No| C[🤖 Direct AI Processing] B ==> |Yes| D[📋 Parse Tools List] D ==> E[🔄 For Each Tool] E ==> F{🛠️ Tool Exists?} F ==> |Yes| G[⚙️ Execute Tool Function] F ==> |No| H[⚠️ Log Warning & Skip] G ==> I[📝 Process Tool Output] I ==> J[🔗 Chain to Next Tool] H ==> J J ==> K{🔚 More Tools?} K ==> |Yes| E K ==> |No| L[📤 Final Processed Input] L ==> M[🤖 AI Processing with Tool Results] C ==> M M ==> N[📊 Update Tool Usage Stats] N ==> O[📤 Return Final Response] classDef blue fill:#e1f5fe,stroke:#039be5,stroke-width:3px,color:#000 classDef green fill:#e8f5e8,stroke:#43a047,stroke-width:3px,color:#000 classDef yellow fill:#fff3e0,stroke:#fbc02d,stroke-width:3px,color:#000 classDef rose fill:#ffebee,stroke:#d32f2f,stroke-width:3px,color:#000 class A,B,D,E,F,G,I,J,K,L,M,N,O green class H rose class C blue ``` --- ## 📊 Statistics Tracking Workflow ```mermaid %%{init: {'theme': 'neo'}}%% flowchart TD S1([Idle]):::blue S2([Processing]):::green S3{{Need Tools?}}:::yellow S4([Tool Exec]):::green S5([AI Call]):::blue S6{{AI OK?}}:::yellow S7([Success]):::green S8([Failure]):::rose S9([Update Stats]):::purple S1 --> S2 --> S3 S3 -- Yes --> S4 --> S5 S3 -- No --> S5 S5 --> S6 S6 -- Yes --> S7 --> S9 --> S1 S6 -- No --> S8 --> S9 --> S1 classDef blue fill:#e1f5fe,stroke:#039be5,stroke-width:3px,color:#000 classDef green fill:#e8f5e8,stroke:#43a047,stroke-width:3px,color:#000 classDef yellow fill:#fff3e0,stroke:#fbc02d,stroke-width:3px,color:#000 classDef purple fill:#f3e5f5,stroke:#8e24aa,stroke-width:3px,color:#000 classDef rose fill:#ffebee,stroke:#d32f2f,stroke-width:3px,color:#000 ``` --- ## ⚠️ Error Handling Workflow ```mermaid %%{init: {'theme': 'neo'}}%% flowchart TD A[📥 Request Received] ==> B{🔍 Validation Check} B ==> |Invalid| C[❌ Return 400 Error] B ==> |Valid| D[⚙️ Process Request] D ==> E{🛠️ Tool Execution} E ==> |Tool Error| F[⚠️ Log Tool Error] E ==> |Tool Success| G[🤖 AI Processing] F ==> H[🔄 Continue Without Tool] H ==> G G ==> I{🧠 AI Response} I ==> |AI Error| J[❌ Log AI Error] I ==> |AI Success| K[✅ Success Response] J ==> L[📊 Update Failure Stats] L ==> M[🔄 Return Error Response] K ==> N[📊 Update Success Stats] N ==> O[📤 Return Success Response] C ==> P[📝 Log Request Error] M ==> Q[📝 Log Processing Error] P ==> R[📊 Update Error Metrics] Q ==> R classDef blue fill:#e1f5fe,stroke:#039be5,stroke-width:3px,color:#000 classDef green fill:#e8f5e8,stroke:#43a047,stroke-width:3px,color:#000 classDef yellow fill:#fff3e0,stroke:#fbc02d,stroke-width:3px,color:#000 classDef rose fill:#ffebee,stroke:#d32f2f,stroke-width:3px,color:#000 class A,B,D,E,G,I,K,N,O green class C,F,H,J,L,M,P,Q,R rose ``` --- ## 👤 User Interaction Workflow ```mermaid journey title User Journey Through MCP AI System section Discovery Open Dashboard: 5: User View Interface: 4: User Read Instructions: 3: User section Server Selection Choose Custom MCP: 5: User Choose Public MCP: 5: User Understand Difference: 4: User section Custom MCP Usage Enter Task Description: 5: User Select Tools: 4: User Submit Task: 5: User Wait for Processing: 3: User View Results: 5: User section Public MCP Usage Enter Direct Query: 5: User Submit Query: 5: User Get Instant Response: 5: User section Monitoring Check Statistics: 4: User Monitor Performance: 4: User Track Usage: 3: User section Advanced Usage Test Different Inputs: 4: User Compare Server Types: 4: User Optimize Queries: 5: User ``` --- ## 🧠 AI Processing Workflow ```mermaid %%{init: {'theme': 'neo'}}%% flowchart TD A([📥 Input Received]):::blue B([🔧 Preprocessing]):::green C{{🛠️ Tool Processing?}}:::yellow D([⚙️ Execute Tools]):::green E([📝 Format Prompt]):::purple F([🤖 Gemini API Call]):::rose G{{📡 API Response}}:::yellow H([📝 Extract Response Text]):::green I([⚠️ Handle API Error]):::rose J([🔍 Validate Response]):::blue K{{✅ Valid Response?}}:::yellow L([📤 Return Success]):::green M([🔄 Retry Logic]):::purple N{{🔢 Retry Count < Max?}}:::yellow O([❌ Return Failure]):::rose P([📝 Log Error Details]):::rose Q([📊 Update Success Metrics]):::blue R([📊 Update Failure Metrics]):::rose A --> B --> C C -- Yes --> D --> E C -- No --> E E --> F --> G G -- Success --> H --> J --> K G -- Error --> I --> P --> O K -- Yes --> L --> Q K -- No --> M --> N N -- Yes --> F N -- No --> O --> R classDef blue fill:#e1f5fe,stroke:#039be5,stroke-width:3px,color:#000 classDef green fill:#e8f5e8,stroke:#43a047,stroke-width:3px,color:#000 classDef yellow fill:#fff3e0,stroke:#fbc02d,stroke-width:3px,color:#000 classDef rose fill:#ffebee,stroke:#d32f2f,stroke-width:3px,color:#000 classDef purple fill:#f3e5f5,stroke:#8e24aa,stroke-width:3px,color:#000 ``` --- ## 🚀 Deployment Workflow (Flowchart Version) ```mermaid %%{init: {'theme': 'neo'}}%% flowchart TD S1([Initial Setup]):::blue S2([Environment Config]):::blue S3([Development Branch]):::green S4([Custom MCP Server]):::green S5([Public MCP Server]):::green S6([Streamlit Dashboard]):::green S7([Tool Integration]):::green S8([Statistics System]):::green S9([Main Branch]):::yellow S10([Testing Phase]):::yellow S11([Production Branch]):::purple S12([Production Config]):::purple S13([Security Hardening]):::purple S14([Performance Optimization]):::purple S15([Monitoring Setup]):::purple S16([Merge to Main]):::rose S17([Release v1.0]):::rose S1 --> S2 --> S3 S3 --> S4 S3 --> S5 S3 --> S6 S3 --> S7 S3 --> S8 S3 --> S9 S9 --> S10 S10 --> S11 S11 --> S12 S12 --> S13 S13 --> S14 S14 --> S15 S15 --> S16 S16 --> S17 classDef blue fill:#e1f5fe,stroke:#039be5,stroke-width:3px,color:#000 classDef green fill:#e8f5e8,stroke:#43a047,stroke-width:3px,color:#000 classDef yellow fill:#fff3e0,stroke:#fbc02d,stroke-width:3px,color:#000 classDef purple fill:#f3e5f5,stroke:#8e24aa,stroke-width:3px,color:#000 classDef rose fill:#ffebee,stroke:#d32f2f,stroke-width:3px,color:#000 ``` --- ## 🔄 Real-time Data Flow ```mermaid %%{init: {'theme': 'neo'}}%% sequenceDiagram participant Browser as 🌐 Browser participant Streamlit as 🎨 Streamlit participant CustomMCP as 🔧 Custom MCP participant PublicMCP as 🌐 Public MCP participant Gemini as 🧠 Gemini API participant Stats as 📊 Statistics loop Every 2 seconds Browser->>Streamlit: Auto-refresh request Streamlit->>CustomMCP: GET /stats Streamlit->>PublicMCP: GET /stats CustomMCP->>Stats: Fetch current metrics PublicMCP->>Stats: Fetch current metrics Stats->>CustomMCP: Return stats data Stats->>PublicMCP: Return stats data CustomMCP->>Streamlit: Stats response PublicMCP->>Streamlit: Stats response Streamlit->>Browser: Updated dashboard end Note over Browser,Stats: Real-time monitoring ensures<br/>users see live system performance ``` --- ## 🔧 System Initialization Workflow ```mermaid %%{init: {'theme': 'neo'}}%% flowchart TD A([🚀 System Start]):::blue B([📁 Load Environment Variables]):::green C{{🔑 API Key Present?}}:::yellow D([❌ Exit with Error]):::rose E([🤖 Initialize Gemini Client]):::green F([🔧 Start Custom MCP Server]):::green G([🌐 Start Public MCP Server]):::green H([🎨 Start Streamlit Dashboard]):::green I([📊 Initialize Statistics]):::green J([🛠️ Load Tool Modules]):::green K([📝 Setup Logging]):::green L([✅ System Ready]):::blue M([🔄 Health Check Loop]):::yellow N{{🏥 All Services Healthy?}}:::yellow O([😴 Wait 30 seconds]):::blue P([⚠️ Alert & Restart]):::rose Q([🔄 Restart Failed Services]):::rose A --> B --> C C -- No --> D C -- Yes --> E --> F --> G --> H --> I --> J --> K --> L L --> M --> N N -- Yes --> O --> M N -- No --> P --> Q --> M classDef blue fill:#e1f5fe,stroke:#039be5,stroke-width:3px,color:#000 classDef green fill:#e8f5e8,stroke:#43a047,stroke-width:3px,color:#000 classDef yellow fill:#fff3e0,stroke:#fbc02d,stroke-width:3px,color:#000 classDef rose fill:#ffebee,stroke:#d32f2f,stroke-width:3px,color:#000 ``` --- ## 📈 Performance Monitoring Workflow ```mermaid %%{init: {'theme': 'neo'}}%% flowchart LR A([📊 Metrics Collection]):::blue B([⏱️ Response Time]):::green C([✅ Success Rate]):::green D([📈 Query Count]):::green E([🕒 Uptime]):::green F([📊 Statistics Engine]):::purple G([🔄 Real-time Updates]):::blue H([🎨 Dashboard Display]):::green I([📝 Logging System]):::green J([📁 Log Files]):::blue K{{⚠️ Threshold Check}}:::yellow L([✅ Continue Monitoring]):::green M([🚨 Send Notification]):::rose N([📧 Email Alert]):::rose O([📱 Dashboard Warning]):::rose A --> B --> F A --> C --> F A --> D --> F A --> E --> F F --> G --> H F --> I --> J F --> K K -- Normal --> L --> A K -- Alert --> M --> N --> A M --> O --> A classDef blue fill:#e1f5fe,stroke:#039be5,stroke-width:3px,color:#000 classDef green fill:#e8f5e8,stroke:#43a047,stroke-width:3px,color:#000 classDef purple fill:#f3e5f5,stroke:#8e24aa,stroke-width:3px,color:#000 classDef yellow fill:#fff3e0,stroke:#fbc02d,stroke-width:3px,color:#000 classDef rose fill:#ffebee,stroke:#d32f2f,stroke-width:3px,color:#000 ``` --- ## 🔐 Security Workflow ```mermaid %%{init: {'theme': 'neo'}}%% sequenceDiagram participant Client as 👤 Client participant Dashboard as 🎨 Dashboard participant Server as 🔧 Server participant Env as 🔐 Environment participant AI as 🧠 AI Service Client->>Dashboard: Request with input Dashboard->>Dashboard: Input validation alt Invalid Input Dashboard->>Client: Reject request else Valid Input Dashboard->>Server: Forward request Server->>Server: Sanitize input Server->>Env: Get API key alt API Key Missing Server->>Dashboard: Authentication error else API Key Valid Server->>AI: Secure API call AI->>Server: Response Server->>Dashboard: Sanitized response end Dashboard->>Client: Final response end Note over Client,AI: All sensitive data<br/>handled securely ``` --- ## 🎯 Summary These workflow diagrams provide a comprehensive view of how the MCP Agentic AI Server system operates: - **🌐 Overall System**: Shows the complete user journey and system interactions - **🔧 Custom MCP**: Detailed task-based processing with tool integration - **🌐 Public MCP**: Simple query-response pattern for direct AI interaction - **🎨 Dashboard**: Real-time UI updates and user interaction patterns - **🛠️ Tools**: Extensible tool framework for custom functionality - **📊 Statistics**: Thread-safe performance monitoring and metrics - **⚠️ Error Handling**: Robust error management and recovery - **👤 User Journey**: Complete user experience mapping - **🧠 AI Processing**: Detailed AI integration and response handling - **🚀 Deployment**: Development to production workflow Each diagram uses consistent color coding and emoji symbols to make the workflows easy to understand and follow. These diagrams serve as both documentation and implementation guides for developers working with the system.