# box-community/langchain-box-mcp-adapter architecture

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

- Interactive diagram: https://gitdiagram.com/box-community/langchain-box-mcp-adapter
- Repository: https://github.com/box-community/langchain-box-mcp-adapter

## Overview

##### File structure
- Top level:
- pyproject.toml & uv.lock – dependency definitions
- .gitignore, .python-version, .vscode, LICENSE, README.md
- images/ – screenshots only
- src/
- console_utils/console_app.py – reusable console I/O with rich rendering and typewriter effects
- simple_client.py – “hello world” REPL that spins up a React-style agent, loads tools, and routes prompts to ChatOpenAI + MCPAdapter
- graph.py + langgraph.json – alternative workflow using the LangGraph engine to define multi-step pipelines via JSON

##### Extract additional insights from README
- Two modes of operation:
a) Simple client: uv run src/simple_client.py (console REPL)
b) Graph agent: uv run langgraph dev --config src/langgraph.json (visual/JSON-driven pipelines)
- Key libraries: langchain-openai, langchain-mcp-adapters (stdio), langgraph, rich

##### Main components & interactions
a. Components
1) Configuration Layer
– langgraph.json for graph mode
2) CLI Entrypoints
– simple_client module
– graph.py module
3) Console Utilities
– console_app rendering engine (rich)
4) Agent Core
– React-style agent orchestrator (from Langchain)
5) Model Layer
– ChatOpenAI (langchain-openai)
6) Adapter Layer
– MCPAdapter (langchain-mcp-adapters) over stdio transport
7) External Service
b. Relationships & Data Flows
– User types prompt in CLI → console_app captures it → Agent Core
– Agent Core routes prompt to ChatOpenAI → receives response
– In graph mode, graph.py reads langgraph.json → constructs directed workflow → at each node, uses ChatOpenAI or MCPAdapter similarly
c. Architectural patterns
– Hexagonal/Ports & Adapters: separation between core agent logic and transport (stdio)
– Orchestration via external graph engine (LangGraph)
d. Key technologies & libraries
– Python 3.13, uv CLI tool
– rich for console UI
– langchain-openai, langchain-mcp-adapters, langgraph

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Configuration Layer
    subgraph "Configuration Layer"
        ENV[".env.sample"]:::document
        CFGJSON["langgraph.json"]:::document
    end

    %% CLI Entrypoints
    subgraph "CLI Entrypoints"
        SimpleClient["simple_client.py"]:::pythonModule
        GraphAgent["graph.py"]:::pythonModule
    end

    %% Console Utilities
    subgraph "Console Utilities"
        ConsoleApp["console_app.py"]:::pythonModule
    end

    %% Core Components
    subgraph "Core Components"
        AgentCore["React-Style Orchestrator"]:::coreService
        LLM["ChatOpenAI"]:::coreService
        Adapter["MCPAdapter (StdIO)"]:::coreService
    end

    %% External Services
    subgraph "External Services"
        Box["Box MCP Server"]:::external
        LangGraph["LangGraph Engine"]:::external
    end

    %% Dependencies
    subgraph "Dependencies"
        PYPROJ["pyproject.toml"]:::document
    end

    %% User
    User["User"]:::external

    %% Flows - Simple REPL
    User -->|"types prompt"| SimpleClient
    SimpleClient -->|"invokes"| ConsoleApp
    ConsoleApp -->|"passes prompt"| AgentCore

    %% Flows - Graph Mode
    User -->|"starts graph mode"| GraphAgent
    GraphAgent -->|"reads workflow"| CFGJSON
    GraphAgent -->|"delegates steps to"| LangGraph
    LangGraph -->|"executes nodes"| AgentCore

    %% Agent Core interactions
    AgentCore -->|"LLM API call"| LLM
    LLM -->|"response"| AgentCore
    AgentCore -->|"invokes tool"| Adapter
    Adapter -->|"stdin/stdout (JSON)"| Box
    Box -->|"tool result"| Adapter
    Adapter -->|"result"| AgentCore
    AgentCore -->|"outputs"| ConsoleApp
    ConsoleApp -->|"renders"| User

    %% Dependencies link
    PYPROJ -->|"defines deps"| SimpleClient
    PYPROJ -->|"defines deps"| GraphAgent

    %% Click Events
    click ENV "https://github.com/box-community/langchain-box-mcp-adapter/blob/main/.env.sample"
    click CFGJSON "https://github.com/box-community/langchain-box-mcp-adapter/blob/main/src/langgraph.json"
    click SimpleClient "https://github.com/box-community/langchain-box-mcp-adapter/blob/main/src/simple_client.py"
    click GraphAgent "https://github.com/box-community/langchain-box-mcp-adapter/blob/main/src/graph.py"
    click ConsoleApp "https://github.com/box-community/langchain-box-mcp-adapter/blob/main/src/console_utils/console_app.py"
    click AgentCore "https://github.com/box-community/langchain-box-mcp-adapter/blob/main/src/simple_client.py"
    click LLM "https://github.com/box-community/langchain-box-mcp-adapter/blob/main/src/simple_client.py"
    click Adapter "https://github.com/box-community/langchain-box-mcp-adapter/blob/main/src/simple_client.py"
    click LangGraph "https://github.com/box-community/langchain-box-mcp-adapter/blob/main/src/graph.py"
    click PYPROJ "https://github.com/box-community/langchain-box-mcp-adapter/blob/main/pyproject.toml"

    %% Styles
    classDef pythonModule fill:#e0ffe0,stroke:#2d7,stroke-width:1px,shape:rounded
    classDef coreService fill:#ffd080,stroke:#d97706,stroke-width:1px
    classDef external fill:#cfe2ff,stroke:#1e3a8a,stroke-width:1px
    classDef document fill:#f4f4f4,stroke:#888,stroke-width:1px
    class User,Box,LangGraph external
    class ENV,CFGJSON,PYPROJ document
    class SimpleClient,GraphAgent,ConsoleApp pythonModule
    class AgentCore,LLM,Adapter coreService
```
