# adam-paterson/mcp-crew-ai architecture

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

- Interactive diagram: https://gitdiagram.com/adam-paterson/mcp-crew-ai
- Repository: https://github.com/adam-paterson/mcp-crew-ai

## Overview

##### Project type and purpose
- This is a Python-based CLI + server application (“MCP Crew AI Server”) whose primary purpose is to load two YAML configuration files (agents.yml and tasks.yml), then orchestrate multi-agent workflows by interacting with the Model Context Protocol (MCP) SDK and external LLM/tool hosts (e.g., Claude Desktop, Cursor IDE).

##### File structure
- Top-level files:
- README.md, pyproject.toml (packaging metadata), .gitignore
- examples/ (sample agent/task YAMLs)
- src/mcp_crew_ai/ contains four modules:
- __main__.py – entry point for “python -m mcp_crew_ai”
- cli.py – parses CLI arguments (--agents, --tasks, --topic, etc.)
- server.py – core workflow-orchestration logic (loads YAMLs, initializes MCP SDK, runs workflows)
- server_cmd.py – glue between CLI arguments and server.py invocation
- No separate “frontend”; the user interface is purely command-line or STDIO.

##### Key insights from the README
- Configuration-driven design: loads agents.yml and tasks.yml automatically or via CLI flags
- Two operational modes: local STDIO (development/test) vs MCP run_workflow (production orchestration)
- External dependencies: MCP SDK (protocol to wrap LLMs/tools), PyYAML (config parsing), CrewAI library

##### Main components
A. CLI Layer
- mcp-crew-ai command (invokes __main__.py → cli.py)
- CLI parser: reads paths to agents.yml + tasks.yml + variables
- Passes args to server_cmd.py
B. Server Layer
- server_cmd.py: constructs Server instance
- server.py:
- Config Loader (YAML parser + variable substitution)
- Workflow Manager (implements run_workflow via MCP SDK)
- Multi-Agent Orchestrator (dispatches tasks to agent roles)
C. External/Infrastructure Services
- MCP SDK (Python library that implements the Model Context Protocol)
- LLM Hosts & Tools (e.g., Claude Desktop, Cursor IDE) – external endpoints
- File System (reads/writes YAML and output files)
D. Configuration Artifacts
- agents.yml
- tasks.yml
- Optional JSON variables file

##### Relationships & data flows
1. User runs “mcp-crew-ai --agents path/... --tasks path/… [--variables …]”
2. CLI Layer parses flags → hands off to server_cmd
3. Server Layer reads YAML files + variables → builds in-memory config objects
4. Workflow Manager calls MCP SDK’s run_workflow API
5. MCP SDK opens streaming channels to external LLM hosts / tools
6. LLM Hosts process agent instructions and return responses via MCP
7. Workflow Manager collects results, writes to STDIO or output files
8. User sees aggregated output (e.g., zoo_report.md)

##### Architectural patterns & design principles
- Separation of concerns: CLI parsing vs business logic vs external protocol
- Configuration-driven: no hard-coded workflows; agents/tasks defined in YAML
- Adapter/Wrapper: MCP SDK abstracts over various LLM endpoints
- Pipeline/Orchestration: sequential or hierarchical processing of multi-agent tasks

##### Technology & frameworks to annotate
- Python 3.11+ runtime
- click / argparse (if used inside cli.py)
- PyYAML for config loading
- MCP SDK for protocol interactions
- uvx (optional UV execution)

## Diagram (Mermaid)

```mermaid
graph TD
    subgraph "CLI Layer"
        CLI["mcp-crew-ai CLI\n(entry: __main__.py)"]:::internal
        Parser["CLI Parser\n(cli.py)"]:::internal
        ServerCmd["CLI-to-Server Glue\n(server_cmd.py)"]:::internal
    end

    subgraph "CrewAI Server"
        Server["Server Core\n(server.py)"]:::internal
        ConfigLoader["Config Loader\n(PyYAML)"]:::internal
        WorkflowMgr["Workflow Manager\n(MCP run_workflow)"]:::internal
        Orchestrator["Multi-Agent Orchestrator"]:::internal
    end

    subgraph "Configuration Store"
        AgentsYML["agents.yml"]:::docs
        TasksYML["tasks.yml"]:::docs
        VarsJSON["variables.json"]:::docs
    end

    subgraph "External Systems"
        MCP["MCP SDK"]:::external
        LLM["LLM Hosts & Tools"]:::external
        FS["File System / STDIO"]:::external
        User["User Output\n(zoo_report.md / STDIO)"]:::external
    end

    subgraph "Project Files"
        PYProj["pyproject.toml"]:::docs
        README["README.md"]:::docs
        GIT[".gitignore"]:::docs
    end

    CLI -->|"parse flags"| Parser
    Parser -->|"build args"| ServerCmd
    ServerCmd -->|"invoke"| Server
    Server -->|"load configs"| ConfigLoader
    ConfigLoader -->|"read"| AgentsYML
    ConfigLoader -->|"read"| TasksYML
    ConfigLoader -->|"read"| VarsJSON
    Server -->|"orchestrate"| WorkflowMgr
    WorkflowMgr -->|"run_workflow(request)"| MCP
    MCP -->|"streaming"| LLM
    WorkflowMgr -->|"write results"| FS
    FS -->|"output"| User

    click CLI "https://github.com/adam-paterson/mcp-crew-ai/blob/main/src/mcp_crew_ai/__main__.py"
    click Parser "https://github.com/adam-paterson/mcp-crew-ai/blob/main/src/mcp_crew_ai/cli.py"
    click ServerCmd "https://github.com/adam-paterson/mcp-crew-ai/blob/main/src/mcp_crew_ai/server_cmd.py"
    click Server "https://github.com/adam-paterson/mcp-crew-ai/blob/main/src/mcp_crew_ai/server.py"
    click AgentsYML "https://github.com/adam-paterson/mcp-crew-ai/blob/main/examples/agents.yml"
    click TasksYML "https://github.com/adam-paterson/mcp-crew-ai/blob/main/examples/tasks.yml"
    click PYProj "https://github.com/adam-paterson/mcp-crew-ai/blob/main/pyproject.toml"
    click README "https://github.com/adam-paterson/mcp-crew-ai/blob/main/README.md"
    click GIT "https://github.com/adam-paterson/mcp-crew-ai/blob/main/.gitignore"

    classDef internal fill:#bbdefb,stroke:#0d47a1,color:#0d47a1;
    classDef external fill:#c8e6c9,stroke:#1b5e20,color:#1b5e20;
    classDef docs fill:#fff9c4,stroke:#f57f17,color:#f57f17;
```
