# ABRA Flexi MCP Server

Local `stdio` MCP server for ABRA Flexi / FlexiBee accounting workflows. It is intended for agent clients such as Codex, Claude Desktop, or any MCP-compatible local runtime that can launch a Node process.

This is the standalone MCP project. The separate remote ChatGPT App project is here: [vvitovec/abra-flexi-chatgpt-app](https://github.com/vvitovec/abra-flexi-chatgpt-app).

## What It Does

- connects to ABRA Flexi over the official REST API
- reads companies, evidence metadata, records, partners, products, balances, overdue items, and accounting summaries
- prepares accountant-focused document drafts
- supports guarded write flows with validation, dry-run style checks, confirmations, and an audit log
- keeps Flexi credentials out of prompts and MCP tool arguments

## Safety Model

The server is configured through `flexi.config.json` profiles. Each profile controls:

- Flexi base URL and company slug
- test or production mode
- default response format
- which env vars contain credentials
- read, dry-run, and write evidence allowlists
- whether writes require confirmation

Writes are not free-form passthrough calls. Tool handlers build known payloads, validate them, enforce evidence permissions, and record request audit files under `.flexi-harness/logs`.

## Setup

```bash
npm install
cp .env.example .env
```

Edit `.env` with a dedicated ABRA Flexi REST API user:

```dotenv
FLEXI_PROD_USERNAME=api-user
FLEXI_PROD_PASSWORD=replace-me
```

Then edit `flexi.config.json`:

```json
{
  "defaultProfile": "prod",
  "profiles": {
    "prod": {
      "baseUrl": "https://example.flexibee.eu",
      "company": "example_company_s_r_o_",
      "usernameEnv": "FLEXI_PROD_USERNAME",
      "passwordEnv": "FLEXI_PROD_PASSWORD"
    }
  }
}
```

## Run Locally

```bash
npm run dev
```

For a production-style build:

```bash
npm run build
npm start
```

## Codex MCP Config

After building, add a server entry like this to your Codex config:

```toml
[mcp_servers.abra_flexi]
command = "node"
args = ["/absolute/path/to/abra-flexi-mcp-server/dist/index.js"]
enabled = true
```

The server loads `.env` and `flexi.config.json` from the project directory.

## Main Tool Areas

- company and evidence discovery
- flexible read-only evidence queries
- partner and product search
- invoice, payable, receivable, bank, cash, and internal document workflows
- overdue and saldo summaries
- accountant-first draft creation and guarded posting
- latest-error explanation from the local audit log

## Verification

```bash
npm run check
npm test
npm run build
```

The tests use mocked HTTP servers and fixture-style responses. They do not need real ABRA Flexi credentials.

## Related Docs

- [ABRA Flexi auth and API notes](./docs/abra-flexi-auth-and-api.md)