# adhikasp/mcp-client-cli architecture

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

- Interactive diagram: https://gitdiagram.com/adhikasp/mcp-client-cli
- Repository: https://github.com/adhikasp/mcp-client-cli

## Overview

##### Main components of the system and include the relevant filenames
a. CLI “Entry Point” Layer:
- Component: Command Line Interface
- Key File: src/mcp_client_cli/cli.py
- Description: Acts as the user-facing entry point where commands are received, and it passes them on for processing.
b. Configuration Management:
- Component: Config Manager / Settings Loader
- Key File: src/mcp_client_cli/config.py
- Description: Loads and parses the MCP and LLM configuration details (as shown in the README and mcp-server-config-example.json).
c. Prompt Handling and Interpretation:
- Components: Prompt Builder and Input Parser
- Key Files: src/mcp_client_cli/prompt.py and src/mcp_client_cli/input.py
- Description: These modules handle user input, parse commands (including CLI flags like --list-prompts or tool calls), and map them into equivalent prompt actions.
d. I/O Processing:
- Components: Output Engine and Clipboard / Image Support
- Key Files: src/mcp_client_cli/output.py
- Description: Manages the response output (text/image), interfacing with the terminal, and formatting results.
e. Memory and Context Management:
- Component: Memory Manager
- Key File: src/mcp_client_cli/memory.py
- Description: Maintains and retrieves context continuity (e.g., when using continuation “c ” commands).
f. Tool/Command Invocation:
- Components: Tool Invoker and Storage
- Key Files: src/mcp_client_cli/tool.py and src/mcp_client_cli/storage.py
- Description: Coordinates triggering of external MCP tools (e.g., fetching from Brave Search, YouTube), managing parameters (like confirmation flags) and handling tool-specific protocols.
g. Constant Definitions:
- Component: Type & Command Constants
- Key File: src/mcp_client_cli/const.py
- Description: Stores constants to maintain consistency throughout the client logic.

##### Mapping External and Deployment Components
a. LLM Providers and External MCP Servers:
- These external services interact with the CLI via network/API calls defined by the configuration (as described in the README’s JSON sample) and correspond to invoked command-line tools.
b. Local File Configuration:
- Also reference CONFIG.md (documentation for configuration) and mcp-server-config-example.json as examples of the expected configuration schema.
c. Build and Integration Tools:
- Mention supporting files in the root like pyproject.toml, .github workflows (release.yml, test.yml) which indicate CI/CD processes, even though they are more supportive than central to the runtime architecture.
- We can show these on the periphery if desired.

##### Relationships and Data Flow
- From “User Terminal” → “CLI (cli.py)” indicating command input.
- From “CLI” → “Config Manager (config.py)” for loading settings.
- From “CLI” → “Prompt/Input Parser (prompt.py, input.py)” to transform the user command into application logic.
- From “CLI” and its sub-components (memory.py, tool.py) → “LLM Provider/MCP Servers” indicating requests that go out to external services.
- Finally, responses are routed back from external services into “Output Handler (output.py)” and then to the terminal.
- The CLI calling the tool handler in tool.py after processing via the prompt and input parsers.
- The configuration manager reading and interpreting data from ~.llm/config.json (as well as from repomix.config.json/CONFIG.md) to inform both tool behavior and LLM settings.

##### Architectural Patterns and Design Principles
a. Modularity: The directory structure in src/mcp_client_cli shows a modular approach, with separate modules for CLI logic, config management, input/output handling, and tool invocation.
c. Extensibility: The integration of multiple MCP servers (as seen in the configuration example) demonstrates that the architecture is designed to be extensible. Make clear extension points where new tool modules could be plugged in.
d. External Dependencies: Highlight that external API calls and third-party services are decoupled from the internal logic.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Interface
    USER["User Terminal"]

    %% MCP Client Internal Components
    subgraph "MCP Client"
        CLI["CLI (cli.py)"]
        CONFIG["Config Manager (config.py)"]
        PROMPT["Prompt Builder (prompt.py)"]
        INPUT["Input Parser (input.py)"]
        MEMORY["Memory Manager (memory.py)"]
        TOOL["Tool Invoker (tool.py)"]
        STORAGE["Storage Manager (storage.py)"]
        CONST["Constants (const.py)"]
        OUTPUT["Output Engine (output.py)"]
    end

    %% External Services
    subgraph "External Services"
        LLM["LLM Providers (ex: OpenAI, Groq, etc.)"]
        MCP["MCP Servers (Brave Search, YouTube, etc.)"]
    end

    %% Local Configuration Files
    subgraph "Local & Config Files"
        CONFIGFILE["Config File (~/.llm/config.json)"]
        CONFIGDOC["Config Documentation (CONFIG.md)"]
        MCP_CONFIG["MCP Config Example (mcp-server-config-example.json)"]
    end

    %% CI/CD and Build Tools
    subgraph "CI/CD & Build Tools"
        PYPROJECT["Build Config (pyproject.toml)"]
        WORKFLOW["GitHub Workflows (.github/release.yml, test.yml)"]
    end

    %% Data Flow Connections
    USER -->|"input command"| CLI

    %% Within MCP Client
    CLI -->|"load_config"| CONFIG
    CLI -->|"build_prompt"| PROMPT
    CLI -->|"parse_input"| INPUT
    CLI -->|"manage_context"| MEMORY

    %% Combine prompt and input to invoke tools
    PROMPT -->|"prepare_args"| TOOL
    INPUT -->|"prepare_args"| TOOL

    %% Tool invocation may also use storage and constants internally (for parameters)
    CONST --> TOOL
    TOOL --> STORAGE

    %% External API calls from Tool, Memory, and CLI components
    TOOL -->|"call APIs"| LLM
    TOOL -->|"call APIs"| MCP
    MEMORY -->|"context request"| LLM

    %% External responses route to Output Engine
    LLM -->|"response"| OUTPUT
    MCP -->|"response"| OUTPUT

    %% Output rendered to User Terminal
    OUTPUT -->|"display_output"| USER

    %% Configuration connections from config files to Config Manager
    CONFIGFILE -->|"provide settings"| CONFIG
    CONFIGDOC ---|"reference"| CONFIG
    MCP_CONFIG ---|"reference"| CONFIG

    %% Styles
    classDef internal fill:#A9D0F5,stroke:#1B6CA8,stroke-width:2px;
    classDef external fill:#C5F7C3,stroke:#2E8B57,stroke-width:2px;
    classDef config fill:#FFF2B2,stroke:#D4AC0D,stroke-width:2px;
    classDef cicd fill:#F9E79F,stroke:#B7950B,stroke-width:2px;

    %% Apply classes to nodes
    class CLI,CONFIG,PROMPT,INPUT,OUTPUT,MEMORY,TOOL,STORAGE,CONST internal;
    class LLM,MCP external;
    class CONFIGFILE,CONFIGDOC,MCP_CONFIG config;
    class PYPROJECT,WORKFLOW cicd;

    %% Click Events for component mapping
    click CLI "https://github.com/adhikasp/mcp-client-cli/blob/master/src/mcp_client_cli/cli.py"
    click CONFIG "https://github.com/adhikasp/mcp-client-cli/blob/master/src/mcp_client_cli/config.py"
    click PROMPT "https://github.com/adhikasp/mcp-client-cli/blob/master/src/mcp_client_cli/prompt.py"
    click INPUT "https://github.com/adhikasp/mcp-client-cli/blob/master/src/mcp_client_cli/input.py"
    click OUTPUT "https://github.com/adhikasp/mcp-client-cli/blob/master/src/mcp_client_cli/output.py"
    click MEMORY "https://github.com/adhikasp/mcp-client-cli/blob/master/src/mcp_client_cli/memory.py"
    click TOOL "https://github.com/adhikasp/mcp-client-cli/blob/master/src/mcp_client_cli/tool.py"
    click STORAGE "https://github.com/adhikasp/mcp-client-cli/blob/master/src/mcp_client_cli/storage.py"
    click CONST "https://github.com/adhikasp/mcp-client-cli/blob/master/src/mcp_client_cli/const.py"
```
