How adam-paterson/mcp-crew-ai works
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)