# OneFile Invoice Generator — local MCP server

`onefile-invoice-mcp.js` is a **zero-dependency, single-file** [MCP](https://modelcontextprotocol.io)
server that exposes the OneFile Invoice Generator's `generateDocument` tool to any MCP client
(Claude Desktop, Claude Code, etc.). It runs **locally** — your invoice data never leaves your machine,
the same promise as the OneFile tool itself.

It implements the MCP stdio transport (JSON-RPC 2.0) directly, so there is **no `npm install`** — just Node.

## Requirements

- Node 18+ (`node --version`).

## Add it to your MCP client

### Claude Code

```
claude mcp add onefile-invoice -- node "/absolute/path/to/onefile-invoice-mcp.js"
```

### Claude Desktop

Settings → Developer → Edit Config, then add the server and restart:

```json
{
  "mcpServers": {
    "onefile-invoice": {
      "command": "node",
      "args": ["/absolute/path/to/onefile-invoice-mcp.js"]
    }
  }
}
```

## Use it

Ask the agent in plain language, e.g.:

> Generate a OneFile invoice for Folio Studio (VAT 4720123456) billing Acme Holdings: 2 days
> consulting at R4 500 and a R3 200 brand asset pack, additive VAT.

The agent calls `generateDocument` and returns a structured invoice (lines, totals, notes) —
e.g. subtotal R12 200, VAT R1 830, total R14 030.

## The tool

`generateDocument` — deterministic, no network, no storage. Unit prices are VAT-exclusive; VAT
defaults to 15% (South Africa); `taxBehaviour` is one of `additive` · `reverse_charge` (DRC) ·
`zero` · `exempt`. It mirrors the inline MCP manifest and the live demo on
<https://azad.co.za/onefile/invoice/>.

## Quick self-test (no client needed)

```
printf '%s\n' \
  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05"}}' \
  '{"jsonrpc":"2.0","id":2,"method":"tools/list"}' \
  | node onefile-invoice-mcp.js
```

## Privacy / scope

This is a **local stdio** server: the agent launches it on your machine and the invoice data stays
on the device. A hosted/remote MCP endpoint is deliberately **not** provided — routing invoice data
through a server would break the "data never leaves your device" promise.