# dazzaji/mcp-agent-router architecture

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

- Interactive diagram: https://gitdiagram.com/dazzaji/mcp-agent-router
- Repository: https://github.com/dazzaji/mcp-agent-router

## Overview

##### Main Components
- Clients: Notice the clients directory (e.g., the “claude-desktop” client) which likely serves as an interface to send user queries.
- Gateway Agent: The “gateway-agent” directory contains a service (service.py) and supporting scripts that act as the main router or mediator between clients and the downstream servers.
- Servers: There are at least two main servers (“server-a” and “server-b”). Each is implemented as a separate service (with their own server.py and talk.py) to perform specialized tasks (e.g., creating or updating a markdown file, as described in the README).
- Example Service: Although this appears to be an auxiliary or example implementation (in “example-service”), it can be included to demonstrate further modularity if needed.
- Supporting Infrastructure: Docker files and configuration files (such as Dockerfile, docker-compose.yaml, .gitignore, etc.) indicate that containerization and consistent environments are part of the design.

##### Relationships and Data Flow
- Incorporate a control or decision component inside the Gateway Agent that acts as the “decider” (routing logic) between the servers.
- Optionally, indicate how the “example-service” might be used as another plug-and-play module in similar fashion.
- A shared virtual environment and note that the same dependencies (installed via uv pip) are being used across components.

##### Architectural Patterns and Technologies
- Containerization: Dockerfiles in several directories imply that services can be containerized, which is essential for modular deployment.
- Environment Consistency: Note how virtual environments are set up and linked (venv - .venv) to ensure consistency across deployments and debugging sessions.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Clients Layer
    subgraph "Clients Layer"
        CLIENT["Claude Desktop Client"]:::client
    end

    %% Gateway Layer
    subgraph "Gateway Layer"
        GATEWAY["Gateway Agent (/mcp/v1) - with Decider Logic"]:::gateway
    end

    %% Servers Layer
    subgraph "Servers Layer"
        SERVER_A["Server A – Personal Trainer (/mcp/v1)"]:::server
        SERVER_B["Server B – Work Assistant (/mcp/v1)"]:::server
        EXAMPLE["Example Service"]:::example
    end

    %% Observability/Tools
    subgraph "Observability/Tools"
        INSPECTOR["MCP Inspector (Logging & Debugging)"]:::tool
    end

    %% Infrastructure
    subgraph "Infrastructure"
        INFRA["Containerization & Config (Docker, etc.)"]:::infra
    end

    %% Flow Connections
    CLIENT -->|"user_input"| GATEWAY
    GATEWAY -->|"routes:training"| SERVER_A
    GATEWAY -->|"routes:work"| SERVER_B
    GATEWAY -->|"optional-routing"| EXAMPLE
    INSPECTOR -->|"observes"| GATEWAY
    INFRA --- GATEWAY
    INFRA --- SERVER_A
    INFRA --- SERVER_B
    INFRA --- EXAMPLE

    %% Styles
    classDef client fill:#a8dadc,stroke:#457b9d,stroke-width:2px;
    classDef gateway fill:#81c784,stroke:#388e3c,stroke-width:2px;
    classDef server fill:#ffb74d,stroke:#f57c00,stroke-width:2px;
    classDef example fill:#ba68c8,stroke:#8e24aa,stroke-width:2px;
    classDef tool fill:#e57373,stroke:#d32f2f,stroke-width:2px;
    classDef infra fill:#90a4ae,stroke:#607d8b,stroke-width:2px;

    %% Click Events
    click CLIENT "https://github.com/dazzaji/mcp-agent-router/tree/main/clients/claude-desktop"
    click GATEWAY "https://github.com/dazzaji/mcp-agent-router/blob/main/gateway-agent/service.py"
    click SERVER_A "https://github.com/dazzaji/mcp-agent-router/blob/main/server-a/server.py"
    click SERVER_B "https://github.com/dazzaji/mcp-agent-router/blob/main/server-b/server.py"
    click EXAMPLE "https://github.com/dazzaji/mcp-agent-router/blob/main/example-service/service.py"
    click INFRA "https://github.com/dazzaji/mcp-agent-router/blob/main/docker-compose.yaml"
```
