How fluid-ai/fluidmcp works
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