# fluid-ai/fluidmcp architecture

> Architecture diagram of the GitHub repository fluid-ai/fluidmcp, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-23). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/fluid-ai/fluidmcp
- Repository: https://github.com/fluid-ai/fluidmcp

## Overview

##### Project type and purpose
- This is an open-source, full-featured CLI application (“FluidMCP CLI”) written in Python.
- Purpose: install, configure, and orchestrate “MCP” (Model Context Protocol) server packages from a central registry, manage env vars, spawn multiple servers, expose a FastAPI-based gateway, and optionally use S3 for centralized configuration.

##### File structure
- Top-level artifacts:
– Dockerfile, entrypoint.sh – container entrypoint
– setup.py, pyproject.toml, requirements.txt – packaging/build config
– README.md, command.md – documentation
- Package code under fluidai_mcp/:
– cli.py – main command dispatcher (Click commands: install, run, list, edit-env)
– services/ – core business logic broken into modules:
- env_manager.py – load/validate environment variables
- network_utils.py – port discovery & conflict resolution
- package_installer.py – fetch & install packages from MCP registry
- package_launcher.py – spawn MCP servers (subprocess calls to npx, uvx, etc.)
- package_list.py – enumerate installed packages
- s3_utils.py – upload/download metadata to/from S3 for “master” mode
– examples/ – Jupyter notebooks demonstrating usage

##### README for additional insights
- Technical stack: Python, Click, FastAPI/Uvicorn, boto3 (S3), subprocess (npx), JSON-RPC over HTTP/SSE
- Key flows:
– install: HTTP fetch → local .fmcp-packages directory → metadata.json
– run: metadata merge (local or S3) → assign ports → spawn server processes → start FastAPI “SuperGateway”
– list & edit-env: file-system based introspection & interactive CLI UI

##### Detail is critical—capture all essential elements
- Metadata.json flow: registry → local store → merged metadata → gateway
- Environment variable manager injecting secrets into subprocesses
- Port management loop: NetworkUtils scanning → assign unique ports
- Secure/secure-token flow if secure mode is enabled

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Auxiliary Components
    subgraph "Auxiliary"
        EX["Jupyter Examples"]:::aux
        DOC["Documentation"]:::aux
        BUILD["Packaging & Build"]:::aux
        DOCKER["Docker Entrypoint"]:::aux
    end

    %% Core Layers
    subgraph "CLI Layer"
        CLI["CLI Frontend"]:::cli
    end

    subgraph "Service Layer"
        EM["EnvManager"]:::service
        NU["NetworkUtils"]:::service
        PI["PackageInstaller"]:::service
        PLch["PackageLauncher & FastAPI SuperGateway"]:::service
        PLst["PackageList"]:::service
        S3["S3Utils"]:::service
    end

    subgraph "Storage & FS"
        FS[".fmcp-packages"]:::fs
    end

    subgraph "External Services"
        REG["Registry HTTP API"]:::external
        S3Store["S3 Storage"]:::external
    end

    subgraph "Runtime"
        Proc["MCP Server Processes"]:::runtime
        Gateway["FastAPI SuperGateway"]:::gateway
        Client["Client Applications"]:::client
    end

    %% Relationships
    CLI -->|parse commands| EM
    CLI -->|parse commands| NU
    CLI -->|parse commands| PI
    CLI -->|parse commands| PLch
    CLI -->|parse commands| PLst
    CLI -->|parse commands| S3

    PI -->|HTTP fetch packages| REG
    PI -->|write packages| FS

    S3 <-->|sync metadata| S3Store

    PLch -->|load env vars| EM
    PLch -->|port allocation| NU
    PLch -->|read metadata| FS
    PLch -->|spawn processes| Proc
    PLch -->|start gateway| Gateway

    Gateway -->|forward JSON-RPC/SSE| Proc
    Client -->|HTTP/SSE calls| Gateway

    %% Click Events
    click CLI "https://github.com/fluid-ai/fluidmcp/blob/main/fluidai_mcp/cli.py"
    click EM "https://github.com/fluid-ai/fluidmcp/blob/main/fluidai_mcp/services/env_manager.py"
    click NU "https://github.com/fluid-ai/fluidmcp/blob/main/fluidai_mcp/services/network_utils.py"
    click PI "https://github.com/fluid-ai/fluidmcp/blob/main/fluidai_mcp/services/package_installer.py"
    click PLch "https://github.com/fluid-ai/fluidmcp/blob/main/fluidai_mcp/services/package_launcher.py"
    click PLst "https://github.com/fluid-ai/fluidmcp/blob/main/fluidai_mcp/services/package_list.py"
    click S3 "https://github.com/fluid-ai/fluidmcp/blob/main/fluidai_mcp/services/s3_utils.py"
    click FS "https://github.com/fluid-ai/fluidmcp/tree/main/.fmcp-packages/"
    click Gateway "https://github.com/fluid-ai/fluidmcp/blob/main/fluidai_mcp/services/package_launcher.py"
    click EX "https://github.com/fluid-ai/fluidmcp/tree/main/fluidai_mcp/examples/"
    click DOC "https://github.com/fluid-ai/fluidmcp/blob/main/README.md"
    click BUILD "https://github.com/fluid-ai/fluidmcp/blob/main/setup.py"
    click DOCKER "https://github.com/fluid-ai/fluidmcp/tree/main/Dockerfile"

    %% Styles
    classDef aux fill:#f9f,stroke:#333,stroke-width:1px
    classDef cli fill:#efe,stroke:#2a5,stroke-width:1px,stroke-dasharray: 5 5
    classDef service fill:#cff,stroke:#07a,stroke-width:1px
    classDef fs fill:#ddd,stroke:#888,stroke-width:1px,stroke-dasharray: 2 2
    classDef external fill:#cfc,stroke:#070,stroke-width:1px
    classDef runtime fill:#fcf,stroke:#a07,stroke-width:1px
    classDef gateway fill:#fdd,stroke:#f55,stroke-width:1px
    classDef client fill:#ffd,stroke:#aa7,stroke-width:1px
```
