# Invoice Query MCP Server

> **Portfolio showcase only.** All customers and invoices are fictional sample data. This is not a production product and does not represent a real client engagement.

TypeScript **Model Context Protocol (MCP)** server that turns a sample invoice CSV into agent-ready tools (`list_invoices`, `get_invoice`, `invoice_summary`, `overdue_invoices`). Built for Claude Desktop / MCP clients with Zod-validated inputs, Vitest coverage, and a reproducible demo transcript. Shows how to package small, useful data tools for AI agents without dumping whole spreadsheets into the prompt.

![Demo transcript](screenshots/transcript.png)

![Summary card](screenshots/summary-card.png)

## Problem

Agents and chat tools often need structured access to tabular finance data (open invoices, overdue balances, customer lookups) without stuffing an entire spreadsheet into the context window.

## Solution

A focused MCP server that loads a sample invoice CSV and exposes four tools:

| Tool | Purpose |
|------|---------|
| `list_invoices` | Filter by status, customer substring, amount range, category |
| `get_invoice` | Fetch one invoice by ID |
| `invoice_summary` | Counts and USD totals (optionally filtered) |
| `overdue_invoices` | Shortcut for overdue rows + total |

## Stack

- TypeScript / Node.js
- `@modelcontextprotocol/sdk` (stdio transport)
- Zod for tool input schemas
- `csv-parse` for CSV loading
- Vitest for unit tests

## Quick start

```bash
npm install
npm test
npm run build
npm run demo          # writes demo/transcript.txt
npm start             # stdio MCP server (for Claude Desktop / MCP clients)
```

### Claude Desktop config snippet

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

Optional: set `INVOICE_CSV_PATH` to point at a different CSV with the same columns.

## Sample data

See `data/sample-invoices.csv` — twelve fictional local-business invoices used only for demos.

## License

MIT © John Gantz