Content
# 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" }
}
}
}
```
