# acnet-ai/mcp-factory architecture

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

- Interactive diagram: https://gitdiagram.com/acnet-ai/mcp-factory
- Repository: https://github.com/acnet-ai/mcp-factory

## Overview

##### Project type and purpose
- This is an open-source Python “factory framework” (library + CLI tool) for creating, configuring, mounting, and running MCP (Model Context Protocol) servers.
- It provides programmatic API (MCPFactory, ManagedServer), a YAML-based configuration system, a project-scaffolding mode, and a CLI front-end.

##### File structure
- Top-level modules:
- mcp_factory/cli – CLI commands, helpers, error filters
- mcp_factory/config – configuration manager and schema
- mcp_factory/factory.py – MCPFactory core
- mcp_factory/server.py – ManagedServer
- mcp_factory/auth.py – authentication providers
- mcp_factory/middleware.py – server middleware hooks
- mcp_factory/mounting – multi-server mounting (models, mounter, registry)
- mcp_factory/project – project builder, template, validator, publisher
- Configuration files & examples:
- examples/… YAML configs and demo scripts
- docs/architecture – detailed architecture docs
- Tests are organized by unit, integration, e2e; CI workflows and code coverage in .github and .codecov.yml

##### README for additional insights
- Core components listed: MCPFactory, ManagedServer, Configuration System, Project Builder
- Operation modes: dict-based, file-based, project-scaffold, direct server creation
- Auth: JWT or OAuth2 with 4 permission levels
- Management tools: decorator + auto-registration of 20+ native tools

a. Main components to include:
- CLI Layer (mcp-factory commands)
- Factory Core (MCPFactory)
- Config Manager & Schema (YAML/dict loader + validator)
- Authentication Provider (JWT/OAuth2)
- Project Builder / Publisher (scaffolding + template engine)
- ManagedServer (tool registration, middleware pipeline, HTTP transport)
- Mounting System (Mounter, Registry, multi-server management)
- Management Tools Registry (20+ tools with permission levels)
- File System / Workspace Root (generated project structures, config files)
- External Dependencies (FastMCP, YAML files, environment variables, external auth server)

b. Relationships & interactions:
- CLI → invokes MCPFactory or ManagedServer entrypoints
- MCPFactory → uses Config Manager to parse & validate configuration
- Config Manager → supplies config to Factory or direct server
- Factory.create_server → orchestrates Project Builder + Publisher → writes to workspace
- Factory.create_server → instantiates ManagedServer + mounts configured tools
- ManagedServer → registers tools (decorator-based) into Tools Registry
- ManagedServer → applies Middleware chain on incoming requests
- ManagedServer → consults Auth Provider for permission checks
- Mounter / Registry → manages multiple ManagedServer instances within one process
- HTTP Transport Layer → exposes server endpoints to clients
- External auth server (if OAuth2) ←→ Auth Provider

c. Architectural patterns & design principles:
- Factory Pattern (MCPFactory) for abstracting server creation
- Builder / Template Pattern (Project Builder) for scaffolding file structure
- Decorator Pattern (@server.tool) for registering tools
- Plugin Architecture (middleware, management tools, custom components)
- Separation of concerns: CLI, config, auth, factory, server, project, mounting

d. Key technologies & libraries:
- Python ≥3.10
- Click or Typer (for CLI commands in mcp_factory/cli)
- PyYAML (configuration loading)
- FastMCP (underlying server library, native tools)
- Jinja2 or built-in template engine (project scaffolding)
- JWT / OAuth2 libraries (auth)

##### Essential details to capture
- Permission levels on the Tools Registry boundary
- Workspace directory as the persistent store for scaffolded projects and config files

## Diagram (Mermaid)

```mermaid
flowchart TD
  subgraph "CLI Layer"
    CLI_main["main.py"]:::frontend
    CLI_helpers["helpers.py"]:::frontend
    CLI_error["error_filter.py"]:::frontend
  end

  subgraph "Factory Core"
    Factory["MCPFactory"]:::core
  end

  subgraph "Config Manager & Schema"
    ConfigMgr["manager.py"]:::config
    ConfigSchema["schema.py"]:::config
  end

  Auth["Authentication Provider (auth.py)"]:::auth

  Server["ManagedServer (server.py)"]:::core

  Middleware["Middleware Pipeline"]:::core

  subgraph "Mounting System"
    Models["models.py"]:::core
    Mounter["mounter.py"]:::core
    Registry["registry.py"]:::core
  end

  subgraph "Project Builder & Publisher"
    Builder["builder.py"]:::config
    Publisher["publisher.py"]:::config
    Template["template.py"]:::config
    Validator["validator.py"]:::config
    Components["components.py"]:::config
    Constants["constants.py"]:::config
  end

  ToolsRegistry["Management Tools Registry"]:::core

  HTTP["HTTP Transport"]:::frontend

  subgraph "External & FS"
    ConfigExamples["configs/"]:::external
    Docs["docs/architecture/"]:::external
    Demo["demo/"]:::external
    Workspace["Workspace Root"]:::external
    ExternalAuth["External Auth Server"]:::external
  end

  CLI_helpers --> CLI_main
  CLI_error --> CLI_main
  CLI_main -->|"invokes create"| Factory
  CLI_main -->|"invokes server"| Server

  ConfigExamples -->|"YAML/dict input"| ConfigMgr
  ConfigMgr -->|"validate"| ConfigSchema
  Factory -->|"load config"| ConfigMgr

  Factory -->|"scaffold generate"| Builder
  Factory -->|"scaffold generate"| Publisher
  Builder --> Workspace
  Publisher --> Workspace

  Factory -->|"instantiate"| Server

  Server -->|"register tools"| ToolsRegistry
  Server -->|"uses middleware"| Middleware
  Middleware --> ToolsRegistry
  Server -->|"authenticate_request"| Auth
  Auth -->|"oauth2/jwt"| ExternalAuth
  Server -->|"expose endpoints"| HTTP

  Mounter --> Server
  Registry --> Server
  Server --> Registry
  Server --> Mounter

  Docs --> Factory
  Demo --> Workspace

  classDef frontend fill:#ADD8E6,stroke:#333,stroke-width:1px
  classDef core fill:#90EE90,stroke:#333,stroke-width:1px
  classDef config fill:#FFA500,stroke:#333,stroke-width:1px
  classDef auth fill:#FF6347,stroke:#333,stroke-width:1px
  classDef external fill:#D3D3D3,stroke:#333,stroke-width:1px

  click CLI_main "https://github.com/acnet-ai/mcp-factory/blob/main/mcp_factory/cli/main.py"
  click CLI_helpers "https://github.com/acnet-ai/mcp-factory/blob/main/mcp_factory/cli/helpers.py"
  click CLI_error "https://github.com/acnet-ai/mcp-factory/blob/main/mcp_factory/cli/error_filter.py"
  click Factory "https://github.com/acnet-ai/mcp-factory/blob/main/mcp_factory/factory.py"
  click ConfigMgr "https://github.com/acnet-ai/mcp-factory/blob/main/mcp_factory/config/manager.py"
  click ConfigSchema "https://github.com/acnet-ai/mcp-factory/blob/main/mcp_factory/config/schema.py"
  click Auth "https://github.com/acnet-ai/mcp-factory/blob/main/mcp_factory/auth.py"
  click Server "https://github.com/acnet-ai/mcp-factory/blob/main/mcp_factory/server.py"
  click Middleware "https://github.com/acnet-ai/mcp-factory/blob/main/mcp_factory/middleware.py"
  click Models "https://github.com/acnet-ai/mcp-factory/blob/main/mcp_factory/mounting/models.py"
  click Mounter "https://github.com/acnet-ai/mcp-factory/blob/main/mcp_factory/mounting/mounter.py"
  click Registry "https://github.com/acnet-ai/mcp-factory/blob/main/mcp_factory/mounting/registry.py"
  click Builder "https://github.com/acnet-ai/mcp-factory/blob/main/mcp_factory/project/builder.py"
  click Publisher "https://github.com/acnet-ai/mcp-factory/blob/main/mcp_factory/project/publisher.py"
  click Template "https://github.com/acnet-ai/mcp-factory/blob/main/mcp_factory/project/template.py"
  click Validator "https://github.com/acnet-ai/mcp-factory/blob/main/mcp_factory/project/validator.py"
  click Components "https://github.com/acnet-ai/mcp-factory/blob/main/mcp_factory/project/components.py"
  click Constants "https://github.com/acnet-ai/mcp-factory/blob/main/mcp_factory/project/constants.py"
  click ConfigExamples "https://github.com/acnet-ai/mcp-factory/tree/main/examples/configs/"
  click Docs "https://github.com/acnet-ai/mcp-factory/tree/main/docs/architecture/"
  click Demo "https://github.com/acnet-ai/mcp-factory/tree/main/examples/demo/"
```
