# zandko/mcp-use architecture

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

- Interactive diagram: https://gitdiagram.com/zandko/mcp-use
- Repository: https://github.com/zandko/mcp-use

## Overview

##### Project type and purpose
- This is a TypeScript/Node.js client library (“Unified MCP Client Library”) for connecting any LLM (via LangChain.js) to any MCP server. It provides abstractions (agents, adapters, connectors, task managers) to let you build custom tool‑enabled agents without closed‑source dependencies.

##### File structure
- Top‑level entrypoints:
- index.ts – re‑exports public API
- src/client.ts – MCPClient implementation
- src/agents/MCPAgent.ts – agent orchestration
- src/config.ts – configuration loader
- Core folders under src/:
- adapters/ – Adapter pattern to convert between LangChain and MCP
- agents/ – Base agent, prompts, and server manager logic
- connectors/ – Pluggable transports (HTTP, WebSocket, STDIO)
- task_managers/ – Stream managers matching connectors (SSE, WS, STDIO)
- session.ts – Session context and state
- logging.ts – Unified logging interface
- Config, tsconfig, build scripts, and GitHub CI workflows indicate a published npm package.

##### README for additional insights
- Purpose: “open‑source way to connect any LLM to any MCP server”
- Key features: multi‑server support, tool restrictions, dynamic server selection
- Usage flow: configure MCPClient → wrap an LLM → instantiate MCPAgent → run queries

##### Final advice
- How configuration, logging, and session wrap around the core flow
- Don’t over‑simplify: detail adapters, connectors, and task managers as first‑class components

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External
    UserApp["User Application"]:::external
    LLMProvider["LLM Provider"]:::external
    MCPServer["MCP Server"]:::external

    %% Public API
    PublicAPI["Library Entry Point\nindex.ts"]:::core
    click PublicAPI "https://github.com/zandko/mcp-use/blob/main/index.ts"

    %% Core Library
    subgraph "Core Library" 
        direction TB
        MCPClient["MCPClient"]:::core
        click MCPClient "https://github.com/zandko/mcp-use/blob/main/src/client.ts"
        ServerManager["ServerManager"]:::core
        click ServerManager "https://github.com/zandko/mcp-use/blob/main/src/agents/server_manager.ts"
        ConfigStore["Configuration Store\n(src/config.ts)"]:::util
        click ConfigStore "https://github.com/zandko/mcp-use/blob/main/src/config.ts"
        Session["Session Context & State"]:::util
        click Session "https://github.com/zandko/mcp-use/blob/main/src/session.ts"
        Logging["Unified Logging"]:::util
        click Logging "https://github.com/zandko/mcp-use/blob/main/src/logging.ts"
    end

    %% Agents
    subgraph "Agents" 
        direction TB
        MCPAgent["MCPAgent"]:::agent
        click MCPAgent "https://github.com/zandko/mcp-use/blob/main/src/agents/mcp_agent.ts"
        BaseAgent["BaseAgent"]:::agent
        click BaseAgent "https://github.com/zandko/mcp-use/blob/main/src/agents/base.ts"
        SystemPromptBuilder["System Prompt Builder"]:::agent
        click SystemPromptBuilder "https://github.com/zandko/mcp-use/blob/main/src/agents/prompts/system_prompt_builder.ts"
        PromptTemplates["Prompt Templates"]:::agent
        click PromptTemplates "https://github.com/zandko/mcp-use/blob/main/src/agents/prompts/templates.ts"
    end

    %% Adapters
    subgraph "Adapters" 
        direction TB
        AdaptersIndex["Adapters Index"]:::adapter
        click AdaptersIndex "https://github.com/zandko/mcp-use/blob/main/src/adapters/index.ts"
        BaseAdapter["BaseAdapter"]:::adapter
        click BaseAdapter "https://github.com/zandko/mcp-use/blob/main/src/adapters/base.ts"
        LangChainAdapter["LangChainAdapter"]:::adapter
        click LangChainAdapter "https://github.com/zandko/mcp-use/blob/main/src/adapters/langchain_adapter.ts"
    end

    %% Connectors
    subgraph "Connectors"
        direction TB
        ConnectorsIndex["Connectors Index"]:::connector
        click ConnectorsIndex "https://github.com/zandko/mcp-use/blob/main/src/connectors/index.ts"
        BaseConnector["BaseConnector"]:::connector
        click BaseConnector "https://github.com/zandko/mcp-use/blob/main/src/connectors/base.ts"
        HTTPConnector["HTTPConnector"]:::connector
        click HTTPConnector "https://github.com/zandko/mcp-use/blob/main/src/connectors/http.ts"
        WebSocketConnector["WebSocketConnector"]:::connector
        click WebSocketConnector "https://github.com/zandko/mcp-use/blob/main/src/connectors/websocket.ts"
        STDIOConnector["STDIOConnector"]:::connector
        click STDIOConnector "https://github.com/zandko/mcp-use/blob/main/src/connectors/stdio.ts"
    end

    %% Task Managers
    subgraph "Task Managers"
        direction TB
        TaskManagersIndex["TaskManagers Index"]:::taskmgr
        click TaskManagersIndex "https://github.com/zandko/mcp-use/blob/main/src/task_managers/index.ts"
        BaseTaskManager["BaseTaskManager"]:::taskmgr
        click BaseTaskManager "https://github.com/zandko/mcp-use/blob/main/src/task_managers/base.ts"
        SSEManager["SSE Task Manager"]:::taskmgr
        click SSEManager "https://github.com/zandko/mcp-use/blob/main/src/task_managers/sse.ts"
        WebSocketManager["WebSocket Task Manager"]:::taskmgr
        click WebSocketManager "https://github.com/zandko/mcp-use/blob/main/src/task_managers/websocket.ts"
        STDIOManager["STDIO Task Manager"]:::taskmgr
        click STDIOManager "https://github.com/zandko/mcp-use/blob/main/src/task_managers/stdio.ts"
    end

    %% Flow
    UserApp -->|uses| PublicAPI
    PublicAPI --> MCPClient
    MCPClient --> ServerManager
    MCPClient --> ConfigStore
    MCPClient --> Logging
    MCPClient --> Session

    MCPClient --> ConnectorsIndex
    ConnectorsIndex --> HTTPConnector
    ConnectorsIndex --> WebSocketConnector
    ConnectorsIndex --> STDIOConnector

    MCPClient --> AdaptersIndex
    AdaptersIndex --> BaseAdapter
    AdaptersIndex --> LangChainAdapter

    MCPClient --> TaskManagersIndex
    TaskManagersIndex --> SSEManager
    TaskManagersIndex --> WebSocketManager
    TaskManagersIndex --> STDIOManager

    MCPClient --> MCPAgent
    MCPAgent --> BaseAgent
    MCPAgent --> SystemPromptBuilder
    MCPAgent --> PromptTemplates
    MCPAgent --> LangChainAdapter
    MCPAgent --> ServerManager

    LangChainAdapter -->|calls LLM| LLMProvider
    LLMProvider -->|responses/events| MCPClient

    HTTPConnector -->|transport| MCPServer
    WebSocketConnector -->|transport| MCPServer
    STDIOConnector -->|transport| MCPServer

    SSEManager -->|handles events| HTTPConnector
    WebSocketManager -->|handles events| WebSocketConnector
    STDIOManager -->|handles events| STDIOConnector

    %% Styles
    classDef core fill:#D0E8FF,stroke:#0366D6,color:#0366D6;
    classDef agent fill:#E8F4FF,stroke:#1C7ED6,color:#1C7ED6;
    classDef adapter fill:#FFF4E6,stroke:#FD7E14,color:#D9480F;
    classDef connector fill:#F3E8FF,stroke:#7048E8,color:#6336EA;
    classDef taskmgr fill:#FFE3E3,stroke:#FA5252,color:#C92A2A;
    classDef util fill:#E6FCF5,stroke:#2F9E44,color:#2B8A3E;
    classDef external fill:#F8F9FA,stroke:#ADB5BD,color:#495057;
```
