@dojocoding/hacienda-mcp 0.4.0 → 0.4.2

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # @dojocoding/hacienda-mcp
 
+## 0.4.2
+
+### Patch Changes
+
+- b6b25b4: Correct shared fiscal document codes, preserve current official schema provenance, enforce document identity and tax consistency, and use Costa Rica calendar dates in claves. Scope MCP invoice numbering by issuer/environment and invalidate authenticated clients after profile or credential changes. Preserve existing HTTP cancellation and redirect protections, make token deadlines configurable, disable mutation replays by default, and redact diagnostic secrets. Add regression coverage and document actual sandbox reception failures separately from offline test success. Live acceptance of all document families remains a release gate.
+- Updated dependencies [b6b25b4]
+  - @dojocoding/hacienda-sdk@0.4.2
+  - @dojocoding/hacienda-shared@0.4.2
+
+## 0.4.1
+
+### Patch Changes
+
+- Updated dependencies
+- Updated dependencies [7c800ab]
+- Updated dependencies [682bce8]
+  - @dojocoding/hacienda-shared@0.4.1
+  - @dojocoding/hacienda-sdk@0.4.1
+
 ## 0.4.0
 
 - Declare Node.js 22+ and public package metadata; verify installed TypeScript consumers and ship corrected upgrade documentation.

package/README.md

@@ -65,23 +65,65 @@ const transport = new StdioServerTransport();
 await server.connect(transport);
 ```
 
+## Authentication and document lifecycle
+
+`lookup_taxpayer`, `draft_invoice`, and `create_invoice` do not need IDP
+authentication. `draft_invoice` produces a template with provider and issuer
+location placeholders. Complete these and review the activity, CABYS, taxes,
+and customer before passing it to `create_invoice`.
+
+`create_invoice` returns **unsigned XML**, its clave, and calculated totals. It
+does not sign or submit to Hacienda. It increments the default local sequence
+store for document type `01`, branch `001`, POS `00001`; the counter does not
+separate issuers or environments. Save the returned XML and clave before
+handing them to your backend for validation, signing, submission, and status
+tracking. Repeating `create_invoice` allocates a new number and clave.
+
+`check_status`, `list_documents`, and `get_document` need a saved profile and
+`HACIENDA_PASSWORD` in the **MCP server process**. First create the profile with
+the CLI (using the corresponding password in its environment):
+
+```bash
+hacienda auth login --cedula-type 02 --cedula 3101234567 \
+  --environment sandbox --profile sandbox
+```
+
+Replace the identification with your issuer's. Select `profile: "sandbox"`
+when calling these tools; all three default to `"default"`. A desktop client's
+server may not inherit your terminal's environment. Use your client's secret
+or environment configuration to supply `HACIENDA_PASSWORD` to the server. The
+password is not stored by `auth login`; saving a profile alone is insufficient.
+Restart the server after updating profiles or credentials because authenticated
+clients are cached by profile name.
+
+For a complete SDK handoff, see the [sandbox walkthrough](https://github.com/DojoCodingLabs/hacienda-cr/blob/main/docs/sandbox-guide.md#usar-la-cli-o-mcp-en-el-mismo-flujo).
+For multiple companies or application instances, see the
+[production integration guide](https://github.com/DojoCodingLabs/hacienda-cr/blob/main/docs/production-integration.md).
+
 ## Tools
 
 ### `create_invoice`
 
-Create a Factura Electronica (electronic invoice). Accepts emisor, receptor, and line items. Automatically computes taxes, totals, generates the clave numerica, and builds the XML.
+Create a Factura Electronica (electronic invoice). Automatically computes taxes,
+totals, generates the clave numerica, validates input and XSD, and returns
+unsigned XML. Local validation does not imply Hacienda acceptance.
 
 **Parameters:**
 
-- `emisor` -- Issuer information (name, ID, email)
+- `proveedorSistemas` -- Required identification of the invoicing system provider (9–12 digits)
+- `emisor` -- Issuer information: name, ID, email, and required `ubicacion` with `provincia`, `canton`, `distrito`, `otrasSenas`; optional `nombreComercial`
 - `receptor` -- Receiver information (name, optional ID, optional email)
-- `codigoActividadEmisor` -- Issuer economic activity code (6 digits)
-- `proveedorSistemas` -- Actual invoicing-system provider ID (required; no issuer fallback)
+- `codigoActividadEmisor` -- Issuer economic activity code (6 digits), distinct from each item's 13-digit CABYS code
 - `condicionVenta` -- Sale condition code (default: `"01"` = cash)
-- `medioPago` -- Payment method code (default: `"01"` = cash; emitted inside ResumenFactura per v4.4)
-- `lineItems` -- Array of line items with CABYS code, quantity, unit, description, price, and optional tax/discount
+- `medioPago` -- Single payment-method string (default: `"01"` = cash); emitted with its amount inside `ResumenFactura`
+- `lineItems` -- Array of 1–1000 items with `codigoCabys`, `cantidad`, `unidadMedida`, `detalle`, `precioUnitario`, optional `impuesto` (up to 10), `descuento` (up to 5), and `esServicio` (defaults to `false`; set `true` for services)
 - `plazoCredito` -- Credit term in days (optional)
 
+`plazoCredito` is a string and is required for credit sales (`condicionVenta: "02"`).
+Tax inputs contain `codigo`, `tarifa`, and optional `codigoTarifaIVA`; discount
+inputs contain `montoDescuento`, `naturalezaDescuento`, and `codigoDescuento` (defaults to `"01"`). The tool calculates
+the resulting amounts.
+
 ### `check_status`
 
 Check the processing status of a document by its 50-digit clave numerica.
@@ -89,6 +131,7 @@ Check the processing status of a document by its 50-digit clave numerica.
 **Parameters:**
 
 - `clave` -- The 50-digit clave numerica
+- `profile` -- Saved profile name (default: `"default"`); requires server password environment
 
 ### `list_documents`
 
@@ -102,6 +145,7 @@ List recent electronic documents with optional filters.
 - `receptorIdentificacion` -- Filter by receiver ID (optional)
 - `fechaDesde` -- Start date filter, ISO 8601 (optional)
 - `fechaHasta` -- End date filter, ISO 8601 (optional)
+- `profile` -- Saved profile name (default: `"default"`); requires server password environment
 
 ### `get_document`
 
@@ -110,6 +154,7 @@ Get full details of an electronic document by its 50-digit clave numerica.
 **Parameters:**
 
 - `clave` -- The 50-digit clave numerica
+- `profile` -- Saved profile name (default: `"default"`); requires server password environment
 
 ### `lookup_taxpayer`
 
@@ -121,7 +166,10 @@ Look up a Costa Rica taxpayer by identification number (cedula). Returns name, I
 
 ### `draft_invoice`
 
-Generate a draft invoice template with sensible defaults. Returns JSON that can be passed to `create_invoice`.
+Generate a draft invoice template. Fill in `proveedorSistemas` and issuer
+location placeholders, review the default CABYS/activity and tax inputs, then
+pass the completed JSON to `create_invoice`. It is not the full invoice JSON
+accepted by CLI `submit`.
 
 **Parameters:**
 
@@ -149,8 +197,18 @@ Generate a draft invoice template with sensible defaults. Returns JSON that can
 
 ## Full Documentation
 
-See the [root README](https://github.com/DojoCodingLabs/hacienda-cr#readme) for comprehensive documentation with examples.
+See the [MCP reference](https://github.com/DojoCodingLabs/hacienda-cr/blob/main/docs/reference.md#mcp-server--integración-con-ia),
+[sandbox walkthrough](https://github.com/DojoCodingLabs/hacienda-cr/blob/main/docs/sandbox-guide.md), and
+[production integration guide](https://github.com/DojoCodingLabs/hacienda-cr/blob/main/docs/production-integration.md).
 
 ## Migrating to 0.4.0
 
 Read the [migration guide](https://github.com/DojoCodingLabs/hacienda-cr/blob/main/packages/sdk/MIGRATION-v4.4.md) before upgrading.
+
+### Issuer numbering and credential rotation
+
+`create_invoice` accepts `environment` (defaults to `sandbox`) and stores local counters under `issuer-sequences/<environment>/<sha256 identity>/sequences.json` in the configuration directory. The digest covers environment, identification type and identification number. Branch, terminal and document type remain separate counters within that file. This is local-process/file coordination, not a distributed transactional counter.
+
+If an old global `sequences.json` contains positive counters, creating a new unseeded issuer series fails closed. Stop writers, back up the old file, establish the issuer/environment that owns each series, and seed each corresponding scoped file with the last reserved number before resuming. Do not copy a mixed-company global file blindly, delete counters, or restart a production series at one. There is no automatic migration because the old file does not identify its owner.
+
+Authenticated clients are invalidated when the resolved profile, environment, issuer configuration, certificate path, password or PIN changes. Replacing certificate bytes at the same path still requires restarting the process or clearing the cache. Configure one profile per identity/environment.

package/dist/{chunk-Q2UJO3PQ.js → chunk-A5SYNMZP.js}

@@ -2,6 +2,36 @@
 import { readFileSync } from "fs";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 
+// src/tools/issuer-sequence.ts
+import { createHash } from "crypto";
+import { readFile, access } from "fs/promises";
+import { join } from "path";
+import { getConfigDir, getNextSequence } from "@dojocoding/hacienda-sdk";
+function issuerSequenceDirectory(environment, idType, idNumber, configDir) {
+  const identity = createHash("sha256").update(JSON.stringify([environment, idType, idNumber])).digest("hex");
+  return join(getConfigDir(configDir), "issuer-sequences", environment, identity);
+}
+async function nextIssuerSequence(environment, idType, idNumber, documentType, branch, pos, configDir) {
+  const destination = issuerSequenceDirectory(environment, idType, idNumber, configDir);
+  try {
+    const legacy = JSON.parse(
+      await readFile(join(getConfigDir(configDir), "sequences.json"), "utf8")
+    );
+    if (legacy && typeof legacy === "object" && Object.values(legacy).some((v) => typeof v === "number" && v > 0)) {
+      try {
+        await access(join(destination, "sequences.json"));
+      } catch {
+        throw new Error(
+          "Legacy numbering exists. Migrate and seed the issuer/environment series before creating a document."
+        );
+      }
+    }
+  } catch (error) {
+    if (!(error instanceof Error && "code" in error && error.code === "ENOENT")) throw error;
+  }
+  return getNextSequence(documentType, branch, pos, { configDir: destination });
+}
+
 // src/tools/create-invoice.ts
 import { z } from "zod";
 import {
@@ -13,7 +43,7 @@ import {
   Situation,
   calculateLineItemTotals,
   calculateInvoiceSummary,
-  getNextSequence,
+  sanitizeLogString,
   DEFAULT_BRANCH,
   DEFAULT_POS
 } from "@dojocoding/hacienda-sdk";
@@ -62,6 +92,7 @@ var ReceptorInputSchema = z.object({
   correoElectronico: z.string().optional().describe("Email address")
 });
 var CreateInvoiceInputSchema = z.object({
+  environment: z.enum(["sandbox", "production"]).default("sandbox"),
   emisor: EmisorInputSchema.describe("Invoice issuer (emisor)"),
   receptor: ReceptorInputSchema.describe("Invoice receiver (receptor)"),
   proveedorSistemas: z.string().regex(/^\d{9,12}$/).describe("Actual invoicing-system provider identification number (ProveedorSistemas)"),
@@ -78,6 +109,7 @@ function registerCreateInvoiceTool(server) {
     "create_invoice",
     "Create a Factura Electronica (electronic invoice) for Costa Rica. Accepts emisor, receptor, and line items. Automatically computes taxes, totals, generates the clave numerica, and builds the XML. Returns the unsigned XML string.",
     {
+      environment: CreateInvoiceInputSchema.shape.environment,
       emisor: EmisorInputSchema,
       receptor: ReceptorInputSchema,
       proveedorSistemas: CreateInvoiceInputSchema.shape.proveedorSistemas,
@@ -183,7 +215,14 @@ function registerCreateInvoiceTool(server) {
         let xml = buildFacturaXml(factura);
         const xmlValidation = await validateDocumentXml(xml);
         if (!xmlValidation.valid) throw new Error(xmlValidation.issues.join("; "));
-        const allocatedSequence = await getNextSequence(docTypeCode, branch, pos);
+        const allocatedSequence = await nextIssuerSequence(
+          args.environment,
+          args.emisor.identificacion.tipo,
+          taxpayerId,
+          docTypeCode,
+          branch,
+          pos
+        );
         clave = buildClave({
           date: now,
           taxpayerId,
@@ -214,7 +253,7 @@ function registerCreateInvoiceTool(server) {
           ]
         };
       } catch (error) {
-        const message = error instanceof Error ? error.message : String(error);
+        const message = sanitizeLogString(error instanceof Error ? error.message : String(error));
         return {
           content: [
             {
@@ -230,6 +269,7 @@ function registerCreateInvoiceTool(server) {
 }
 
 // src/tools/document-tools.ts
+import { sanitizeLogString as sanitizeLogString2 } from "@dojocoding/hacienda-sdk";
 import { z as z2 } from "zod";
 import {
   parseClave,
@@ -241,17 +281,33 @@ import {
 import { DOCUMENT_TYPE_NAMES } from "@dojocoding/hacienda-shared";
 
 // src/tools/api-client.ts
-import { bootstrapClient } from "@dojocoding/hacienda-sdk";
+import { createHash as createHash2 } from "crypto";
+import { bootstrapClient, loadConfig } from "@dojocoding/hacienda-sdk";
 var clientCache = /* @__PURE__ */ new Map();
-async function createMcpApiClient(profileName) {
-  const key = profileName ?? "default";
-  const cached = clientCache.get(key);
-  if (cached) {
-    return cached;
-  }
-  const { httpClient } = await bootstrapClient({ profileName: key });
-  clientCache.set(key, httpClient);
-  return httpClient;
+function fingerprint(config) {
+  return createHash2("sha256").update(JSON.stringify([config.profileName, config.profile, config.password, config.p12Pin])).digest("hex");
+}
+async function createMcpApiClient(profileName = "default") {
+  const env = {
+    HACIENDA_USERNAME: process.env.HACIENDA_USERNAME,
+    HACIENDA_PASSWORD: process.env.HACIENDA_PASSWORD,
+    HACIENDA_P12_PIN: process.env.HACIENDA_P12_PIN
+  };
+  const config = await loadConfig(profileName, { env });
+  const identity = fingerprint(config);
+  const cached = clientCache.get(profileName);
+  if (cached?.fingerprint === identity) return cached.promise;
+  const promise = bootstrapClient({ profileName, configOptions: { env } }).then(({ httpClient, config: authenticatedConfig }) => {
+    if (clientCache.get(profileName) === entry)
+      entry.fingerprint = fingerprint(authenticatedConfig);
+    return httpClient;
+  }).catch((error) => {
+    if (clientCache.get(profileName) === entry) clientCache.delete(profileName);
+    throw error;
+  });
+  const entry = { fingerprint: identity, promise };
+  clientCache.set(profileName, entry);
+  return entry.promise;
 }
 
 // src/tools/document-tools.ts
@@ -294,7 +350,7 @@ function registerCheckStatusTool(server) {
           ]
         };
       } catch (error) {
-        const message = error instanceof Error ? error.message : String(error);
+        const message = sanitizeLogString2(error instanceof Error ? error.message : String(error));
         return {
           content: [
             {
@@ -360,7 +416,7 @@ function registerListDocumentsTool(server) {
           ]
         };
       } catch (error) {
-        const message = error instanceof Error ? error.message : String(error);
+        const message = sanitizeLogString2(error instanceof Error ? error.message : String(error));
         return {
           content: [
             {
@@ -426,7 +482,7 @@ ${xmlContent}` : null
           ]
         };
       } catch (error) {
-        const message = error instanceof Error ? error.message : String(error);
+        const message = sanitizeLogString2(error instanceof Error ? error.message : String(error));
         return {
           content: [
             {
@@ -443,7 +499,7 @@ ${xmlContent}` : null
 
 // src/tools/lookup-tools.ts
 import { z as z3 } from "zod";
-import { lookupTaxpayer } from "@dojocoding/hacienda-sdk";
+import { lookupTaxpayer, sanitizeLogString as sanitizeLogString3 } from "@dojocoding/hacienda-sdk";
 import { IDENTIFICATION_TYPE_NAMES } from "@dojocoding/hacienda-shared";
 function registerLookupTaxpayerTool(server) {
   server.tool(
@@ -474,7 +530,7 @@ function registerLookupTaxpayerTool(server) {
           ]
         };
       } catch (error) {
-        const message = error instanceof Error ? error.message : String(error);
+        const message = sanitizeLogString3(error instanceof Error ? error.message : String(error));
         return {
           content: [
             {

package/dist/cli.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import {
   createServer
-} from "./chunk-Q2UJO3PQ.js";
+} from "./chunk-A5SYNMZP.js";
 
 // src/cli.ts
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";

package/dist/index.js

@@ -1,6 +1,6 @@
 import {
   createServer
-} from "./chunk-Q2UJO3PQ.js";
+} from "./chunk-A5SYNMZP.js";
 
 // src/index.ts
 var PACKAGE_NAME = "@dojocoding/hacienda-mcp";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dojocoding/hacienda-mcp",
-  "version": "0.4.0",
+  "version": "0.4.2",
   "description": "MCP Server for Costa Rica electronic invoicing (AI-accessible tools)",
   "type": "module",
   "main": "./dist/index.js",
@@ -28,11 +28,11 @@
     "model-context-protocol"
   ],
   "dependencies": {
+    "@dojocoding/hacienda-sdk": "0.4.2",
+    "@dojocoding/hacienda-shared": "0.4.2",
     "@modelcontextprotocol/sdk": "^1.32.0",
     "xmllint-wasm": "^5.3.0",
-    "zod": "^4.6.5",
-    "@dojocoding/hacienda-sdk": "0.4.0",
-    "@dojocoding/hacienda-shared": "0.4.0"
+    "zod": "^4.6.5"
   },
   "license": "MIT",
   "author": "Dojo Coding Labs <dev@dojocoding.io> (https://dojocoding.io)",
@@ -57,4 +57,4 @@
     "test:watch": "vitest",
     "test:coverage": "vitest run --coverage"
   }
-}
+}