# dabidstudio/python_mcp_agent architecture

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

- Interactive diagram: https://gitdiagram.com/dabidstudio/python_mcp_agent
- Repository: https://github.com/dabidstudio/python_mcp_agent

## Overview

##### Project type and purpose
- This is an example “tool‐server + client” project illustrating the MCP (Model Context Protocol).
- Purpose:
- Build a local MCP Server that exposes YouTube‐related tools (search, transcript fetch, summarization, channel analysis).
- Provide two client examples: one using the OpenAI Agents SDK (“3_openai_agents_basics.py”) and one Streamlit UI (“4_mcp_client.py”).

##### File structure
- Top‐level files:
- 2_mcp_server.py – the MCP Server implementation.
- 3_openai_agents_basics.py – quickstart client using OpenAI Agents.
- 4_mcp_client.py – Streamlit‐based UI client.
- .env.example + python‐dotenv – environment variables loader for API keys.
- mcp.json – configuration for external MCP clients (e.g., Claude Desktop) to spawn/connect to the server.
- 1_mcp_server_functions.ipynb – notebook with server tool‐function development examples.
- External integrations: YouTube Data API, YouTube Transcript API, OpenAI API.

##### README for additional insights
- MCP server registers a set of “tools” and listens for JSON‐RPC calls over stdin/stdout.
- Clients load those tools via the MCP protocol, then issue commands (e.g., “search YouTube for X”).
- Two client flavors demonstrate extensibility: direct SDK usage vs. a web UI.

a. Main components
- MCP Server (container)
- Tool Registry
- Tool Handlers: YouTube Search, Transcript Fetch, Summarizer, Channel Analyzer
- Config Loader (.env via python‐dotenv)
- MCP Client(s)
- OpenAI Agents SDK Client (CLI)
- Streamlit UI Client (Web)
- External Services
- YouTube Data API
- YouTube Transcript API
- OpenAI API
- Configuration Artifact
- mcp.json (used by third‐party clients)
b. Relationships & data flow
1. Client process starts MCP Server (or connects to a running server) using the command/args in mcp.json.
2. Client sends a tool invocation request (JSON-RPC over stdin/stdout).
3. Server’s Tool Handler calls the appropriate external API (YouTube or OpenAI).
4. External API response flows back into the handler, which returns results to the client.
5. Client processes and displays results (CLI output or Streamlit UI).
c. Architectural patterns/design principles
- Microservice / RPC pattern: server exposes discrete tools, client invokes them as services.
- Separation of concerns: clean divide between tool implementation (server) and user interaction (clients).
- Config‐driven deployment: environment variables for keys, JSON config for client‐server wiring.
d. Key technologies/frameworks
- Python, python‐dotenv, requests
- MCP and OpenAI‐Agents SDK
- Streamlit for UI
- YouTube Data and Transcript APIs

##### Final advice
- Every major piece: server internals, clients, config, and external services.
- How environment variables and mcp.json configure runtime behavior.
- Don’t overcomplicate—break the system into these clear components and their interactions.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Configuration Inputs
    subgraph "Configuration" 
        ENV[".env (python-dotenv)"]:::config
        MCPJSON["mcp.json"]:::config
        README["readme.md"]:::doc
    end

    %% MCP Server
    subgraph "MCP Server" 
        direction TB
        SERVER["MCP Server\n(JSON-RPC over stdin/stdout)"]:::server
        Registry["Tool Registry"]:::server
        Handlers["Tool Handlers"]:::server
        subgraph "Handlers Details"
            YTSearch["YouTube Search Handler"]:::server
            Transcript["Transcript Fetch Handler"]:::server
            Summarizer["Summarizer Handler"]:::server
            ChannelAnalyzer["Channel Analyzer Handler"]:::server
        end
    end

    %% Clients
    subgraph "Clients"
        direction TB
        AgentsClient["OpenAI Agents SDK Client (CLI)"]:::client
        StreamlitClient["Streamlit UI Client (Web)"]:::client
    end

    %% External Services
    subgraph "External APIs"
        direction TB
        YTData["YouTube Data API"]:::external
        YTTranscript["YouTube Transcript API"]:::external
        OpenAIAPI["OpenAI API"]:::external
    end

    %% Connections
    ENV -->|loads env vars| SERVER
    MCPJSON -->|client-server wiring| AgentsClient
    MCPJSON -->|client-server wiring| StreamlitClient
    README -->|usage instructions| AgentsClient

    AgentsClient -->|"invoke tool"| SERVER
    StreamlitClient -->|"invoke tool"| SERVER

    SERVER -->|"calls API"| YTData
    SERVER -->|"calls API"| YTTranscript
    SERVER -->|"calls API"| OpenAIAPI

    YTData -->|"response"| SERVER
    YTTranscript -->|"response"| SERVER
    OpenAIAPI -->|"response"| SERVER

    SERVER -->|"returns RPC response"| AgentsClient
    SERVER -->|"returns RPC response"| StreamlitClient

    %% Click Events
    click SERVER "https://github.com/dabidstudio/python_mcp_agent/blob/main/2_mcp_server.py"
    click Registry "https://github.com/dabidstudio/python_mcp_agent/blob/main/2_mcp_server.py"
    click Handlers "https://github.com/dabidstudio/python_mcp_agent/blob/main/2_mcp_server.py"
    click YTSearch "https://github.com/dabidstudio/python_mcp_agent/blob/main/2_mcp_server.py"
    click Transcript "https://github.com/dabidstudio/python_mcp_agent/blob/main/2_mcp_server.py"
    click Summarizer "https://github.com/dabidstudio/python_mcp_agent/blob/main/2_mcp_server.py"
    click ChannelAnalyzer "https://github.com/dabidstudio/python_mcp_agent/blob/main/2_mcp_server.py"
    click ENV "https://github.com/dabidstudio/python_mcp_agent/blob/main/.env.example"
    click AgentsClient "https://github.com/dabidstudio/python_mcp_agent/blob/main/3_openai_agents_basics.py"
    click StreamlitClient "https://github.com/dabidstudio/python_mcp_agent/blob/main/4_mcp_client.py"
    click MCPJSON "https://github.com/dabidstudio/python_mcp_agent/blob/main/mcp.json"
    click README "https://github.com/dabidstudio/python_mcp_agent/blob/main/readme.md"

    %% Styles
    classDef server fill:#D6EAF8,stroke:#2980B9,color:#1B4F72
    classDef client fill:#D5F5E3,stroke:#27AE60,color:#145A32
    classDef external fill:#FCF3CF,stroke:#F1C40F,color:#7D6608
    classDef config fill:#FADBD8,stroke:#E74C3C,color:#641E16
    classDef doc fill:#EBEDEF,stroke:#95A5A6,color:#424949
```
