# automation-health-mcp

**An MCP server that finds the automation which stopped working without telling anyone.**

Most automation does not fail loudly. It keeps running, keeps exiting zero, keeps writing to its log — and quietly stops doing the work. The dashboard stays green. Nobody finds out until somebody asks a question about the numbers.

This server gives an LLM agent the tools to go and check.

```
> Audit the automation on this machine.

  critical  com.acme.sync           scheduled job is failing (exit code 1)
  critical  publisher.log           no output for 74h (threshold 26h)
  critical  api.example.com/accounts  HTTP 200 but 'data' is empty —
                                      the endpoint answers while holding nothing
  warning   worker.log              recent errors: login_required
  warning   billing.py:42           unfinished logic returning a hardcoded value
```

---

## Why this exists

I audited my own stack and found six scheduled jobs that had been dead for weeks. Every one of them reported success in the way that mattered to whatever was watching:

- a messaging job authenticated, received `login_required`, and exited quietly
- a publishing integration returned `HTTP 200` while holding **zero** connected accounts
- a report had been renamed `.DISABLED` during debugging and never renamed back
- a budget function read its input file, ignored it, and returned the constant it was seeded with

None of these are exotic. They are the normal ways automation dies, and none of them trip a conventional "is the process running" check.

## What it checks

| Tool | Question it answers |
|------|--------------------|
| `list_jobs` | What is scheduled on this machine, and what did it exit with? |
| `find_failing_jobs` | Which scheduled jobs are failing right now? |
| `check_log_freshness` | Which daily jobs have produced no output in over a day? |
| `check_recent_errors` | Which logs show failures *in the last 24 hours*? |
| `check_endpoint` | Does this integration return **content**, or just a status code? |
| `find_stale_placeholders` | Which functions are marked TODO and still return a hardcoded number? |
| `audit` | All of the above, in one prioritised report |

Two design decisions worth calling out:

**Recent errors only, tail only.** Scanning whole log files resurfaces failures that were fixed weeks ago and turns the report into noise you learn to ignore. Only recently-modified files are read, and only their last lines.

**Payload over status code.** `check_endpoint` takes a JSON path — `data`, `result.accounts` — and treats an empty collection there as critical. This is the check that catches a disconnected integration, which presents itself as a perfectly healthy `HTTP 200`.

## Install

```bash
uvx --from automation-health-mcp automation-health
```

Or add it to your MCP client configuration:

```json
{
  "mcpServers": {
    "automation-health": {
      "command": "uvx",
      "args": ["--from", "automation-health-mcp", "automation-health"]
    }
  }
}
```

Requires Python 3.10+. macOS reads `launchd`; Linux reads `systemd`.

## Use it from an agent

```
Audit /var/log with job prefix "com.acme." and code in ~/src/api.

Check whether https://api.example.com/v1/accounts still holds live accounts —
the JSON path is "data".
```

## Use the checks directly

The check layer has no MCP dependency, so it also works as a plain library — in a cron job, a CI step, or a health endpoint:

```python
from automation_health import checks

findings = (
    checks.failing_jobs("com.acme.")
    + checks.log_freshness("/var/log/acme", max_age_hours=26)
    + checks.recent_errors("/var/log/acme")
)

for f in findings:
    print(f.severity, f.subject, f.detail)
```

## The part that actually matters

The checks are the easy half. The half that decides whether any of this works is **where the findings go**.

I had a monitoring script before any of this. It ran daily, correctly detected that my main plan file was eleven days stale, and wrote that finding to a log file. Nobody reads log files. I had built a smoke detector and installed it in a room I never enter.

> A detector whose output nobody consumes is not a detector. It is a diary.

So route the output of `audit` somewhere unavoidable: a Slack channel, the top of a dashboard, a file that gets injected into your agent's context at the start of every session. Push, not pull.

The question to ask about any automated system is not *"is it running?"* It is:

**"If this stopped working tonight, how exactly would I find out?"**

## Development

```bash
uv run --with pytest --with "mcp[cli]" python -m pytest tests/ -q
```

## Licence

MIT — see [LICENSE](LICENSE).

Built by [Elite Product LLC](https://automate-ai.live). We build and stabilise automation systems for companies: integrations, AI agents, and the reliability layer that tells you when they quietly stop working.