# @m8t-jacob/mcp-polish-biz

[![CI](https://img.shields.io/github/actions/workflow/status/M8T-Jacob/mcp-polish-biz/ci.yml?branch=main&label=CI)](https://github.com/M8T-Jacob/mcp-polish-biz/actions/workflows/ci.yml)
[![npm version](https://img.shields.io/npm/v/%40m8t-jacob%2Fmcp-polish-biz)](https://www.npmjs.com/package/@m8t-jacob/mcp-polish-biz)
[![npm downloads](https://img.shields.io/npm/dm/%40m8t-jacob%2Fmcp-polish-biz)](https://www.npmjs.com/package/@m8t-jacob/mcp-polish-biz)
[![license: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)

An **MCP (Model Context Protocol) server** that gives AI agents — Claude
Desktop, Claude Code, Cursor, or any other MCP client — direct access to
Polish business data: identifier validation, the VAT whitelist, EU VIES
lookups, and NBP exchange rates.

It's a thin wiring layer: every tool delegates to a small, independently
published, fully-tested package —
[`@m8t-jacob/validate`](https://www.npmjs.com/package/@m8t-jacob/validate),
[`@m8t-jacob/polish-registry`](https://www.npmjs.com/package/@m8t-jacob/polish-registry),
and [`@m8t-jacob/pln-utils`](https://www.npmjs.com/package/@m8t-jacob/pln-utils)
— so this repo contains no domain logic of its own, just MCP tool
definitions, zod input schemas, and error mapping.

- Built on the official [`@modelcontextprotocol/sdk`](https://www.npmjs.com/package/@modelcontextprotocol/sdk) `McpServer` API
- Runs over **stdio** — the transport used when an MCP client launches a
  server as a local subprocess (typically via `npx`)
- Every tool validates its input with `zod` and **never throws**: failures
  come back as a normal tool result with `isError: true`, so one bad call
  can't crash the server
- Strict TypeScript, ships dual ESM + CJS builds with `.d.ts`
- 100% test coverage on tool handlers — dependencies are mocked, so the
  test suite makes zero real network calls

## Install for Claude Desktop / Claude Code

Add this to your MCP client's configuration (for Claude Desktop,
`claude_desktop_config.json`; for Claude Code, `.mcp.json` or via
`claude mcp add`):

```json
{
  "mcpServers": {
    "polish-biz": {
      "command": "npx",
      "args": ["-y", "@m8t-jacob/mcp-polish-biz"]
    }
  }
}
```

No API key or configuration is required — every underlying API (the VAT
whitelist, VIES, and NBP) is free and public.

You can also run it directly to smoke-test it:

```bash
npx -y @m8t-jacob/mcp-polish-biz
```

It will sit waiting for JSON-RPC requests on stdin — that's expected; it's
meant to be driven by an MCP client, not used interactively.

## Tools

| Tool                   | Description                                                                                      | Backed by                       |
| ---------------------- | ------------------------------------------------------------------------------------------------- | -------------------------------- |
| `validate_polish_id`   | Validate a NIP, PESEL, REGON, KRS, or IBAN/NRB and return its normalized form. Offline, no network. | `@m8t-jacob/validate`           |
| `check_vat_whitelist`  | Look up a NIP on the Polish VAT whitelist ("Biała lista podatników VAT"): status, name, accounts.  | `@m8t-jacob/polish-registry`     |
| `check_vies`           | Validate an EU VAT number via VIES, returning company name/address when available.                 | `@m8t-jacob/polish-registry`     |
| `get_exchange_rate`    | Get the official NBP mid exchange rate for a currency against PLN, for today or a given date.       | `@m8t-jacob/pln-utils`           |
| `convert_currency`     | Convert an amount between two currencies using NBP mid rates.                                       | `@m8t-jacob/pln-utils`           |

### `validate_polish_id`

```json
{ "type": "nip", "value": "PL 526-000-12-46" }
```

```json
{ "valid": true, "type": "nip", "normalized": "5260001246" }
```

`type` is one of `nip`, `pesel`, `regon`, `krs`, `iban`.

### `check_vat_whitelist`

```json
{ "nip": "5252445767", "date": "2026-07-13" }
```

Returns the `WhitelistResult` shape from `@m8t-jacob/polish-registry`
(`name`, `statusVat`, `regon`, `krs`, `accountNumbers`, `found`, ...).
`date` is optional (`YYYY-MM-DD`, defaults to today).

### `check_vies`

```json
{ "countryCode": "PL", "vatNumber": "5252445767" }
```

Returns the `ViesResult` shape (`valid`, `name?`, `address?`,
`countryCode`, `vatNumber`, `requestDate`).

### `get_exchange_rate`

```json
{ "code": "USD", "date": "2025-01-15" }
```

Returns `{ code, rate, date, table }`. `date` is optional.

### `convert_currency`

```json
{ "amount": 100, "from": "USD", "to": "EUR" }
```

Returns `{ amount, from, to, result, date? }`. `date` is optional and, when
given, is used for both legs of the conversion.

## Programmatic use

The server can also be embedded directly, without going through stdio —
useful for tests or for hosting it behind a different transport:

```ts
import { createServer, TOOLS } from '@m8t-jacob/mcp-polish-biz';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';

const server = createServer();
await server.connect(new StdioServerTransport());
```

`TOOLS` (also exported) is the array of `{ name, description, inputSchema,
handler }` this server registers — each `handler` can be called directly
in tests without any transport, see `examples/basic.ts`.

## 🇵🇱 Po polsku

`@m8t-jacob/mcp-polish-biz` to serwer **MCP (Model Context Protocol)**
dający agentom AI (Claude Desktop, Claude Code, Cursor) dostęp do polskich
danych biznesowych: walidacji NIP/PESEL/REGON/KRS/IBAN, Białej listy
podatników VAT, unijnego systemu VIES oraz kursów walut NBP. Cała logika
domenowa pochodzi z trzech niezależnie opublikowanych pakietów
(`@m8t-jacob/validate`, `@m8t-jacob/polish-registry`,
`@m8t-jacob/pln-utils`) — ten serwer jest wyłącznie cienką warstwą narzędzi
MCP nad nimi. Każde narzędzie waliduje dane wejściowe przez `zod` i nigdy
nie rzuca wyjątku — błąd wraca jako zwykły wynik z `isError: true`, więc
jedno nieudane wywołanie nie może zatrzymać całego serwera. Instalacja nie
wymaga żadnego klucza API — wszystkie API źródłowe (Biała lista, VIES, NBP)
są darmowe i publiczne.

## Contributing

Contributions are welcome! See [`CONTRIBUTING.md`](./CONTRIBUTING.md) for the
development workflow and [`GOOD_FIRST_ISSUES.md`](./GOOD_FIRST_ISSUES.md) for
ideas if you're looking for a place to start. This project follows the
[Contributor Covenant](./CODE_OF_CONDUCT.md).

## License

[MIT](./LICENSE) © 2026 Jakub Jagiełło