ua-mcp
# ua-mcp
An MCP server for three Ukrainian services: Nova Poshta, Ukrposhta and Monobank. Seven tools, all read-only, each built around a question a person asks rather than around an API method.
```
"Скільки коштує відправити 2 кг з Києва до Одеси?" → np_quote
"Де посилка 0500100031143?" → ukrposhta_track
"Скільки я витратив у Сільпо за листопад?" → mono_statement
```
## Tools
| Tool | Answers | Needs |
| --- | --- | --- |
| `np_track` | Where a Nova Poshta parcel is, when it is expected, whether it was picked up. Up to 20 numbers. | nothing |
| `np_find_branch` | Branches and parcel lockers in a city: address, hours, weight limit, working or not. | nothing |
| `np_quote` | Delivery cost and arrival date between two cities, from city names. | nothing |
| `ukrposhta_track` | Status and full route of a Ukrposhta shipment. | `UKRPOSHTA_TRACKING_BEARER` |
| `mono_rates` | Monobank buy and sell rates against the hryvnia. | nothing |
| `mono_accounts` | Cards, accounts and jars with balances. | `MONOBANK_TOKEN` |
| `mono_statement` | Operations for up to 31 days with totals, optionally filtered by text. | `MONOBANK_TOKEN` |
A tool is registered only when it can work. With no credentials the server offers four tools; the other three appear when their token is set. The model never sees a tool it cannot use.
## Run it
```bash
npm install
npm run build
```
`.mcp.json` for Claude Code, or the same block in any MCP client:
```json
{
"mcpServers": {
"ua": {
"command": "node",
"args": ["/path/to/ua-mcp/dist/index.js"],
"env": {
"NOVA_POSHTA_API_KEY": "",
"UKRPOSHTA_TRACKING_BEARER": "",
"MONOBANK_TOKEN": ""
}
}
}
}
```
| Variable | Where it comes from |
| --- | --- |
| `NOVA_POSHTA_API_KEY` | Optional. The business cabinet at new.novaposhta.ua. The three tools work without it. |
| `UKRPOSHTA_TRACKING_BEARER` | The status-tracking bearer from the annex to an agreement with Ukrposhta. |
| `MONOBANK_TOKEN` | A personal token from api.monobank.ua. It reads your own accounts, so treat it as a password. |
## Decisions
- **Read-only.** Nothing here creates a waybill or moves money. Every tool carries `readOnlyHint`, so a client can run them without asking each time. Writes belong in a separate server with its own confirmation step.
- **Questions, not endpoints.** `np_quote` takes "Київ" and "Одеса", resolves both to the carrier's ids, then asks for the price and the date in parallel. A model should not have to chain four calls and carry UUIDs between them.
- **Plain numbers out.** Monobank answers in kopiykas and numeric currency codes; the tools return `12500.5` and `"UAH"`. A foreign payment keeps its original amount next to the hryvnia one.
- **Limits become advice.** Monobank allows one personal request a minute and 31 days per statement. The server refuses a longer period before calling the bank and turns a `429` into "wait a minute and ask again" instead of a stack trace. Exchange rates are cached for five minutes, which is how often the bank refreshes them.
- **"Not found" is an answer.** An unknown tracking number comes back as `found: false`, not as an empty parcel or an error.
## How it was checked
| Part | Check |
| --- | --- |
| All seven tools | 20 tests that call the tools through a real MCP client over an in-memory transport. |
| `np_find_branch`, `np_quote`, `np_track`, `mono_rates` | `npm run smoke` starts the built server over stdio and calls the live services. Passing on 2026-11-16. |
| `np_track` on a delivered parcel | Fixture only: the field set is a live answer, the values are invented. No real tracking number was used. |
| `ukrposhta_track` | Fixture only, written from the example in Ukrposhta's Status Tracking documentation. **Not run against the live service**: the bearer is issued under an agreement. |
| `mono_accounts`, `mono_statement` | Fixture only, written from the field list in Monobank's API documentation. **Not run against a live account.** |
The Nova Poshta fixtures and the exchange rates in `fixtures/` are trimmed answers of the live services, so the tests parse what the services really send. The live smoke found one bug the fixtures could not: parcel lockers were filtered out of the first page of branches, which in a large city holds none. The carrier now does that filtering.
## Tool-selection eval
`npm run eval` asks 23 questions in Ukrainian, Russian and English through the Claude Code CLI with only this server's tools available, and compares the first tool the model calls, and its arguments, with the expected ones. Four of the questions have no fitting tool (weather, another carrier, a money transfer, creating a waybill) and pass only if no tool is called.
Last run, 2026-11-16, `claude-haiku-5-5`: **23 of 23**. The full record is in `evals/last-report.json`.
Read that number with care. The questions and the tool descriptions were written by the same person, so this is a regression check on the descriptions, not a measure of how the server does with questions from the wild. During the eval the services are answered from fixtures: it costs them nothing and no token leaves the machine.
## Other servers
Nova Poshta has a larger MCP server, [shopanaio/carrier-api](https://github.com/shopanaio/carrier-api), which also creates and manages waybills; several community servers cover Monobank. This one is narrower on purpose: three services behind one small tool list, no writes, and a published check of whether a model picks the right tool.
## Layout
```
src/
server.ts tool list, descriptions and input schemas
novaposhta.ts tracking, branch search, quote
ukrposhta.ts tracking
monobank.ts rates, accounts, statement
http.ts one fetch wrapper with a timeout and a service-named error
fixtures/ saved answers of the services
scripts/smoke.ts live check over stdio
evals/ cases, the offline server and the runner
```
MIT.
TDQS
Scored across 4 tools
Each tool has a clearly distinct purpose: parcel tracking, branch lookup, delivery cost/time quoting, and currency exchange rates. The only potential overlap between np_track and np_quote is resolved by their descriptions: status of an existing parcel versus cost/time for a hypothetical new shipment.
All names use snake_case and follow a service-prefix convention (np_ for Nova Poshta, mono_ for Monobank). The verb style is mostly consistent within np_ tools, though mono_rates is a noun phrase rather than a verb_noun pattern, which is a minor deviation.
Four tools is well within the appropriate 3–15 range for a focused utility server, and each tool covers a distinct operation. There are no redundant or filler tools.
The Nova Poshta surface covers tracking, branch lookup, and delivery quoting, while Monobank has exchange rates. Minor gaps exist, such as no city lookup to support np_quote or broader Monobank operations, but the core utility workflows are covered.