Orchestrator MCP Server

This project implements an AI-based workflow orchestration MCP server, achieving intelligent decision-making and dynamic adjustment through large language models (LLMs), supporting complex task decomposition, state persistence, and workflow recovery.

Developer tools Artificial intelligence chatbots #AI Workflow #Dynamic Orchestration #State Management #MCP Service .Python

rating : 2 points

downloads : 7

update time : 2025-04-28

What is the Workflow Orchestrator?

The Workflow Orchestrator is a smart server that helps automate and manage complex tasks by breaking them down into smaller steps. It uses AI to decide the best sequence of actions based on your needs and can adapt to changes or unexpected outcomes automatically.

How does it work?

You define workflows in simple Markdown files, then the orchestrator uses AI to guide the execution. It remembers where you are in each workflow and can pick up where you left off if interrupted.

When should I use it?

Ideal for: automating repetitive multi-step processes, handling tasks with unpredictable outcomes, creating adaptable workflows that may need changes, and managing long-running operations that might get interrupted.

Key Features

AI-Powered DecisionsThe system intelligently determines next steps based on workflow definitions and real-time outcomes, making your processes more flexible.

Simple Markdown DefinitionsCreate and modify workflows using easy-to-read Markdown files instead of complex programming.

State PreservationAutomatically saves progress in a database so workflows can be paused and resumed later.

Smart Error RecoveryThe AI helps reconcile inconsistencies when resuming interrupted workflows.

Benefits and Limitations

Benefits

Handles complex, non-linear processes that traditional automation tools struggle with

Workflows are human-readable and editable without coding knowledge

Automatically adapts to unexpected situations or outcomes

Maintains workflow state even if interrupted

Limitations

Requires access to an AI service (like Gemini) for full functionality

Complex workflows may require careful step definition

Initial setup of workflow definitions has a learning curve

Getting Started

Install and Configure

Set up the server by configuring environment variables including your AI service credentials and file paths.

Define Your Workflow

Create Markdown files in the workflows directory to define your process steps and AI guidance.

Start the Server

Launch the orchestrator service to make it available for workflow execution.

Interact via MCP

Use MCP commands to start, monitor, and advance workflows through the API.

Example Scenarios

Code Review AutomationAutomatically analyze GitLab issues, suggest improvements, and generate refactoring recommendations.

Documentation CheckVerify README files are up-to-date with current project status.

Code RefactoringGuide through systematic refactoring with test coverage.

Frequently Asked Questions

Do I need programming skills to use this?

How does the AI help with workflows?

Can I edit a workflow while it's running?

What happens if my workflow gets interrupted?

Additional Resources

Workflow Definition Guide

Detailed instructions for creating workflow Markdown files

API Reference

Complete technical specifications for MCP tools

Sample Workflows

Collection of pre-built workflow templates

🚀 Workflow Orchestrator MCP Server

The Workflow Orchestrator MCP Server implements a system for managing and executing complex workflows, leveraging AI-driven decision-making capabilities. It automatically coordinates and supervises distributed tasks and services by defining clear steps, conditions, and goals.

📜 Background

As workflows in modern applications become increasingly complex, manual management of these processes is both time-consuming and error-prone. This project aims to provide an intelligent solution that uses advanced AI technology to optimize workflow management, improve efficiency, and reduce the risk of human error.

📐 Architecture Overview

The system architecture mainly consists of the following core components:

MCP Server: Responsible for receiving and processing requests from external systems or users, and coordinating the execution of each step.
Workflow Definitions: A series of workflow templates are defined in YAML format. Each template details the dependencies between tasks, conditional judgments, and goal settings.
AI-driven Engine: Based on the Gemini model, it provides intelligent decision support and can generate optimal execution strategies according to the current state and preset rules.

💻 Workflow Example

Here is a typical Web application deployment workflow:

Environment Preparation
Code Distribution
Dependency Installation
Database Migration
Application Startup
Health Check

🧩 Components

MCP Server Functions

Receive and parse workflow requests.
Coordinate the execution order of various tasks.
Handle conditional judgments and branching logic.
Summarize and feedback execution results.
Implement exception handling and recovery mechanisms.

Workflow Definition Format

It uses the YAML format and includes the following key fields:

workflow_id: Unique identifier.
steps: List of task steps.
conditions: Conditional judgment rules.
goals: Goal configuration.
dependencies: Dependency relationships.

AI-driven Engine Functions

Provide intelligent decision support.
Automatically generate optimization strategies.
Implement dynamic priority adjustment.
Handle complex logical reasoning.

⚙️ Configuration

Configuration is done through environment variables. The specific parameters are as follows:

Property	Required	Default Value	Details
`WORKFLOW_DEFINITIONS_DIR`	Yes	`./workflows`	Directory for workflow definitions
`WORKFLOW_DB_PATH`	Yes	`./data/workflows.sqlite`	Path to the database file
`GEMINI_MODEL_NAME`	No	-	Name of the Gemini model to use
`USE_STUB_AI_CLIENT`	No	`false`	Whether to use the stub client for testing
`LOG_LEVEL`	No	`info`	Log level
`AI_SERVICE_ENDPOINT`	No	-	Endpoint address of the LLM service
`AI_SERVICE_API_KEY`	No	-	API authentication key
`MAX_PARALLEL_TASKS`	No	10	Maximum number of parallel tasks

🚀 Quick Start / Running the Server

Install Dependencies

uv sync

Run the Server

uv run python -m orchestrator.server

Example Workflow Definition

workflow_id: deploy_web_app
steps:
  - id: prepare_env
    type: execute_command
    command: "source setup.sh"
  - id: distribute_code
    type: git_checkout
    branch: main
dependencies:
  - step_id: prepare_env
    must_succeed_before: true

🚧 Development Status

The project is currently in the alpha version. The main functions have been initially implemented. Future work will focus on improving the system's stability and scalability.

🧪 Testing Strategy

A layered testing strategy is adopted:

Unit Testing: Verify the independent functions of each component.
Integration Testing: Ensure that all components work together correctly.
Performance Testing: Evaluate the system's performance under high load.
Security Testing: Detect potential security vulnerabilities.
User Acceptance Testing (UAT): Collect user feedback for optimization.

📝 Workflow Instance

Here is a typical workflow execution log:

INFO: Starting execution of workflow deploy_web_app
INFO: Step prepare_env executed successfully
INFO: Step distribute_code is in progress...
INFO: Step distribute_code completed
INFO: The target state has been reached, and the workflow is completed