Skip to main content
Glama
peon-orchestrator

peon-orchestrator

by prmgint

Peon AI Orchestrator

MCP server orchestrator for managing AI agents (coder, reviewer, tester) in the Peon AI ecosystem.

Features

  • Agent Management: Dynamic spawning, stopping, and monitoring of agent processes.

  • Asynchronous Task Execution: Assign tasks and receive a task_id immediately. Agents process tasks in parallel.

  • Persistent Task History: Global history of all tasks, statuses, and results, saved to disk and accessible even after agent termination.

  • Shared Atomic Storage: Thread-safe, file-based "pit" (.peon-orchestrator/storage/) for data exchange with safe key encoding (Base64).

  • AI Integration: OpenAI support with configurable iteration limits and timeouts.

  • Conductor-Ready: Detailed task statuses including missing_tools and partial flags for iterative agent coordination.

Related MCP server: any-model-plugin

Installation

It is recommended to use uv for dependency management and execution.

1. Install uv

If uv is not installed yet:

curl -LsSf https://astral.sh/uv/install.sh | sh

2. Install from GitHub

uv pip install git+https://github.com/prmgint/peon-ai-orchestrator.git

3. Local Installation (for development)

uv pip install -e .

Eclipse Configuration (MCP)

  1. Open MCP settings in Eclipse (Peon AI / MCP Settings).

  2. Add a new server:

    • Name: peon-orchestrator

    • Command: uvx

    • Args: peon-orchestrator

  3. Set environment variables: ORCHAI_API_KEY, ORCHAI_MODEL (e.g., gpt-4o).

Usage

The orchestrator provides the following tools via MCP:

Agent Management

  • spawn_agent(role_name, system_prompt, tools?) - Create an agent. Returns agent_id.

  • list_agents() - List agents with busy status and task counts.

  • stop_agent(agent_id) - Stop an agent.

Task Management

  • assign_task(agent_id, task, tools?, max_iterations?) - Assign task asynchronously. Returns task_id.

  • task_status(agent_id, task_id) - Get detailed status (pending, running, done, error, agent_stopped).

  • task_result(agent_id, task_id?) - Get enriched result with output and missing_tools.

  • aggregate_results(tasks) - Collect results for multiple {agent_id, task_id} pairs.

  • cleanup_task_history(older_than_seconds?) - Remove old task metadata.

Storage Operations

  • read_storage(key) - Read value from shared storage.

  • write_storage(key, value) - Write value (atomic). Protected keys are restricted.

  • list_storage() - List all keys.

  • storage_cleanup(pattern?, exclude?) - Remove keys using glob patterns.

Conductor Workflow

  1. Spawn agents with specific roles.

  2. Assign a task to an agent.

  3. Poll task_status until it is done.

  4. Analyze missing_tools in the result.

  5. Iterate by spawning new agents or reassigning with more tools if needed.

  6. Aggregate sub-task results into a final synthesis.

License

MIT License.

Available Tools

14 tools
agent_statusC

Get the status of an agent

Inputs: agent_id (required).

aggregate_resultsC

Aggregate results for multiple tasks including missing_tools, status and output.

Inputs: tasks (required).

assign_taskA

Assign a task to an agent asynchronously. Returns task_id immediately. Use task_status and task_result to track progress.

Inputs: task (required), agent_id (required), tools, max_iterations.

broadcastA

Send a message to all running agents in parallel. Returns list of {agent_id, task_id}.

Inputs: message (required).

cleanup_task_historyC

Remove old tasks from history.

Inputs: older_than_seconds.

list_agentsA

List all managed agents with status, busy flag, current task and task counts

Inputs: no named parameters.

list_storageA

List all keys in shared storage

Inputs: no named parameters.

read_storageC

Read data from shared storage

Inputs: key (required).

spawn_agentC

Spawn a new agent with the given role and system prompt

Inputs: role_name (required), system_prompt (required), tools.

stop_agentB

Stop a running agent

Inputs: agent_id (required).

storage_cleanupA

Remove keys from storage matching a glob pattern with optional exclusion.

Inputs: exclude, pattern.

task_resultB

Get the result of a task enriched with task_id and status. If task_id is omitted, returns the last result.

Inputs: agent_id (required), task_id.

task_statusB

Get detailed status of a specific task including missing_tools, partial flag, and timestamps.

Inputs: task_id (required), agent_id (required).

write_storageB

Write data to shared storage. Handles JSON strings automatically. Protected keys are restricted.

Inputs: key (required), value (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.2/5.0

    Scored across 14 tools

    Disambiguation4/5

    Most tools are clearly distinct: agent lifecycle tools (list, spawn, stop, status) and task tools (assign, status, result, aggregate) separate cleanly. Minor overlap exists between list_agents and agent_status since list_agents already includes status fields, but descriptions clarify the singular focus of agent_status. Storage tools are unambiguous.

    Naming Consistency3/5

    Naming mixes conventions: verb_noun (list_agents, spawn_agent, assign_task, read_storage, write_storage, aggregate_results), noun_noun (task_status, task_result, agent_status), and single verb (broadcast). While readable, the pattern is not uniform and violates expectations (e.g., agent_status vs status_agent, storage_cleanup vs cleanup_storage).

    Tool Count4/5

    14 tools is within a reasonable range for an orchestrator covering agent lifecycle, task management, and shared storage. Each tool serves a distinct purpose and the count reflects the breadth of functionality without being excessive.

    Completeness4/5

    The tool surface covers core workflows well: agent creation/listing/removal/status, task assignment/tracking/results/aggregation, and storage read/write/cleanup. Minor gaps like a direct task cancellation or agent update are missing, but these are edge cases not fundamental to the domain.

    Maintenance

    ActivitySlowing
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers