mcp-project-orchestrator

Overview

The mcp-project-orchestrator is an MCP server designed to assist with the orchestration of new software projects by applying standardized templates and best practices in design patterns and software architecture.

This server extracts key information from user input, selects an appropriate project template from a standardized catalogue (with consistent structure for both project and component templates), and generates comprehensive documentation that includes:

• Software Architecture
• Components and Modules
• File Structures and Directory Trees
• Implementation Strategies
• Visual diagrams using the Mermaid tool

Key Features

• Standardized Templates: All project and component templates follow a consistent structure with standardized keys (e.g., 'name', 'type', 'mermaid', 'directory_structure').
• Redundancy Elimination: Redundant or overlapping templates have been consolidated or removed to keep the catalogue clean and configurable.
• Dynamic Configuration: The server loads its configuration from project_orchestration.json, which contains MCP-specific settings such as communication protocols and compliance standards.
• Documentation Generation: Automatically generated comprehensive README files and Mermaid diagrams help visualize the project architecture and implementation strategy.

How It Works

1. Information Extraction: The server analyzes the user's project idea to extract design patterns and architecture concepts.
2. Template Selection: Based on the analysis, an appropriate project template is selected from a standardized catalogue (e.g., Microservices Architecture, Event-Driven, Repository Pattern, etc.).
3. Project Setup: The server creates the project directory structure and placeholder files based on the chosen template. It populates component files (interfaces, implementations, tests, etc.) with TODO comments, ensuring consistent naming and file organization.
4. Documentation and Visualization: The server generates a comprehensive README with details about the software architecture, components, process flows, file structures, and implementation strategy, including visual diagrams generated by the Mermaid tool.

Configuration

The server loads its configuration from project_orchestration.json, which contains settings such as:

• Communication Protocol: JSON-RPC
• MCP Compliance: true
• Steps for orchestration and orchestration guidelines

This configuration is attached to the FastMCP instance as mcp.config.

Usage

To run the MCP server, execute:

python project_orchestration.py

Ensure that the required JSON template files (e.g., project_templates.json, component_templates.json, and project_orchestration.json) are present in the workspace.

Extending the Server

Developers can extend or modify the orchestration process by:

• Updating the standardized templates (both project and component templates) to change the structure or add new keys as needed.
• Modifying project_orchestration.json to update configuration details and orchestration steps.
• Customizing the MCP orchestration logic in project_orchestration.py to refine project and documentation generation.

License

This project is licensed under the MIT License.

Virtual Environment Setup

To set up the project locally using a virtual environment:

1. Create a virtual environment:

   python3 -m venv venv

2. Activate the virtual environment:

   source ./venv/bin/activate

3. Upgrade pip (optional but recommended):

   pip install --upgrade pip

4. Install the package in editable mode:

   pip install -e . --break-system-packages

Running Tests

Run tests using pytest (clear cache to avoid stale data):

python -m pytest --cache-clear

Containerized Deployment

A Containerfile is provided for containerizing the application using either Docker or Podman.

Build the Container Image

Choose your preferred container engine:

Using Docker

docker build -t mcp-project-orchestrator:latest -f Containerfile .

Using Podman

podman build -t mcp-project-orchestrator:latest -f Containerfile .

Run the Container

Using Docker

docker run -d --rm -p 8080:8080 --name mcp-server mcp-project-orchestrator:latest

Using Podman

podman run -d --rm -p 8080:8080 localhost/mcp-project-orchestrator:latest

Testing with Containers

If you're encountering "module not found" errors with containers, use this approach that mounts the project directory:

Podman (Recommended)

# Build the container
podman build -t mcp-project-orchestrator:latest -f Containerfile .

# Run with project directory mounted and explicit entrypoint
podman run --rm -p 8080:8080 \
  -v "$(pwd):/app:Z" \
  --workdir /app \
  --entrypoint python \
  localhost/mcp-project-orchestrator:latest \
  -m mcp_project_orchestrator.fastmcp

Docker

# Build the container
docker build -t mcp-project-orchestrator:latest -f Containerfile .

# Run with project directory mounted and explicit entrypoint
docker run --rm -p 8080:8080 \
  -v "$(pwd):/app" \
  --workdir /app \
  --entrypoint python \
  mcp-project-orchestrator:latest \
  -m mcp_project_orchestrator.fastmcp

Note: Docker doesn't use the 'localhost/' prefix that Podman uses. Make sure to use the correct image name for your container engine.

GitHub Actions Workflow for CI/CD

A comprehensive GitHub Actions workflow is set up in the .github/workflows/ci-cd.yml file to automate:

• Code linting and type checking
• Running tests with coverage reporting
• Building and testing container images
• Testing with MCP Inspector
• Publishing to GitHub Container Registry
• Deployment to production (on manual trigger)

Key features of the CI/CD pipeline:

• Validates MCP server functionality with multiple inspector tests
• Tests with both Docker and Podman (disabled by default)
• Includes a dedicated manual validation step

For further details, refer to the workflow file.

MCP Integration

This server follows the Model Context Protocol (MCP) standards:

Resources Exposed

• Project templates catalog
• Component templates catalog
• Generated project structures

Tools Provided

• create_project: Create a new project based on description and design patterns
• list_templates: List available project templates
• generate_documentation: Generate documentation for existing code

MCP Protocol Compliance

• Implements the MCP server specification version 0.9
• Uses the FastMCP server for communication
• Provides proper error handling and logging

Testing with MCP Inspector

The MCP Inspector is a powerful tool for testing and validating MCP servers. Follow these steps to test your server:

1. Install the MCP Inspector:

   npm install -g @modelcontextprotocol/inspector

2. Start your MCP server (if not already running):

   # Using the container
   docker run -d -p 8080:8080 mcp-project-orchestrator
   
   # Or directly with Python
   python -m mcp_project_orchestrator.fastmcp

3. Run the MCP Inspector against your server:

   npx @modelcontextprotocol/inspector http://localhost:8080

4. Validate your server:

   npx @modelcontextprotocol/inspector http://localhost:8080 --validate

5. Interactive mode for testing tools:

   npx @modelcontextprotocol/inspector http://localhost:8080 --interactive

The inspector will:

• Verify your server complies with the MCP protocol
• List the resources and tools your server exposes
• Allow you to interactively call tools and test functionality
• Provide detailed error information if issues are found

For more information on MCP Inspector, visit MCP Inspector Documentation.

Interactive Testing with MCP Inspector

The interactive mode of MCP Inspector is particularly useful for manual testing:

npx @modelcontextprotocol/inspector http://localhost:8080 --interactive

In interactive mode, you can:

1. View all available tools and resources
2. Execute tools with custom parameters
3. View detailed server responses
4. Test edge cases and error handling

Common MCP Inspector commands:

# List all resources
resources

# List all tools
tools

# Execute a tool
call <tool_name> --param1 value1 --param2 value2

# View detailed resources 
resource <resource_name>

# Exit the inspector
exit

MCP Server Validation Commands

You can run various validation checks on your MCP server:

# Basic connectivity test
npx @modelcontextprotocol/inspector http://localhost:8080

# Full validation test
npx @modelcontextprotocol/inspector http://localhost:8080 --validate

# Verbose output for debugging
npx @modelcontextprotocol/inspector http://localhost:8080 --verbose

For CI/CD environments, you can run non-interactive validation:

# Exit with non-zero code if validation fails
npx @modelcontextprotocol/inspector http://localhost:8080 --validate --strict

Convenience Testing Script

A convenience script is provided to run all the key MCP test commands in sequence:

# Give execute permission to the script
chmod +x scripts/mcp_test.sh

# Run with Docker (default)
./scripts/mcp_test.sh 

# Or run with Podman
./scripts/mcp_test.sh podman

The script:

1. Builds the container image
2. Runs the container
3. Installs MCP Inspector if needed
4. Runs basic connectivity test
5. Runs validation test
6. Cleans up containers

Claude Desktop Integration

To add this MCP server to Claude Desktop, you have two options:

Option 1: Using the Setup Script (Recommended)

We provide a convenient setup script that automatically configures Claude Desktop for you:

For Container Integration Issues

If you're experiencing "module not found" errors, use these specialized scripts for container-based integration with volume mounting:

# For Podman (recommended)
chmod +x scripts/setup_podman_config.sh
./scripts/setup_podman_config.sh

# For Docker
chmod +x scripts/setup_docker_config.sh
./scripts/setup_docker_config.sh

These scripts:

1. Mount your project directory into the container
2. Use the container's Python interpreter to run the module
3. Override the entrypoint to ensure the module is found

Using the Shell Script (Easiest)

A shell script wrapper is provided that automatically finds a suitable Python interpreter and handles environment issues:

# Make the script executable
chmod +x scripts/setup_claude.sh

# For Python-based integration (default)
./scripts/setup_claude.sh

# For Docker-based integration
./scripts/setup_claude.sh --method docker

# For Podman-based integration
./scripts/setup_claude.sh --method podman

Using the Python Script Directly

If you prefer to use the Python script directly:

# Make the script executable
chmod +x scripts/setup_claude_desktop.py

# For Python-based integration (default)
./scripts/setup_claude_desktop.py

# For Docker-based integration
./scripts/setup_claude_desktop.py --method docker

# For Podman-based integration
./scripts/setup_claude_desktop.py --method podman

If you encounter Python environment errors when running the Python script directly, try using a specific Python interpreter:

# Using Python 3 explicitly
python3 scripts/setup_claude_desktop.py

# Using a virtual environment's Python
venv/bin/python scripts/setup_claude_desktop.py

# Specifying a custom project path
python3 scripts/setup_claude_desktop.py --project-path /absolute/path/to/mcp-project-orchestrator

The script will:

1. Detect your OS and locate the Claude Desktop config file
2. Check if the necessary tools are installed
3. Generate the appropriate configuration
4. Save it to the correct location

Run with --help to see all available options:

python3 scripts/setup_claude_desktop.py --help

Option 2: Manual Configuration

1. Install Claude Desktop if you haven't already
2. Open Claude Desktop and go to Settings > Developer > Edit Config
3. Add the configuration that matches your setup:

Option 1: Using the installed package (recommended)

First, make sure the package is installed globally or in a virtual environment that Claude Desktop can access:

# Install the package 
pip install -e /path/to/mcp-project-orchestrator

Then add this to your claude_desktop_config.json:

{
  "mcpServers": {
    "project-orchestrator": {
      "command": "python",
      "args": [
        "-m",
        "mcp_project_orchestrator.fastmcp"
      ],
      "env": {
        "PYTHONPATH": "/path/to/mcp-project-orchestrator"
      }
    }
  }
}

Option 2: Using Docker

{
  "mcpServers": {
    "project-orchestrator": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-p",
        "8080:8080",
        "mcp-project-orchestrator:latest"
      ]
    }
  }
}

If you've published the image to GitHub Container Registry:

{
  "mcpServers": {
    "project-orchestrator": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-p",
        "8080:8080",
        "ghcr.io/YOUR_USERNAME/mcp-project-orchestrator:latest"
      ]
    }
  }
}

Option 3: Using Podman

{
  "mcpServers": {
    "project-orchestrator": {
      "command": "podman",
      "args": [
        "run",
        "--rm",
        "-p",
        "8080:8080",
        "localhost/mcp-project-orchestrator:latest"
      ]
    }
  }
}

4. Restart Claude Desktop to access the Project Orchestrator tools in the tools menu (hammer icon).

Troubleshooting Claude Desktop Integration

If you encounter errors with the MCP server in Claude Desktop:

1. Check the logs at:

   • MacOS: ~/Library/Logs/Claude/mcp-server-project-orchestrator.log
   • Windows: %APPDATA%\Claude\logs\mcp-server-project-orchestrator.log

2. Common issues and solutions:

   • Module not found errors: Make sure your Python path includes the package or use the containerized version with the specialized scripts provided
   • Port conflicts: Change the port number if 8080 is already in use
   • Permission issues: Run Claude Desktop with appropriate permissions to execute commands
   • Container issues: Ensure the container image is built correctly and accessible to Claude Desktop

For more information on MCP, visit modelcontextprotocol.io.