# thelearningdev/build-ai-agents-with-mcp-apr-2025 architecture

> Architecture diagram of the GitHub repository thelearningdev/build-ai-agents-with-mcp-apr-2025, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-11). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/thelearningdev/build-ai-agents-with-mcp-apr-2025
- Repository: https://github.com/thelearningdev/build-ai-agents-with-mcp-apr-2025

## Overview

##### Project Type and Purpose
- This is a server-based project (written in Python) that functions as an MCP (Model Context Protocol) server, with capabilities for integrating AI agents.
- Its purpose is twofold: to demonstrate building an MCP server (for example, a “weather agent server”) and to optionally integrate clients that connect to AI service providers (such as Anthropic and possibly MCP “Gemini” via ADK).
- The README clarifies that it functions in a full-stack capacity where the server is core and external tools (like Claude Desktop, NodeJS, and uv) provide supporting functionalities and integrations.

##### Analyzing the File Structure
- At the project’s root, you have configuration files (e.g., .gitignore, .python-version, pyproject.toml, uv.lock) that support environment/packaging and dependency management.
- The main server entry point is server.py, which is likely the MCP server where requests are processed.
- The clients directory includes two scripts:
- clients/adk_with_mcp_gemini.py: This likely demonstrates an integration client for the MCP Gemini ADK.
- clients/anthropic_client.py: This script integrates with the Anthropic API and represents a paid client example.
- This layout indicates a clear separation between the server component and optional clients handling external communications.

##### Key Components
- MCP Server
- Represented as the central “server.py” component.
- This is the backbone of the application handling incoming requests, agent orchestration, and interfacing with external models.
- Client Integrations
- Two separate components:
- Anthropic Client: Integrated via clients/anthropic_client.py.
- ADK/MCP Gemini Client: Integrated via clients/adk_with_mcp_gemini.py.
- These clients handle outbound communication with external third-party AI services.
- External Dependencies and Tools
- NodeJS and npx: As per the README instructions, they play a role in the environment setup.
- uv: Appears in uv.lock and “uv venv” / “uv sync” commands which imply uv is managing virtual environments, deployments, or bundling.
- Claude Desktop: Highlighted as an integration point for interacting with the Claude free version model.
- Other External Providers: Mention of “Google Agent SDK” and references to API Keys for providers like OpenAI, Anthropic, and Google.

##### Relationships and Communications
- The MCP Server (server.py) sits at the center, interacting with both internal modules and external AI agents.
- The server sends/receives data and likely communicates with:
- Internal client modules (the two scripts in the clients directory) that may be triggered based on server events.
- External AI services (Claude Desktop, Anthropic, and optionally via Google’s Agent SDK) where each client represents a distinct integration pathway.
- Data flow from the MCP Server to external services via the client modules.
- Requests coming from a hypothetical client UI (if applicable) that reaches the MCP Server.
- Feedback and responses from external AI services returning to the MCP Server and subsequently, potentially, to the end user.

##### Architectural Patterns and Technologies
- The architecture follows a modular pattern, with decoupled components:
- The MCP Server manages core logic and agent orchestration.
- Modular client scripts serve as adapters to integrate external services.
- The design utilizes external tools (uv for environment and package management) and a clear separation between server and client responsibilities.
- That the project shows a pattern typical for event-driven or microservice-like architectures, where single-responsibility and separation of concerns are maintained.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Interface
    externalUser("User Interface/Requester"):::external

    %% Environment Tools
    subgraph "Environment Tools"
        nodejs("NodeJS & npx"):::env
        uv("uv Environment"):::env
        python("Python"):::env
    end

    %% Core Server
    subgraph "Core Server"
        mcp("MCP Server (server.py)"):::server
    end

    %% Client Integrations
    subgraph "Client Integrations"
        anthropic("Anthropic Integration Client (clients/anthropic_client.py)"):::client
        adk("ADK/MCP Gemini Client (clients/adk_with_mcp_gemini.py)"):::client
    end

    %% External AI Services
    subgraph "External AI Services"
        anthApi("Anthropic API"):::externalService
        geminiApi("MCP Gemini API"):::externalService
        claude("Claude Desktop"):::externalService
        google("Google Agent SDK"):::externalService
    end

    %% Connections
    externalUser -->|"requests"| mcp

    nodejs -->|"supports"| mcp
    uv -->|"supports"| mcp
    python -->|"supports"| mcp

    mcp -->|"calls"| anthropic
    mcp -->|"calls"| adk

    anthropic -->|"integrates"| anthApi
    adk -->|"integrates"| geminiApi

    mcp -->|"optional"| claude
    mcp -->|"optional"| google

    %% Click Events
    click mcp "https://github.com/thelearningdev/build-ai-agents-with-mcp-apr-2025/blob/main/server.py"
    click anthropic "https://github.com/thelearningdev/build-ai-agents-with-mcp-apr-2025/blob/main/clients/anthropic_client.py"
    click adk "https://github.com/thelearningdev/build-ai-agents-with-mcp-apr-2025/blob/main/clients/adk_with_mcp_gemini.py"

    %% Styles
    classDef server fill:#cce5ff,stroke:#003366,stroke-width:2px;
    classDef client fill:#d4edda,stroke:#155724,stroke-width:2px;
    classDef externalService fill:#fff3cd,stroke:#856404,stroke-width:2px;
    classDef env fill:#d1ecf1,stroke:#0c5460,stroke-width:2px;
    classDef external fill:#e2e3e5,stroke:#6c757d,stroke-width:2px;
```
