Skip to main content
Glama
README.md
# saqme

`saqme` (საქმე, Georgian for “business” or “matter”) is a TypeScript, MIT-licensed local MCP server, CLI and agent skill for checking Georgian invoices and payment terms. See [SPEC.md](SPEC.md) for the tool contracts and source limits.

[Saqme skill overview in English and Georgian](https://tsirbiladze.com/skills/saqme)

## Related work

[ABGEO/georgia-mcp](https://github.com/ABGEO/georgia-mcp) is a GPL-3.0 Go server for broad Georgian public data with hosted HTTP and self-hosted stdio. [akalongman/nbg-rates-mcp](https://github.com/akalongman/nbg-rates-mcp) is an MIT server for dated NBG rates and conversion. This package brings rates, statutory facts, working days, IBAN checks and a pinned HS lookup together for an invoice workflow.

[LogisticsHub](https://github.com/tsirbiladze/logisticshub) by Tornike Sirbiladze (MIT) supplied the HS lookup, dataset and generator and informed the Revenue Service parser and stdio setup. The pinned source is the original annex to Order No. 21 of 26 January 2024. Later amendments were not verified. See [THIRD-PARTY.md](THIRD-PARTY.md).

## Run locally

Requires Node 24 and pnpm. The package is unreleased.

```bash
pnpm install
pnpm verify
pnpm cli tax vat_rate
```

Add this entry to your MCP host and replace `<path-to-saqme>` with the full path to your checkout.

```json
{
  "mcpServers": {
    "saqme": {
      "command": "node",
      "args": ["<path-to-saqme>/src/cli.ts", "mcp"]
    }
  }
}
```

Use `pnpm pack` to build the installable tarball. In the config above, set `command` to `npx` and `args` to `["-y", "--package=<path-to-saqme>/saqme-0.1.0.tgz", "saqme", "mcp"]` to run the packed version. Once published, the command will be `npx -y saqme@0.1.0 mcp`.

Install the [saqme skill](skills/saqme/SKILL.md) by copying its folder into your host's skills directory or importing it as a local skill. The skill requires access to the MCP tools.

## Tools and commands

Commands below run from the checkout. Successful checks and supported failure outcomes emit JSON on stdout with the same shape as the MCP results. CLI misuse or a disabled VAT command exits 2 with a short stderr message. Read `status` and the result before using it.

| MCP tool | CLI example | Result |
| --- | --- | --- |
| `gel_exchange_rate` | `pnpm cli rate USD 2026-11-15 --amount 100` | NBG quoted GEL per published quantity, requested and effective dates, retrieval time, and optional GEL conversion |
| `validate_ge_iban` | `pnpm cli iban GE71ZZ0000000000000001` | Georgian format and checksum validity using a synthetic example |
| `ge_business_day` | `pnpm cli workday 2026-12-28 --add 5` | Excluding the start gives January 5, 2027 in the statutory calendar |
| `ge_tax_fact` | `pnpm cli tax vat_rate` | Decimal string `"18"`, unit `percent`, Art. 166 |
| `lookup_hs_code` | `pnpm cli hs 940330 --limit 1` | Description and ancestors in the 2024 original annex. Later amendments were not verified |
| `ge_company_vat_status` | `pnpm cli vat <company-code> --enable-company-vat --confirm-disclosure` | Current observed VAT status for a recognized legal entity, when the response can be resolved |

The tax keys are `vat_rate`, `vat_period`, `vat_declaration_due`, `vat_registration_threshold`, `personal_income_tax_rate`, `profit_tax_rate` and `fx_rate_rule`. They reference Matsne publication 248 and have no as-of selector.

Every result includes `status` and `sources`. A successful result includes `data`. The source manifest is available at `saqme://sources`.

- `ok` means the check completed. An IBAN can have `status: "ok"` and `data.valid: false`.
- `not_found` means the source returned no matching data.
- `unsupported` means the date, entity or request falls outside supported scope.
- `upstream_error` means the live lookup could not yield a usable response.
- `stale` includes the last good quote and its original retrieval time after a failed refresh. Treat it as historical evidence.

### Exchange rates

The NBG feed can carry a quote forward from an earlier effective date. Conversion uses the published rate divided by its quoted quantity, then rounds the final GEL amount to two decimal places with ties away from zero. Pass negative amounts as `--amount=-100.50`. Cached quotes are fresh for five minutes and may be returned as `stale` for up to 24 hours on upstream failure. The cache stores at most 64 entries. Only the requested date goes to NBG.

If your network requires a proxy, set `NODE_USE_ENV_PROXY=1` alongside `HTTP_PROXY` or `HTTPS_PROXY` before starting the CLI. Set the same variables in the MCP server's environment when launching from a host. [Node.js proxy configuration](https://nodejs.org/learn/http/enterprise-network-configuration)

### Calendar and scope

The default `statutory` scope uses Monday to Friday with the pinned Labour Code Art. 30 holidays removed, including Orthodox Good Friday through Easter Monday. It applies the same edition from 2000 through 2100 inclusive, with no weekday substitution. Historical applicability and future amendments require separate verification. A positive count excludes the starting date, and `--add 0` keeps a working start date or rolls to the next working day. `decreeOverridesReviewed` reports review status for the input year, and `calculation.decreeOverridesReviewed` reports it for the result year. [Labour Code Art. 30, Matsne publication 28](https://matsne.gov.ge/ka/document/view/1155567?publication=28)

Use `--scope public_administration` (`administrative` is an alias) only when the decree covers the body and activity. This scope supports 2026 only and returns `unsupported` if the calculation reaches an unreviewed year. Decree 563 gives January 5–6, 2026 off for covered staff and has exceptions for designated essential services, NBG-supervised financial obligations and procurement. Confirm separate contract rules, statutory deadlines and bank cutoffs before relying on a date. [Decree 563](https://matsne.gov.ge/ka/document/view/6713428?publication=0)

### Revenue Service and privacy

Enable VAT lookup by appending `--enable-company-vat` after `mcp` in the host command or setting `SAQME_ENABLE_COMPANY_VAT=1` in the server environment. This adds the tool to `tools/list`. Each request needs the user's confirmation of disclosure and a nine-digit code from a known legal entity. The check sends that code alone, keeps no cache and reports only the VAT status, time and source. Individual entrepreneurs, personal numbers, unrecognized entity forms and mixed responses are outside scope. Revenue Service automation terms and successful live response shapes are unverified. The opt-in path is covered by synthetic tests.

There is no telemetry. IBAN, HS, tax and workday checks run offline. IBAN validation covers format and checksum. Use the CLI if you want to avoid sharing inputs with a model host. A local host may retain command history or MCP arguments under its own settings.

## Development

`pnpm verify` typechecks and runs network-free tests, including stdio negotiation, tool schemas and synthetic provider replies. `pnpm pack` emits JavaScript and bundles the pinned HS data so Node can run the installed binary. Regenerate the original HS edition with `python3 scripts/build-hs-nomenclature.py <annex.docx>`. The generator checks the source document's SHA-256.