Metadata-Version: 2.4
Name: mcp-agent-orchestrator
Version: 0.2.0
Summary: MCP server for orchestration, lane management, worker daemons, and turn metrics.
Project-URL: Homepage, https://github.com/darce/agentic-protocol-monorepo
Project-URL: Source, https://github.com/darce/agentic-protocol-monorepo/tree/main/packages/mcp-agent-orchestrator
Project-URL: Changelog, https://github.com/darce/agentic-protocol-monorepo/blob/main/packages/mcp-agent-orchestrator/CHANGELOG.md
Project-URL: Issues, https://github.com/darce/agentic-protocol-monorepo/issues
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: fastmcp
Requires-Dist: mcp-agent-handoff<0.6.0,>=0.5.0
Requires-Dist: agentic-protocol<0.2.0,>=0.1.0
Provides-Extra: test
Requires-Dist: hypothesis>=6.0.0; extra == "test"
Requires-Dist: pytest>=8.0.0; extra == "test"
Provides-Extra: dev
Requires-Dist: hypothesis>=6.0.0; extra == "dev"
Requires-Dist: pytest>=8.0.0; extra == "dev"
Requires-Dist: ruff<1.0.0,>=0.11.0; extra == "dev"
Requires-Dist: mypy<2.0.0,>=1.13.0; extra == "dev"

# Agent Orchestrator MCP

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

## Installation

### From PyPI (recommended)

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

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

### From the monorepo source tree (development)

From this package root inside `agentic-protocol-monorepo`:

```bash
cd packages/mcp-agent-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:

```bash
pip install -e ../mcp-agent-handoff
pip install -e ".[dev]"
```

## Development

Run package-local commands from the package root:

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

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

Direct commands also work:

```bash
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-agent-handoff/docs/guides/token-efficient-usage.md`](../mcp-agent-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.

## Source Checkout Usage

For local source execution without installation:

```bash
PYTHONPATH=src python -m agent_orchestrator_mcp --help
```

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