MCP Project Orchestrator
by sparesparrow
# 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:
```bash
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:
```bash
python3 -m venv venv
```
2. Activate the virtual environment:
```bash
source ./venv/bin/activate
```
3. Upgrade pip (optional but recommended):
```bash
pip install --upgrade pip
```
4. Install the package in editable mode:
```bash
pip install -e . --break-system-packages
```
## Running Tests
Run tests using pytest (clear cache to avoid stale data):
```bash
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
```bash
docker build -t mcp-project-orchestrator:latest -f Containerfile .
```
#### Using Podman
```bash
podman build -t mcp-project-orchestrator:latest -f Containerfile .
```
### Run the Container
#### Using Docker
```bash
docker run -d --rm -p 8080:8080 --name mcp-server mcp-project-orchestrator:latest
```
#### Using Podman
```bash
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)
```bash
# 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
```bash
# 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:
```bash
npm install -g @modelcontextprotocol/inspector
```
2. Start your MCP server (if not already running):
```bash
# 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:
```bash
npx @modelcontextprotocol/inspector http://localhost:8080
```
4. Validate your server:
```bash
npx @modelcontextprotocol/inspector http://localhost:8080 --validate
```
5. Interactive mode for testing tools:
```bash
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](https://modelcontextprotocol.io/docs/tools/inspector).
### Interactive Testing with MCP Inspector
The interactive mode of MCP Inspector is particularly useful for manual testing:
```bash
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:
```bash
# 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:
```bash
# 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:
```bash
# 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:
```bash
# 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:
```bash
# 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:
```bash
# 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:
```bash
# 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:
```bash
python3 scripts/setup_claude_desktop.py --help
```
#### Option 2: Manual Configuration
1. Install [Claude Desktop](https://claude.ai/download) 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:
```bash
# Install the package
pip install -e /path/to/mcp-project-orchestrator
```
Then add this to your `claude_desktop_config.json`:
```json
{
"mcpServers": {
"project-orchestrator": {
"command": "python",
"args": [
"-m",
"mcp_project_orchestrator.fastmcp"
],
"env": {
"PYTHONPATH": "/path/to/mcp-project-orchestrator"
}
}
}
}
```
#### Option 2: Using Docker
```json
{
"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:
```json
{
"mcpServers": {
"project-orchestrator": {
"command": "docker",
"args": [
"run",
"--rm",
"-p",
"8080:8080",
"ghcr.io/YOUR_USERNAME/mcp-project-orchestrator:latest"
]
}
}
}
```
#### Option 3: Using Podman
```json
{
"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](https://modelcontextprotocol.io).