Skip to main content
Glama

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 for the tool contracts and source limits.

Saqme skill overview in English and Georgian

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 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 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.

Related MCP server: mcp-europe-business

Run locally

Requires Node 24 and pnpm. The package is unreleased.

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.

{
  "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 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

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

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

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.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      Enables natural language queries for Georgian tax system waybills through the RS.ge SOAP API. Supports waybill retrieval by date range, company TIN lookups, and access to tax system dictionaries.
      5
      1
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      European business compliance suite for AI agents — 28 tools covering tax ID validation (PT, ES, FR, DE, IT, UK, NL), IBAN verification, EU VAT rates, invoice requirements, e-invoicing rules, payment terms, labor calendar helpers, VAT breakdown calculations and invoice schema validation for 18+ European countries.
      28
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables users to ask in natural language for Georgian public data — exchange rates, fuel prices, bank card offers, Tbilisi transit, postal codes, cinema listings, Geostat statistics, and air quality — with every answer sourced from the publishing organizations and read-only. No account or API key is needed for the hosted endpoint.
      11
      GPL 3.0