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:

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):

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

Using Podman

Run the Container

Using Docker

Using Podman

Testing with Containers

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

Podman (Recommended)

Docker

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:

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:

MCP Server Validation Commands

You can run various validation checks on your MCP server:

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

Convenience Testing Script

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

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:

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:

Using the Python Script Directly

If you prefer to use the Python script directly:

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

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:

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:

Then add this to your claude_desktop_config.json:

Option 2: Using Docker

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

Option 3: Using Podman

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.