# automation-queue-mcp

An MCP (Model Context Protocol) server that lets an LLM like Claude inspect
and control an automation job queue — list jobs, check status, trigger new
runs, retry failures, and pull queue-wide stats through natural language.

## Why I built this

Over several years leading platform engineering for enterprise RPA
(UiPath queues triggered via AWS Lambda, robot/machine lifecycle,
license and infrastructure administration), I kept coming back to the
same question: what would it look like if an LLM could actually operate
that queue directly, instead of a human checking a dashboard and
manually re-triggering failed jobs?

This project is a generalized, non-proprietary version of that idea —
an MCP server exposing the operations any automation queue needs
(list, inspect, trigger, retry, stats) so an LLM client can reason
about and manage automation jobs conversationally.

It uses an in-memory mock queue so it's safe to run and explore
immediately with no setup. Swap `job_queue.py` for a real backend
(REST API, database, Orchestrator client) to point this at a live
automation environment.

## What it does

| Tool | Description |
|---|---|
| `list_jobs` | List jobs in the queue, optionally filtered by status (`queued`, `running`, `completed`, `failed`) |
| `get_job_details` | Full detail for a single job, including its execution logs |
| `trigger_job` | Trigger a new job for a given workflow, optionally on a specific machine |
| `retry_failed_job` | Re-queue a job that's currently in `failed` status |
| `get_queue_stats` | Aggregate stats — counts by status, machines currently in use |

## Example interaction (via Claude)

> **You:** What's failed in the queue right now?
>
> **Claude:** *(calls `list_jobs` with `status_filter="failed"`)*
> Two jobs have failed: `EligibilityCheck_Workflow` on BOT-VM-02 (2 retries
> already) and `ExceptionHandling_Workflow` on BOT-VM-04 (1 retry). Want me
> to retry either of them?
>
> **You:** Retry the eligibility one.
>
> **Claude:** *(calls `retry_failed_job` with `job_id=2`)*
> Done — it's back in the queue, now on retry #3.

## Getting started

```bash
git clone https://github.com/<your-username>/automation-queue-mcp.git
cd automation-queue-mcp
python -m venv venv
source venv/bin/activate   # Windows: venv\Scripts\activate
pip install -r requirements.txt
python server.py
```

### Connecting it to Claude Desktop

Add the server to your Claude Desktop config (see
`examples/claude_desktop_config.json` for a template):

```json
{
  "mcpServers": {
    "automation-queue": {
      "command": "python",
      "args": ["/absolute/path/to/automation-queue-mcp/server.py"]
    }
  }
}
```

Restart Claude Desktop, and the five tools above become available in
conversation.

## Project structure

```
automation-queue-mcp/
├── server.py              # MCP server + tool definitions
├── job_queue.py            # In-memory mock job queue (swap for a real backend)
├── requirements.txt
├── examples/
│   └── claude_desktop_config.json
└── LICENSE
```

## Extending this

The mock `JobQueue` class in `job_queue.py` is intentionally isolated
from the MCP server logic in `server.py` — to connect this to a real
automation system, you only need to reimplement `JobQueue`'s five
methods (`list_jobs`, `get_job`, `queue_stats`, `trigger_job`,
`retry_job`) against your actual queue/API. The MCP tool layer doesn't
need to change.

## Background

Built by John Samuel Jacob David Ravichandran — Technical Lead background
in enterprise intelligent automation, platform engineering, and healthcare
RPA. More at [LinkedIn](https://www.linkedin.com/in/john-samuel-jacob-david-ravichandran-5082601a9).

## License

MIT — see [LICENSE](LICENSE).