Metadata-Version: 2.5
Name: backroom-mcp
Version: 0.1.0
Summary: MCP server for the Backroom invoice-extraction API
Project-URL: Homepage, https://backroom-api-wmk6.onrender.com/backroom/api/docs
Project-URL: Repository, https://github.com/pardhuparimi/backroom
Author: Backroom
Keywords: backroom,extraction,invoice,mcp,model-context-protocol
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27
Requires-Dist: mcp<2,>=1.2
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == 'dev'
Description-Content-Type: text/markdown

# Backroom MCP Server

mcp-name: io.github.pardhuparimi/backroom

An MCP (Model Context Protocol) server that wraps the **Backroom**
invoice-extraction API, so any MCP client can submit invoice PDFs and
read back structured, verified extractions as tools.

Backroom never guesses: every field in a proposal carries a value, a
verification status (`verified` / `extracted` / `unclear`), a
confidence, and provenance. A field the engine could not verify comes
back `unclear` with a **null** value instead of a fabricated one.

## Install & run

With [uv](https://docs.astral.sh/uv/):

```bash
uvx backroom-mcp
```

Or with pip:

```bash
pip install backroom-mcp
backroom-mcp
```

The server speaks MCP over **stdio** — your client launches it as a
subprocess. Example client configuration:

```json
{
  "mcpServers": {
    "backroom": {
      "command": "uvx",
      "args": ["backroom-mcp"],
      "env": {
        "BACKROOM_API_KEY": "bk_test_…"
      }
    }
  }
}
```

## Configuration

| Variable | Required | Purpose |
|---|---|---|
| `BACKROOM_API_KEY` | Yes, for all tools except `check_health` | Your Backroom API key. Mint a free test key (100 documents/month) at <https://backroom-api-wmk6.onrender.com/backroom/get-a-key>. The key is only ever sent to the Backroom API as a bearer token — never logged or stored by this server. |
| `BACKROOM_API_BASE` | No | API base URL override (default `https://backroom-api-wmk6.onrender.com`), e.g. for a staging deployment. |

## Tools

| Tool | What it does |
|---|---|
| `submit_invoice(pdf_path)` | Upload a local invoice PDF; returns the job id and a `deduped` flag. |
| `submit_invoice_and_wait(pdf_path, timeout_seconds=180)` | Submit, then poll until the job reaches a terminal state; returns the outcome, the reason code when no proposal was issued, and the `proposal_id` when one was. Does **not** fetch the proposal (see the warning below). |
| `get_job(job_id)` | A job's state and terminal payload. |
| `get_proposal(proposal_id)` | The full proposal, exactly as the API serves it. **Fetch exactly once** — see below. |
| `get_usage()` | Your meter for the current month: documents used, cap, remaining. |
| `check_health()` | API health (no key required). |

### ⚠ Proposals are fetch-exactly-once

The API runs zero-retention by default: the first successful
`get_proposal` fetch **purges the result**, and a second fetch of the
same id returns 404. Whatever client calls it must keep the returned
proposal — it cannot be fetched again.

## Errors

The API reports errors as RFC 9457 problem documents (`title`,
`code`, `detail`, `retryable`, `request_id`). This server surfaces
them verbatim as the tool error — including reason codes such as
`NO_EXTRACTABLE_TEXT` when a document is a scan with no readable
text, which the API refuses rather than guesses at.

## Zero retention

This wrapper stores nothing. PDFs are read from disk at call time and
sent to the API over HTTPS; no document, result, or key is written to
disk or logged by the server. On the API side, zero-retention keys
purge results on first fetch or after 24 hours.

## Development

```bash
python -m venv .venv && .venv/bin/pip install -e ".[dev]"
.venv/bin/python -m pytest
```

Tests mock the HTTP layer — no network and no API key needed.
