Workstate Orchestrator MCP

MCP server for orchestration, lane management, worker daemons, review dispatch, and ACE metrics.

Installation

From PyPI (recommended)

pip install mcp-workstate-orchestrator
# or, as an isolated tool:
uv tool install mcp-workstate-orchestrator
# or, ad-hoc without installing:
uvx mcp-workstate-orchestrator --help

mcp-workstate-orchestrator declares mcp-workstate-handoff>=0.5.0,<0.6.0 as a required dependency; pip resolves it from PyPI automatically. workstate-codex-bridge remains optional unless you want the local bridge backend.

From the monorepo source tree (development)

From this package root inside workstate:

cd packages/mcp-workstate-orchestrator
python -m pip install -e ".[dev]"

When developing both MCP servers in lockstep, install the sibling handoff package as an editable first so the orchestrator picks it up:

pip install -e ../mcp-workstate-handoff
pip install -e ".[dev]"

Development

Run package-local commands from the package root:

make lint-orchestrator
make fix-lint-orchestrator
make format-orchestrator
make mypy-orchestrator
make test-orchestrator
make check-orchestrator

The package Makefile keeps workstate-codex-bridge as an optional sibling source path for local bridge-backend development, but it expects mcp-workstate-handoff to be installed as a normal package dependency.

Direct commands also work:

PYTHONPATH=src python -m ruff check src tests
PYTHONPATH=src python -m mypy src
PYTHONPATH=src python -m pytest tests -q

Token-Efficient Usage

For bounded reads and compact caller patterns, follow the shared guide in packages/mcp-workstate-handoff/docs/guides/token-efficient-usage.md. The orchestrator package reuses that guidance instead of maintaining a separate copy of the same parameter semantics.

Runtime Notes

This package orchestrates work against a target workspace. The workspace you point it at still needs the expected task state and orchestration inputs, such as:

• .task-state/
• lane manifests
• task plans or other orchestration docs the lane logic references

Those assets belong to the workspace being orchestrated, not to the package checkout itself.

Backends

The orchestration layer supports multiple execution backends, including:

• codex-cli
• codex-subagent
• claude-code
• local-model-openai

Some backends are optional and require host-specific tooling to be installed separately.

Availability vs. the optional bridge

The static backend table always lists every declared backend. That a backend is listed does not mean it will run in the current process. The codex-subagent backend needs the optional workstate-codex-bridge host module, which is not a base dependency and is not installed by the bootstrap presync (the launcher runs uv run --no-sync). If the orchestrator server launches from a venv that lacks the bridge, resolve_bridge("codex-subagent") raises ImportError at dispatch even though the backend is listed.

To surface this without a live turn, call the MCP tool list_available_backends with its default settings, or call the CLI with probing on:

mcp-workstate-orchestrator list-backends --probe

Each probed backend carries an availability_state:

• available — in-process adapter, or a CLI binary found on PATH.
• reachable — a bridge module imports and exposes a runner; liveness is not verified (a real turn may still time out at dispatch).
• declared_not_installed — the backend is declared but its optional host module (e.g. workstate-codex-bridge) is not importable in this runtime.
• unavailable — a CLI backend whose binary is not on PATH, or a bridge module that imports but does not expose the required runner.
• unknown — no probe is implemented for that backend kind.

Install the bridge on demand to move codex-subagent from declared_not_installed to reachable:

uv sync --extra bridge   # resolves workstate-codex-bridge from the sibling source

Source Checkout Usage

For local source execution without installation:

PYTHONPATH=src python -m workstate_orchestrator_mcp --help

If you are testing against a sibling workstate-codex-bridge checkout instead of an installed bridge dependency, extend PYTHONPATH with that sibling src directory as needed.