@useyona/einvoice-mcp 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Elyonar
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,202 @@
-# Temporary Holding Version
+# @useyona/einvoice-mcp
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The [Model Context Protocol](https://modelcontextprotocol.io) server for the Yona e-invoicing API. It lets an AI
+assistant (Claude, Cursor, VS Code, Muse and any MCP client) create buyers and invoices, validate them, report them to
+the tax authority and follow their status, with the same API key an integration uses.
+
+It runs on your machine over stdio (`npx @useyona/einvoice-mcp`). A hosted endpoint is coming soon.
+
+## Before you start
+
+- Node.js 20 or later.
+- A Yona API key from the dashboard (API keys). Start with a **sandbox** key (`sk_test_…`): sandbox submissions go to
+  the tax authority's test environment and spend sandbox credits only. The key's capabilities decide which tools
+  succeed; the `full_integration` preset is the usual choice.
+
+## Install and configure
+
+The server reads its configuration from the environment:
+
+| Variable | Required | Meaning |
+|---|---|---|
+| `YONA_API_KEY` | yes | Your API key, `sk_test_…` (sandbox) or `sk_live_…` (live). A missing or malformed key stops the server with a message. |
+| `YONA_ALLOW_LIVE` | no | `true` to allow a live key. Without it a live key is refused at start. |
+| `YONA_BASE_URL` | no | Another API host, for testing against a local gateway. Leave it unset. |
+
+Keep the key out of shared files: put it in your client's secret or environment settings where it offers one.
+
+### Claude Desktop
+
+`claude_desktop_config.json` (Settings → Developer → Edit Config):
+
+```json
+{
+  "mcpServers": {
+    "yona": {
+      "command": "npx",
+      "args": ["-y", "@useyona/einvoice-mcp"],
+      "env": { "YONA_API_KEY": "sk_test_…" }
+    }
+  }
+}
+```
+
+Restart Claude Desktop after saving.
+
+### Claude Code
+
+```bash
+claude mcp add yona --env YONA_API_KEY=sk_test_… -- npx -y @useyona/einvoice-mcp
+```
+
+### Cursor
+
+`~/.cursor/mcp.json` (all projects) or `.cursor/mcp.json` (one project):
+
+```json
+{
+  "mcpServers": {
+    "yona": {
+      "command": "npx",
+      "args": ["-y", "@useyona/einvoice-mcp"],
+      "env": { "YONA_API_KEY": "sk_test_…" }
+    }
+  }
+}
+```
+
+### VS Code
+
+`.vscode/mcp.json`; VS Code asks for the key once and stores it as a secret:
+
+```json
+{
+  "inputs": [
+    { "type": "promptString", "id": "yona-api-key", "description": "Yona API key", "password": true }
+  ],
+  "servers": {
+    "yona": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "@useyona/einvoice-mcp"],
+      "env": { "YONA_API_KEY": "${input:yona-api-key}" }
+    }
+  }
+}
+```
+
+### Muse Code
+
+`~/.config/muse/settings.json`:
+
+```json
+{
+  "mcp_servers": {
+    "yona": {
+      "command": "npx",
+      "args": ["-y", "@useyona/einvoice-mcp"],
+      "env": { "YONA_API_KEY": "sk_test_…" }
+    }
+  }
+}
+```
+
+### Hosted (coming soon)
+
+A hosted endpoint will serve the same tools over streamable HTTP, with nothing to install:
+
+- URL: `https://gp.useyona.com/mcp`
+- Header: `Authorization: Bearer sk_test_…`
+
+```bash
+# Claude Code, once the endpoint is live
+claude mcp add --transport http yona https://gp.useyona.com/mcp --header "Authorization: Bearer sk_test_…"
+```
+
+It is not live yet; use the local server until this section says otherwise.
+
+## Tools
+
+| Tool | What it does | Kind |
+|---|---|---|
+| `get_organization` | The key's organisation: profile and readiness to report invoices | read |
+| `lookup_tin` | Looks up a tax id with the tax authority | charged |
+| `search_buyers` | Lists saved buyers, by text or verification status | read |
+| `get_buyer` | One buyer | read |
+| `create_buyer` | Saves a buyer | write, charged |
+| `search_items` | Lists saved goods and services | read |
+| `create_item` | Saves a good or service | write |
+| `list_invoices` | Lists invoices, by status, payment status, buyer, date or text | read |
+| `get_invoice` | One invoice | read |
+| `create_invoice` | Creates a **draft** invoice | write, charged |
+| `update_invoice` | Changes a draft | write |
+| `validate_invoice` | Checks a draft or a document with the tax authority's rules, storing nothing | charged |
+| `finalise_invoice` | Freezes a draft for submission | write |
+| `submit_invoice` | Reports an invoice to the tax authority | **destructive**, charged |
+| `get_submission_status` | Where a report stands: accepted, rejected, parked and why | read |
+| `cancel_invoice` | Cancels an issued invoice | **destructive** |
+| `issue_credit_note` | Credits a reported invoice in full, by lines or by amount | **destructive**, charged |
+| `get_download_link` | A short-lived link to the invoice PDF | charged |
+| `create_share_link` | A revocable public link to view an invoice | write |
+| `list_received_invoices` | Invoices other businesses issued to you | read |
+| `get_received_invoice` | One received invoice | read |
+| `get_balance` | The credit balance for the key's mode | read |
+| `list_webhook_deliveries` | Webhook deliveries to your endpoints, to debug an integration | read |
+
+**Resources:** `yona://reference/tax-categories`, `yona://reference/units`, `yona://reference/hs-codes` (search with
+`?q=laptop`), `yona://organization`.
+
+**Prompts:** `draft_invoice` (a validated draft from a plain description), `explain_rejection` (why the tax authority
+did not accept an invoice, in plain words).
+
+A typical session: *"Invoice Acme Ltd for 2 laptops at ₦850,000 each"* → `search_buyers` → `create_invoice` →
+`validate_invoice` → you review → `finalise_invoice` → `submit_invoice` (after you approve) → `get_submission_status`.
+
+## Safety
+
+- **Mode in every result.** Each tool result carries `"mode": "sandbox"` or `"live"`, so the assistant always knows
+  whether an action is real.
+- **Live is opt-in.** A live key is refused at start unless `YONA_ALLOW_LIVE=true`. In live mode a submission is a
+  legal filing and spends real credits.
+- **Destructive tools need `confirm: true`.** `submit_invoice`, `cancel_invoice` and `issue_credit_note` are annotated
+  as destructive and refuse to run without `confirm: true` in their input, so a client that ignores annotations still
+  cannot submit by accident. The assistant is told to set it only after you approve the exact action.
+- **Charged calls are not marked read-only**, so clients that auto-approve read-only tools still ask before spending
+  credits.
+- **No double charges on retries.** Writes carry an `Idempotency-Key` derived from the MCP call (its request id, the
+  tool and its arguments): a client that retries the same call gets the first result and is charged once.
+- **No secrets in output.** No tool, resource or error returns the key or a token. Errors carry the API's
+  `errorCode`, message, `requestId` and field-level reasons only.
+
+## Embedding the server
+
+The package exports the server for hosts that run their own transport:
+
+```ts
+import { EInvoice } from '@useyona/einvoice-js';
+import { createYonaMcpServer, handleStreamableHttp } from '@useyona/einvoice-mcp';
+
+// Any transport:
+const server = createYonaMcpServer({ client: new EInvoice({ apiKey }), allowLive: false });
+
+// Streamable HTTP, stateless, JSON responses (no SSE, no session), one server per request:
+app.post('/mcp', (req, res) => handleStreamableHttp(req, res, { client: clientFor(req), parsedBody: req.body }));
+```
+
+`handleStreamableHttp` answers `POST` only (`GET` and `DELETE` are 405: there is no session) and 403 for a live client
+without `allowLive`. Build the client per request from the caller's credentials.
+
+## Development
+
+```bash
+npm install
+npm run lint     # types, src and tests
+npm test         # jest with coverage
+npm run build    # dist/
+```
+
+`npm run live-check` drives the built server against a local Yona e2e stack (see `scripts/live-check.mjs`).
+
+## License
+
+MIT

package/bin/cli.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+require('../dist/cli.js').main();

package/dist/cli.d.ts

@@ -0,0 +1,24 @@
+import { EInvoice } from '@useyona/einvoice-js';
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+/** A configuration problem the binary reports and exits on. Its message never contains the key. */
+export declare class CliConfigError extends Error {
+    constructor(message: string);
+}
+/** The binary's configuration, from the environment. */
+export interface CliConfig {
+    client: EInvoice;
+    allowLive: boolean;
+}
+/**
+ * Reads `YONA_API_KEY` (required), `YONA_ALLOW_LIVE` (`true` to allow a live key) and
+ * `YONA_BASE_URL` (an override for testing against another gateway).
+ */
+export declare function configFromEnv(env: NodeJS.ProcessEnv): CliConfig;
+/** Builds the server from the environment; throws {@link CliConfigError} for a bad configuration. */
+export declare function serverFromEnv(env: NodeJS.ProcessEnv): {
+    server: McpServer;
+    mode: string;
+};
+/** The `einvoice-mcp` binary: the server over stdio. Diagnostics go to stderr; stdout is the protocol. */
+export declare function main(env?: NodeJS.ProcessEnv): Promise<void>;
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AACA,OAAO,EAAC,QAAQ,EAAoC,MAAM,sBAAsB,CAAC;AACjF,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,yCAAyC,CAAC;AAIvE,mGAAmG;AACnG,qBAAa,cAAe,SAAQ,KAAK;gBACzB,OAAO,EAAE,MAAM;CAI9B;AAED,wDAAwD;AACxD,MAAM,WAAW,SAAS;IACtB,MAAM,EAAE,QAAQ,CAAC;IACjB,SAAS,EAAE,OAAO,CAAC;CACtB;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,CAAC,UAAU,GAAG,SAAS,CAsB/D;AAED,qGAAqG;AACrG,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,CAAC,UAAU,GAAG;IAAC,MAAM,EAAE,SAAS,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAC,CAQvF;AAED,0GAA0G;AAC1G,wBAAsB,IAAI,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,OAAO,CAAC,IAAI,CAAC,CAW9E"}

package/dist/cli.js

@@ -0,0 +1,73 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CliConfigError = void 0;
+exports.configFromEnv = configFromEnv;
+exports.serverFromEnv = serverFromEnv;
+exports.main = main;
+const stdio_js_1 = require("@modelcontextprotocol/sdk/server/stdio.js");
+const einvoice_js_1 = require("@useyona/einvoice-js");
+const server_1 = require("./server");
+const version_1 = require("./version");
+/** A configuration problem the binary reports and exits on. Its message never contains the key. */
+class CliConfigError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'CliConfigError';
+    }
+}
+exports.CliConfigError = CliConfigError;
+/**
+ * Reads `YONA_API_KEY` (required), `YONA_ALLOW_LIVE` (`true` to allow a live key) and
+ * `YONA_BASE_URL` (an override for testing against another gateway).
+ */
+function configFromEnv(env) {
+    const apiKey = env.YONA_API_KEY?.trim();
+    if (!apiKey) {
+        throw new CliConfigError('YONA_API_KEY is not set. Create an API key in the Yona dashboard (API keys) and pass it in the ' +
+            'environment of this server, e.g. "env": { "YONA_API_KEY": "sk_test_…" } in your MCP client configuration.');
+    }
+    try {
+        (0, einvoice_js_1.modeOfApiKey)(apiKey);
+    }
+    catch (error) {
+        // The SDK's message describes the expected shape and never echoes the key.
+        throw new CliConfigError(`YONA_API_KEY: ${error.message}`);
+    }
+    const allowLive = env.YONA_ALLOW_LIVE === 'true';
+    try {
+        const client = new einvoice_js_1.EInvoice({ apiKey, ...(env.YONA_BASE_URL ? { baseUrl: env.YONA_BASE_URL } : {}) });
+        return { client, allowLive };
+    }
+    catch (error) {
+        if (error instanceof einvoice_js_1.EInvoiceConfigError)
+            throw new CliConfigError(error.message);
+        throw error;
+    }
+}
+/** Builds the server from the environment; throws {@link CliConfigError} for a bad configuration. */
+function serverFromEnv(env) {
+    const { client, allowLive } = configFromEnv(env);
+    try {
+        return { server: (0, server_1.createYonaMcpServer)({ client, allowLive }), mode: client.mode };
+    }
+    catch (error) {
+        if (error instanceof server_1.LiveModeRefusedError)
+            throw new CliConfigError(error.message);
+        throw error;
+    }
+}
+/** The `einvoice-mcp` binary: the server over stdio. Diagnostics go to stderr; stdout is the protocol. */
+async function main(env = process.env) {
+    let built;
+    try {
+        built = serverFromEnv(env);
+    }
+    catch (error) {
+        process.stderr.write(`einvoice-mcp: ${error.message}\n`);
+        process.exitCode = 1;
+        return;
+    }
+    await built.server.connect(new stdio_js_1.StdioServerTransport());
+    process.stderr.write(`einvoice-mcp ${version_1.VERSION}: Yona e-invoicing, ${built.mode} mode, on stdio\n`);
+}
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";;;AAwBA,sCAsBC;AAGD,sCAQC;AAGD,oBAWC;AAvED,wEAA+E;AAC/E,sDAAiF;AAEjF,qCAAmE;AACnE,uCAAkC;AAElC,mGAAmG;AACnG,MAAa,cAAe,SAAQ,KAAK;IACrC,YAAY,OAAe;QACvB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,gBAAgB,CAAC;IACjC,CAAC;CACJ;AALD,wCAKC;AAQD;;;GAGG;AACH,SAAgB,aAAa,CAAC,GAAsB;IAChD,MAAM,MAAM,GAAG,GAAG,CAAC,YAAY,EAAE,IAAI,EAAE,CAAC;IACxC,IAAI,CAAC,MAAM,EAAE,CAAC;QACV,MAAM,IAAI,cAAc,CACpB,iGAAiG;YAC7F,2GAA2G,CAClH,CAAC;IACN,CAAC;IACD,IAAI,CAAC;QACD,IAAA,0BAAY,EAAC,MAAM,CAAC,CAAC;IACzB,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACb,2EAA2E;QAC3E,MAAM,IAAI,cAAc,CAAC,iBAAkB,KAAe,CAAC,OAAO,EAAE,CAAC,CAAC;IAC1E,CAAC;IACD,MAAM,SAAS,GAAG,GAAG,CAAC,eAAe,KAAK,MAAM,CAAC;IACjD,IAAI,CAAC;QACD,MAAM,MAAM,GAAG,IAAI,sBAAQ,CAAC,EAAC,MAAM,EAAE,GAAG,CAAC,GAAG,CAAC,aAAa,CAAC,CAAC,CAAC,EAAC,OAAO,EAAE,GAAG,CAAC,aAAa,EAAC,CAAC,CAAC,CAAC,EAAE,CAAC,EAAC,CAAC,CAAC;QAClG,OAAO,EAAC,MAAM,EAAE,SAAS,EAAC,CAAC;IAC/B,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACb,IAAI,KAAK,YAAY,iCAAmB;YAAE,MAAM,IAAI,cAAc,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;QAClF,MAAM,KAAK,CAAC;IAChB,CAAC;AACL,CAAC;AAED,qGAAqG;AACrG,SAAgB,aAAa,CAAC,GAAsB;IAChD,MAAM,EAAC,MAAM,EAAE,SAAS,EAAC,GAAG,aAAa,CAAC,GAAG,CAAC,CAAC;IAC/C,IAAI,CAAC;QACD,OAAO,EAAC,MAAM,EAAE,IAAA,4BAAmB,EAAC,EAAC,MAAM,EAAE,SAAS,EAAC,CAAC,EAAE,IAAI,EAAE,MAAM,CAAC,IAAI,EAAC,CAAC;IACjF,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACb,IAAI,KAAK,YAAY,6BAAoB;YAAE,MAAM,IAAI,cAAc,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;QACnF,MAAM,KAAK,CAAC;IAChB,CAAC;AACL,CAAC;AAED,0GAA0G;AACnG,KAAK,UAAU,IAAI,CAAC,MAAyB,OAAO,CAAC,GAAG;IAC3D,IAAI,KAAK,CAAC;IACV,IAAI,CAAC;QACD,KAAK,GAAG,aAAa,CAAC,GAAG,CAAC,CAAC;IAC/B,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACb,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,iBAAkB,KAAe,CAAC,OAAO,IAAI,CAAC,CAAC;QACpE,OAAO,CAAC,QAAQ,GAAG,CAAC,CAAC;QACrB,OAAO;IACX,CAAC;IACD,MAAM,KAAK,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,+BAAoB,EAAE,CAAC,CAAC;IACvD,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,gBAAgB,iBAAO,uBAAuB,KAAK,CAAC,IAAI,mBAAmB,CAAC,CAAC;AACtG,CAAC"}

package/dist/http.d.ts

@@ -0,0 +1,16 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import type { YonaMcpServerOptions } from './server';
+/** Options of {@link handleStreamableHttp}. */
+export interface StreamableHttpOptions extends YonaMcpServerOptions {
+    /** The request body when the host framework already parsed it (Express/NestJS `req.body`). */
+    parsedBody?: unknown;
+}
+/**
+ * Answers one MCP request over streamable HTTP, stateless, with JSON responses (no SSE, no
+ * session): a fresh server and transport per request, closed when the response closes. This is
+ * how a host (the hosted Yona MCP service) mounts the server on `POST /mcp`; build `client` per
+ * request with the caller's credentials. GET and DELETE answer 405 (there is no session to stream
+ * or end); a live client without `allowLive` answers 403.
+ */
+export declare function handleStreamableHttp(req: IncomingMessage, res: ServerResponse, options: StreamableHttpOptions): Promise<void>;
+//# sourceMappingURL=http.d.ts.map

package/dist/http.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"http.d.ts","sourceRoot":"","sources":["../src/http.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAC,eAAe,EAAE,cAAc,EAAC,MAAM,WAAW,CAAC;AAG/D,OAAO,KAAK,EAAC,oBAAoB,EAAC,MAAM,UAAU,CAAC;AAEnD,+CAA+C;AAC/C,MAAM,WAAW,qBAAsB,SAAQ,oBAAoB;IAC/D,8FAA8F;IAC9F,UAAU,CAAC,EAAE,OAAO,CAAC;CACxB;AAOD;;;;;;GAMG;AACH,wBAAsB,oBAAoB,CAAC,GAAG,EAAE,eAAe,EAAE,GAAG,EAAE,cAAc,EAAE,OAAO,EAAE,qBAAqB,GAAG,OAAO,CAAC,IAAI,CAAC,CAsBnI"}

package/dist/http.js

@@ -0,0 +1,41 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.handleStreamableHttp = handleStreamableHttp;
+const streamableHttp_js_1 = require("@modelcontextprotocol/sdk/server/streamableHttp.js");
+const server_1 = require("./server");
+function jsonRpcError(res, status, code, message, headers = {}) {
+    res.writeHead(status, { 'content-type': 'application/json', ...headers });
+    res.end(JSON.stringify({ jsonrpc: '2.0', error: { code, message }, id: null }));
+}
+/**
+ * Answers one MCP request over streamable HTTP, stateless, with JSON responses (no SSE, no
+ * session): a fresh server and transport per request, closed when the response closes. This is
+ * how a host (the hosted Yona MCP service) mounts the server on `POST /mcp`; build `client` per
+ * request with the caller's credentials. GET and DELETE answer 405 (there is no session to stream
+ * or end); a live client without `allowLive` answers 403.
+ */
+async function handleStreamableHttp(req, res, options) {
+    if (req.method !== 'POST') {
+        jsonRpcError(res, 405, -32000, 'Method not allowed: this MCP endpoint is stateless and answers POST only.', { allow: 'POST' });
+        return;
+    }
+    let server;
+    try {
+        server = (0, server_1.createYonaMcpServer)({ client: options.client, allowLive: options.allowLive });
+    }
+    catch (error) {
+        if (error instanceof server_1.LiveModeRefusedError) {
+            jsonRpcError(res, 403, -32001, error.message);
+            return;
+        }
+        throw error;
+    }
+    const transport = new streamableHttp_js_1.StreamableHTTPServerTransport({ sessionIdGenerator: undefined, enableJsonResponse: true });
+    res.on('close', () => {
+        void transport.close();
+        void server.close();
+    });
+    await server.connect(transport);
+    await transport.handleRequest(req, res, options.parsedBody);
+}
+//# sourceMappingURL=http.js.map

package/dist/http.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"http.js","sourceRoot":"","sources":["../src/http.ts"],"names":[],"mappings":";;AAuBA,oDAsBC;AA5CD,0FAAiG;AACjG,qCAAmE;AASnE,SAAS,YAAY,CAAC,GAAmB,EAAE,MAAc,EAAE,IAAY,EAAE,OAAe,EAAE,UAAkC,EAAE;IAC1H,GAAG,CAAC,SAAS,CAAC,MAAM,EAAE,EAAC,cAAc,EAAE,kBAAkB,EAAE,GAAG,OAAO,EAAC,CAAC,CAAC;IACxE,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,SAAS,CAAC,EAAC,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,EAAC,IAAI,EAAE,OAAO,EAAC,EAAE,EAAE,EAAE,IAAI,EAAC,CAAC,CAAC,CAAC;AAChF,CAAC;AAED;;;;;;GAMG;AACI,KAAK,UAAU,oBAAoB,CAAC,GAAoB,EAAE,GAAmB,EAAE,OAA8B;IAChH,IAAI,GAAG,CAAC,MAAM,KAAK,MAAM,EAAE,CAAC;QACxB,YAAY,CAAC,GAAG,EAAE,GAAG,EAAE,CAAC,KAAK,EAAE,2EAA2E,EAAE,EAAC,KAAK,EAAE,MAAM,EAAC,CAAC,CAAC;QAC7H,OAAO;IACX,CAAC;IACD,IAAI,MAAM,CAAC;IACX,IAAI,CAAC;QACD,MAAM,GAAG,IAAA,4BAAmB,EAAC,EAAC,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,SAAS,EAAE,OAAO,CAAC,SAAS,EAAC,CAAC,CAAC;IACzF,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACb,IAAI,KAAK,YAAY,6BAAoB,EAAE,CAAC;YACxC,YAAY,CAAC,GAAG,EAAE,GAAG,EAAE,CAAC,KAAK,EAAE,KAAK,CAAC,OAAO,CAAC,CAAC;YAC9C,OAAO;QACX,CAAC;QACD,MAAM,KAAK,CAAC;IAChB,CAAC;IACD,MAAM,SAAS,GAAG,IAAI,iDAA6B,CAAC,EAAC,kBAAkB,EAAE,SAAS,EAAE,kBAAkB,EAAE,IAAI,EAAC,CAAC,CAAC;IAC/G,GAAG,CAAC,EAAE,CAAC,OAAO,EAAE,GAAG,EAAE;QACjB,KAAK,SAAS,CAAC,KAAK,EAAE,CAAC;QACvB,KAAK,MAAM,CAAC,KAAK,EAAE,CAAC;IACxB,CAAC,CAAC,CAAC;IACH,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IAChC,MAAM,SAAS,CAAC,aAAa,CAAC,GAAG,EAAE,GAAG,EAAE,OAAO,CAAC,UAAU,CAAC,CAAC;AAChE,CAAC"}

package/dist/idempotency.d.ts

@@ -0,0 +1,16 @@
+/** What identifies one tool call: the MCP request id and, when the transport has one, the session. */
+export interface CallIdentity {
+    requestId: string | number;
+    sessionId?: string;
+}
+/**
+ * The `Idempotency-Key` of a write, derived from the tool call: the MCP request id (plus the session
+ * id when there is one), the tool name and its arguments. A client that retries the same call (same
+ * request id, same arguments) sends the same key, so the API answers the first result and charges
+ * once. The arguments are part of the key because request ids restart at 1 in every stateless HTTP
+ * request and in every new stdio process: two different calls must never share a key.
+ *
+ * The result is `mcp_` + 40 hex characters, inside the API's `[A-Za-z0-9_-]{8,128}`.
+ */
+export declare function deriveIdempotencyKey(tool: string, call: CallIdentity, args: unknown): string;
+//# sourceMappingURL=idempotency.d.ts.map

package/dist/idempotency.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"idempotency.d.ts","sourceRoot":"","sources":["../src/idempotency.ts"],"names":[],"mappings":"AAEA,sGAAsG;AACtG,MAAM,WAAW,YAAY;IACzB,SAAS,EAAE,MAAM,GAAG,MAAM,CAAC;IAC3B,SAAS,CAAC,EAAE,MAAM,CAAC;CACtB;AAeD;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,YAAY,EAAE,IAAI,EAAE,OAAO,GAAG,MAAM,CAG5F"}

package/dist/idempotency.js

@@ -0,0 +1,31 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.deriveIdempotencyKey = deriveIdempotencyKey;
+const node_crypto_1 = require("node:crypto");
+/** Sorts object keys so equal arguments always serialise the same way. */
+function canonical(value) {
+    if (Array.isArray(value))
+        return value.map(canonical);
+    if (value && typeof value === 'object') {
+        const out = {};
+        for (const key of Object.keys(value).sort()) {
+            out[key] = canonical(value[key]);
+        }
+        return out;
+    }
+    return value;
+}
+/**
+ * The `Idempotency-Key` of a write, derived from the tool call: the MCP request id (plus the session
+ * id when there is one), the tool name and its arguments. A client that retries the same call (same
+ * request id, same arguments) sends the same key, so the API answers the first result and charges
+ * once. The arguments are part of the key because request ids restart at 1 in every stateless HTTP
+ * request and in every new stdio process: two different calls must never share a key.
+ *
+ * The result is `mcp_` + 40 hex characters, inside the API's `[A-Za-z0-9_-]{8,128}`.
+ */
+function deriveIdempotencyKey(tool, call, args) {
+    const material = JSON.stringify([tool, call.sessionId ?? null, String(call.requestId), canonical(args)]);
+    return `mcp_${(0, node_crypto_1.createHash)('sha256').update(material).digest('hex').slice(0, 40)}`;
+}
+//# sourceMappingURL=idempotency.js.map

package/dist/idempotency.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"idempotency.js","sourceRoot":"","sources":["../src/idempotency.ts"],"names":[],"mappings":";;AA8BA,oDAGC;AAjCD,6CAAuC;AAQvC,0EAA0E;AAC1E,SAAS,SAAS,CAAC,KAAc;IAC7B,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;IACtD,IAAI,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QACrC,MAAM,GAAG,GAA4B,EAAE,CAAC;QACxC,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,KAAgC,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC;YACrE,GAAG,CAAC,GAAG,CAAC,GAAG,SAAS,CAAE,KAAiC,CAAC,GAAG,CAAC,CAAC,CAAC;QAClE,CAAC;QACD,OAAO,GAAG,CAAC;IACf,CAAC;IACD,OAAO,KAAK,CAAC;AACjB,CAAC;AAED;;;;;;;;GAQG;AACH,SAAgB,oBAAoB,CAAC,IAAY,EAAE,IAAkB,EAAE,IAAa;IAChF,MAAM,QAAQ,GAAG,IAAI,CAAC,SAAS,CAAC,CAAC,IAAI,EAAE,IAAI,CAAC,SAAS,IAAI,IAAI,EAAE,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IACzG,OAAO,OAAO,IAAA,wBAAU,EAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,EAAE,CAAC;AACrF,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,12 @@
+export { createYonaMcpServer, LiveModeRefusedError } from './server';
+export type { YonaMcpServerOptions } from './server';
+export { handleStreamableHttp } from './http';
+export type { StreamableHttpOptions } from './http';
+export { TOOLS } from './tools';
+export type { ToolDefinition, ToolContext, ToolOutput } from './tools';
+export { RESOURCE_URIS } from './resources';
+export { PROMPT_NAMES } from './prompts';
+export { deriveIdempotencyKey } from './idempotency';
+export { redact } from './result';
+export { VERSION, SERVER_NAME } from './version';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,mBAAmB,EAAE,oBAAoB,EAAC,MAAM,UAAU,CAAC;AACnE,YAAY,EAAC,oBAAoB,EAAC,MAAM,UAAU,CAAC;AACnD,OAAO,EAAC,oBAAoB,EAAC,MAAM,QAAQ,CAAC;AAC5C,YAAY,EAAC,qBAAqB,EAAC,MAAM,QAAQ,CAAC;AAClD,OAAO,EAAC,KAAK,EAAC,MAAM,SAAS,CAAC;AAC9B,YAAY,EAAC,cAAc,EAAE,WAAW,EAAE,UAAU,EAAC,MAAM,SAAS,CAAC;AACrE,OAAO,EAAC,aAAa,EAAC,MAAM,aAAa,CAAC;AAC1C,OAAO,EAAC,YAAY,EAAC,MAAM,WAAW,CAAC;AACvC,OAAO,EAAC,oBAAoB,EAAC,MAAM,eAAe,CAAC;AACnD,OAAO,EAAC,MAAM,EAAC,MAAM,UAAU,CAAC;AAChC,OAAO,EAAC,OAAO,EAAE,WAAW,EAAC,MAAM,WAAW,CAAC"}

package/dist/index.js

@@ -0,0 +1,22 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SERVER_NAME = exports.VERSION = exports.redact = exports.deriveIdempotencyKey = exports.PROMPT_NAMES = exports.RESOURCE_URIS = exports.TOOLS = exports.handleStreamableHttp = exports.LiveModeRefusedError = exports.createYonaMcpServer = void 0;
+var server_1 = require("./server");
+Object.defineProperty(exports, "createYonaMcpServer", { enumerable: true, get: function () { return server_1.createYonaMcpServer; } });
+Object.defineProperty(exports, "LiveModeRefusedError", { enumerable: true, get: function () { return server_1.LiveModeRefusedError; } });
+var http_1 = require("./http");
+Object.defineProperty(exports, "handleStreamableHttp", { enumerable: true, get: function () { return http_1.handleStreamableHttp; } });
+var tools_1 = require("./tools");
+Object.defineProperty(exports, "TOOLS", { enumerable: true, get: function () { return tools_1.TOOLS; } });
+var resources_1 = require("./resources");
+Object.defineProperty(exports, "RESOURCE_URIS", { enumerable: true, get: function () { return resources_1.RESOURCE_URIS; } });
+var prompts_1 = require("./prompts");
+Object.defineProperty(exports, "PROMPT_NAMES", { enumerable: true, get: function () { return prompts_1.PROMPT_NAMES; } });
+var idempotency_1 = require("./idempotency");
+Object.defineProperty(exports, "deriveIdempotencyKey", { enumerable: true, get: function () { return idempotency_1.deriveIdempotencyKey; } });
+var result_1 = require("./result");
+Object.defineProperty(exports, "redact", { enumerable: true, get: function () { return result_1.redact; } });
+var version_1 = require("./version");
+Object.defineProperty(exports, "VERSION", { enumerable: true, get: function () { return version_1.VERSION; } });
+Object.defineProperty(exports, "SERVER_NAME", { enumerable: true, get: function () { return version_1.SERVER_NAME; } });
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;AAAA,mCAAmE;AAA3D,6GAAA,mBAAmB,OAAA;AAAE,8GAAA,oBAAoB,OAAA;AAEjD,+BAA4C;AAApC,4GAAA,oBAAoB,OAAA;AAE5B,iCAA8B;AAAtB,8FAAA,KAAK,OAAA;AAEb,yCAA0C;AAAlC,0GAAA,aAAa,OAAA;AACrB,qCAAuC;AAA/B,uGAAA,YAAY,OAAA;AACpB,6CAAmD;AAA3C,mHAAA,oBAAoB,OAAA;AAC5B,mCAAgC;AAAxB,gGAAA,MAAM,OAAA;AACd,qCAA+C;AAAvC,kGAAA,OAAO,OAAA;AAAE,sGAAA,WAAW,OAAA"}

package/dist/prompts.d.ts

@@ -0,0 +1,5 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { EInvoice } from '@useyona/einvoice-js';
+export declare const PROMPT_NAMES: readonly ["draft_invoice", "explain_rejection"];
+export declare function registerPrompts(server: McpServer, client: EInvoice): void;
+//# sourceMappingURL=prompts.d.ts.map

package/dist/prompts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompts.d.ts","sourceRoot":"","sources":["../src/prompts.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,yCAAyC,CAAC;AACvE,OAAO,KAAK,EAAC,QAAQ,EAAC,MAAM,sBAAsB,CAAC;AAGnD,eAAO,MAAM,YAAY,iDAAkD,CAAC;AAE5E,wBAAgB,eAAe,CAAC,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,QAAQ,GAAG,IAAI,CAyEzE"}

package/dist/prompts.js

@@ -0,0 +1,72 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PROMPT_NAMES = void 0;
+exports.registerPrompts = registerPrompts;
+const zod_1 = require("zod");
+const result_1 = require("./result");
+exports.PROMPT_NAMES = ['draft_invoice', 'explain_rejection'];
+function registerPrompts(server, client) {
+    server.registerPrompt('draft_invoice', {
+        title: 'Draft an invoice',
+        description: 'Turns a plain description ("2 laptops at ₦850,000 each for Acme Ltd") into a validated draft invoice.',
+        argsSchema: { description: zod_1.z.string().describe('What was sold, to whom, for how much.') },
+    }, ({ description }) => ({
+        messages: [
+            {
+                role: 'user',
+                content: {
+                    type: 'text',
+                    text: [
+                        `Draft an e-invoice in Yona (${client.mode} mode) from this description:`,
+                        '',
+                        description,
+                        '',
+                        'Steps:',
+                        '1. Find the buyer with search_buyers. If there is none, ask me before create_buyer (it is charged); use lookup_tin when the tax id is uncertain.',
+                        '2. Find matching items with search_items; otherwise write each line with description, unitCode (yona://reference/units), unitPrice in major units and taxCategory (yona://reference/tax-categories, e.g. STANDARD_VAT).',
+                        '3. Call create_invoice with invoiceKind (B2B, B2C, B2G or G2B), today’s invoiceDate, the currency and the lines. It stays a draft.',
+                        '4. Call validate_invoice with the new invoiceId and fix what it reports with update_invoice.',
+                        '5. Show me the draft (buyer, lines, totals, tax). Do NOT call finalise_invoice or submit_invoice unless I explicitly ask.',
+                    ].join('\n'),
+                },
+            },
+        ],
+    }));
+    server.registerPrompt('explain_rejection', {
+        title: 'Explain a rejection',
+        description: 'Explains in plain words why the tax authority rejected or parked an invoice, and what to do next.',
+        argsSchema: { invoiceId: zod_1.z.string().describe('The invoice id.') },
+    }, async ({ invoiceId }, extra) => {
+        let status;
+        try {
+            status = JSON.stringify((0, result_1.compact)(await client.submissions.getStatus(invoiceId, { signal: extra.signal })), null, 2);
+        }
+        catch (error) {
+            const e = error;
+            status = `(could not read the status: ${e.errorCode ?? ''} ${e.message ?? String(error)}; call get_submission_status)`;
+        }
+        return {
+            messages: [
+                {
+                    role: 'user',
+                    content: {
+                        type: 'text',
+                        text: (0, result_1.redact)([
+                            `Explain in plain words, for a business owner, why invoice ${invoiceId} was not accepted by the tax authority, and what to do next.`,
+                            '',
+                            'Its submission status as Yona last recorded it:',
+                            status,
+                            '',
+                            'Read authorityState, parkReason and the submissions’ errors. Know that:',
+                            '- "parked" means Yona holds the invoice until something outside it changes; the parkReason says what.',
+                            '- A message that the buyer’s access points are offline usually means the BUYER’s tax id is not registered for e-invoicing, not an outage: check the buyer with lookup_tin.',
+                            '- A validation rejection names the field: fix the draft (a reported invoice is corrected with a credit note, never edited).',
+                            'Do not resubmit, cancel or credit anything without my explicit approval.',
+                        ].join('\n')),
+                    },
+                },
+            ],
+        };
+    });
+}
+//# sourceMappingURL=prompts.js.map

package/dist/prompts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompts.js","sourceRoot":"","sources":["../src/prompts.ts"],"names":[],"mappings":";;;AAOA,0CAyEC;AAhFD,6BAAsB;AAGtB,qCAAyC;AAE5B,QAAA,YAAY,GAAG,CAAC,eAAe,EAAE,mBAAmB,CAAU,CAAC;AAE5E,SAAgB,eAAe,CAAC,MAAiB,EAAE,MAAgB;IAC/D,MAAM,CAAC,cAAc,CACjB,eAAe,EACf;QACI,KAAK,EAAE,kBAAkB;QACzB,WAAW,EAAE,uGAAuG;QACpH,UAAU,EAAE,EAAC,WAAW,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,uCAAuC,CAAC,EAAC;KAC1F,EACD,CAAC,EAAC,WAAW,EAAC,EAAE,EAAE,CAAC,CAAC;QAChB,QAAQ,EAAE;YACN;gBACI,IAAI,EAAE,MAAM;gBACZ,OAAO,EAAE;oBACL,IAAI,EAAE,MAAM;oBACZ,IAAI,EAAE;wBACF,+BAA+B,MAAM,CAAC,IAAI,+BAA+B;wBACzE,EAAE;wBACF,WAAW;wBACX,EAAE;wBACF,QAAQ;wBACR,kJAAkJ;wBAClJ,yNAAyN;wBACzN,oIAAoI;wBACpI,8FAA8F;wBAC9F,2HAA2H;qBAC9H,CAAC,IAAI,CAAC,IAAI,CAAC;iBACf;aACJ;SACJ;KACJ,CAAC,CACL,CAAC;IAEF,MAAM,CAAC,cAAc,CACjB,mBAAmB,EACnB;QACI,KAAK,EAAE,qBAAqB;QAC5B,WAAW,EAAE,mGAAmG;QAChH,UAAU,EAAE,EAAC,SAAS,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,iBAAiB,CAAC,EAAC;KAClE,EACD,KAAK,EAAE,EAAC,SAAS,EAAC,EAAE,KAAK,EAAE,EAAE;QACzB,IAAI,MAAc,CAAC;QACnB,IAAI,CAAC;YACD,MAAM,GAAG,IAAI,CAAC,SAAS,CAAC,IAAA,gBAAO,EAAC,MAAM,MAAM,CAAC,WAAW,CAAC,SAAS,CAAC,SAAS,EAAE,EAAC,MAAM,EAAE,KAAK,CAAC,MAAM,EAAC,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC;QACrH,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACb,MAAM,CAAC,GAAG,KAA+C,CAAC;YAC1D,MAAM,GAAG,+BAA+B,CAAC,CAAC,SAAS,IAAI,EAAE,IAAI,CAAC,CAAC,OAAO,IAAI,MAAM,CAAC,KAAK,CAAC,+BAA+B,CAAC;QAC3H,CAAC;QACD,OAAO;YACH,QAAQ,EAAE;gBACN;oBACI,IAAI,EAAE,MAAM;oBACZ,OAAO,EAAE;wBACL,IAAI,EAAE,MAAM;wBACZ,IAAI,EAAE,IAAA,eAAM,EACR;4BACI,6DAA6D,SAAS,8DAA8D;4BACpI,EAAE;4BACF,iDAAiD;4BACjD,MAAM;4BACN,EAAE;4BACF,yEAAyE;4BACzE,uGAAuG;4BACvG,4KAA4K;4BAC5K,6HAA6H;4BAC7H,0EAA0E;yBAC7E,CAAC,IAAI,CAAC,IAAI,CAAC,CACf;qBACJ;iBACJ;aACJ;SACJ,CAAC;IACN,CAAC,CACJ,CAAC;AACN,CAAC"}

package/dist/resources.d.ts

@@ -0,0 +1,16 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { EInvoice } from '@useyona/einvoice-js';
+/** The resource URIs this server serves. */
+export declare const RESOURCE_URIS: {
+    readonly taxCategories: "yona://reference/tax-categories";
+    readonly units: "yona://reference/units";
+    readonly hsCodes: "yona://reference/hs-codes";
+    readonly organization: "yona://organization";
+};
+/** The jurisdiction's code-list type behind each reference resource (`reference.getResource`). */
+export declare const CODE_LIST_OF: {
+    readonly "yona://reference/tax-categories": "tax-categories";
+    readonly "yona://reference/units": "invoice-quantity-codes";
+};
+export declare function registerResources(server: McpServer, client: EInvoice): void;
+//# sourceMappingURL=resources.d.ts.map

package/dist/resources.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resources.d.ts","sourceRoot":"","sources":["../src/resources.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,yCAAyC,CAAC;AAIvE,OAAO,KAAK,EAAC,QAAQ,EAAC,MAAM,sBAAsB,CAAC;AAInD,4CAA4C;AAC5C,eAAO,MAAM,aAAa;;;;;CAKhB,CAAC;AAEX,kGAAkG;AAClG,eAAO,MAAM,YAAY;;;CAGf,CAAC;AAuBX,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,QAAQ,GAAG,IAAI,CAkD3E"}