# mozilla-ai/mcpd architecture

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

- Interactive diagram: https://gitdiagram.com/mozilla-ai/mcpd
- Repository: https://github.com/mozilla-ai/mcpd

## Overview

##### Project type and purpose
- This is a Go-based CLI tool with a long-running “daemon” component that manages Model Context Protocol (MCP) servers as subprocesses and exposes them over HTTP.
- Purpose: provide a unified, declarative way (`.mcpd.toml`) to configure, launch, and proxy MCP servers locally or in containers, with built-in secrets management, runtime arguments, and plugin support.

##### File structure
- Top-level directories:
- cmd/       → CLI commands (`add`, `config`, `daemon`, `init`, etc.)
- internal/  → Core application logic organized by concern (api, cmd, config, context, daemon, domain, plugin, provider, registry, runtime, etc.)
- tools/     → Utility programs (docs generator, registry validator)
- docs/      → MkDocs-powered documentation
- Configuration & build: Dockerfile, Makefile, mkdocs.yaml, GitHub workflows
- Patterns:
- Hexagonal (Ports & Adapters): internal/domain services, external adapters for CLI, HTTP API, file I/O, subprocess orchestration
- Subsystems for plugin management, providers (e.g., mcpm, mozilla_ai), registries, runtime loaders

##### README for additional insights
- Core components: CLI front-end, “mcpd daemon” HTTP proxy, subprocess-based MCP servers over STDIO
- Key features: declarative `.mcpd.toml`, plugin protocol buffers, secrets isolation, local→prod parity

##### Additional notes
- Plugin subsystem prominently (internal/plugin), as the latest main branch enhances plugin capabilities.
- STDIO-based communication channel between the daemon and MCP servers as a separate interface.
- Critical paths (e.g., config export, health tracking, runtime argument injection).

- Reflects the hexagonal layering
- Highlights the CLI vs. daemon boundary
- Shows plugin and provider integrations
- Illustrates subprocess orchestration and HTTP proxying
- Captures configuration and secrets management flows

## Diagram (Mermaid)

```mermaid
flowchart TD
  %% Presentation Layer
  subgraph "Presentation Layer"
    CLI["CLI Front-end"]:::frontend
    APIServer["REST HTTP API Server"]:::frontend
  end

  %% Application Layer
  subgraph "Application Layer"
    CmdHandlers["Command Handlers"]:::application
    APIRoutes["API Adapters & Controllers"]:::application
    ConfigMgr["Configuration Manager"]:::application
    ContextLoader["Context Loader"]:::application
    PluginSubsystem["Plugin Subsystem"]:::application
  end

  %% Domain & Orchestration
  subgraph "Domain & Orchestration"
    DaemonSvc["Daemon & Client Manager"]:::domain
    RuntimeMgr["Runtime Manager & Loader"]:::domain
    CacheLayer["Cache Layer"]:::domain
    RegistryMod["Registry Module"]:::domain
    ProviderMod["Provider Modules"]:::domain
  end

  %% Infrastructure & External Systems
  subgraph "Infrastructure & External Systems"
    FileSystem["File System Adapter"]:::infra
    Subprocess["Subprocess Orchestration (STDIO)"]:::infra
    DockerSupport["Docker/Container Runtime"]:::infra
    ExternalAgents["External Agents / Clients"]:::external
  end

  %% Connections
  CLI -->|invokes| PluginSubsystem
  PluginSubsystem -->|routes to| CmdHandlers
  CmdHandlers -->|uses| ConfigMgr
  CmdHandlers -->|loads| ContextLoader

  ExternalAgents -->|HTTP calls| APIServer
  APIServer -->|routes requests| APIRoutes
  APIRoutes -->|passes through| PluginSubsystem
  PluginSubsystem -->|calls| DaemonSvc

  DaemonSvc -->|spawns| Subprocess
  Subprocess -->|managed by| RuntimeMgr
  RuntimeMgr -->|resolves via| RegistryMod
  RuntimeMgr -->|adapts via| ProviderMod
  ContextLoader -->|reads config| ConfigMgr
  ConfigMgr <-->|reads/writes| FileSystem
  DaemonSvc -->|caches metadata| CacheLayer
  RuntimeMgr -->|supports| DockerSupport

  %% Click Events
  click CLI "https://github.com/mozilla-ai/mcpd/tree/main/cmd/"
  click CmdHandlers "https://github.com/mozilla-ai/mcpd/tree/main/internal/cmd/"
  click APIServer "https://github.com/mozilla-ai/mcpd/blob/main/internal/daemon/api_server.go"
  click APIRoutes "https://github.com/mozilla-ai/mcpd/blob/main/internal/api/routes.go"
  click ConfigMgr "https://github.com/mozilla-ai/mcpd/blob/main/internal/config/config.go"
  click ContextLoader "https://github.com/mozilla-ai/mcpd/blob/main/internal/context/loader.go"
  click PluginSubsystem "https://github.com/mozilla-ai/mcpd/blob/main/internal/plugin/adapter.go"
  click DaemonSvc "https://github.com/mozilla-ai/mcpd/blob/main/internal/daemon/daemon.go"
  click RuntimeMgr "https://github.com/mozilla-ai/mcpd/blob/main/internal/runtime/loader.go"
  click CacheLayer "https://github.com/mozilla-ai/mcpd/blob/main/internal/cache/cache.go"
  click RegistryMod "https://github.com/mozilla-ai/mcpd/blob/main/internal/registry/registry.go"
  click ProviderMod "https://github.com/mozilla-ai/mcpd/tree/main/internal/provider/"
  click FileSystem "https://github.com/mozilla-ai/mcpd/blob/main/internal/files/files.go"
  click Subprocess "https://github.com/mozilla-ai/mcpd/blob/main/internal/runtime/server.go"
  click DockerSupport "https://github.com/mozilla-ai/mcpd/blob/main/internal/runtime/runtimes.go"

  %% Styles
  classDef frontend fill:#cfe2f3,stroke:#0366d6,stroke-width:2px
  classDef application fill:#d9ead3,stroke:#38761d,stroke-width:2px
  classDef domain fill:#fff2cc,stroke:#bf9000,stroke-width:2px
  classDef infra fill:#f4cccc,stroke:#cc0000,stroke-width:2px
  classDef external fill:#e7e6e6,stroke:#555555,stroke-width:2px
```
