# esxr/langgraph-mcp architecture

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

- Interactive diagram: https://gitdiagram.com/esxr/langgraph-mcp
- Repository: https://github.com/esxr/langgraph-mcp

## Overview

##### Project Type & Purpose
- This project is a specialized full-stack tool that integrates LangGraph (a modular workflow framework based on graphs) with MCP (a protocol for interfacing LLM applications with external tools and data sources). It essentially creates a Universal Assistant that interprets user messages, routes them to the appropriate agent, and uses MCP to invoke external tools.
- The README emphasizes two main functionalities: building a routing graph (to determine which tool or agent to trigger based on available MCP server data) and an assistant graph (for orchestrating multi-agent interactions). A generic MCP wrapper supports these operations via a consistent interface.

##### Key Components
a. Routing Subsystem:
- Component: Build Router Graph (represented by build_router_graph.py)
- Role: Connects to MCP servers (using mcp_wrapper.py) to collect routing information (tools, resources, prompts) and builds a vector index (which may use Milvus Lite or an alternative vector database configuration).
- External Interaction: MCP servers and the vector database.

b. Assistant Subsystem:
- Component: Assistant Graph (assistant_graph.py and its variant with summarization)
- Role: Processes incoming user messages, chooses the appropriate agent based on the routing decision, and orchestrates the entire conversation flow.
- Data Flow: Receives user input, uses decision nodes to select agents, and coordinates with the MCP Agent.

c. MCP Wrapper:
- Component: MCP Wrapper (mcp_wrapper.py)
- Role: Implements the Strategy Pattern (through an abstract base class and concrete implementations such as RoutingDescription, GetTools, RunTool) to standardize interactions with external MCP servers.
- Design Note: This wrapper abstracts session handling and tool execution, allowing for easy extension (e.g., new operations can be added without modifying core logic).

d. Supporting Utilities & Configuration:
- Components: Configuration (configuration.py), Prompts (prompts.py), Retriever (retriever.py), and additional utility scripts in src/langgraph_mcp/utils for handling OpenAPI specifications and other common tasks.
- Role: Provide configuration and helper functions to support main operations.

e. External & Test Artifacts:
- Components: Environment file templates (env.example), configuration samples for MCP servers (mcp-servers-config.sample.json), and tests (unit_tests and integration_tests folders).
- Role: Provide setup instructions, sample configurations, and verification of system behavior.

##### Relationships and Interactions
- The overall flow begins with the Assistant receiving a user message that is then passed to the Assistant Graph, which in turn makes decisions based on routing data.
- The Assistant Graph interacts with the MCP Wrapper to call the appropriate MCP server endpoints (e.g., list_tools, list_resources, list_prompts) to retrieve the necessary routing information.
- The Build Router Graph aggregates this data and indexes it in a vector database to support rapid matching.
- Optionally, the Retriever module can be used to fetch contextual data from the vector index, especially if Milvus Lite is configured.

##### Architectural Patterns and Technologies
- The project demonstrates clear separation of concerns: routing, assistant orchestration, and MCP server integration are managed by different modules.
- The use of a Strategy Pattern in the MCP Wrapper allows for extensibility.
- The project leverages modular design principles, breaking complex workflows into graph-based nodes (per LangGraph).
- Languages/Frameworks: Python, the LangGraph framework for creating dynamic workflows, and external tools like Milvus Lite for vector indexing.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Global Entities
    UserInput["User Interface/Client"]:::external

    %% Universal Assistant Container
    subgraph "Universal Assistant"
        direction TB
        AssistantGraph["Assistant Graph (assistant_graph.py)"]:::internal
        AssistantGraphSum["Assistant Graph with Summarization (assistant_graph_with_summarization.py)"]:::internal
        BuildRouter["Build Router Graph (build_router_graph.py)"]:::internal
    end

    %% MCP Wrapper Component
    MCPWrapper["MCP Wrapper (mcp_wrapper.py)"]:::internal

    %% External Services
    MCPServers["MCP Servers"]:::external
    VectorIndex["Vector Index (Milvus Lite)"]:::database
    Retriever["Retriever Utility (retriever.py)"]:::internal

    %% Supporting Utilities Subgraph
    subgraph "Supporting Utilities"
        direction TB
        Config["Configuration (configuration.py)"]:::utility
        Prompts["Prompts (prompts.py)"]:::utility
        Utils["Utils (OpenAPI & general)"]:::utility
    end

    %% External Configuration Artifacts
    ConfigArtifacts["Config Artifacts (env.example, mcp-servers-config.sample.json)"]:::external

    %% Data Flow Connections
    UserInput -->|"user_message"| AssistantGraph
    UserInput -->|"user_message"| AssistantGraphSum
    UserInput -->|"user_message"| BuildRouter

    AssistantGraph -->|"invoke_MCP"| MCPWrapper
    AssistantGraphSum -->|"invoke_MCP"| MCPWrapper
    BuildRouter -->|"fetch_MCP_data"| MCPWrapper

    MCPWrapper -->|"MCP_calls"| MCPServers

    BuildRouter -->|"index_routing_info"| VectorIndex
    VectorIndex -->|"retrieve_context"| Retriever

    %% Connections to Supporting Utilities
    AssistantGraph ---|"load_config_and_prompts"| Config
    AssistantGraphSum ---|"load_config_and_prompts"| Prompts
    BuildRouter ---|"load_config_and_prompts"| Config
    MCPWrapper ---|"use_utils"| Utils
    AssistantGraph ---|"read_artifacts"| ConfigArtifacts
    BuildRouter ---|"read_artifacts"| ConfigArtifacts

    %% Click Events
    click BuildRouter "https://github.com/esxr/langgraph-mcp/blob/main/src/langgraph_mcp/build_router_graph.py"
    click AssistantGraph "https://github.com/esxr/langgraph-mcp/blob/main/src/langgraph_mcp/assistant_graph.py"
    click AssistantGraphSum "https://github.com/esxr/langgraph-mcp/blob/main/src/langgraph_mcp/assistant_graph_with_summarization.py"
    click MCPWrapper "https://github.com/esxr/langgraph-mcp/blob/main/src/langgraph_mcp/mcp_wrapper.py"
    click Config "https://github.com/esxr/langgraph-mcp/blob/main/src/langgraph_mcp/configuration.py"
    click Prompts "https://github.com/esxr/langgraph-mcp/blob/main/src/langgraph_mcp/prompts.py"
    click Retriever "https://github.com/esxr/langgraph-mcp/blob/main/src/langgraph_mcp/retriever.py"
    click Utils "https://github.com/esxr/langgraph-mcp/tree/main/src/langgraph_mcp/utils"

    %% Styles
    classDef internal fill:#cce5ff,stroke:#003366,stroke-width:2px;
    classDef external fill:#ffefcc,stroke:#995c00,stroke-width:2px;
    classDef database fill:#d4edda,stroke:#155724,stroke-width:2px;
    classDef utility fill:#e2e3e5,stroke:#6c757d,stroke-width:2px;
```
