# cebelca-mcp

An [MCP](https://modelcontextprotocol.io) server that wraps the
[cebelca.biz](https://www.cebelca.biz) accounting API, exposing it as tools an
MCP client (Claude, etc.) can call.

## Development

This project uses **[devenv](https://devenv.sh)** for its development
environment (Node.js, yarn). With direnv installed, `cd` into the directory and
the environment loads automatically; otherwise run `devenv shell`.

The cebelca.biz API key is read from the **`CEBELCA_BIZ_API_KEY`** environment
variable. It is set in `.envrc` (git-ignored) and loaded by direnv/devenv. The
server refuses to start if the variable is missing.

Optional: `CEBELCA_BIZ_BASE_URL` overrides the API base URL (defaults to
`https://www.cebelca.biz/API`).

## Commands

```bash
yarn install     # install dependencies
yarn dev         # run from source with tsx (no build step)
yarn build       # compile TypeScript to dist/
yarn start       # run the compiled server (dist/index.js)
yarn typecheck   # type-check without emitting
```

## Project layout

```
src/
  index.ts    Entry point: builds the server, connects over stdio.
  config.ts   Loads config from the environment (API key, base URL).
  client.ts   HTTP client for the cebelca.biz resource/method API.
  tools.ts    MCP tool registration. Add new tools here.
```

## The cebelca.biz API

The API is a resource/method RPC over HTTP (docs:
[Workonomic-API-bash](https://github.com/InvoiceFox/Workonomic-API-bash/blob/master/API-docs.md),
[making-an-invoice](https://github.com/InvoiceFox/InvoiceFox-API-bash/blob/master/making-an-invoice.md)):

- Every call is an HTTP `POST` with `x-www-form-urlencoded` arguments.
- Resource and method go in the `_r` and `_m` query params (`_m2` stacks a
  second method, `_f` picks the output format, `_x=1` is explore mode).
- Auth is HTTP Basic: the API token is the **username**, the password is the
  literal `x`.
- Success responses look like `["ok", [{...}]]` or `[[{...}]]`; errors like
  `["validation", {...}]` or `[[{"err": "..."}]]`. `CebelcaClient` unwraps the
  success payload and throws `CebelcaError` on failures.
- PDFs come from a separate `.../API-pdf` endpoint.

## Tools

| Tool | Purpose |
|------|---------|
| `cebelca_explore` | Discover resources / methods / arguments (explore mode). |
| `cebelca_call` | Generic escape hatch: call any resource/method directly. |
| `cebelca_assure_partner` | Find-or-create a partner, return its id. |
| `cebelca_create_invoice_head` | Create an issued-invoice head (`insert-smart-2`). |
| `cebelca_add_invoice_line` | Add a body line to an invoice. |
| `cebelca_mark_invoice_paid` | Mark an invoice paid (by id or external id). |
| `cebelca_finalize_invoice` | Issue an invoice — `noncash` or `fiscal` (FURS). |
| `cebelca_get_fiscal_info` | Fetch ZOI/EOR/QR fiscal details. |
| `cebelca_create_proforma_head` | Create a proforma (pre-invoice) head. |
| `cebelca_add_proforma_line` | Add a body line to a proforma. |
| `cebelca_proforma_to_invoice` | Convert a proforma into an invoice. |
| `cebelca_get_pdf` | Fetch a document PDF as a base64 resource. |

## Adding tools

Register new tools in `src/tools.ts` via `server.registerTool(...)`, using
`CebelcaClient.call(resource, method, args)` and the `run` helper to turn
responses (and `CebelcaError`s) into MCP tool results. When you need an
operation no dedicated tool covers, `cebelca_explore` + `cebelca_call` reach the
whole API.

## Using with an MCP client

Build first (`yarn build`), then point your client at the compiled entry:

```json
{
  "mcpServers": {
    "cebelca": {
      "command": "node",
      "args": ["/absolute/path/to/cebelca-mcp/dist/index.js"],
      "env": { "CEBELCA_BIZ_API_KEY": "your-key-here" }
    }
  }
}
```