# ishanextreme/a2a_mcp-example architecture

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

- Interactive diagram: https://gitdiagram.com/ishanextreme/a2a_mcp-example
- Repository: https://github.com/ishanextreme/a2a_mcp-example

## Overview

##### Project type and purpose
- This is a full-stack, microservice-style application: an LLM-powered terminal assistant that allows users to issue natural-language commands which get executed on a Linux host.
- It leverages two backend services (A2A and MCP), a Python demo UI, and a reusable Python SDK to tie them together.

##### File structure
- Top-level directories:
- client/ – the demo UI app, the a2a-python-sdk, docs, sample code, and test suites
- a2a_server/ – the Agent-to-Agent server (“langgraph” module)
- mcp_server/ – the Model Context Protocol server
- Under client/demo/ui: Python UI code (FastAPI + Uvicorn) that renders pages and components and communicates with both backend services.
- client/a2a-python-sdk: the shared SDK used by the UI (and other clients) to call the A2A and MCP servers.
- a2a_server/langgraph: implements agent orchestration, task management, and OpenAI integration.
- mcp_server/mcp_server.py: implements the MCP protocol endpoint.

##### README for additional insights
- Three processes must run concurrently:
1. UI Server at http://localhost:12000
2. A2A Server (default port 10000)
3. MCP Server
- The UI allows users to register Linux Agents (at A2A endpoint) and send natural-language requests.
- Built with Python 3.12, FastAPI/Uvicorn, OpenAI GPT, A2A & MCP protocols.

##### Main components
a. Frontend (Demo UI)
- client/demo/ui/main.py + UI components/pages
- Uses a2a-python-sdk to call backends
b. Agent-to-Agent (A2A) Server
- a2a_server/langgraph/main.py (FastAPI app)
- Subcomponents: Agent, TaskManager, Helpers, StreamingResponseQueue
- Integrates with OpenAI GPT API
- Exposes REST/WebSocket endpoints on port 10000
c. Model Context Protocol (MCP) Server
- mcp_server/mcp_server.py (FastAPI app)
- Provides contextual model calls to OpenAI or other LLM providers
d. Linux Host Execution Environment
- The underlying shell where commands are actually run
e. External Service: OpenAI GPT
- External LLM API used by both A2A and MCP servers
f. (Optional) Python SDK
- client/a2a-python-sdk used by any other client to interact with A2A/MCP

##### Relationships and interactions
1. User in Browser → Demo UI (HTTP/WebSocket)
2. Demo UI → A2A Server (via a2a-python-sdk)
3. A2A Server → OpenAI GPT (for planning and interpretation)
4. A2A Server → Linux Shell (executes commands)
5. Demo UI → MCP Server (via a2a-python-sdk) for context-aware LLM calls
6. MCP Server → OpenAI GPT

##### Architectural patterns and design principles
- Microservice separation: UI, A2A, MCP as independent FastAPI services
- SDK abstraction: a2a-python-sdk provides a uniform client API
- Agent orchestration: A2A uses an internal task manager pattern
- Asynchronous streams: StreamingResponseQueue for real-time UI updates

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Frontend Layer
    subgraph "Frontend (Demo UI)"
        direction TB
        UI["Demo UI"]:::frontend
        UI_main["main.py"]:::frontend
        UI_comp["components/"]:::frontend
        UI_pages["pages/"]:::frontend
        UI_service["service/"]:::frontend
        UI_state["state/"]:::frontend
        UI_styles["styles/"]:::frontend
    end

    %% SDK Layer
    subgraph "Python SDK (a2a-python-sdk)"
        direction TB
        SDK["SDK Client/Server"]:::backend
        SDK_client["client/client.py"]:::backend
        SDK_errors["client/errors.py"]:::backend
        SDK_app["server/app.py"]:::backend
        SDK_executor["server/agent_executor.py"]:::backend
        SDK_queue["server/streaming_response_queue.py"]:::backend
        SDK_store["server/task_store.py"]:::backend
        SDK_utils["utils/helpers.py"]:::backend
    end

    %% Backend Layer
    subgraph "Agent-to-Agent (A2A) Server"
        direction TB
        A2A["A2A Server"]:::backend
        A2A_main["main.py"]:::backend
        A2A_agent["agent.py"]:::backend
        A2A_task["task_manager.py"]:::backend
        A2A_helpers["helpers.py"]:::backend
    end

    subgraph "Model Context Protocol (MCP) Server"
        direction TB
        MCP["MCP Server"]:::backend
        MCP_main["mcp_server.py"]:::backend
    end

    %% External & Host
    subgraph "External Services"
        direction TB
        OpenAI["OpenAI GPT API"]:::external
    end

    subgraph "Host Environment"
        direction TB
        Shell["Linux Shell"]:::host
    end

    %% Connections
    User["User (Browser)"]:::frontend -->|"HTTP/WS"| UI
    UI -->|"uses SDK"| SDK
    SDK -->|"A2A API"| A2A
    SDK -->|"MCP API"| MCP
    A2A -->|"calls GPT"| OpenAI
    A2A -->|"executes cmds"| Shell
    MCP -->|"calls GPT"| OpenAI

    %% Click Events Frontend
    click UI_main "https://github.com/ishanextreme/a2a_mcp-example/blob/main/client/demo/ui/main.py"
    click UI_comp "https://github.com/ishanextreme/a2a_mcp-example/tree/main/client/demo/ui/components/"
    click UI_pages "https://github.com/ishanextreme/a2a_mcp-example/tree/main/client/demo/ui/pages/"
    click UI_service "https://github.com/ishanextreme/a2a_mcp-example/tree/main/client/demo/ui/service/"
    click UI_state "https://github.com/ishanextreme/a2a_mcp-example/tree/main/client/demo/ui/state/"
    click UI_styles "https://github.com/ishanextreme/a2a_mcp-example/tree/main/client/demo/ui/styles/"

    %% Click Events SDK
    click SDK_client "https://github.com/ishanextreme/a2a_mcp-example/blob/main/client/a2a-python-sdk/src/a2a/client/client.py"
    click SDK_errors "https://github.com/ishanextreme/a2a_mcp-example/blob/main/client/a2a-python-sdk/src/a2a/client/errors.py"
    click SDK_app "https://github.com/ishanextreme/a2a_mcp-example/blob/main/client/a2a-python-sdk/src/a2a/server/app.py"
    click SDK_executor "https://github.com/ishanextreme/a2a_mcp-example/blob/main/client/a2a-python-sdk/src/a2a/server/agent_executor.py"
    click SDK_queue "https://github.com/ishanextreme/a2a_mcp-example/blob/main/client/a2a-python-sdk/src/a2a/server/streaming_response_queue.py"
    click SDK_store "https://github.com/ishanextreme/a2a_mcp-example/blob/main/client/a2a-python-sdk/src/a2a/server/task_store.py"
    click SDK_utils "https://github.com/ishanextreme/a2a_mcp-example/blob/main/client/a2a-python-sdk/src/a2a/utils/helpers.py"

    %% Click Events A2A Server
    click A2A_main "https://github.com/ishanextreme/a2a_mcp-example/blob/main/a2a_server/langgraph/main.py"
    click A2A_agent "https://github.com/ishanextreme/a2a_mcp-example/blob/main/a2a_server/langgraph/agent.py"
    click A2A_task "https://github.com/ishanextreme/a2a_mcp-example/blob/main/a2a_server/langgraph/task_manager.py"
    click A2A_helpers "https://github.com/ishanextreme/a2a_mcp-example/blob/main/a2a_server/langgraph/helpers.py"

    %% Click Events MCP Server
    click MCP_main "https://github.com/ishanextreme/a2a_mcp-example/blob/main/mcp_server/mcp_server.py"

    %% Styles
    classDef frontend fill:#E3F2FD,stroke:#1E88E5,color:#0D47A1
    classDef backend fill:#E8F5E9,stroke:#43A047,color:#1B5E20
    classDef external fill:#FFF3E0,stroke:#FB8C00,color:#E65100
    classDef host fill:#EEEEEE,stroke:#757575,color:#424242
```
