monobank-mcp 2.0.0

package/README.md

@@ -0,0 +1,174 @@
+<p align="center">
+  <img src="https://upload.wikimedia.org/wikipedia/commons/d/db/Monobank_logo.svg" alt="Monobank" width="280" />
+</p>
+
+<h1 align="center">monobank-mcp</h1>
+
+<p align="center">
+  MCP server for Monobank Open API — accounts, transactions, exchange rates, jars & webhooks for Claude and other LLM clients.
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/monobank-mcp"><img src="https://img.shields.io/npm/v/monobank-mcp" alt="npm version" /></a>
+  <a href="https://www.npmjs.com/package/monobank-mcp"><img src="https://img.shields.io/npm/dm/monobank-mcp" alt="npm downloads" /></a>
+  <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT" /></a>
+  <a href="https://nodejs.org/"><img src="https://img.shields.io/badge/node-%3E%3D18-brightgreen?logo=node.js&logoColor=white" alt="Node.js" /></a>
+  <a href="https://www.typescriptlang.org/"><img src="https://img.shields.io/badge/TypeScript-5-3178C6?logo=typescript&logoColor=white" alt="TypeScript" /></a>
+  <a href="https://modelcontextprotocol.io"><img src="https://badge.mcpx.dev?type=server&features=tools,resources,prompts" alt="MCP" /></a>
+</p>
+
+<p align="center">
+  <a href="https://insiders.vscode.dev/redirect/mcp/install?name=monobank&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22monobank-mcp%22%5D%2C%22env%22%3A%7B%22MONOBANK_TOKEN%22%3A%22%24%7Binput%3Amonobank-token%7D%22%7D%7D"><img src="https://img.shields.io/badge/VS_Code-Install_Server-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white" alt="Install in VS Code" /></a>
+</p>
+
+---
+
+## Features
+
+- **8 Personal API tools** — accounts, statements, exchange rates, jars, webhooks
+- **4 Corporate API tools** — ECDSA signing, multi-user auth flow, zero rate limits
+- **Smart caching** — respects Monobank's 1 req/60s limit automatically
+- **Retry with backoff** — exponential retry on transient failures
+- **Request deduplication** — concurrent identical calls merged into one HTTP request
+- **Resources & Prompts** — exchange rates as context, spending analysis template
+- **English-first docs** — full API reference, agent setup guide, corporate guide
+
+## Quick Start
+
+Get your token at **https://api.monobank.ua/** (scan QR with Monobank app), then:
+
+```bash
+npx -y monobank-mcp
+```
+
+## Configuration
+
+### Claude Desktop
+
+Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
+
+```json
+{
+  "mcpServers": {
+    "monobank": {
+      "command": "npx",
+      "args": ["-y", "monobank-mcp"],
+      "env": {
+        "MONOBANK_TOKEN": "your_token_here"
+      }
+    }
+  }
+}
+```
+
+### VS Code / Cursor
+
+Add to `.vscode/mcp.json` or `.cursor/mcp.json`:
+
+```json
+{
+  "servers": {
+    "monobank": {
+      "command": "npx",
+      "args": ["-y", "monobank-mcp"],
+      "env": {
+        "MONOBANK_TOKEN": "your_token_here"
+      }
+    }
+  }
+}
+```
+
+### Claude Code
+
+```bash
+claude mcp add monobank -- npx -y monobank-mcp
+```
+
+Then set `MONOBANK_TOKEN` in your environment.
+
+## Tools
+
+### Personal API
+
+| Tool | Description |
+|------|-------------|
+| `get_client_info` | Client profile, all accounts and jars with balances, IBANs |
+| `get_statement` | Transaction history for any date range (max 31 days) |
+| `get_recent_transactions` | Latest N transactions from the last X minutes |
+| `get_exchange_rates` | Current UAH/USD/EUR and 100+ exchange rate pairs |
+| `get_jars` | Savings jars with balances, goals, and progress |
+| `set_webhook` | Register a URL for real-time transaction events |
+| `delete_webhook` | Stop receiving webhook notifications |
+| `get_webhook_status` | Check currently registered webhook URL |
+
+### Corporate API
+
+Available when `MONOBANK_AUTH_MODE=corporate`. See [Corporate API Setup](docs/CORPORATE_API.md).
+
+| Tool | Description |
+|------|-------------|
+| `initiate_authorization` | Start user auth flow, returns Monobank app URL |
+| `check_authorization` | Check if user approved the auth request |
+| `get_corp_settings` | Get corporate app settings (key, name, webhook) |
+| `set_corp_webhook` | Set webhook URL for the corporate application |
+
+## Resources
+
+| Resource | URI | Description |
+|----------|-----|-------------|
+| Exchange Rates | `monobank://exchange-rates` | Current exchange rates as background context |
+
+## Prompts
+
+| Prompt | Description |
+|--------|-------------|
+| `spending-analysis` | Analyze spending patterns for a given period (week / month / quarter) |
+
+## Rate Limits
+
+| Endpoint | Personal API | Corporate API |
+|----------|-------------|---------------|
+| `client-info` | 1 req / 60s | Unlimited |
+| `statement` | 1 req / 60s | Unlimited |
+| `currency` | No limit | No limit |
+| `webhook` | No limit | No limit |
+
+The server caches responses automatically (59s for rate-limited endpoints, 5 min for exchange rates). Retry with exponential backoff handles transient failures.
+
+## Environment Variables
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `MONOBANK_TOKEN` | Personal mode | Token from https://api.monobank.ua/ |
+| `MONOBANK_AUTH_MODE` | No | `personal` (default) or `corporate` |
+| `MONOBANK_KEY_ID` | Corporate mode | SHA1 hash of your public key |
+| `MONOBANK_PRIVATE_KEY_PATH` | Corporate mode | Path to ECDSA secp256k1 private key |
+| `MONOBANK_PRIVATE_KEY_PEM` | Corporate mode | PEM string (alternative to file path) |
+
+## Docker
+
+```bash
+docker build -t monobank-mcp .
+docker run -e MONOBANK_TOKEN=your_token monobank-mcp
+```
+
+## Development
+
+```bash
+git clone https://github.com/serhiizghama/monobank-mcp.git
+cd monobank-mcp
+npm install
+npm run build
+npm test
+```
+
+## Documentation
+
+- [API Reference](docs/API_REFERENCE.md) — full tool/resource/prompt reference with examples
+- [Corporate API Setup](docs/CORPORATE_API.md) — ECDSA key generation, auth flow
+- [Agent Setup Guide](docs/AGENT_SETUP.md) — instructions for AI agents to auto-install
+
+## License
+
+MIT

package/dist/cache/dedup.d.ts

@@ -0,0 +1 @@
+export declare function dedup<T>(key: string, fn: () => Promise<T>): Promise<T>;

package/dist/cache/dedup.js

@@ -0,0 +1,10 @@
+const inflight = new Map();
+export async function dedup(key, fn) {
+    const existing = inflight.get(key);
+    if (existing)
+        return existing;
+    const promise = fn().finally(() => inflight.delete(key));
+    inflight.set(key, promise);
+    return promise;
+}
+//# sourceMappingURL=dedup.js.map

package/dist/cache/dedup.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dedup.js","sourceRoot":"","sources":["../../src/cache/dedup.ts"],"names":[],"mappings":"AAAA,MAAM,QAAQ,GAAG,IAAI,GAAG,EAA4B,CAAC;AAErD,MAAM,CAAC,KAAK,UAAU,KAAK,CAAI,GAAW,EAAE,EAAoB;IAC9D,MAAM,QAAQ,GAAG,QAAQ,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IACnC,IAAI,QAAQ;QAAE,OAAO,QAAsB,CAAC;IAE5C,MAAM,OAAO,GAAG,EAAE,EAAE,CAAC,OAAO,CAAC,GAAG,EAAE,CAAC,QAAQ,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC;IACzD,QAAQ,CAAC,GAAG,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;IAC3B,OAAO,OAAO,CAAC;AACjB,CAAC"}

package/dist/cache/ttl-cache.d.ts

@@ -0,0 +1,6 @@
+export declare class TtlCache {
+    private store;
+    get<T>(key: string): T | undefined;
+    set<T>(key: string, data: T, ttlSeconds: number): void;
+    invalidate(key: string): void;
+}

package/dist/cache/ttl-cache.js

@@ -0,0 +1,20 @@
+export class TtlCache {
+    store = new Map();
+    get(key) {
+        const entry = this.store.get(key);
+        if (!entry)
+            return undefined;
+        if (Date.now() > entry.expiresAt) {
+            this.store.delete(key);
+            return undefined;
+        }
+        return entry.data;
+    }
+    set(key, data, ttlSeconds) {
+        this.store.set(key, { data, expiresAt: Date.now() + ttlSeconds * 1000 });
+    }
+    invalidate(key) {
+        this.store.delete(key);
+    }
+}
+//# sourceMappingURL=ttl-cache.js.map

package/dist/cache/ttl-cache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ttl-cache.js","sourceRoot":"","sources":["../../src/cache/ttl-cache.ts"],"names":[],"mappings":"AAKA,MAAM,OAAO,QAAQ;IACX,KAAK,GAAG,IAAI,GAAG,EAA+B,CAAC;IAEvD,GAAG,CAAI,GAAW;QAChB,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QAClC,IAAI,CAAC,KAAK;YAAE,OAAO,SAAS,CAAC;QAC7B,IAAI,IAAI,CAAC,GAAG,EAAE,GAAG,KAAK,CAAC,SAAS,EAAE,CAAC;YACjC,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;YACvB,OAAO,SAAS,CAAC;QACnB,CAAC;QACD,OAAO,KAAK,CAAC,IAAS,CAAC;IACzB,CAAC;IAED,GAAG,CAAI,GAAW,EAAE,IAAO,EAAE,UAAkB;QAC7C,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,UAAU,GAAG,IAAI,EAAE,CAAC,CAAC;IAC3E,CAAC;IAED,UAAU,CAAC,GAAW;QACpB,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IACzB,CAAC;CACF"}

package/dist/client/base.d.ts

@@ -0,0 +1,5 @@
+export declare function apiFetch<T>(path: string, options?: {
+    headers?: Record<string, string>;
+    method?: string;
+    body?: Record<string, unknown>;
+}): Promise<T>;

package/dist/client/base.js

@@ -0,0 +1,25 @@
+import { AuthError, MonobankError, RateLimitError } from '../errors/index.js';
+const BASE_URL = 'https://api.monobank.ua';
+export async function apiFetch(path, options = {}) {
+    const response = await fetch(`${BASE_URL}${path}`, {
+        method: options.method ?? 'GET',
+        headers: { 'Content-Type': 'application/json', ...options.headers },
+        body: options.body ? JSON.stringify(options.body) : undefined,
+    });
+    if (response.ok) {
+        const text = await response.text();
+        return text ? JSON.parse(text) : undefined;
+    }
+    if (response.status === 401)
+        throw new AuthError();
+    if (response.status === 403)
+        throw new AuthError('Access denied. Token may lack required permissions.');
+    if (response.status === 429) {
+        const retryAfter = parseInt(response.headers.get('Retry-After') ?? '60', 10);
+        throw new RateLimitError(retryAfter);
+    }
+    const errorBody = await response.text().catch(() => '');
+    const message = errorBody || `HTTP ${response.status}`;
+    throw new MonobankError('server', message, undefined, response.status);
+}
+//# sourceMappingURL=base.js.map

package/dist/client/base.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"base.js","sourceRoot":"","sources":["../../src/client/base.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAE9E,MAAM,QAAQ,GAAG,yBAAyB,CAAC;AAE3C,MAAM,CAAC,KAAK,UAAU,QAAQ,CAC5B,IAAY,EACZ,UAII,EAAE;IAEN,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,GAAG,QAAQ,GAAG,IAAI,EAAE,EAAE;QACjD,MAAM,EAAE,OAAO,CAAC,MAAM,IAAI,KAAK;QAC/B,OAAO,EAAE,EAAE,cAAc,EAAE,kBAAkB,EAAE,GAAG,OAAO,CAAC,OAAO,EAAE;QACnE,IAAI,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,SAAS;KAC9D,CAAC,CAAC;IAEH,IAAI,QAAQ,CAAC,EAAE,EAAE,CAAC;QAChB,MAAM,IAAI,GAAG,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAC;QACnC,OAAO,IAAI,CAAC,CAAC,CAAE,IAAI,CAAC,KAAK,CAAC,IAAI,CAAO,CAAC,CAAC,CAAE,SAAe,CAAC;IAC3D,CAAC;IAED,IAAI,QAAQ,CAAC,MAAM,KAAK,GAAG;QAAE,MAAM,IAAI,SAAS,EAAE,CAAC;IACnD,IAAI,QAAQ,CAAC,MAAM,KAAK,GAAG;QAAE,MAAM,IAAI,SAAS,CAAC,qDAAqD,CAAC,CAAC;IAExG,IAAI,QAAQ,CAAC,MAAM,KAAK,GAAG,EAAE,CAAC;QAC5B,MAAM,UAAU,GAAG,QAAQ,CAAC,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,aAAa,CAAC,IAAI,IAAI,EAAE,EAAE,CAAC,CAAC;QAC7E,MAAM,IAAI,cAAc,CAAC,UAAU,CAAC,CAAC;IACvC,CAAC;IAED,MAAM,SAAS,GAAG,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,EAAE,CAAC,CAAC;IACxD,MAAM,OAAO,GAAG,SAAS,IAAI,QAAQ,QAAQ,CAAC,MAAM,EAAE,CAAC;IACvD,MAAM,IAAI,aAAa,CAAC,QAAQ,EAAE,OAAO,EAAE,SAAS,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;AACzE,CAAC"}

package/dist/client/corporate.d.ts

@@ -0,0 +1,26 @@
+import type { ClientInfo, ExchangeRate, StatementItem } from '../types/monobank.js';
+export interface CorpSettings {
+    pubkey: string;
+    name: string;
+    permission: string;
+    logo: string;
+    webhook: string | null;
+}
+export declare class CorporateClient {
+    private readonly signingConfig;
+    constructor(keyId: string, privateKeyPem: string);
+    private userHeaders;
+    private corpHeaders;
+    getClientInfo(requestId: string): Promise<ClientInfo>;
+    getStatement(requestId: string, accountId: string, from: number, to?: number): Promise<StatementItem[]>;
+    initiateAuthorization(callbackUrl: string, permissions?: string): Promise<{
+        tokenRequestId: string;
+        acceptUrl: string;
+    }>;
+    checkAuthorization(requestId: string): Promise<{
+        status: string;
+    }>;
+    getCorpSettings(): Promise<CorpSettings>;
+    setCorpWebhook(url: string): Promise<void>;
+    getExchangeRates(): Promise<ExchangeRate[]>;
+}

package/dist/client/corporate.js

@@ -0,0 +1,70 @@
+import { dedup } from '../cache/dedup.js';
+import { apiFetch } from './base.js';
+import { withRetry } from './retry.js';
+import { signRequest } from './signing.js';
+export class CorporateClient {
+    signingConfig;
+    constructor(keyId, privateKeyPem) {
+        this.signingConfig = { keyId, privateKeyPem };
+    }
+    userHeaders(path, requestId) {
+        return {
+            ...signRequest(this.signingConfig, path, requestId),
+            'X-Request-Id': requestId,
+        };
+    }
+    corpHeaders(path) {
+        return signRequest(this.signingConfig, path, '');
+    }
+    // --- Per-user endpoints (require requestId from auth flow) ---
+    async getClientInfo(requestId) {
+        const path = '/personal/client-info';
+        return dedup(`corp:client-info:${requestId}`, () => withRetry(() => apiFetch(path, { headers: this.userHeaders(path, requestId) })));
+    }
+    async getStatement(requestId, accountId, from, to) {
+        const path = to
+            ? `/personal/statement/${accountId}/${from}/${to}`
+            : `/personal/statement/${accountId}/${from}`;
+        return dedup(`corp:statement:${path}:${requestId}`, () => withRetry(() => apiFetch(path, { headers: this.userHeaders(path, requestId) })));
+    }
+    // --- Auth flow endpoints ---
+    async initiateAuthorization(callbackUrl, permissions = 'sp') {
+        const path = '/personal/auth/request';
+        const sigHeaders = signRequest(this.signingConfig, path, permissions);
+        return withRetry(() => apiFetch(path, {
+            method: 'POST',
+            headers: {
+                ...sigHeaders,
+                'X-Callback': callbackUrl,
+                'X-Permissions': permissions,
+            },
+        }));
+    }
+    async checkAuthorization(requestId) {
+        const path = '/personal/auth/request';
+        const sigHeaders = signRequest(this.signingConfig, path, requestId);
+        return withRetry(() => apiFetch(path, {
+            headers: {
+                ...sigHeaders,
+                'X-Request-Id': requestId,
+            },
+        }));
+    }
+    // --- Corp-level endpoints (no user context) ---
+    async getCorpSettings() {
+        const path = '/personal/corp/settings';
+        return withRetry(() => apiFetch(path, { headers: this.corpHeaders(path) }));
+    }
+    async setCorpWebhook(url) {
+        const path = '/personal/corp/webhook';
+        await withRetry(() => apiFetch(path, {
+            method: 'POST',
+            headers: this.corpHeaders(path),
+            body: { webHookUrl: url },
+        }));
+    }
+    async getExchangeRates() {
+        return dedup('exchange-rates', () => withRetry(() => apiFetch('/bank/currency')));
+    }
+}
+//# sourceMappingURL=corporate.js.map

package/dist/client/corporate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"corporate.js","sourceRoot":"","sources":["../../src/client/corporate.ts"],"names":[],"mappings":"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"}

package/dist/client/personal.d.ts

@@ -0,0 +1,10 @@
+import type { ClientInfo, ExchangeRate, StatementItem } from '../types/monobank.js';
+export declare class PersonalClient {
+    private readonly token;
+    constructor(token: string);
+    private headers;
+    getClientInfo(): Promise<ClientInfo>;
+    getStatement(accountId: string, from: number, to?: number): Promise<StatementItem[]>;
+    setWebhook(url: string): Promise<void>;
+    getExchangeRates(): Promise<ExchangeRate[]>;
+}

package/dist/client/personal.js

@@ -0,0 +1,34 @@
+import { dedup } from '../cache/dedup.js';
+import { apiFetch } from './base.js';
+import { withRetry } from './retry.js';
+export class PersonalClient {
+    token;
+    constructor(token) {
+        this.token = token;
+    }
+    headers() {
+        return { 'X-Token': this.token };
+    }
+    async getClientInfo() {
+        return dedup('client-info', () => withRetry(() => apiFetch('/personal/client-info', {
+            headers: this.headers(),
+        })));
+    }
+    async getStatement(accountId, from, to) {
+        const path = to
+            ? `/personal/statement/${accountId}/${from}/${to}`
+            : `/personal/statement/${accountId}/${from}`;
+        return dedup(`statement:${path}`, () => withRetry(() => apiFetch(path, { headers: this.headers() })));
+    }
+    async setWebhook(url) {
+        await withRetry(() => apiFetch('/personal/webhook', {
+            method: 'POST',
+            headers: this.headers(),
+            body: { webHookUrl: url },
+        }));
+    }
+    async getExchangeRates() {
+        return dedup('exchange-rates', () => withRetry(() => apiFetch('/bank/currency')));
+    }
+}
+//# sourceMappingURL=personal.js.map

package/dist/client/personal.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"personal.js","sourceRoot":"","sources":["../../src/client/personal.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,EAAE,MAAM,mBAAmB,CAAC;AAC1C,OAAO,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AACrC,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAEvC,MAAM,OAAO,cAAc;IACI;IAA7B,YAA6B,KAAa;QAAb,UAAK,GAAL,KAAK,CAAQ;IAAG,CAAC;IAEtC,OAAO;QACb,OAAO,EAAE,SAAS,EAAE,IAAI,CAAC,KAAK,EAAE,CAAC;IACnC,CAAC;IAED,KAAK,CAAC,aAAa;QACjB,OAAO,KAAK,CAAC,aAAa,EAAE,GAAG,EAAE,CAC/B,SAAS,CAAC,GAAG,EAAE,CACb,QAAQ,CAAa,uBAAuB,EAAE;YAC5C,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE;SACxB,CAAC,CACH,CACF,CAAC;IACJ,CAAC;IAED,KAAK,CAAC,YAAY,CAChB,SAAiB,EACjB,IAAY,EACZ,EAAW;QAEX,MAAM,IAAI,GAAG,EAAE;YACb,CAAC,CAAC,uBAAuB,SAAS,IAAI,IAAI,IAAI,EAAE,EAAE;YAClD,CAAC,CAAC,uBAAuB,SAAS,IAAI,IAAI,EAAE,CAAC;QAC/C,OAAO,KAAK,CAAC,aAAa,IAAI,EAAE,EAAE,GAAG,EAAE,CACrC,SAAS,CAAC,GAAG,EAAE,CACb,QAAQ,CAAkB,IAAI,EAAE,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,EAAE,CAAC,CAC7D,CACF,CAAC;IACJ,CAAC;IAED,KAAK,CAAC,UAAU,CAAC,GAAW;QAC1B,MAAM,SAAS,CAAC,GAAG,EAAE,CACnB,QAAQ,CAAO,mBAAmB,EAAE;YAClC,MAAM,EAAE,MAAM;YACd,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE;YACvB,IAAI,EAAE,EAAE,UAAU,EAAE,GAAG,EAAE;SAC1B,CAAC,CACH,CAAC;IACJ,CAAC;IAED,KAAK,CAAC,gBAAgB;QACpB,OAAO,KAAK,CAAC,gBAAgB,EAAE,GAAG,EAAE,CAClC,SAAS,CAAC,GAAG,EAAE,CAAC,QAAQ,CAAiB,gBAAgB,CAAC,CAAC,CAC5D,CAAC;IACJ,CAAC;CACF"}

package/dist/client/retry.d.ts

@@ -0,0 +1 @@
+export declare function withRetry<T>(fn: () => Promise<T>, maxAttempts?: number): Promise<T>;

package/dist/client/retry.js

@@ -0,0 +1,32 @@
+import { AuthError, MonobankError, RateLimitError } from '../errors/index.js';
+const BACKOFF_DELAYS_MS = [2000, 4000, 8000, 16000, 32000];
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+export async function withRetry(fn, maxAttempts = 3) {
+    let lastError;
+    for (let attempt = 0; attempt < maxAttempts; attempt++) {
+        try {
+            return await fn();
+        }
+        catch (err) {
+            lastError = err;
+            if (err instanceof AuthError)
+                throw err;
+            if (err instanceof MonobankError && err.category === 'validation')
+                throw err;
+            if (err instanceof RateLimitError) {
+                const delay = err.retryAfterSeconds
+                    ? err.retryAfterSeconds * 1000
+                    : (BACKOFF_DELAYS_MS[attempt] ?? 32000);
+                await sleep(delay);
+                continue;
+            }
+            if (attempt < maxAttempts - 1) {
+                await sleep(BACKOFF_DELAYS_MS[attempt] ?? 32000);
+            }
+        }
+    }
+    throw lastError;
+}
+//# sourceMappingURL=retry.js.map

package/dist/client/retry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"retry.js","sourceRoot":"","sources":["../../src/client/retry.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAE9E,MAAM,iBAAiB,GAAG,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,KAAK,CAAC,CAAC;AAE3D,SAAS,KAAK,CAAC,EAAU;IACvB,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,CAAC;AAC3D,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,SAAS,CAC7B,EAAoB,EACpB,WAAW,GAAG,CAAC;IAEf,IAAI,SAAkB,CAAC;IAEvB,KAAK,IAAI,OAAO,GAAG,CAAC,EAAE,OAAO,GAAG,WAAW,EAAE,OAAO,EAAE,EAAE,CAAC;QACvD,IAAI,CAAC;YACH,OAAO,MAAM,EAAE,EAAE,CAAC;QACpB,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,SAAS,GAAG,GAAG,CAAC;YAEhB,IAAI,GAAG,YAAY,SAAS;gBAAE,MAAM,GAAG,CAAC;YACxC,IAAI,GAAG,YAAY,aAAa,IAAI,GAAG,CAAC,QAAQ,KAAK,YAAY;gBAAE,MAAM,GAAG,CAAC;YAE7E,IAAI,GAAG,YAAY,cAAc,EAAE,CAAC;gBAClC,MAAM,KAAK,GAAG,GAAG,CAAC,iBAAiB;oBACjC,CAAC,CAAC,GAAG,CAAC,iBAAiB,GAAG,IAAI;oBAC9B,CAAC,CAAC,CAAC,iBAAiB,CAAC,OAAO,CAAC,IAAI,KAAK,CAAC,CAAC;gBAC1C,MAAM,KAAK,CAAC,KAAK,CAAC,CAAC;gBACnB,SAAS;YACX,CAAC;YAED,IAAI,OAAO,GAAG,WAAW,GAAG,CAAC,EAAE,CAAC;gBAC9B,MAAM,KAAK,CAAC,iBAAiB,CAAC,OAAO,CAAC,IAAI,KAAK,CAAC,CAAC;YACnD,CAAC;QACH,CAAC;IACH,CAAC;IAED,MAAM,SAAS,CAAC;AAClB,CAAC"}

package/dist/client/signing.d.ts

@@ -0,0 +1,6 @@
+export interface SigningConfig {
+    keyId: string;
+    privateKeyPem: string;
+}
+export declare function signRequest(config: SigningConfig, requestPath: string, secondIngredient?: string): Record<string, string>;
+export declare function loadPrivateKey(): string;

package/dist/client/signing.js

@@ -0,0 +1,24 @@
+import { createSign } from 'node:crypto';
+import { readFileSync } from 'node:fs';
+export function signRequest(config, requestPath, secondIngredient = '') {
+    const timestamp = Math.floor(Date.now() / 1000);
+    const dataToSign = `${timestamp}${secondIngredient}${requestPath}`;
+    const signer = createSign('SHA256');
+    signer.update(dataToSign);
+    const signature = signer.sign(config.privateKeyPem, 'base64');
+    return {
+        'X-Key-Id': config.keyId,
+        'X-Time': timestamp.toString(),
+        'X-Sign': signature,
+    };
+}
+export function loadPrivateKey() {
+    if (process.env.MONOBANK_PRIVATE_KEY_PEM) {
+        return process.env.MONOBANK_PRIVATE_KEY_PEM.replace(/\\n/g, '\n');
+    }
+    const path = process.env.MONOBANK_PRIVATE_KEY_PATH;
+    if (path)
+        return readFileSync(path, 'utf-8');
+    throw new Error('Corporate API requires MONOBANK_PRIVATE_KEY_PEM or MONOBANK_PRIVATE_KEY_PATH');
+}
+//# sourceMappingURL=signing.js.map

package/dist/client/signing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"signing.js","sourceRoot":"","sources":["../../src/client/signing.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAOvC,MAAM,UAAU,WAAW,CACzB,MAAqB,EACrB,WAAmB,EACnB,mBAA2B,EAAE;IAE7B,MAAM,SAAS,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,CAAC;IAChD,MAAM,UAAU,GAAG,GAAG,SAAS,GAAG,gBAAgB,GAAG,WAAW,EAAE,CAAC;IAEnE,MAAM,MAAM,GAAG,UAAU,CAAC,QAAQ,CAAC,CAAC;IACpC,MAAM,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC;IAC1B,MAAM,SAAS,GAAG,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,aAAa,EAAE,QAAQ,CAAC,CAAC;IAE9D,OAAO;QACL,UAAU,EAAE,MAAM,CAAC,KAAK;QACxB,QAAQ,EAAE,SAAS,CAAC,QAAQ,EAAE;QAC9B,QAAQ,EAAE,SAAS;KACpB,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,cAAc;IAC5B,IAAI,OAAO,CAAC,GAAG,CAAC,wBAAwB,EAAE,CAAC;QACzC,OAAO,OAAO,CAAC,GAAG,CAAC,wBAAwB,CAAC,OAAO,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;IACpE,CAAC;IACD,MAAM,IAAI,GAAG,OAAO,CAAC,GAAG,CAAC,yBAAyB,CAAC;IACnD,IAAI,IAAI;QAAE,OAAO,YAAY,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;IAC7C,MAAM,IAAI,KAAK,CAAC,8EAA8E,CAAC,CAAC;AAClG,CAAC"}

package/dist/errors/index.d.ts

@@ -0,0 +1,12 @@
+export declare class MonobankError extends Error {
+    readonly category: 'auth' | 'rate_limit' | 'validation' | 'not_found' | 'server';
+    readonly retryAfterSeconds?: number | undefined;
+    readonly statusCode?: number | undefined;
+    constructor(category: 'auth' | 'rate_limit' | 'validation' | 'not_found' | 'server', message: string, retryAfterSeconds?: number | undefined, statusCode?: number | undefined);
+}
+export declare class RateLimitError extends MonobankError {
+    constructor(retryAfterSeconds: number);
+}
+export declare class AuthError extends MonobankError {
+    constructor(message?: string);
+}

package/dist/errors/index.js

@@ -0,0 +1,25 @@
+export class MonobankError extends Error {
+    category;
+    retryAfterSeconds;
+    statusCode;
+    constructor(category, message, retryAfterSeconds, statusCode) {
+        super(message);
+        this.category = category;
+        this.retryAfterSeconds = retryAfterSeconds;
+        this.statusCode = statusCode;
+        this.name = 'MonobankError';
+    }
+}
+export class RateLimitError extends MonobankError {
+    constructor(retryAfterSeconds) {
+        super('rate_limit', `Rate limit exceeded. Retry after ${retryAfterSeconds} seconds.`, retryAfterSeconds);
+        this.name = 'RateLimitError';
+    }
+}
+export class AuthError extends MonobankError {
+    constructor(message = 'Invalid or missing token. Get your token at https://api.monobank.ua/') {
+        super('auth', message, undefined, 401);
+        this.name = 'AuthError';
+    }
+}
+//# sourceMappingURL=index.js.map

package/dist/errors/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/errors/index.ts"],"names":[],"mappings":"AAAA,MAAM,OAAO,aAAc,SAAQ,KAAK;IAEpB;IAEA;IACA;IAJlB,YACkB,QAAuE,EACvF,OAAe,EACC,iBAA0B,EAC1B,UAAmB;QAEnC,KAAK,CAAC,OAAO,CAAC,CAAC;QALC,aAAQ,GAAR,QAAQ,CAA+D;QAEvE,sBAAiB,GAAjB,iBAAiB,CAAS;QAC1B,eAAU,GAAV,UAAU,CAAS;QAGnC,IAAI,CAAC,IAAI,GAAG,eAAe,CAAC;IAC9B,CAAC;CACF;AAED,MAAM,OAAO,cAAe,SAAQ,aAAa;IAC/C,YAAY,iBAAyB;QACnC,KAAK,CACH,YAAY,EACZ,oCAAoC,iBAAiB,WAAW,EAChE,iBAAiB,CAClB,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,gBAAgB,CAAC;IAC/B,CAAC;CACF;AAED,MAAM,OAAO,SAAU,SAAQ,aAAa;IAC1C,YAAY,OAAO,GAAG,sEAAsE;QAC1F,KAAK,CAAC,MAAM,EAAE,OAAO,EAAE,SAAS,EAAE,GAAG,CAAC,CAAC;QACvC,IAAI,CAAC,IAAI,GAAG,WAAW,CAAC;IAC1B,CAAC;CACF"}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { createServer } from './server.js';
+async function main() {
+    const transport = new StdioServerTransport();
+    const server = createServer();
+    await server.connect(transport);
+    console.error('Monobank MCP server running on stdio');
+}
+main().catch((error) => {
+    console.error('Fatal error:', error);
+    process.exit(1);
+});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AACjF,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAE3C,KAAK,UAAU,IAAI;IACjB,MAAM,SAAS,GAAG,IAAI,oBAAoB,EAAE,CAAC;IAC7C,MAAM,MAAM,GAAG,YAAY,EAAE,CAAC;IAC9B,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IAChC,OAAO,CAAC,KAAK,CAAC,sCAAsC,CAAC,CAAC;AACxD,CAAC;AAED,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,KAAK,EAAE,EAAE;IACrB,OAAO,CAAC,KAAK,CAAC,cAAc,EAAE,KAAK,CAAC,CAAC;IACrC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}

package/dist/server.d.ts

@@ -0,0 +1,2 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function createServer(): McpServer;