@dojocoding/hacienda-mcp 0.3.0 → 0.4.1

package/CHANGELOG.md

@@ -0,0 +1,85 @@
+# @dojocoding/hacienda-mcp
+
+## 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.
+- Report the package manifest version in CLI/MCP metadata instead of a hardcoded version.
+
+### Minor Changes
+
+- eaf7cff: Validate XML offline against the vendored Hacienda v4.4 schemas before submission.
+  Fix discount totals, reconcile summaries with detail, serialize sequence resets
+  and increments, and enforce concurrent API rate limits. Return nonzero CLI exit
+  codes for rejected submissions. MCP invoice creation requires the actual system
+  provider ID and validates generated documents; its JSON schema resource now
+  reflects the tool input schema.
+- 4e89886: Harden cancellation, submission deadlines, response/XML limits, certificate
+  readiness, secret-safe diagnostics and retry semantics. Fix standalone MCP ESM
+  startup and validate inputs before sequence allocation. Update security-sensitive
+  dependencies and add hostile-input, cryptographic, local HTTP lifecycle,
+  multiprocess sequence and installed-package regression suites.
+
+  Submission timeout now covers POST and polling; POST/PATCH are not automatically
+  retried. HTTP requests default to a 30-second deadline and reject redirects.
+  See docs/security-hardening.md for input caps and remaining trust boundaries.
+
+### Patch Changes
+
+- Updated dependencies [eaf7cff]
+- Updated dependencies [4e89886]
+  - @dojocoding/hacienda-sdk@0.4.0
+  - @dojocoding/hacienda-shared@0.4.0
+
+## 0.3.0
+
+### Minor Changes (BREAKING — pre-1.0)
+
+- `create_invoice` and `draft_invoice` tools and the `factura-schema` resource now speak the v4.4 contract (`proveedorSistemas`, `codigoActividadEmisor`, required emisor `ubicacion`, single `medioPago` code emitted inside `ResumenFactura`, `codigoTarifaIVA`, `codigoDescuento`, ID types 05/06). `unidadMedida` is validated against the official catalog and location fields enforce the v4.4 bounds.
+
+### Patch Changes
+
+- Updated dependencies
+  - @dojocoding/hacienda-sdk@0.3.0
+  - @dojocoding/hacienda-shared@0.3.0
+
+## 0.2.0
+
+### Minor Changes
+
+- Rename npm scope from `@hacienda-cr` to `@dojocoding` for DojoCoding ecosystem branding. All packages now published under the `@dojocoding` org. No API changes.
+
+### Patch Changes
+
+- Updated dependencies
+  - @dojocoding/hacienda-shared@0.2.0
+  - @dojocoding/hacienda-sdk@0.2.0
+
+## 0.1.0
+
+### Minor Changes
+
+- Initial public release of hacienda-cr — TypeScript SDK, CLI, and MCP Server for Costa Rica electronic invoicing (Hacienda API v4.4).
+
+  **@dojocoding/hacienda-shared** — Shared types, Zod schemas, and constants for all 7 document types, tax codes, and identification types.
+
+  **@dojocoding/hacienda-sdk** — Core SDK with OAuth2 authentication, 50-digit clave generation/parsing, XML builder, XAdES-EPES digital signing, API client with submission/polling, and document builders for all 7 electronic document types.
+
+  **@dojocoding/hacienda-cli** — `hacienda` CLI binary for login, invoice drafting, validation, signing, submission, status checking, and document listing.
+
+  **@dojocoding/hacienda-mcp** — MCP Server exposing invoice creation, status checking, document retrieval, taxpayer lookup, and reference data as AI-accessible tools and resources.
+
+### Patch Changes
+
+- Updated dependencies
+  - @dojocoding/hacienda-shared@0.1.0
+  - @dojocoding/hacienda-sdk@0.1.0

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` -- Invoicing-system provider ID (optional, defaults to the emisor ID)
+- `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,4 +197,10 @@ Generate a draft invoice template with sensible defaults. Returns JSON that can
 
 ## Full Documentation
 
-See the [root README](../../README.md) 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.