# chi-n-nguyen/any-mcp architecture

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

- Interactive diagram: https://gitdiagram.com/chi-n-nguyen/any-mcp
- Repository: https://github.com/chi-n-nguyen/any-mcp

## Overview

##### Project type and purpose
- Any-MCP is a full-stack, production-ready client framework written in Python.
- It exposes both a rich CLI (under any_mcp/cli) and a Web API (any_mcp/api/web_mcp.py) for orchestrating “Model Context Protocol” (MCP) servers.
- Its goal is to let developers discover, install, manage, and call tools on multiple MCP servers (e.g., Notion, Discord, custom scripts) without building each integration from scratch.

##### File structure
Top-level directories:
- any_mcp/ – core framework
– cli/            # Command-line interface modules
– api/            # REST Web API modules
– core/           # Client logic, LLM integrations (claude.py, gemini.py), error handling
– managers/       # MCP lifecycle & plugin management (installer.py, manager.py)
– integration/    # Message bridging & protocol adapters
– servers/        # Helpers to connect & talk to MCP servers
- all_mcp_servers/ – Official reference server implementations (Notion, Discord)
- mcps/            – Local example servers (demo_calculator.py, notion-official.py)
- config/          – YAML config for installed MCPs (mcp_config.yaml)
- tools_for_mcp_server/ – Test fixtures & JSON payloads for server tooling
- examples/, llmgine-mcp-integration/, universal_mcp_adapter/ – Extension and packaging modules
- tests/           – Unit and integration tests

Notice:
– CLI and WebAPI are two entry points into the same application layer.
– Managers handle discovery, installation, start/stop, health checks.
– Core contains the MCPClient which orchestrates calls to external LLM-backed servers.
– Integration modules bridge events & protocol mappings.

##### README for additional insights
User → CLI/WebAPI → MCPManager → MCPClient → LLM Services & MCP Servers
- It also outlines six logical layers: UI, Application, LLM Services, MCP Management, MCP Core, Server Ecosystem.

a. Main components
1. User Interface Layer
– CLI Interface (any_mcp/cli)
– Web API (any_mcp/api)
2. Application Layer
– MCP Manager & Installer (any_mcp/managers)
– Integration & Event Handlers (any_mcp/integration)
– Command orchestration & Core client logic (any_mcp/core)
3. LLM Services
– Cloud LLMs (Claude, Gemini) via core/claude.py & core/gemini.py
4. MCP Core
– MCPClient & ProtocolAdapter abstractions (any_mcp/core/client.py, integration/tool_adapter.py)
5. Server Ecosystem
– Official Servers (all_mcp_servers/notion_mcp_server, discord_mcp_server)
– Local Script Servers (mcps/demo_calculator.py)
– Third-Party or Custom Servers (loaded via config/mcp_config.yaml)
6. Configuration
– YAML store (config/mcp_config.yaml) & .env variables
7. Test & Tooling
– tools_for_mcp_server for load testing & contract validation

b. Relationships & interactions
User → CLI / WebAPI
CLI/WebAPI → MCP Manager → MCPClient
MCPClient → LLM Services (Claude, Gemini)
MCPClient → MCP Servers (Official, Local, Third-Party)
MCPManager → Installer / Lifecycle manager → OS / Docker
MCPClient ↔ Integration / MessageBridge for protocol conversion
MCPClient reads config from config/mcp_config.yaml
- Bidirectional flows where appropriate (e.g., health checks, message replies).

c. Architectural patterns & design principles
- Layered architecture (UI → Application → Core → External)
- Plugin-based extensibility (protocol adapters, custom servers, custom clients)
- Adapter pattern for MCP protocol abstractions
- CLI commands implemented via Click or argparse (any_mcp/cli/main.py)
- Declarative server configuration (YAML + env vars)

d. Technologies & frameworks
- Python 3.x
- Click or built-in CLI library (any_mcp/cli)
- FastAPI or Flask (if used in any_mcp/api/web_mcp.py)
- PyYAML for configuration
- Asyncio / aiohttp for HTTP & WebSocket calls
- Docker integration (manager invokes docker:// sources)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Interface Layer
    subgraph "User Interface Layer"
        direction TB
        CLI["CLI Interface\n(any_mcp/cli)"]:::ui
        WebAPI["Web API\n(any_mcp/api)"]:::ui
    end

    %% Application Layer
    subgraph "Application Layer"
        direction TB
        Manager["MCP Manager\n(any_mcp/managers/manager.py)"]:::app
        Installer["Installer\n(any_mcp/managers/installer.py)"]:::app
        Integration["Integration & Event Handlers\n(any_mcp/integration)"]:::app
        Orchestration["Core Orchestration\n(any_mcp/core)"]:::app
    end

    %% Core Layer
    subgraph "Core Layer"
        direction TB
        Client["MCPClient & Protocol Adapters\n(any_mcp/core/client.py)"]:::core
        RunTools["run_tools.py"]:::core
        ToolsCore["tools.py"]:::core
        ErrorHandling["error_handling.py"]:::core
        ChatCore["chat.py"]:::core
        CLIChat["cli_chat.py"]:::core
        MessageBridge["message_bridge.py"]:::core
        EventHandlers["event_handlers.py"]:::core
        ToolAdapter["tool_adapter.py"]:::core
        Engine["engine.py"]:::core
        ServerHelper["connect_server.py"]:::core
    end

    %% LLM Services
    subgraph "LLM Services"
        direction TB
        Claude["Claude Integration\n(claude.py)"]:::service
        Gemini["Gemini Integration\n(gemini.py)"]:::service
    end

    %% Server Ecosystem
    subgraph "Server Ecosystem"
        direction TB
        subgraph "Official Servers"
            DiscordServer["Discord MCP Server\n(discord_mcp_server.py)"]:::ext
            NotionServer["Notion MCP Server\n(notion_mcp_server.py)"]:::ext
            Handlers["Handlers\n(base, pages, databases, search, health)"]:::ext
            ServerCore["Server Core\n(server.py)"]:::ext
        end
        subgraph "Local Example Servers"
            DemoCalc["Demo Calculator\n(demo_calculator.py)"]:::ext
            NotionOfficial["Notion Official\n(notion-official.py)"]:::ext
        end
        ThirdParty["Third-Party Servers\n(via config)"]:::ext
    end

    %% Configuration & Test
    Config["Configuration Store\n(mcp_config.yaml, .env)"]:::config
    subgraph "Test & Tooling"
        direction TB
        DiscordTools["Discord Server Tools"]:::test
        NotionTools["Notion Server Tools"]:::test
        LoadTools["load_tools.py"]:::test
    end

    %% Main Entry
    MainApp["Main Application\n(any_mcp/main.py)"]:::core

    %% Connections
    CLI -->|"invoke"| Manager
    WebAPI -->|"invoke"| Manager
    Manager -->|"uses"| Installer
    Manager -->|"orchestrates"| Client
    Client -->|"calls"| Claude
    Client -->|"calls"| Gemini
    Client -->|"connects"| DiscordServer
    Client -->|"connects"| NotionServer
    Client -->|"connects"| DemoCalc
    Client -->|"connects"| NotionOfficial
    Client -->|"loads"| ThirdParty
    Client <-->|"bridges"| MessageBridge
    MessageBridge -->|"handles"| EventHandlers
    EventHandlers -->|"adapts"| ToolAdapter
    Client -->|"executes"| RunTools
    Client -->|"executes"| ToolsCore
    Client -->|"reads"| Config
    Manager -->|"reads"| Config
    Manager -->|"uses"| ServerHelper
    MainApp -->|"starts"| CLI
    MainApp -->|"starts"| WebAPI

    %% Click Events
    click CLI "https://github.com/chi-n-nguyen/any-mcp/blob/main/any_mcp/cli/main.py"
    click WebAPI "https://github.com/chi-n-nguyen/any-mcp/blob/main/any_mcp/api/web_mcp.py"
    click Manager "https://github.com/chi-n-nguyen/any-mcp/blob/main/any_mcp/managers/manager.py"
    click Installer "https://github.com/chi-n-nguyen/any-mcp/blob/main/any_mcp/managers/installer.py"
    click Client "https://github.com/chi-n-nguyen/any-mcp/blob/main/any_mcp/core/client.py"
    click RunTools "https://github.com/chi-n-nguyen/any-mcp/blob/main/any_mcp/core/run_tools.py"
    click ToolsCore "https://github.com/chi-n-nguyen/any-mcp/blob/main/any_mcp/core/tools.py"
    click ErrorHandling "https://github.com/chi-n-nguyen/any-mcp/blob/main/any_mcp/core/error_handling.py"
    click ChatCore "https://github.com/chi-n-nguyen/any-mcp/blob/main/any_mcp/core/chat.py"
    click CLIChat "https://github.com/chi-n-nguyen/any-mcp/blob/main/any_mcp/core/cli_chat.py"
    click MessageBridge "https://github.com/chi-n-nguyen/any-mcp/blob/main/any_mcp/integration/message_bridge.py"
    click EventHandlers "https://github.com/chi-n-nguyen/any-mcp/blob/main/any_mcp/integration/event_handlers.py"
    click ToolAdapter "https://github.com/chi-n-nguyen/any-mcp/blob/main/any_mcp/integration/tool_adapter.py"
    click Engine "https://github.com/chi-n-nguyen/any-mcp/blob/main/any_mcp/integration/engine.py"
    click ServerHelper "https://github.com/chi-n-nguyen/any-mcp/blob/main/any_mcp/servers/connect_server.py"
    click DiscordServer "https://github.com/chi-n-nguyen/any-mcp/blob/main/all_mcp_servers/discord_mcp_server.py"
    click NotionServer "https://github.com/chi-n-nguyen/any-mcp/blob/main/all_mcp_servers/notion_mcp_server.py"
    click Handlers "https://github.com/chi-n-nguyen/any-mcp/tree/main/all_mcp_servers/notion_mcp_server/handlers"
    click ServerCore "https://github.com/chi-n-nguyen/any-mcp/blob/main/all_mcp_servers/notion_mcp_server/server.py"
    click DemoCalc "https://github.com/chi-n-nguyen/any-mcp/blob/main/mcps/demo_calculator.py"
    click NotionOfficial "https://github.com/chi-n-nguyen/any-mcp/blob/main/mcps/notion-official.py"
    click Config "https://github.com/chi-n-nguyen/any-mcp/blob/main/config/mcp_config.yaml"
    click DiscordTools "https://github.com/chi-n-nguyen/any-mcp/tree/main/tools_for_mcp_server/discord_mcp_server_tools"
    click NotionTools "https://github.com/chi-n-nguyen/any-mcp/tree/main/tools_for_mcp_server/notion_mcp_server_tools"
    click LoadTools "https://github.com/chi-n-nguyen/any-mcp/blob/main/tools_for_mcp_server/tool_mcp_server_loading_package/load_tools.py"
    click MainApp "https://github.com/chi-n-nguyen/any-mcp/blob/main/any_mcp/main.py"

    %% Styles
    classDef ui fill:#D0E6F6,stroke:#3B8DC1,color:#000;
    classDef app fill:#DFF2BF,stroke:#8BBF3B,color:#000;
    classDef core fill:#C9DAF8,stroke:#3B5E8E,color:#000;
    classDef service fill:#FDE9D9,stroke:#E85C41,color:#000;
    classDef ext fill:#E8E8E8,stroke:#A9A9A9,color:#000;
    classDef config fill:#FFF2B2,stroke:#E1A800,color:#000;
    classDef test fill:#FADADD,stroke:#D6618F,color:#000;
```
