# rubenszimbres/a2a_adk_mcp architecture

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

- Interactive diagram: https://gitdiagram.com/rubenszimbres/a2a_adk_mcp
- Repository: https://github.com/rubenszimbres/a2a_adk_mcp

## Overview

##### Project Type and Purpose
- This is a multi-agent, security-focused data processing pipeline built on the Agent-to-Agent (A2A) protocol with Model Context Protocol (MCP) integration.
- Purpose: accept client queries, run them through a security pipeline (threat detection, SQL execution, PII masking), and return sanitized results.

##### File Structure
Top-Level Directories and Files:
- agents/           – ADK agent definitions and eval sets
- clients/          – A2A client code and query script
- servers/          – A2A server implementations, MCP server, task manager
- data/             – Sample dataset (CSV) and SQLite DB
- evaluation/       – Security test scenarios and scoring scripts
- examples/         – Tutorial notebook
- utilities/        – Shared types and helper functions
- main.py, readme.md, requirements.txt, salaries.db

Architectural Clues:
– servers run multiple A2A endpoints (Judge, SQL, Mask, MCP)
– agents implement business logic for each pipeline stage
– MCP server provides specialized SQL tools
– evaluation folder contains automated tests for security and correctness

##### README for Additional Insights
– Layers: A2A Protocol → ADK Framework → MCP Server
– Core components: A2A Servers, ADK Agents (Judge, SQL, Mask), MCP Server, Task Manager
– Pipeline flow:
Client Request → A2A Server → Judge Agent → SQL Agent → Mask Agent → Client Response
– Key technologies: Python 3.8+, aiohttp, FastAPI, Google ADK, Uvicorn, SQLite, MCP

a. Clients:
- a2a_client.py / query_MCP_ADK_A2A.py – initiates pipeline requests
b. A2A Server Layer:
- run_servers.py / a2a_servers.py – host endpoints for each agent
- server_mcp.py – MCP tool provider
- task_manager.py – orchestrates cross-agent calls
c. Agents (ADK Layer):
- mcp_agent.py – wraps MCP tools for SQL
- agent.py, mcp_agent and mcp eval sets – implement Judge, SQL, Mask logic
d. Database & Data Stores:
- salaries.db – underlying data source
- Updated_Salaries_Data.csv – seed data
e. External Services:
- Model Armor API (threat detection)
- Google Generative AI (LLM models)
- (Optional) Cloud secret manager or env files

##### Relationships and Data Flow
– Client → A2A Server (HTTP/gRPC)
– A2A Server → Task Manager
– Task Manager sequences: Judge Agent → SQL Agent (via MCP Server & DB) → Mask Agent
– Mask Agent → A2A Server → Client
– MCP Server ↔ SQL Agent communicates over stdio or local socket
– Agents call external APIs (LLM, Model Armor) as side channels

##### Architectural Patterns and Principles
– Layered architecture: client, API/server, agent business logic, data store
– Pipeline/middleware pattern: sequential processing steps
– Micro-service style: each agent and MCP server runs in its own process
– Dependency inversion: Task Manager abstracts agent interactions
– Security by design: input validation (Judge), controlled DB access (SQL), DLP (Mask)

##### Relevant Technologies and Frameworks
– Python, FastAPI / aiohttp, Uvicorn
– Google ADK for agent creation
– MCP for SQL tool integration
– SQLite for data persistence
– JSON for configuration and test scenarios

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Clients Layer
    subgraph "Clients" 
        direction TB
        Client1["A2A Client"]:::client
        Client2["MCP-ADK-A2A Query Script"]:::client
    end

    %% A2A Server Layer
    subgraph "A2A Protocol Layer"
        direction TB
        A2A_Servers["A2A Servers"]:::server
        Run_Servers["Server Launcher"]:::server
        MCP_Tool_Server["MCP Tool Provider Server"]:::server
        Task_Manager["Task Manager"]:::server
    end

    %% ADK Agents Layer
    subgraph "ADK Agents Layer"
        direction TB
        Judge_Agent["Judge Agent"]:::agent
        SQL_Agent["SQL Agent"]:::agent
        Mask_Agent["Mask Agent"]:::agent
        MCP_Agent["MCP Agent Wrapper"]:::agent
        EvalSet["Agent Eval Set"]:::agent
    end

    %% MCP Server
    subgraph "MCP Server"
        direction TB
        MCP_Server["MCP Server"]:::mcp
    end

    %% Data Stores
    subgraph "Data Stores"
        direction TB
        CSV["Updated Salaries Data.csv"]:::data
        DB["SQLite Database"]:::data
    end

    %% External Services
    subgraph "External Services"
        direction TB
        ModelArmor["Model Armor API"]:::external
        GoogleAI["Google Generative AI"]:::external
    end

    %% Testing Zone
    subgraph "Testing"
        direction TB
        TestScenarios["Test Scenarios"]:::testing
        TestConfig["Test Configuration"]:::testing
        Evaluator["Evaluation Harness"]:::testing
        TestResults["Security Test Results"]:::testing
    end

    %% Connections: Clients to Servers
    Client1 -->|HTTP/gRPC| A2A_Servers
    Client2 -->|HTTP/gRPC| A2A_Servers

    %% Server orchestration
    A2A_Servers -->|invoke| Task_Manager
    Run_Servers -->|launch endpoints| A2A_Servers
    A2A_Servers -->|register| MCP_Tool_Server

    %% Task Manager to Agents
    Task_Manager -->|Judge->SQL->Mask| Judge_Agent
    Judge_Agent -->|next| SQL_Agent
    SQL_Agent -->|next| Mask_Agent
    Mask_Agent -->|response| A2A_Servers

    %% Agent to MCP Server and Data
    SQL_Agent -->|tool handshake| MCP_Server
    MCP_Agent -->|wrap SQL tools| SQL_Agent
    EvalSet -->|scenarios| Judge_Agent

    SQL_Agent -->|SQL queries| DB
    CSV -->|seed data| DB

    %% Agents to External
    Judge_Agent -->|threat detection| ModelArmor
    SQL_Agent -->|LLM calls| GoogleAI
    Mask_Agent -->|PII masking| GoogleAI

    %% Response back to Clients
    A2A_Servers -->|HTTP/gRPC| Client1
    A2A_Servers -->|HTTP/gRPC| Client2

    %% Testing connections
    TestScenarios -->|definitions| Evaluator
    TestConfig -->|config| Evaluator
    Evaluator -->|runs| A2A_Servers
    Evaluator -->|outputs| TestResults

    %% Click Events
    click Client1 "https://github.com/rubenszimbres/a2a_adk_mcp/blob/main/clients/a2a_client.py"
    click Client2 "https://github.com/rubenszimbres/a2a_adk_mcp/blob/main/clients/query_MCP_ADK_A2A.py"
    click A2A_Servers "https://github.com/rubenszimbres/a2a_adk_mcp/blob/main/servers/a2a_servers.py"
    click Run_Servers "https://github.com/rubenszimbres/a2a_adk_mcp/blob/main/servers/run_servers.py"
    click MCP_Tool_Server "https://github.com/rubenszimbres/a2a_adk_mcp/blob/main/servers/server_mcp.py"
    click Task_Manager "https://github.com/rubenszimbres/a2a_adk_mcp/blob/main/servers/task_manager.py"
    click EvalSet "https://github.com/rubenszimbres/a2a_adk_mcp/blob/main/agents/evalsetd5f05e.evalset.json"
    click MCP_Agent "https://github.com/rubenszimbres/a2a_adk_mcp/blob/main/agents/mcp_agent.py"
    click Judge_Agent "https://github.com/rubenszimbres/a2a_adk_mcp/blob/main/agents/agent.py"
    click SQL_Agent "https://github.com/rubenszimbres/a2a_adk_mcp/blob/main/agents/agent.py"
    click Mask_Agent "https://github.com/rubenszimbres/a2a_adk_mcp/blob/main/agents/agent.py"
    click CSV "https://github.com/rubenszimbres/a2a_adk_mcp/blob/main/data/Updated_Salaries_Data.csv"
    click DB "https://github.com/rubenszimbres/a2a_adk_mcp/blob/main/salaries.db"
    click TestScenarios "https://github.com/rubenszimbres/a2a_adk_mcp/blob/main/evaluation/test_scenarios.json"
    click TestConfig "https://github.com/rubenszimbres/a2a_adk_mcp/blob/main/evaluation/test_config.json"
    click Evaluator "https://github.com/rubenszimbres/a2a_adk_mcp/blob/main/evaluation/simple_evaluator.py"
    click TestResults "https://github.com/rubenszimbres/a2a_adk_mcp/blob/main/evaluation/security_test_results.json"

    %% Styles
    classDef client fill:#f9f,stroke:#333;
    classDef server fill:#aaf,stroke:#333;
    classDef agent fill:#afa,stroke:#333;
    classDef mcp fill:#ff9,stroke:#333;
    classDef data fill:#faa,stroke:#333;
    classDef external fill:#cdf,stroke:#333;
    classDef testing fill:#eee,stroke:#333;
```
