Swarm Rd Orchestrator

What swarm-rd-orchestrator does

The swarm-rd-orchestrator MCP server gives parallel research agents a shared, append-only event log. Each entry is associated with a task ID and agent ID, and contains content plus a kind value such as note, result, or tool_output. Other agents can retrieve the history for a task, either from the beginning or after a cursor.

The implementation stores events in SQLite using WAL mode and wraps the log in a Ray actor. This design targets workloads where multiple agents need to publish findings and read one another’s updates without directly sharing mutable application state. The project is intentionally narrow: it does not provide memory search, ranking, or general-purpose task orchestration.

How it works

Install the Python package and run swarm-rd-cli mcp to start the swarm-rd-orchestrator MCP server over stdio. An MCP client launches that command and invokes the exposed operations using typed arguments rather than parsing terminal output.

append_delta writes a new event for a task. pull_deltas returns events in oldest-first order and accepts a cursor so callers can request only entries added after a known position. list_tasks reports each task currently present in the log and its event count. The same operations are available through the command-line interface, whose data-returning commands support JSON output for scripts and agents.

The repository includes tests for malformed input, crash behavior during writes, and concurrent appends from three real Ray actors. The concurrency test checks that the resulting log contains no missing or duplicate deltas.

Setup and configuration

Install the MCP extra with:

pip install "swarm-rd-orchestrator-cli[mcp]"

Then configure an MCP client to launch:

{
  "mcpServers": {
    "swarm-rd-orchestrator": {
      "command": "swarm-rd-cli",
      "args": ["mcp"]
    }
  }
}

The package requires Python 3.10 or newer. The event log path can be changed with the CLI’s global --db option; otherwise it uses swarm-events.db. The README demonstrates configuration with Claude Desktop and states that other MCP clients can use the stdio command. The project was tested on macOS; Windows support is unverified because of Ray’s platform support.

Tools and capabilities

The swarm-rd-orchestrator MCP server exposes these tools:

• append_delta(task_id, agent_id, content, kind="note"): adds a finding, result, or tool output to the log.
• pull_deltas(task_id, since_cursor=0): retrieves a task’s events after the supplied cursor.
• list_tasks(): lists task IDs and their event counts.

The CLI also provides append, pull, and list-tasks commands, plus --json output for structured consumption. Input without task_id, agent_id, or content is rejected before storage. The event log is append-only, and the documented crash test verifies that a failed write does not leave partial rows.

Limitations and notes

This is a 0.0.x Milestone 1 prototype rather than a stable release. Its stated purpose is to validate a Ray-native coordination approach on a real workload. The implementation is Python-focused, offers no memory search or ranking, and retrieves data by task_id rather than by semantic or keyword query. Choose it specifically when the Ray actor model and append-only task history fit the workload; otherwise, the README identifies a separate HTTP-based project as the more complete alternative.