sparesparrow/mcp-project-orchestrator

Purpose and Canonical Surface

This is a Python 3.9+ MCP project-orchestration package: it manages reusable project/component templates and prompts, generates/renders Mermaid diagrams, and exposes MCP/AWS/OpenSSL-oriented orchestration. The primary maintained implementation appears at repository root under src/; mcp-project-orchestrator/ and restructured/ contain substantial duplicated or reorganized copies.

Entry Points and Runtime

CLI/package startup is centered on src/mcp_project_orchestrator/__main__.py and src/mcp_project_orchestrator/cli.py; MCP server exposure is in src/mcp_project_orchestrator/server.py. The runtime is Python, packaged through pyproject.toml, with container support in Containerfile and a Conan recipe in conanfile.py. The advertised executable is mcp-orchestrator.

Core Orchestration Layer

Shared lifecycle, configuration, manager abstractions, logging, and FastMCP integration are concentrated in:

• src/mcp_project_orchestrator/core/base.py

• src/mcp_project_orchestrator/core/config.py

• src/mcp_project_orchestrator/core/managers.py

CLI/server requests should cross this boundary before invoking template, prompt, diagram, AWS, or specialist orchestration features. Repository-level feature selection/scaffolding is driven by config/project_orchestration.json.

Template and Project Generation

The template subsystem discovers, validates, renders, and applies project/component definitions:

• src/mcp_project_orchestrator/templates/manager.py

• src/mcp_project_orchestrator/templates/renderer.py

• src/mcp_project_orchestrator/templates/project.py

Templates are JSON assets, including design-pattern component templates under src/mcp_project_orchestrator/templates/component/ and OpenSSL-consumer scaffolding under templates/openssl-consumer/. This is a filesystem-driven generation boundary: inputs are template identifiers plus variables; outputs are generated project files.

Prompt and Resource Catalog

Prompt content is versioned as package data and loaded/rendered through a separate management API:

• src/mcp_project_orchestrator/prompt_manager/loader.py

• src/mcp_project_orchestrator/prompt_manager/manager.py

• src/mcp_project_orchestrator/prompts/index.json

The categorized JSON prompt corpus under src/mcp_project_orchestrator/prompts/ is a primary data asset rather than executable logic. Resources are similarly indexed under src/mcp_project_orchestrator/resources/index.json.

Diagram Pipeline

Mermaid support is a distinct transformation pipeline:

• src/mcp_project_orchestrator/mermaid/generator.py

• src/mcp_project_orchestrator/mermaid/mermaid_orchestrator.py

• src/mcp_project_orchestrator/mermaid/renderer.py

Callers provide graph/diagram intent; the generator produces Mermaid text, orchestration selects templates/options, and the renderer emits artifacts such as SVG/PNG. Diagram templates are stored alongside the code in src/mcp_project_orchestrator/mermaid/templates/.

External Integrations and Specialized Flows

AWS MCP functionality is isolated in src/mcp_project_orchestrator/aws_mcp.py, targeting AWS services named in the README: S3, EC2, Lambda, CloudFormation, and IAM. OpenSSL/FIPS and Cursor deployment flows are exposed through:

• src/mcp_project_orchestrator/commands/openssl_cli.py

• src/mcp_project_orchestrator/openssl_tools_orchestration.py

• src/mcp_project_orchestrator/cursor_deployer.py

Additional operational subprojects are separate deployables, notably the containerized Printcast MCP agent (printcast-agent/src/mcp_server/main.py) and AWS SIP/Asterisk infrastructure (aws-sip-trunk/terraform/main.tf); they should not be treated as dependencies of the core package without explicit integration wiring.

Automation and Repository Boundary

GitHub Actions provide CI/CD, deployment, release, ecosystem monitoring, and fan-out orchestration under .github/workflows/. The repository includes many duplicated snapshots and generated/content-heavy directories; new core changes should target src/mcp_project_orchestrator/, root packaging metadata, and root tests unless the task explicitly concerns restructured/ or the nested copy.