merit_api: Instructions file for Codex

AGENTS.md

Codebase guidance for AI coding agents working in this repository.

What This Project Is

Unofficial MCP server and Python SDK for the Merit Aktiva accounting REST API (Estonian/Polish). The project is a uv workspace with two independently publishable packages:

• merit_api/ — Python SDK (merit-api on PyPI)
• mcp/ — FastMCP server (merit-unofficial-mcp-server on PyPI)

Commands

# Install all dependencies (both packages)
uv sync --all-extras

# Run SDK tests
uv run --package merit-api pytest

# Run MCP server tests
uv run --package merit-unofficial-mcp-server pytest

# Run a single test file
uv run --package merit-api pytest merit_api/tests/test_read_methods.py

# Run integration tests (requires live Merit credentials)
MERIT_API_INTEGRATION_TEST=true MERIT_API_ID=xxx MERIT_API_KEY=xxx \
  uv run --package merit-api pytest

# Start the MCP server locally
uv run --package merit-unofficial-mcp-server merit-unofficial-mcp

There is no separate linting configuration. CI runs pytest for both packages.

Architecture

SDK (merit_api/src/merit_api/)

MeritAPI in client.py is the single entry point. It owns the HTTP session and HMAC-SHA256 request signing: every request body is deterministically serialized (json.dumps with sort_keys=True), then signed with api_id + timestamp + body. Auth params (apiId, timestamp, signature) go on the query string.

Thirteen domain namespaces are instantiated as properties on MeritAPI (e.g. client.sales, client.customers). They all inherit from Namespace in namespaces.py and call self._client._post() or self._client._get(). The client exposes three HTTP methods: _post, _get, and _get_pdf (for base64-encoded PDF responses).

Key SDK behaviours to know:

• Date format: Merit API fields expect YYYYMMDD strings. _to_yyyymmdd() converts ISO 8601 to this format; use it when passing dates from invoice-list responses (which return ISO 8601) to write endpoints.
• Default period: Namespace._apply_default_period() injects the last 90 days when PeriodStart/PeriodEnd are omitted.
• Business errors: Merit returns HTTP 200 with {"Success": false, "Error": "..."} for errors. _raise_for_business_error() detects this and raises MeritAPIError.
• Plain-text responses: Some endpoints (email/e-invoice delivery) return "OK" as a plain string. The client normalises these to {"Message": "OK", "Success": true}.