Apppublic

MCP-1st-Birthday/conductor-mcp

sourceHugging Facemitupdated 10mo agoView on Hugging Face

0likes

App README

🏆 MCP Hackathon Submission

🎬 Demo Video

![Watch the Demo](https://youtu.be/nP4xgbKMX8Q)

[▶️ Watch Full Demo on YouTube](https://youtu.be/nP4xgbKMX8Q)

📱 Social Media

LinkedIn Post: View on LinkedIn

📖 Project Description

This project is a prototype for a National AI Operating System designed to manage complex, country-level operations by treating AI Agents as a hierarchical workforce. It combines the reliability of Orkes Conductor with the flexibility of Generative AI using the Model Context Protocol (MCP).

Why This Matters

—Nation-Scale Orchestration: Manages AI agents like a government workforce - from strategic planning at the executive level down to specialized task execution
—Enterprise-Grade Reliability: Leverages Orkes Conductor's proven orchestration capabilities for mission-critical operations
—Dynamic Intelligence: Meta-Agent system that understands natural language and automatically plans complex multi-agent workflows
—Security-First Design: OAuth 2.1 + PKCE authentication with human-in-the-loop controls for sensitive operations

Conductor MCP Supervisor: Hierarchical Multi-Agent Ecosystem

This project showcases a hierarchical orchestrator ecosystem with specialized AI managers built on Model Context Protocol (MCP) for Orkes Conductor. Each orchestrator has unique personality via system prompts and specialized algorithms via class inheritance, enabling true organizational AI hierarchy.

🏗️ Hierarchical Orchestrator Architecture

mermaid

graph TD
    CEO[CEO Orchestrator<br/>Port: 7860<br/>Strategic Oversight]
    CTO[CTO Orchestrator<br/>Port: 7870<br/>Technical Architecture]
    COO[COO Orchestrator<br/>Port: 7900<br/>Operations Excellence]
    WeatherMgr[Weather Manager<br/>Port: 7890<br/>Weather Domain Expertise]
    
    CEO --> CTO
    CEO --> COO
    CTO --> WeatherMgr
    
    FinancialAgent[FinancialAgent<br/>Port: 8001]
    ConductorAgent[ConductorAgent<br/>Port: 8002]
    WeatherAgent[WeatherAgent<br/>Port: 8004]
    
    CTO --> FinancialAgent
    CTO --> ConductorAgent
    WeatherMgr --> WeatherAgent
    
    classDef orchestrator fill:#e1f5fe,stroke:#01579b,stroke-width:3px
    classDef worker fill:#f3e5f5,stroke:#4a148c,stroke-width:2px
    
    class CEO,CTO,COO,WeatherMgr orchestrator
    class FinancialAgent,ConductorAgent,WeatherAgent worker

🌟 Specialized Orchestrator Features

—Personality via System Prompts: Each orchestrator has role-specific prompts loaded from files
—Custom Algorithms: Specialized subclasses override core methods for domain expertise
—Dynamic Class Loading: Runtime instantiation based on configuration
—Hierarchical Communication: Parent-child orchestrator relationships
—Role-Based Decision Making: Each level has unique approval workflows

🚀 Key Features

—✅ Dynamic Agent Registration - Agents can register/unregister at runtime
—✅ Meta-Agent Intelligence - Natural language task planning and execution
—✅ Hierarchical Orchestrators - Specialized AI managers with unique personalities
—✅ System Prompt Specialization - Role-based behavior via environment prompts
—✅ Custom Algorithm Classes - Domain-specific orchestrator implementations
—✅ Ecosystem Launcher - Automated hierarchy deployment
—✅ Multi-Agent Coordination via Supervisor Pattern
—✅ Conductor Workflow Integration as MCP tools
—✅ OAuth 2.1 + PKCE enhanced security
—✅ Auto-Discovery - Tools from all registered agents automatically available
—✅ Human-in-the-Loop elicitation for sensitive operations

🏗️ Architecture: Dynamic Agent Ecosystem with Meta-Agent

mermaid

graph TB
    Supervisor[MCP Supervisor<br/>Port 7860<br/>Agent Registry & Meta-Agent]
    
    FinancialAgent[FinancialAgent<br/>Port 8001<br/>Stock Price & Sentiment Tools]
    ConductorAgent[ConductorAgent<br/>Port 8002<br/>Workflow Tools]
    WeatherAgent[WeatherAgent<br/>Port 8004<br/>Weather Tools]
    CustomAgent[CustomAgent<br/>Port 8005<br/>Your Tools]
    
    ExternalClient[External MCP Client]
    ThirdParty[Third-Party Agent]
    UserPrompt[Natural Language<br/>"Get AAPL price and sentiment"]
    
    Supervisor --> FinancialAgent
    Supervisor --> ConductorAgent
    Supervisor --> WeatherAgent
    Supervisor --> CustomAgent
    
    ExternalClient --> Supervisor
    UserPrompt -->|Meta-Agent| Supervisor
    Supervisor -->|AI Planning| Supervisor
    
    ThirdParty -.->|Auto-Register| Supervisor
    
    classDef supervisor fill:#e1f5fe,stroke:#01579b,stroke-width:3px
    classDef agent fill:#f3e5f5,stroke:#4a148c
    classDef external fill:#fff3e0,stroke:#e65100
    classDef ai fill:#e8f5e8,stroke:#2e7d32
    
    class Supervisor supervisor
    class FinancialAgent,ConductorAgent,WeatherAgent,CustomAgent agent
    class ExternalClient,ThirdParty external
    class UserPrompt ai

🚀 Quick Start

Complete Hierarchical Ecosystem (Recommended)

bash

# Launch the entire hierarchical orchestrator ecosystem
python launch_ecosystem.py

# Or with specific configuration
python launch_ecosystem.py --config company_structure.example.json

# Dry run to see what would be launched
python launch_ecosystem.py --dry-run

Individual Agent Development & Testing

For development, testing, or understanding individual agent operations:

bash

# Individual agent launchers (examples for development)
python _examples/individual_launchers/run_agents.py start FinancialAgent
python _examples/individual_launchers/weather_agent_launcher.py

# See _examples/individual_launchers/README.md for detailed usage

Creating Custom Agents

For detailed guide on building third-party agents:

👉 [Read the Agent Developer Guide](AGENT_DEVELOPER_GUIDE.md) - Complete tutorial with examples

Deployment Options

For production deployment strategies:

👉 [See DEPLOYMENT.md](DEPLOYMENT.md) - Docker, Kubernetes, and cloud deployment 👉 [Security Compliance](SECURITY_COMPLIANCE_VALIDATION.md) - OAuth 2.1 + PKCE, audit features

Implementation Details

For technical architecture and design decisions:

👉 [Implementation Summary](IMPLEMENTATION_SUMMARY.md) - System design, patterns, trade-offs 👉 [Agent Developer Guide](AGENT_DEVELOPER_GUIDE.md) - Creating custom worker agents

🔧 Agent Registration Endpoints

Register an Agent

bash

curl -X POST http://localhost:7860/registry/register \
  -H "Content-Type: application/json" \
  -d '{
    "agent_name": "MyCustomAgent",
    "agent_address": "http://localhost:8005",
    "tools": [
      {
        "name": "my_tool",
        "description": "My custom tool",
        "inputSchema": {
          "type": "object",
          "properties": {"input": {"type": "string"}}
        }
      }
    ],
    "description": "My custom third-party agent",
    "version": "1.0.0"
  }'

Unregister an Agent

bash

curl -X POST http://localhost:7860/registry/unregister \
  -H "Content-Type: application/json" \
  -d '{"agent_name": "MyCustomAgent"}'

🧪 API Testing

Discover All Available Tools

bash

curl http://localhost:7860/mcp/tools/list

Call a Weather Tool (delegated to WeatherAgent)

bash

curl -X POST http://localhost:7860/mcp/tools/call \
  -H "Content-Type: application/json" \
  -d '{
    "name": "get_weather",
    "arguments": {"location": "New York", "units": "celsius"}
  }'

Call a Stock Price Tool (delegated to FinancialAgent)

bash

curl -X POST http://localhost:7860/mcp/tools/call \
  -H "Content-Type: application/json" \
  -d '{
    "name": "get_stock_price",
    "arguments": {"symbol": "AAPL"}
  }'

Meta-Agent: Natural Language Task Execution

bash

curl -X POST http://localhost:7860/mcp/execute_task \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Berapa harga saham Apple dan bagaimana sentimen pasar saat ini?"
  }'

Check Agent Status

bash

curl http://localhost:7860/health/agents

🛠️ Creating Specialized Orchestrators

1. Create Custom Orchestrator Class

python

# conductor_mcp_server/orchestrators/my_orchestrator.py
from conductor_mcp_server.orchestrators import MCPHandler, ExecutionPlan

class MyOrchestrator(MCPHandler):
    def __init__(self, conductor_client, settings):
        super().__init__(conductor_client, settings)
        logger.info("MyOrchestrator initialized - Custom logic enabled")
    
    async def _execute_plan(self, plan: ExecutionPlan, user):
        """Override plan execution with custom logic"""
        logger.info("MyOrchestrator - Executing plan with custom oversight")
        
        # Add custom validation or approval step
        custom_step = ExecutionStep(
            tool_name="custom_validation",
            arguments={"validation_type": "my_domain"},
            step_id="my_custom_step"
        )
        
        plan.steps.insert(0, custom_step)
        
        # Execute using parent method
        results = await super()._execute_plan(plan, user)
        
        # Add custom assessment
        results.append({
            "step_id": "my_custom_assessment",
            "tool_name": "custom_oversight",
            "result": {"custom_status": "validated"},
            "step_number": len(plan.steps) + 1
        })
        
        return results

2. Create System Prompt File

bash

# prompts/my_role_prompt.txt
You are a specialized manager with expertise in:
- Custom domain knowledge
- Specific decision-making patterns
- Unique approval workflows
- Domain-specific compliance requirements

Your responsibilities include:
1. Domain-specific oversight
2. Specialized risk assessment
3. Custom approval processes
4. Expert-level decision making

When handling tasks:
- Apply domain-specific expertise
- Follow specialized protocols
- Consider unique risk factors
- Follow custom approval workflows

3. Configure in company_structure.json

json

{
  "name": "My Special Manager",
  "type": "orchestrator",
  "port": 8000,
  "description": "My specialized domain manager",
  "system_prompt_file": "prompts/my_role_prompt.txt",
  "orchestrator_class": "conductor_mcp_server.orchestrators.MyOrchestrator",
  "subordinates": [...]
}

4. Launch with Ecosystem

bash

# Use the ecosystem launcher
python launch_ecosystem.py --config company_structure.json

🛠️ Creating Custom Agents

1. Use the Template

python

from conductor_mcp_server.agents.base import AbstractWorkerAgent, WorkerAgentConfig

class MyCustomAgent(AbstractWorkerAgent):
    def __init__(self, settings):
        config = WorkerAgentConfig(
            agent_name="MyCustomAgent",
            port=8005,
            host="0.0.0.0",
            description="My custom third-party agent",
            version="1.0.0"
        )
        super().__init__(config, settings)
    
    async def initialize(self):
        self._register_my_tools()
    
    def _register_my_tools(self):
        self.register_tool(
            name="my_tool",
            description="My custom tool description",
            input_schema={...},
            implementation=self._my_tool_implementation
        )

2. Add Auto-Registration

python

async def register_agent_with_supervisor(agent_name, agent_url, tools, supervisor_url):
    # Auto-register with supervisor
    registration_payload = {...}
    # ... registration logic

3. Run Your Agent

bash

python my_custom_agent.py

📊 Available Agents & Tools

Default Agents (via run_agents.py)

—FinancialAgent (Port 8001): get_stock_price, get_multiple_prices
—ConductorAgent (Port 8002): start_workflow, get_workflow_status

Third-Party Examples

—WeatherAgent (Port 8004): get_weather, get_forecast

Dynamic Discovery

—All tools from registered agents automatically available via /mcp/tools/list
—Tool calls automatically routed to correct agent
—Real-time agent health monitoring

🔐 Security Features

OAuth 2.1 + PKCE

—Enhanced security with PKCE (Proof Key for Code Exchange)
—PAR (Pushed Authorization Requests) protection
—Dynamic client registration
—Token rotation and refresh

Resource Security

—File System: file:// URIs with path validation
—Database: db:// URIs with operation control
—Agent Context: agent:// URIs for inter-agent sharing

Human-in-the-Loop

—Sensitive operation detection
—Workflow pausing for confirmation
—Elicitation prompts for risky operations

📊 Monitoring

—Supervisor Health: /health - System status
—Agent Status: /health/agents - All registered agents
—Tool Discovery: /mcp/tools/list - Available tools from all agents
—Metrics: /metrics - Prometheus format metrics
—OpenTelemetry: Distributed tracing enabled
—Structured Logging: JSON format with correlation IDs

🎯 Use Cases

1. Dynamic Agent Ecosystem

FinancialAgent + WeatherAgent + CustomAgent
    ↓
Automatic Tool Discovery & Routing
    ↓
Unified MCP Interface

2. Third-Party Integration

External Service → Custom Agent → Supervisor
    ↓
Tools Available to All Clients

3. Plugin Architecture

New Requirement → New Agent → Auto-Register → Available Immediately

🛠️ Technical Stack

—FastAPI: High-performance async web framework
—MCP Protocol: Model Context Protocol for agent communication
—Orkes Conductor: Workflow orchestration engine
—OAuth 2.1 + PKCE: Enhanced security standards
—OpenTelemetry: Distributed tracing and monitoring
—AsyncIO: High-performance concurrent programming
—Pydantic: Data validation and serialization

📖 API Documentation

—Swagger UI: /docs - Interactive API testing
—Agent Registry: /registry/* - Dynamic agent management
—MCP Endpoints: /mcp/* - Standard MCP protocol endpoints
—Health Checks: /health/* - System monitoring
—MCP Spec: Model Context Protocol

🚀 Deployment

The ecosystem is designed for easy deployment:

1.Supervisor: Single instance handling registration and routing
2.Agents: Can be deployed independently on any infrastructure
3.Auto-Discovery: Agents register automatically, no manual configuration
4.Scalability: Add/remove agents without restarting supervisor

Built for the future of AI agent coordination - truly dynamic and extensible!

🏗️ Architecture

mermaid

graph TB
    Agent1[AI Agent 1<br/>Portfolio Manager]
    Agent2[AI Agent 2<br/>Risk Analysis]
    Agent3[AI Agent 3<br/>Notifications]
    
    Gateway[MCP Gateway<br/>Centralized Auth<br/>Rate Limiting]
    
    Server[FastAPI MCP Server<br/>Conductor Integration]
    Conductor[Orkes Conductor<br/>Workflow Orchestration]
    
    Worker1[Stock Price<br/>Worker]
    Worker2[Risk Analysis<br/>Worker]
    Worker3[Alert<br/>Worker]
    
    Agent1 --> Gateway
    Agent2 --> Gateway  
    Agent3 --> Gateway
    
    Gateway --> Server
    Server --> Conductor
    Conductor --> Worker1
    Conductor --> Worker2
    Conductor --> Worker3
    
    classDef agent fill:#e1f5fe,stroke:#01579b
    classDef server fill:#f3e5f5,stroke:#4a148c
    classDef conductor fill:#e8f5e8,stroke:#1b5e20
    
    class Agent1,Agent2,Agent3 agent
    class Gateway,Server server
    class Conductor,Worker1,Worker2,Worker3 conductor

🔧 Quick Start (Local Development)

bash

# Clone and install
git clone https://huggingface.co/spaces/galuh1300d/conductor-mcp
cd conductor-mcp

# Install dependencies  
pip install -r requirements.txt

# Start the MCP server
uvicorn conductor_mcp_server.main:app --host 0.0.0.0 --port 7860

# Run demo client
python conductor_mcp_server/demo_client.py

🧪 API Testing

Discover Available Tools

bash

curl http://localhost:7860/mcp/tools

Call a Stock Price Tool

bash

curl -X POST http://localhost:7860/mcp/tools/call \
  -H "Content-Type: application/json" \
  -d '{
    "name": "get_stock_price", 
    "arguments": {"symbol": "AAPL"}
  }'

Multi-Agent Workflow Demo

bash

curl http://localhost:7860/demo

🔒 Security Features

OAuth 2.1 + PKCE

—Enhanced security with PKCE (Proof Key for Code Exchange)
—PAR (Pushed Authorization Requests) protection
—Dynamic client registration
—Token rotation and refresh

Resource Security

—File System: file:// URIs with path validation
—Database: db:// URIs with operation control
—Agent Context: agent:// URIs for inter-agent sharing

Human-in-the-Loop

—Sensitive operation detection
—Workflow pausing for confirmation
—Elicitation prompts for risky actions

📊 Monitoring

—Health Endpoint: /health - System status
—Metrics: /metrics - Prometheus format metrics
—OpenTelemetry: Distributed tracing enabled
—Structured Logging: JSON format with correlation IDs

🎯 Hackathon Use Cases

1. Portfolio Management Workflow

Portfolio Agent → Risk Analysis Agent → Notification Agent
     ↓
Conductor Workflow Orchestration
     ↓
Real-time Stock Data + Risk Alerts

2. Multi-Agent Decision Making

Agent A (Research) → Agent B (Analysis) → Agent C (Execution)
     ↓
Consensus Building via MCP Protocol
     ↓
Automated Workflow Execution

3. Human-in-the-Loop Operations

Sensitive Operation Detected → Elicitation Request → Human Approval
     ↓
Workflow Continuation or Cancellation

🛠️ Technical Stack

—FastAPI: High-performance async web framework
—MCP Protocol: Model Context Protocol for agent communication
—Orkes Conductor: Workflow orchestration engine
—OAuth 2.1 + PKCE: Enhanced security standards
—OpenTelemetry: Distributed tracing and monitoring
—Redis: Caching and rate limiting
—Pydantic: Data validation and serialization

📖 Documentation

—API Docs: /docs - Swagger/OpenAPI documentation
—MCP Spec: Model Context Protocol
—Conductor Docs: Orkes Conductor
—Deployment Guide: DEPLOYMENT.md

🤝 Hackathon Focus

This demo showcases real-world AI agent coordination through:

1.Standardized Communication: MCP protocol enables different AI systems to work together
2.Workflow Integration: Conductor orchestrates complex multi-agent workflows
3.Security First: OAuth 2.1 + PKCE for production-ready security
4.Production Ready: Comprehensive monitoring, logging, and error handling
5.Human-in-the-Loop: Critical operations require human approval

Perfect for demonstrating enterprise-grade multi-agent systems!

Built for the hackathon - showcasing the future of AI agent coordination

🏆 MCP Hackathon Submission

🎬 Demo Video

📱 Social Media

📖 Project Description

Why This Matters

Conductor MCP Supervisor: Hierarchical Multi-Agent Ecosystem

🏗️ Hierarchical Orchestrator Architecture

🌟 Specialized Orchestrator Features

🚀 Key Features

🏗️ Architecture: Dynamic Agent Ecosystem with Meta-Agent

🚀 Quick Start

Complete Hierarchical Ecosystem (Recommended)

Individual Agent Development & Testing

Creating Custom Agents

Deployment Options

Implementation Details

🔧 Agent Registration Endpoints

Register an Agent

Unregister an Agent

🧪 API Testing

Discover All Available Tools

Call a Weather Tool (delegated to WeatherAgent)

Call a Stock Price Tool (delegated to FinancialAgent)

Meta-Agent: Natural Language Task Execution

Check Agent Status

🛠️ Creating Specialized Orchestrators

1. Create Custom Orchestrator Class

2. Create System Prompt File

3. Configure in company_structure.json

4. Launch with Ecosystem

🛠️ Creating Custom Agents

1. Use the Template

2. Add Auto-Registration

3. Run Your Agent

📊 Available Agents & Tools

Default Agents (via run_agents.py)

Third-Party Examples

Dynamic Discovery

🔐 Security Features

OAuth 2.1 + PKCE

Resource Security

Human-in-the-Loop

📊 Monitoring

🎯 Use Cases

1. Dynamic Agent Ecosystem

2. Third-Party Integration

3. Plugin Architecture

🛠️ Technical Stack

📖 API Documentation

🚀 Deployment

🏗️ Architecture

🔧 Quick Start (Local Development)

🧪 API Testing

Discover Available Tools

Call a Stock Price Tool

Multi-Agent Workflow Demo

🔒 Security Features

OAuth 2.1 + PKCE

Resource Security

Human-in-the-Loop

📊 Monitoring

🎯 Hackathon Use Cases

1. Portfolio Management Workflow

2. Multi-Agent Decision Making

3. Human-in-the-Loop Operations

🛠️ Technical Stack

📖 Documentation

🤝 Hackathon Focus

Force rebuild Fri Nov 21 14:27:50 WIB 2025