# delegations-mcp

An MCP server that exposes a library of **delegation prompts** as tools. A smart
orchestrator LLM uses these tools to hand off bounded tasks to a reduced LLM or
coding agent, which receives a fully-constructed, self-contained prompt requiring
no broader context.

## Configuration

Config is discovered by walking up from the working directory, then merged with
`~/.delegations.toml`. Project config extends global; library blocks merge
field-by-field (project overrides global per field).

```toml
# .delegations.toml

[agent]
executable = "copilot"
args = ["--model", "gpt-4o-mini", "--prompt", "Instructions in: {prompt_path}"]

output_dir = "/tmp"   # where prompts and transcripts are written

[library.devteam]
path = "./library/devteam"
test_executable = "/usr/bin/python3"
test_args = ["-m", "pytest"]
```

`{prompt_path}` in agent args is replaced with the path to the rendered prompt file.

## Running

The server must run on the host filesystem — the agent it spawns edits files
directly and needs access to your project.

### stdio mode — recommended, zero config

The MCP client spawns the server automatically, inheriting its working directory.
Config is discovered from there. No setup required beyond installing the package.

MCP client config (e.g. Claude Desktop):

```json
{
  "mcpServers": {
    "delegations": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/delegations-mcp", "delegations-mcp"]
    }
  }
}
```

### HTTP mode — persistent session server

Useful when multiple agents share a session: the registry is loaded once, and
the async lock for `lock: true` delegations is shared across all connections.

Run from your project directory (so config discovery finds `.delegations.toml`):

```bash
cd /your/project
delegations-mcp --transport http --port 8000
# or: uv run --directory /path/to/delegations-mcp delegations-mcp --transport http
```

Connect your MCP client to `http://localhost:8000/mcp`. One server instance per
project — the working directory at startup determines which config and libraries
are used.

## Tools exposed

| Tool | Description |
|------|-------------|
| `list_delegations()` | Lists available delegations; refreshes registry from disk |
| `get_delegation(name)` | Returns full details and merged input schema for a delegation |
| `run_delegation(name, inputs)` | Runs a delegation; returns `summary`, `prompt_path`, `transcript_path` |

Delegation names are `library:delegation` (e.g. `devteam:implement`).

## Libraries

See [`library/devteam/README.md`](library/devteam/README.md) for the bundled
devteam library. See [`docs/library-implementation.md`](docs/library-implementation.md)
to author your own.