# Automation Audit MCP

An MCP server that helps AI assistants evaluate business processes for
automation. It collects structured discovery answers, estimates manual labor
cost, scores automation potential, and stores completed audits in SQLite.

## What it does

The server exposes tools that let an MCP client:

- create businesses and the processes they want to evaluate;
- calculate monthly hours and labor cost for repetitive work;
- score automation potential using frequency, rule clarity, data readiness,
  process stability, and required human judgment;
- save discovery answers and completed audit recommendations;
- list saved audits and retrieve a complete audit with its discovery answers.

It also includes a `start_automation_audit` prompt that guides the assistant
through the assessment without inventing missing information or saving results
before the user confirms them.

## Available tools

| Tool | Purpose |
| --- | --- |
| `calculate_time_cost` | Estimate monthly hours and labor cost. |
| `calculate_automation_score` | Produce a 0–100 automation score and category. |
| `create_business` | Store a business being audited. |
| `create_process` | Store a process associated with a business. |
| `save_discovery_answer` | Save or update one discovery response. |
| `save_audit` | Store a validated completed audit. |
| `list_audits` | List saved audits, newest first. |
| `get_audit` | Retrieve an audit and all related discovery answers. |

## Requirements

- Python 3.12 or newer
- [uv](https://docs.astral.sh/uv/)
- An MCP-compatible client

## Run locally

```bash
git clone https://github.com/zuperRuslana/automation-audit-mcp.git
cd automation-audit-mcp
uv sync
uv run python main.py
```

The server communicates over standard input/output, so it is normally started
by an MCP client rather than used directly in a terminal.

## MCP client configuration

Add a server entry like this to your MCP client configuration, replacing the
directory with the absolute path where you cloned the project:

```json
{
  "mcpServers": {
    "automation-audit": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/automation-audit-mcp",
        "run",
        "python",
        "main.py"
      ]
    }
  }
}
```

## Example workflow

1. Create a business with `create_business`.
2. Create a process using the returned business ID.
3. Record discovery responses with `save_discovery_answer`.
4. Calculate time and labor cost with `calculate_time_cost`.
5. Calculate suitability with `calculate_automation_score`.
6. Review the recommendation and confirm it with the user.
7. Save the result with `save_audit`.
8. Retrieve the complete record with `get_audit`.

## Data and validation

Audit data is stored locally in `automation_audits.db`. The database file is
ignored by Git, so business data is not uploaded with the source code.

The server rejects negative cost inputs, ratings outside the supported range,
orphaned database records, and audit categories that conflict with their
score.

## Tests

```bash
uv run pytest
```

The regression suite covers startup, input validation, database connection
safety, foreign-key enforcement, and audit consistency.

## Project structure

```text
automation-audit-mcp/
├── main.py              # MCP server entry point
├── server.py            # Tools, prompt, validation, and SQLite storage
├── tests/               # Regression tests
├── pyproject.toml       # Python package and dependency metadata
└── uv.lock              # Reproducible dependency lock file
```