# sattle.me assistant (MCP server)

An [MCP](https://modelcontextprotocol.io) server that makes a [sattle.me](https://sattle.me)
merchant's invoices (numbered in the merchant's one series, with their lines and VAT, a payment
link payable until their due date and a PDF) and follows their payment, with the assistant's
secret key alone (`sattleme_ak_…`, created in the sattle.me app). It never spends: every invoice
pays the merchant's wallet.

Two ways to run it, one code:

- **In Claude Desktop**, on the merchant's own computer: the key never leaves it.
- **Hosted on `mcp.sattle.me`**, for any AI app that connects to MCP servers with OAuth (Claude,
  ChatGPT…).

> Work in progress: not released yet.

| Path                                            | What it is                                                                            |
| ----------------------------------------------- | ------------------------------------------------------------------------------------- |
| [`SPEC.md`](SPEC.md)                            | The assistant's protocol: what this server does with its key. Authoritative.          |
| [`vectors/app/`](vectors/app)                   | Records made by the merchant's app, which this server reads and makes alike.          |
| [`spec/`](spec)                                 | The integrations' specification (sattleme/checkout-spec), pinned: `SPEC.md` names it. |
| [`vendor/checkout-node/`](vendor/checkout-node) | The code of sattleme/checkout-node this server builds on, pinned and unchanged.       |

## In Claude Desktop

1. In the sattle.me app, create an assistant (« Réglages › Assistants ») and copy its key
   (`sattleme_ak_…`).
2. Open `sattleme-assistant-<version>.mcpb` (a release of this repository): Claude Desktop installs
   it and asks for the key, which it keeps in the computer's secret store, and optionally the
   invoices' language, the time zone and a folder for the PDFs.
3. Ask Claude: « Fais une facture à Dupont SA pour 3 jours de conseil à 1200 CHF, échéance à 30
   jours. » It previews the invoice, asks you to confirm the total, then makes it.

Its tools: `business_profile`, `preview_invoice`, `create_invoice` (the only one that is not
read-only), `list_invoices`, `invoice_status`, `invoice_pdf`. Another MCP client starts
`node dist/src/stdio.js` with the settings of [`src/stdio.ts`](src/stdio.ts) in its environment.

## Hosted

`https://mcp.sattle.me/mcp`, added in the AI app as a connector (a custom connector in Claude, an
app or connector in ChatGPT): the app asks the merchant to
connect, and the merchant pastes the assistant key on sattle.me's own page, never in the
conversation. How it is run: [docs/HOSTING.md](docs/HOSTING.md).

## Development

Node 22 or later. `npm ci`, then `npm run check` (pinned copies, lint, format, types, tests, build).
`npm run bundle` writes the Claude Desktop bundle in `build/` (the official `mcpb` tool, pinned).
The lockfile is written by npm 11 (`npx npm@11 install`): npm 10 installs from it (`npm ci`), but
fails to resolve it anew.

## License

[MIT](LICENSE)