@dojocoding/hacienda-mcp 0.7.0 → 0.9.0

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # @dojocoding/hacienda-mcp
 
+## 0.9.0
+
+### Minor Changes
+
+- 72a7670: Require positive one-to-five-digit credit days for current exact FE conditions 02/10 and reject any explicitly supplied zero term while preserving valid leading-zero lexemes. Preserve the existing REP-only 09/11 exclusion and additionally reject FEC-only 13 in current exact FE inputs, while preserving other valid FE conditions and historical read-only 13 compatibility. Add an explicitly read-only retained exact FE schema/calculator for independently bound historical 0.6–0.8 source facts; it does not provide an XML builder or grant signing/transport authority. Legacy Number APIs are unchanged. CLI/MCP participate in the coordinated linked release; no new adapter endpoint or fiscal activation is introduced.
+
+### Patch Changes
+
+- Updated dependencies [72a7670]
+  - @dojocoding/hacienda-shared@0.9.0
+  - @dojocoding/hacienda-sdk@0.9.0
+
+## 0.8.0
+
+### Minor Changes
+
+- 813e329: Correct the read-only Hacienda history contract across all four packages. Lists consume metadata arrays, combined domestic party filters and observed 200/206 range headers; details return metadata/references rather than promised XML/status. Reject unsupported date/legacy filters before authentication and propagate SDK request cancellation and MCP history-request signals (preexisting shared MCP bootstrap remains internally time-bounded, not caller-cancelled). Preserve wrapper names and exact identifier strings, with an explicit pre-1.0 minor migration for removed fictional total/status/XML fields. No automatic paging, completeness claim, live Hacienda verification or fiscal mutation changes.
+
+### Patch Changes
+
+- Updated dependencies [813e329]
+  - @dojocoding/hacienda-shared@0.8.0
+  - @dojocoding/hacienda-sdk@0.8.0
+
 ## 0.7.0
 
 ### Patch Changes

package/README.md

@@ -135,21 +135,19 @@ Check the processing status of a document by its 50-digit clave numerica.
 
 ### `list_documents`
 
-List recent electronic documents with optional filters.
+Read one observed metadata page, with strict combined domestic party filters. No status/XML, inferred total, next page or completeness claim.
 
 **Parameters:**
 
-- `limit` -- Max results (1-100, default: 10)
+- `limit` -- Requested size (1–50 SDK cap, default: 50)
 - `offset` -- Pagination offset (default: 0)
-- `emisorIdentificacion` -- Filter by issuer ID (optional)
-- `receptorIdentificacion` -- Filter by receiver ID (optional)
-- `fechaDesde` -- Start date filter, ISO 8601 (optional)
-- `fechaHasta` -- End date filter, ISO 8601 (optional)
+- `emisor` -- Combined domestic issuer type + ID (optional)
+- `receptor` -- Combined domestic receiver type + ID (optional)
 - `profile` -- Saved profile name (default: `"default"`); requires server password environment
 
 ### `get_document`
 
-Get full details of an electronic document by its 50-digit clave numerica.
+Get observed metadata/references by the current 50-character clave. Use `check_status` separately; this tool does not fetch original XML or status.
 
 **Parameters:**
 
@@ -212,3 +210,5 @@ Read the [migration guide](https://github.com/DojoCodingLabs/hacienda-cr/blob/ma
 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.
+
+See the [history contract migration](../../docs/history-contract.md); unsupported keys are rejected before authentication.

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

@@ -278,7 +278,7 @@ import {
   listComprobantes,
   getComprobante
 } from "@dojocoding/hacienda-sdk";
-import { DOCUMENT_TYPE_NAMES } from "@dojocoding/hacienda-shared";
+import { ComprobantesQuerySchema, DOCUMENT_TYPE_NAMES } from "@dojocoding/hacienda-shared";
 
 // src/tools/api-client.ts
 import { createHash as createHash2 } from "crypto";
@@ -340,7 +340,7 @@ function registerCheckStatusTool(server) {
                 `Document Type: ${docTypeName}`,
                 `Taxpayer ID: ${parsed.taxpayerId}`,
                 `Date: ${parsed.dateRaw}`,
-                `Sequence: ${parsed.sequence}`,
+                `Sequence: ${args.clave.slice(31, 41)}`,
                 ``,
                 `Status: ${status.status}`,
                 status.date ? `Response Date: ${status.date}` : null,
@@ -365,66 +365,42 @@ function registerCheckStatusTool(server) {
   );
 }
 function registerListDocumentsTool(server) {
-  server.tool(
+  server.registerTool(
     "list_documents",
-    "List recent electronic documents. Optionally filter by date range, emisor, or receptor. Returns a summary list with clave, date, type, and status. Requires a configured profile (run `hacienda auth login` first).",
-    {
-      limit: z2.number().int().min(1).max(100).default(10).describe("Maximum number of documents to return (1-100, default 10)"),
-      offset: z2.number().int().min(0).default(0).describe("Pagination offset (default 0)"),
-      emisorIdentificacion: z2.string().optional().describe("Filter by issuer identification number"),
-      receptorIdentificacion: z2.string().optional().describe("Filter by receiver identification number"),
-      fechaDesde: z2.string().optional().describe("Filter by start date (ISO 8601)"),
-      fechaHasta: z2.string().optional().describe("Filter by end date (ISO 8601)"),
-      profile: z2.string().default("default").describe('Config profile name (default: "default")')
+    {
+      description: "Read one bounded page of observed Hacienda metadata, optionally filtered by combined domestic emisor/receptor. No date filters, status/XML, inferred totals or complete-history claim.",
+      inputSchema: ComprobantesQuerySchema.extend({
+        profile: z2.string().default("default")
+      }).strict()
     },
-    async (args) => {
+    async ({ profile, ...query }, extra) => {
       try {
-        const httpClient = await createMcpApiClient(args.profile);
-        const result = await listComprobantes(httpClient, {
-          offset: args.offset,
-          limit: args.limit,
-          emisorIdentificacion: args.emisorIdentificacion,
-          receptorIdentificacion: args.receptorIdentificacion,
-          fechaEmisionDesde: args.fechaDesde,
-          fechaEmisionHasta: args.fechaHasta
-        });
-        const lines = [
-          `Document List`,
-          ``,
-          `Total: ${result.totalRegistros} documents`,
-          `Showing: ${result.comprobantes.length} (offset ${result.offset})`,
-          ``
-        ];
-        if (result.comprobantes.length === 0) {
-          lines.push("No documents found matching the criteria.");
-        } else {
-          for (const doc of result.comprobantes) {
-            lines.push(
-              `- ${doc.clave}`,
-              `  Date: ${doc.fechaEmision} | Status: ${doc.estado}`,
-              `  Emisor: ${doc.emisor.numeroIdentificacion}`,
-              ``
-            );
-          }
-        }
+        const params = ComprobantesQuerySchema.parse(query);
+        extra.signal.throwIfAborted();
+        const httpClient = await createMcpApiClient(profile);
+        const result = await listComprobantes(httpClient, params, { signal: extra.signal });
         return {
           content: [
             {
               type: "text",
-              text: lines.join("\n")
+              text: JSON.stringify({
+                kind: "observed-history-page",
+                ...result,
+                coverage: "not-established",
+                statusAndXml: "not-provided-by-history"
+              })
             }
           ]
         };
       } catch (error) {
-        const message = sanitizeLogString2(error instanceof Error ? error.message : String(error));
         return {
+          isError: true,
           content: [
             {
               type: "text",
-              text: `Error listing documents: ${message}`
+              text: `Error listing documents: ${sanitizeLogString2(error instanceof Error ? error.message : String(error))}`
             }
-          ],
-          isError: true
+          ]
         };
       }
     }
@@ -433,50 +409,41 @@ function registerListDocumentsTool(server) {
 function registerGetDocumentTool(server) {
   server.tool(
     "get_document",
-    "Get full details of an electronic document by its 50-digit clave numerica. Returns the document metadata, status, and XML content. Requires a configured profile (run `hacienda auth login` first).",
+    "Get observed document metadata by its current 50-character clave. Returns observed metadata and credit/debit references only, without status or XML. Use check_status separately. Requires a configured profile (run `hacienda auth login` first).",
     {
-      clave: z2.string().length(50).describe("The 50-digit clave numerica of the document to retrieve"),
+      clave: z2.string().length(50).describe("The current 50-character clave of the document metadata to retrieve"),
       profile: z2.string().default("default").describe('Config profile name (default: "default")')
     },
-    async (args) => {
+    async (args, extra) => {
       try {
+        extra.signal.throwIfAborted();
         const parsed = parseClave(args.clave);
         const docTypeName = DOCUMENT_TYPE_NAMES[parsed.documentType] ?? `Unknown (${parsed.documentType})`;
         const httpClient = await createMcpApiClient(args.profile);
-        const doc = await getComprobante(httpClient, args.clave);
-        let xmlContent;
-        if (doc.comprobanteXml) {
-          try {
-            xmlContent = Buffer.from(doc.comprobanteXml, "base64").toString("utf-8");
-          } catch {
-            xmlContent = "(unable to decode XML)";
-          }
-        }
+        const doc = await getComprobante(httpClient, args.clave, { signal: extra.signal });
         return {
           content: [
             {
               type: "text",
               text: [
-                `Document Details`,
+                `Document Metadata`,
                 ``,
                 `Clave: ${doc.clave}`,
                 `Document Type: ${docTypeName}`,
                 `Taxpayer ID: ${parsed.taxpayerId}`,
-                `Emission Date: ${doc.fechaEmision}`,
-                `Status: ${doc.estado}`,
-                doc.fechaRespuesta ? `Response Date: ${doc.fechaRespuesta}` : null,
+                `Document Date: ${doc.fecha}`,
+                "Metadata only; use check_status for a separate status/response observation.",
+                `Credit references: ${JSON.stringify(doc.notasCredito ?? [])}`,
+                `Debit references: ${JSON.stringify(doc.notasDebito ?? [])}`,
                 ``,
                 `Emisor: ${doc.emisor.tipoIdentificacion} ${doc.emisor.numeroIdentificacion}`,
                 doc.receptor ? `Receptor: ${doc.receptor.tipoIdentificacion} ${doc.receptor.numeroIdentificacion}` : null,
                 ``,
                 `Branch: ${parsed.branch}`,
                 `POS: ${parsed.pos}`,
-                `Sequence: ${parsed.sequence}`,
+                `Sequence: ${args.clave.slice(31, 41)}`,
                 `Situation: ${parsed.situation}`,
-                `Security Code: ${parsed.securityCode}`,
-                xmlContent ? `
---- XML ---
-${xmlContent}` : null
+                `Security Code: ${parsed.securityCode}`
               ].filter(Boolean).join("\n")
             }
           ]

package/dist/cli.js

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

package/dist/index.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dojocoding/hacienda-mcp",
-  "version": "0.7.0",
+  "version": "0.9.0",
   "description": "MCP Server for Costa Rica electronic invoicing (AI-accessible tools)",
   "type": "module",
   "main": "./dist/index.js",
@@ -28,8 +28,8 @@
     "model-context-protocol"
   ],
   "dependencies": {
-    "@dojocoding/hacienda-sdk": "0.7.0",
-    "@dojocoding/hacienda-shared": "0.7.0",
+    "@dojocoding/hacienda-sdk": "0.9.0",
+    "@dojocoding/hacienda-shared": "0.9.0",
     "@modelcontextprotocol/sdk": "^1.32.0",
     "xmllint-wasm": "^5.3.0",
     "zod": "^4.6.5"