@iflow-mcp/dojocodinglabs-hacienda-cr 0.2.0

package/README.md

@@ -0,0 +1,151 @@
+# @dojocoding/hacienda-mcp
+
+MCP (Model Context Protocol) Server for Costa Rica electronic invoicing (Hacienda API v4.4).
+
+Exposes the `@dojocoding/hacienda-sdk` as AI-accessible tools and resources via the Model Context Protocol, allowing AI assistants like Claude Desktop to create invoices, check document status, and look up taxpayer information.
+
+## Installation
+
+```bash
+npm install -g @dojocoding/hacienda-mcp
+```
+
+Requires **Node.js 22+**.
+
+## Setup
+
+### Claude Desktop
+
+Add this to your Claude Desktop configuration file:
+
+**macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
+**Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
+
+```json
+{
+  "mcpServers": {
+    "hacienda-cr": {
+      "command": "npx",
+      "args": ["-y", "@dojocoding/hacienda-mcp"]
+    }
+  }
+}
+```
+
+Or if installed globally:
+
+```json
+{
+  "mcpServers": {
+    "hacienda-cr": {
+      "command": "hacienda-mcp"
+    }
+  }
+}
+```
+
+### Other MCP Clients
+
+The server uses stdio transport. Start it with:
+
+```bash
+npx @dojocoding/hacienda-mcp
+# or
+hacienda-mcp
+```
+
+### Programmatic Usage
+
+```ts
+import { createServer } from "@dojocoding/hacienda-mcp";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+
+const server = createServer();
+const transport = new StdioServerTransport();
+await server.connect(transport);
+```
+
+## 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.
+
+**Parameters:**
+
+- `emisor` -- Issuer information (name, ID, email)
+- `receptor` -- Receiver information (name, optional ID, optional email)
+- `codigoActividad` -- CABYS activity code (6 digits)
+- `condicionVenta` -- Sale condition code (default: `"01"` = cash)
+- `medioPago` -- Payment methods array (default: `["01"]` = cash)
+- `lineItems` -- Array of line items with CABYS code, quantity, unit, description, price, and optional tax/discount
+- `plazoCredito` -- Credit term in days (optional)
+
+### `check_status`
+
+Check the processing status of a document by its 50-digit clave numerica.
+
+**Parameters:**
+
+- `clave` -- The 50-digit clave numerica
+
+### `list_documents`
+
+List recent electronic documents with optional filters.
+
+**Parameters:**
+
+- `limit` -- Max results (1-100, default: 10)
+- `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)
+
+### `get_document`
+
+Get full details of an electronic document by its 50-digit clave numerica.
+
+**Parameters:**
+
+- `clave` -- The 50-digit clave numerica
+
+### `lookup_taxpayer`
+
+Look up a Costa Rica taxpayer by identification number (cedula). Returns name, ID type, and registered economic activities.
+
+**Parameters:**
+
+- `identificacion` -- Taxpayer ID number (9-12 digits)
+
+### `draft_invoice`
+
+Generate a draft invoice template with sensible defaults. Returns JSON that can be passed to `create_invoice`.
+
+**Parameters:**
+
+- `emisorNombre` -- Issuer name
+- `emisorIdTipo` -- Issuer ID type (default: `"02"`)
+- `emisorIdNumero` -- Issuer ID number
+- `emisorEmail` -- Issuer email
+- `receptorNombre` -- Receiver name
+- `receptorIdTipo` -- Receiver ID type (optional)
+- `receptorIdNumero` -- Receiver ID number (optional)
+- `receptorEmail` -- Receiver email (optional)
+- `codigoActividad` -- Activity code (default: `"620100"`)
+- `description` -- Default line item description (default: `"Servicio profesional"`)
+- `amount` -- Default line item amount (default: `0`)
+- `includeIva` -- Include 13% IVA (default: `true`)
+
+## Resources
+
+| URI                                   | Description                                |
+| ------------------------------------- | ------------------------------------------ |
+| `hacienda://schemas/factura`          | JSON schema for invoice creation input     |
+| `hacienda://reference/document-types` | Document types, codes, and descriptions    |
+| `hacienda://reference/tax-codes`      | Tax codes, IVA rates, and units of measure |
+| `hacienda://reference/id-types`       | Identification types and validation rules  |
+
+## Full Documentation
+
+See the [root README](../../README.md) for comprehensive documentation with examples.

package/dist/chunk-YJYSROUZ.js

@@ -0,0 +1,1080 @@
+// src/server.ts
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+
+// src/tools/create-invoice.ts
+import { z } from "zod";
+import {
+  buildFacturaXml,
+  buildClave,
+  DocumentType,
+  Situation,
+  calculateLineItemTotals,
+  calculateInvoiceSummary,
+  getNextSequence,
+  DEFAULT_BRANCH,
+  DEFAULT_POS
+} from "@dojocoding/hacienda-sdk";
+var ImpuestoInputSchema = z.object({
+  codigo: z.string().describe('Tax type code (e.g. "01" for IVA)'),
+  codigoTarifa: z.string().optional().describe('IVA rate code (e.g. "08" for 13%)'),
+  tarifa: z.number().describe("Tax rate percentage (e.g. 13 for 13%)")
+});
+var DescuentoInputSchema = z.object({
+  montoDescuento: z.number().positive().describe("Discount amount"),
+  naturalezaDescuento: z.string().describe("Reason for discount")
+});
+var LineItemInputSchema = z.object({
+  codigoCabys: z.string().describe("CABYS code (13 digits)"),
+  cantidad: z.number().positive().describe("Quantity"),
+  unidadMedida: z.string().describe('Unit of measure (e.g. "Unid", "Sp", "kg")'),
+  detalle: z.string().describe("Item description (max 200 chars)"),
+  precioUnitario: z.number().min(0).describe("Unit price before taxes"),
+  esServicio: z.boolean().optional().describe("Whether this is a service (true) or merchandise (false). Defaults to false"),
+  impuesto: z.array(ImpuestoInputSchema).optional().describe("Taxes to apply to this line item"),
+  descuento: z.array(DescuentoInputSchema).optional().describe("Discounts for this line item")
+});
+var IdentificacionInputSchema = z.object({
+  tipo: z.string().describe('ID type: "01"=Fisica, "02"=Juridica, "03"=DIMEX, "04"=NITE'),
+  numero: z.string().describe("ID number (digits only)")
+});
+var EmisorInputSchema = z.object({
+  nombre: z.string().describe("Issuer name (max 100 chars)"),
+  identificacion: IdentificacionInputSchema.describe("Taxpayer identification"),
+  nombreComercial: z.string().optional().describe("Commercial name"),
+  correoElectronico: z.string().describe("Email address")
+});
+var ReceptorInputSchema = z.object({
+  nombre: z.string().describe("Receiver name (max 100 chars)"),
+  identificacion: IdentificacionInputSchema.optional().describe("Taxpayer identification"),
+  correoElectronico: z.string().optional().describe("Email address")
+});
+var CreateInvoiceInputSchema = z.object({
+  emisor: EmisorInputSchema.describe("Invoice issuer (emisor)"),
+  receptor: ReceptorInputSchema.describe("Invoice receiver (receptor)"),
+  codigoActividad: z.string().describe("CABYS activity code (6 digits)"),
+  condicionVenta: z.string().default("01").describe('Sale condition code: "01"=Cash, "02"=Credit, etc. Defaults to "01"'),
+  medioPago: z.array(z.string()).default(["01"]).describe('Payment methods: ["01"]=Cash, ["02"]=Card, etc. Defaults to ["01"]'),
+  lineItems: z.array(LineItemInputSchema).min(1).describe("Invoice line items (at least one required)"),
+  plazoCredito: z.string().optional().describe("Credit term in days (required when condicionVenta is 02)")
+});
+function registerCreateInvoiceTool(server) {
+  server.tool(
+    "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.",
+    {
+      emisor: EmisorInputSchema,
+      receptor: ReceptorInputSchema,
+      codigoActividad: CreateInvoiceInputSchema.shape.codigoActividad,
+      condicionVenta: CreateInvoiceInputSchema.shape.condicionVenta,
+      medioPago: CreateInvoiceInputSchema.shape.medioPago,
+      lineItems: CreateInvoiceInputSchema.shape.lineItems,
+      plazoCredito: CreateInvoiceInputSchema.shape.plazoCredito
+    },
+    async (args) => {
+      try {
+        const lineItemInputs = args.lineItems.map((item, index) => ({
+          numeroLinea: index + 1,
+          codigoCabys: item.codigoCabys,
+          cantidad: item.cantidad,
+          unidadMedida: item.unidadMedida,
+          detalle: item.detalle,
+          precioUnitario: item.precioUnitario,
+          esServicio: item.esServicio ?? false,
+          impuesto: item.impuesto,
+          descuento: item.descuento
+        }));
+        const calculatedItems = lineItemInputs.map(calculateLineItemTotals);
+        const summary = calculateInvoiceSummary(calculatedItems);
+        const now = /* @__PURE__ */ new Date();
+        const taxpayerId = args.emisor.identificacion.numero;
+        const docTypeCode = "01";
+        const branch = DEFAULT_BRANCH;
+        const pos = DEFAULT_POS;
+        const sequence = await getNextSequence(docTypeCode, branch, pos);
+        const clave = buildClave({
+          date: now,
+          taxpayerId,
+          documentType: DocumentType.FACTURA_ELECTRONICA,
+          sequence,
+          situation: Situation.NORMAL
+        });
+        const seq = String(sequence).padStart(10, "0");
+        const numeroConsecutivo = `${branch}${pos}${docTypeCode}${seq}`;
+        const fechaEmision = now.toISOString();
+        const detalleServicio = calculatedItems.map((item) => ({
+          ...item,
+          unidadMedida: item.unidadMedida
+        }));
+        const factura = {
+          clave,
+          codigoActividad: args.codigoActividad,
+          numeroConsecutivo,
+          fechaEmision,
+          emisor: {
+            nombre: args.emisor.nombre,
+            identificacion: {
+              tipo: args.emisor.identificacion.tipo,
+              numero: args.emisor.identificacion.numero
+            },
+            ...args.emisor.nombreComercial ? { nombreComercial: args.emisor.nombreComercial } : {},
+            correoElectronico: args.emisor.correoElectronico
+          },
+          receptor: {
+            nombre: args.receptor.nombre,
+            ...args.receptor.identificacion ? {
+              identificacion: {
+                tipo: args.receptor.identificacion.tipo,
+                numero: args.receptor.identificacion.numero
+              }
+            } : {},
+            ...args.receptor.correoElectronico ? { correoElectronico: args.receptor.correoElectronico } : {}
+          },
+          condicionVenta: args.condicionVenta,
+          ...args.plazoCredito ? { plazoCredito: args.plazoCredito } : {},
+          medioPago: args.medioPago,
+          detalleServicio,
+          resumenFactura: {
+            totalServGravados: summary.totalServGravados,
+            totalServExentos: summary.totalServExentos,
+            ...summary.totalServExonerado > 0 ? { totalServExonerado: summary.totalServExonerado } : {},
+            totalMercanciasGravadas: summary.totalMercanciasGravadas,
+            totalMercanciasExentas: summary.totalMercanciasExentas,
+            ...summary.totalMercExonerada > 0 ? { totalMercExonerada: summary.totalMercExonerada } : {},
+            totalGravado: summary.totalGravado,
+            totalExento: summary.totalExento,
+            ...summary.totalExonerado > 0 ? { totalExonerado: summary.totalExonerado } : {},
+            totalVenta: summary.totalVenta,
+            totalDescuentos: summary.totalDescuentos,
+            totalVentaNeta: summary.totalVentaNeta,
+            totalImpuesto: summary.totalImpuesto,
+            totalComprobante: summary.totalComprobante
+          }
+        };
+        const xml = buildFacturaXml(factura);
+        return {
+          content: [
+            {
+              type: "text",
+              text: [
+                `Factura Electronica created successfully.`,
+                ``,
+                `Clave: ${clave}`,
+                `Consecutivo: ${numeroConsecutivo}`,
+                `Total: ${summary.totalComprobante}`,
+                `Tax: ${summary.totalImpuesto}`,
+                ``,
+                `--- XML (unsigned) ---`,
+                xml
+              ].join("\n")
+            }
+          ]
+        };
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return {
+          content: [
+            {
+              type: "text",
+              text: `Error creating invoice: ${message}`
+            }
+          ],
+          isError: true
+        };
+      }
+    }
+  );
+}
+
+// src/tools/document-tools.ts
+import { z as z2 } from "zod";
+import {
+  parseClave,
+  getStatus,
+  extractRejectionReason,
+  listComprobantes,
+  getComprobante
+} from "@dojocoding/hacienda-sdk";
+import { DOCUMENT_TYPE_NAMES } from "@dojocoding/hacienda-shared";
+
+// src/tools/api-client.ts
+import { bootstrapClient } 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;
+}
+
+// src/tools/document-tools.ts
+function registerCheckStatusTool(server) {
+  server.tool(
+    "check_status",
+    "Check the processing status of an electronic document by its 50-digit clave numerica. Returns the current status from Hacienda (recibido, procesando, aceptado, rechazado). Requires a configured profile (run `hacienda auth login` first).",
+    {
+      clave: z2.string().length(50).describe("The 50-digit clave numerica of the document to check"),
+      profile: z2.string().default("default").describe('Config profile name (default: "default")')
+    },
+    async (args) => {
+      try {
+        const parsed = parseClave(args.clave);
+        const docTypeName = DOCUMENT_TYPE_NAMES[parsed.documentType] ?? `Unknown (${parsed.documentType})`;
+        const httpClient = await createMcpApiClient(args.profile);
+        const status = await getStatus(httpClient, args.clave);
+        let rejectionReason;
+        if (status.responseXml) {
+          rejectionReason = extractRejectionReason(status.responseXml);
+        }
+        return {
+          content: [
+            {
+              type: "text",
+              text: [
+                `Document Status`,
+                ``,
+                `Clave: ${args.clave}`,
+                `Document Type: ${docTypeName}`,
+                `Taxpayer ID: ${parsed.taxpayerId}`,
+                `Date: ${parsed.dateRaw}`,
+                `Sequence: ${parsed.sequence}`,
+                ``,
+                `Status: ${status.status}`,
+                status.date ? `Response Date: ${status.date}` : null,
+                rejectionReason ? `Rejection Reason: ${rejectionReason}` : null
+              ].filter(Boolean).join("\n")
+            }
+          ]
+        };
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return {
+          content: [
+            {
+              type: "text",
+              text: `Error checking status: ${message}`
+            }
+          ],
+          isError: true
+        };
+      }
+    }
+  );
+}
+function registerListDocumentsTool(server) {
+  server.tool(
+    "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")')
+    },
+    async (args) => {
+      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}`,
+              ``
+            );
+          }
+        }
+        return {
+          content: [
+            {
+              type: "text",
+              text: lines.join("\n")
+            }
+          ]
+        };
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return {
+          content: [
+            {
+              type: "text",
+              text: `Error listing documents: ${message}`
+            }
+          ],
+          isError: true
+        };
+      }
+    }
+  );
+}
+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).",
+    {
+      clave: z2.string().length(50).describe("The 50-digit clave numerica of the document to retrieve"),
+      profile: z2.string().default("default").describe('Config profile name (default: "default")')
+    },
+    async (args) => {
+      try {
+        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)";
+          }
+        }
+        return {
+          content: [
+            {
+              type: "text",
+              text: [
+                `Document Details`,
+                ``,
+                `Clave: ${doc.clave}`,
+                `Document Type: ${docTypeName}`,
+                `Taxpayer ID: ${parsed.taxpayerId}`,
+                `Emission Date: ${doc.fechaEmision}`,
+                `Status: ${doc.estado}`,
+                doc.fechaRespuesta ? `Response Date: ${doc.fechaRespuesta}` : null,
+                ``,
+                `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}`,
+                `Situation: ${parsed.situation}`,
+                `Security Code: ${parsed.securityCode}`,
+                xmlContent ? `
+--- XML ---
+${xmlContent}` : null
+              ].filter(Boolean).join("\n")
+            }
+          ]
+        };
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return {
+          content: [
+            {
+              type: "text",
+              text: `Error getting document: ${message}`
+            }
+          ],
+          isError: true
+        };
+      }
+    }
+  );
+}
+
+// src/tools/lookup-tools.ts
+import { z as z3 } from "zod";
+import { lookupTaxpayer } from "@dojocoding/hacienda-sdk";
+import { IDENTIFICATION_TYPE_NAMES } from "@dojocoding/hacienda-shared";
+function registerLookupTaxpayerTool(server) {
+  server.tool(
+    "lookup_taxpayer",
+    "Look up a Costa Rica taxpayer by their identification number (cedula). Returns the taxpayer name, identification type, and registered economic activities. Useful for validating a receptor before creating an invoice.",
+    {
+      identificacion: z3.string().min(9).max(12).describe("Taxpayer identification number (9-12 digits)")
+    },
+    async (args) => {
+      try {
+        const info = await lookupTaxpayer(args.identificacion);
+        const activities = info.actividades.length > 0 ? info.actividades.map((a) => `  - [${a.codigo}] ${a.descripcion} (${a.estado})`) : ["  (no activities registered)"];
+        return {
+          content: [
+            {
+              type: "text",
+              text: [
+                `Taxpayer Information`,
+                ``,
+                `Name: ${info.nombre}`,
+                `Identification: ${args.identificacion}`,
+                `Type: ${info.tipoIdentificacion}`,
+                ``,
+                `Economic Activities:`,
+                ...activities
+              ].join("\n")
+            }
+          ]
+        };
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return {
+          content: [
+            {
+              type: "text",
+              text: `Error looking up taxpayer: ${message}`
+            }
+          ],
+          isError: true
+        };
+      }
+    }
+  );
+}
+function registerDraftInvoiceTool(server) {
+  server.tool(
+    "draft_invoice",
+    "Generate a draft invoice template with sensible defaults for Costa Rica electronic invoicing. Use this to quickly scaffold an invoice that can then be reviewed and submitted. Returns a JSON template that can be passed to create_invoice.",
+    {
+      emisorNombre: z3.string().describe("Issuer (emisor) name"),
+      emisorIdTipo: z3.string().default("02").describe(
+        'Issuer ID type: "01"=Fisica, "02"=Juridica, "03"=DIMEX, "04"=NITE. Defaults to "02"'
+      ),
+      emisorIdNumero: z3.string().describe("Issuer identification number"),
+      emisorEmail: z3.string().describe("Issuer email address"),
+      receptorNombre: z3.string().describe("Receiver (receptor) name"),
+      receptorIdTipo: z3.string().optional().describe('Receiver ID type (optional): "01"=Fisica, "02"=Juridica, "03"=DIMEX, "04"=NITE'),
+      receptorIdNumero: z3.string().optional().describe("Receiver identification number (optional)"),
+      receptorEmail: z3.string().optional().describe("Receiver email address (optional)"),
+      codigoActividad: z3.string().default("620100").describe("CABYS activity code (6 digits). Defaults to 620100 (IT services)"),
+      description: z3.string().default("Servicio profesional").describe("Default line item description"),
+      amount: z3.number().default(0).describe("Default line item amount (price). Set to 0 to leave as placeholder"),
+      includeIva: z3.boolean().default(true).describe("Whether to include 13% IVA tax. Defaults to true")
+    },
+    async (args) => {
+      const lineItem = {
+        codigoCabys: "8310100000000",
+        cantidad: 1,
+        unidadMedida: "Sp",
+        detalle: args.description,
+        precioUnitario: args.amount,
+        esServicio: true
+      };
+      if (args.includeIva) {
+        lineItem.impuesto = [
+          {
+            codigo: "01",
+            codigoTarifa: "08",
+            tarifa: 13
+          }
+        ];
+      }
+      const draft = {
+        emisor: {
+          nombre: args.emisorNombre,
+          identificacion: {
+            tipo: args.emisorIdTipo,
+            numero: args.emisorIdNumero
+          },
+          correoElectronico: args.emisorEmail
+        },
+        receptor: {
+          nombre: args.receptorNombre,
+          ...args.receptorIdTipo && args.receptorIdNumero ? {
+            identificacion: {
+              tipo: args.receptorIdTipo,
+              numero: args.receptorIdNumero
+            }
+          } : {},
+          ...args.receptorEmail ? { correoElectronico: args.receptorEmail } : {}
+        },
+        codigoActividad: args.codigoActividad,
+        condicionVenta: "01",
+        medioPago: ["01"],
+        lineItems: [lineItem]
+      };
+      const idTypeName = IDENTIFICATION_TYPE_NAMES[args.emisorIdTipo] ?? args.emisorIdTipo;
+      return {
+        content: [
+          {
+            type: "text",
+            text: [
+              `Invoice Draft Template`,
+              ``,
+              `Emisor: ${args.emisorNombre} (${idTypeName}: ${args.emisorIdNumero})`,
+              `Receptor: ${args.receptorNombre}`,
+              `Activity: ${args.codigoActividad}`,
+              `Sale Condition: Contado (cash)`,
+              `Payment: Efectivo (cash)`,
+              args.includeIva ? `IVA: 13% included` : `IVA: not included`,
+              ``,
+              `You can pass this JSON to the create_invoice tool:`,
+              ``,
+              "```json",
+              JSON.stringify(draft, null, 2),
+              "```",
+              ``,
+              `Modify the lineItems array to add more items, change quantities,`,
+              `prices, descriptions, and tax configuration as needed.`
+            ].join("\n")
+          }
+        ]
+      };
+    }
+  );
+}
+
+// src/tools/index.ts
+function registerTools(server) {
+  registerCreateInvoiceTool(server);
+  registerCheckStatusTool(server);
+  registerListDocumentsTool(server);
+  registerGetDocumentTool(server);
+  registerLookupTaxpayerTool(server);
+  registerDraftInvoiceTool(server);
+}
+
+// src/resources/factura-schema.ts
+var FACTURA_SCHEMA = {
+  $schema: "https://json-schema.org/draft/2020-12/schema",
+  title: "Factura Electronica (Costa Rica)",
+  description: "Schema for creating a Factura Electronica via the create_invoice tool. This describes the input format accepted by the tool.",
+  type: "object",
+  required: ["emisor", "receptor", "codigoActividad", "lineItems"],
+  properties: {
+    emisor: {
+      type: "object",
+      description: "Invoice issuer (emisor) information",
+      required: ["nombre", "identificacion", "correoElectronico"],
+      properties: {
+        nombre: {
+          type: "string",
+          maxLength: 100,
+          description: "Issuer name (Nombre o Razon Social)"
+        },
+        identificacion: {
+          type: "object",
+          required: ["tipo", "numero"],
+          properties: {
+            tipo: {
+              type: "string",
+              enum: ["01", "02", "03", "04"],
+              description: "01=Cedula Fisica, 02=Cedula Juridica, 03=DIMEX, 04=NITE"
+            },
+            numero: {
+              type: "string",
+              pattern: "^\\d{9,12}$",
+              description: "Identification number (9-12 digits)"
+            }
+          }
+        },
+        nombreComercial: {
+          type: "string",
+          maxLength: 80,
+          description: "Commercial name (optional)"
+        },
+        correoElectronico: {
+          type: "string",
+          format: "email",
+          description: "Email address"
+        }
+      }
+    },
+    receptor: {
+      type: "object",
+      description: "Invoice receiver (receptor) information",
+      required: ["nombre"],
+      properties: {
+        nombre: {
+          type: "string",
+          maxLength: 100,
+          description: "Receiver name"
+        },
+        identificacion: {
+          type: "object",
+          properties: {
+            tipo: {
+              type: "string",
+              enum: ["01", "02", "03", "04"],
+              description: "Identification type code"
+            },
+            numero: {
+              type: "string",
+              description: "Identification number"
+            }
+          }
+        },
+        correoElectronico: {
+          type: "string",
+          format: "email",
+          description: "Email address (optional)"
+        }
+      }
+    },
+    codigoActividad: {
+      type: "string",
+      pattern: "^\\d{6}$",
+      description: "CABYS economic activity code (6 digits)"
+    },
+    condicionVenta: {
+      type: "string",
+      enum: ["01", "02", "03", "04", "05", "06", "07", "08", "09", "99"],
+      default: "01",
+      description: "Sale condition: 01=Cash, 02=Credit, 03=Consignment, 04=Layaway, 99=Other"
+    },
+    medioPago: {
+      type: "array",
+      items: {
+        type: "string",
+        enum: ["01", "02", "03", "04", "05", "99"]
+      },
+      default: ["01"],
+      description: "Payment methods: 01=Cash, 02=Card, 03=Check, 04=Transfer, 05=Third-party, 99=Other"
+    },
+    plazoCredito: {
+      type: "string",
+      description: "Credit term in days (required when condicionVenta=02)"
+    },
+    lineItems: {
+      type: "array",
+      minItems: 1,
+      description: "Invoice line items",
+      items: {
+        type: "object",
+        required: ["codigoCabys", "cantidad", "unidadMedida", "detalle", "precioUnitario"],
+        properties: {
+          codigoCabys: {
+            type: "string",
+            pattern: "^\\d{13}$",
+            description: "CABYS product/service code (13 digits)"
+          },
+          cantidad: {
+            type: "number",
+            minimum: 0,
+            exclusiveMinimum: true,
+            description: "Quantity"
+          },
+          unidadMedida: {
+            type: "string",
+            description: 'Unit of measure: "Sp"=Service, "Unid"=Unit, "kg"=Kilogram, "m"=Meter, etc.'
+          },
+          detalle: {
+            type: "string",
+            maxLength: 200,
+            description: "Item description"
+          },
+          precioUnitario: {
+            type: "number",
+            minimum: 0,
+            description: "Unit price before taxes"
+          },
+          esServicio: {
+            type: "boolean",
+            default: false,
+            description: "true=service, false=merchandise"
+          },
+          impuesto: {
+            type: "array",
+            description: "Taxes to apply",
+            items: {
+              type: "object",
+              required: ["codigo", "tarifa"],
+              properties: {
+                codigo: {
+                  type: "string",
+                  description: "Tax code: 01=IVA, 02=Selective, etc."
+                },
+                codigoTarifa: {
+                  type: "string",
+                  description: "IVA rate code: 01=0%, 02=1%, 03=2%, 04=4%, 08=13%"
+                },
+                tarifa: {
+                  type: "number",
+                  description: "Tax rate percentage (e.g. 13 for 13%)"
+                }
+              }
+            }
+          },
+          descuento: {
+            type: "array",
+            description: "Discounts",
+            items: {
+              type: "object",
+              required: ["montoDescuento", "naturalezaDescuento"],
+              properties: {
+                montoDescuento: {
+                  type: "number",
+                  description: "Discount amount"
+                },
+                naturalezaDescuento: {
+                  type: "string",
+                  description: "Reason for discount"
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+};
+function registerFacturaSchemaResource(server) {
+  server.resource(
+    "factura-schema",
+    "hacienda://schemas/factura",
+    {
+      description: "JSON Schema for the Factura Electronica (electronic invoice) input format. Use this to understand the required fields and structure for creating invoices.",
+      mimeType: "application/json"
+    },
+    async () => ({
+      contents: [
+        {
+          uri: "hacienda://schemas/factura",
+          mimeType: "application/json",
+          text: JSON.stringify(FACTURA_SCHEMA, null, 2)
+        }
+      ]
+    })
+  );
+}
+
+// src/resources/document-types.ts
+import {
+  DocumentTypeCode,
+  DOCUMENT_TYPE_NAMES as DOCUMENT_TYPE_NAMES2,
+  SituationCode,
+  MensajeReceptorCode,
+  SALE_CONDITION_NAMES,
+  PAYMENT_METHOD_NAMES
+} from "@dojocoding/hacienda-shared";
+var REFERENCE_DATA = {
+  documentTypes: Object.entries(DOCUMENT_TYPE_NAMES2).map(([code, name]) => ({
+    code,
+    name,
+    description: getDocTypeDescription(code)
+  })),
+  situationCodes: [
+    { code: SituationCode.NORMAL, name: "Normal", description: "Standard submission" },
+    {
+      code: SituationCode.CONTINGENCIA,
+      name: "Contingencia",
+      description: "Contingency mode (system issues)"
+    },
+    {
+      code: SituationCode.SIN_INTERNET,
+      name: "Sin Internet",
+      description: "No internet connection at time of sale"
+    }
+  ],
+  mensajeReceptorCodes: [
+    {
+      code: MensajeReceptorCode.ACEPTADO,
+      name: "Aceptado totalmente",
+      description: "Fully accepted"
+    },
+    {
+      code: MensajeReceptorCode.ACEPTADO_PARCIALMENTE,
+      name: "Aceptado parcialmente",
+      description: "Partially accepted"
+    },
+    { code: MensajeReceptorCode.RECHAZADO, name: "Rechazado", description: "Rejected" }
+  ],
+  saleConditions: Object.entries(SALE_CONDITION_NAMES).map(([code, name]) => ({
+    code,
+    name
+  })),
+  paymentMethods: Object.entries(PAYMENT_METHOD_NAMES).map(([code, name]) => ({
+    code,
+    name
+  }))
+};
+function getDocTypeDescription(code) {
+  switch (code) {
+    case DocumentTypeCode.FACTURA_ELECTRONICA:
+      return "Standard electronic invoice. Requires receptor. Most common document type.";
+    case DocumentTypeCode.NOTA_DEBITO_ELECTRONICA:
+      return "Electronic debit note. References an existing invoice to add charges.";
+    case DocumentTypeCode.NOTA_CREDITO_ELECTRONICA:
+      return "Electronic credit note. References an existing invoice to apply credits/returns.";
+    case DocumentTypeCode.TIQUETE_ELECTRONICO:
+      return "Simplified electronic receipt. Receptor is optional. For consumers (B2C).";
+    case DocumentTypeCode.FACTURA_ELECTRONICA_COMPRA:
+      return "Purchase invoice. Issued when buying from unregistered suppliers.";
+    case DocumentTypeCode.FACTURA_ELECTRONICA_EXPORTACION:
+      return "Export invoice. For international sales. Receptor may use foreign ID.";
+    case DocumentTypeCode.RECIBO_ELECTRONICO_PAGO:
+      return "Electronic payment receipt. New in v4.4.";
+    default:
+      return "Document type.";
+  }
+}
+function registerDocumentTypesResource(server) {
+  server.resource(
+    "document-types",
+    "hacienda://reference/document-types",
+    {
+      description: "Reference data for Costa Rica electronic document types, situation codes, receiver message codes, sale conditions, and payment methods.",
+      mimeType: "application/json"
+    },
+    async () => ({
+      contents: [
+        {
+          uri: "hacienda://reference/document-types",
+          mimeType: "application/json",
+          text: JSON.stringify(REFERENCE_DATA, null, 2)
+        }
+      ]
+    })
+  );
+}
+
+// src/resources/tax-codes.ts
+import {
+  TaxCode,
+  IvaRateCode,
+  IVA_RATE_PERCENTAGES,
+  ExonerationType,
+  UnitOfMeasure
+} from "@dojocoding/hacienda-shared";
+var TAX_REFERENCE = {
+  taxCodes: [
+    { code: TaxCode.IVA, name: "IVA", description: "Impuesto al Valor Agregado (Value Added Tax)" },
+    {
+      code: TaxCode.IMPUESTO_SELECTIVO_CONSUMO,
+      name: "Impuesto Selectivo de Consumo",
+      description: "Selective consumption tax"
+    },
+    {
+      code: TaxCode.IMPUESTO_UNICO_COMBUSTIBLES,
+      name: "Impuesto Unico a los Combustibles",
+      description: "Fuel tax"
+    },
+    {
+      code: TaxCode.IMPUESTO_BEBIDAS_ALCOHOLICAS,
+      name: "Impuesto Bebidas Alcoholicas",
+      description: "Alcoholic beverages tax"
+    },
+    {
+      code: TaxCode.IMPUESTO_BEBIDAS_SIN_ALCOHOL,
+      name: "Impuesto Bebidas sin Alcohol",
+      description: "Non-alcoholic beverages and toiletries tax"
+    },
+    { code: TaxCode.IMPUESTO_TABACO, name: "Impuesto al Tabaco", description: "Tobacco tax" },
+    {
+      code: TaxCode.IVA_CALCULO_ESPECIAL,
+      name: "IVA (calculo especial)",
+      description: "IVA with special calculation"
+    },
+    {
+      code: TaxCode.IVA_BIENES_USADOS,
+      name: "IVA Bienes Usados",
+      description: "IVA for used goods regime (factor method)"
+    },
+    {
+      code: TaxCode.IMPUESTO_CEMENTO,
+      name: "Impuesto al Cemento",
+      description: "Cement tax"
+    },
+    { code: TaxCode.OTROS, name: "Otros", description: "Other taxes" }
+  ],
+  ivaRateCodes: Object.entries(IVA_RATE_PERCENTAGES).map(([code, rate]) => ({
+    code,
+    rate,
+    name: getIvaRateName(code)
+  })),
+  exonerationTypes: [
+    { code: ExonerationType.COMPRAS_AUTORIZADAS, name: "Compras autorizadas" },
+    {
+      code: ExonerationType.VENTAS_EXENTAS_DIPLOMATICOS,
+      name: "Ventas exentas a diplomaticos"
+    },
+    {
+      code: ExonerationType.AUTORIZADO_LEY_ESPECIAL,
+      name: "Autorizado por ley especial"
+    },
+    {
+      code: ExonerationType.EXENCIONES_DGH,
+      name: "Exenciones de la Direccion General de Hacienda"
+    },
+    { code: ExonerationType.TRANSITORIO_V, name: "Transitorio V" },
+    { code: ExonerationType.TRANSITORIO_IX, name: "Transitorio IX" },
+    { code: ExonerationType.TRANSITORIO_XVII, name: "Transitorio XVII" },
+    { code: ExonerationType.OTROS, name: "Otros" }
+  ],
+  commonUnitsOfMeasure: [
+    { code: UnitOfMeasure.UNIDAD, name: "Unidad", description: "Unit (general merchandise)" },
+    {
+      code: UnitOfMeasure.SERVICIOS_PROFESIONALES,
+      name: "Servicios Profesionales",
+      description: "Professional services"
+    },
+    { code: UnitOfMeasure.HORAS, name: "Horas", description: "Hours" },
+    { code: UnitOfMeasure.KILOGRAMOS, name: "Kilogramos", description: "Kilograms" },
+    { code: UnitOfMeasure.LITROS, name: "Litros", description: "Liters" },
+    { code: UnitOfMeasure.METROS, name: "Metros", description: "Meters" },
+    {
+      code: UnitOfMeasure.METROS_CUADRADOS,
+      name: "Metros cuadrados",
+      description: "Square meters"
+    },
+    { code: UnitOfMeasure.METROS_CUBICOS, name: "Metros cubicos", description: "Cubic meters" },
+    { code: UnitOfMeasure.CAJAS, name: "Cajas", description: "Boxes" },
+    { code: UnitOfMeasure.PAQUETES, name: "Paquetes", description: "Packages" },
+    { code: UnitOfMeasure.GALONES, name: "Galones", description: "Gallons" },
+    { code: UnitOfMeasure.OTROS, name: "Otros", description: "Other (specify)" }
+  ],
+  notes: {
+    commonUsage: "For most services, use tax code '01' (IVA) with rate code '08' (13% general rate). Unit of measure for services is typically 'Sp' (Servicios Profesionales). For merchandise, use 'Unid' (Unidad).",
+    ivaExempt: "Some goods and services are exempt from IVA (rate code '01', 0%). The reduced rates (1%, 2%, 4%) apply to specific goods like basic foodstuffs."
+  }
+};
+function getIvaRateName(code) {
+  switch (code) {
+    case IvaRateCode.EXENTO:
+      return "Exento (0%)";
+    case IvaRateCode.REDUCIDA_1:
+      return "Tarifa reducida 1%";
+    case IvaRateCode.REDUCIDA_2:
+      return "Tarifa reducida 2%";
+    case IvaRateCode.REDUCIDA_4:
+      return "Tarifa reducida 4%";
+    case IvaRateCode.TRANSITORIO_0:
+      return "Transitorio 0%";
+    case IvaRateCode.TRANSITORIO_4:
+      return "Transitorio 4%";
+    case IvaRateCode.TRANSITORIO_8:
+      return "Transitorio 8%";
+    case IvaRateCode.GENERAL_13:
+      return "Tarifa general 13%";
+    default:
+      return `Code ${code}`;
+  }
+}
+function registerTaxCodesResource(server) {
+  server.resource(
+    "tax-codes",
+    "hacienda://reference/tax-codes",
+    {
+      description: "Reference data for Costa Rica tax codes, IVA rates, exoneration types, and units of measure used in electronic invoicing.",
+      mimeType: "application/json"
+    },
+    async () => ({
+      contents: [
+        {
+          uri: "hacienda://reference/tax-codes",
+          mimeType: "application/json",
+          text: JSON.stringify(TAX_REFERENCE, null, 2)
+        }
+      ]
+    })
+  );
+}
+
+// src/resources/id-types.ts
+import {
+  IdentificationType,
+  IDENTIFICATION_TYPE_NAMES as IDENTIFICATION_TYPE_NAMES2,
+  IDENTIFICATION_LENGTHS
+} from "@dojocoding/hacienda-shared";
+var ID_TYPES_REFERENCE = {
+  identificationTypes: [
+    {
+      code: IdentificationType.CEDULA_FISICA,
+      name: IDENTIFICATION_TYPE_NAMES2[IdentificationType.CEDULA_FISICA],
+      lengths: IDENTIFICATION_LENGTHS[IdentificationType.CEDULA_FISICA],
+      description: "Physical person identification card. 9-digit number. Used for individual taxpayers (personas fisicas).",
+      example: "101230456"
+    },
+    {
+      code: IdentificationType.CEDULA_JURIDICA,
+      name: IDENTIFICATION_TYPE_NAMES2[IdentificationType.CEDULA_JURIDICA],
+      lengths: IDENTIFICATION_LENGTHS[IdentificationType.CEDULA_JURIDICA],
+      description: "Legal entity identification. 10-digit number. Used for companies and organizations (sociedades anonimas, etc.).",
+      example: "3101234567"
+    },
+    {
+      code: IdentificationType.DIMEX,
+      name: IDENTIFICATION_TYPE_NAMES2[IdentificationType.DIMEX],
+      lengths: IDENTIFICATION_LENGTHS[IdentificationType.DIMEX],
+      description: "Foreign resident identification (Documento de Identidad Migratoria para Extranjeros). 11 or 12 digit number. Used for foreign residents in Costa Rica.",
+      example: "12345678901"
+    },
+    {
+      code: IdentificationType.NITE,
+      name: IDENTIFICATION_TYPE_NAMES2[IdentificationType.NITE],
+      lengths: IDENTIFICATION_LENGTHS[IdentificationType.NITE],
+      description: "Tax identification for foreigners without DIMEX (Numero de Identificacion Tributaria Especial). 10-digit number.",
+      example: "1234567890"
+    }
+  ],
+  notes: {
+    formatting: "Identification numbers must contain only digits, no dashes or spaces. The number must match the expected length for the given type.",
+    usage: "The emisor (issuer) always requires identification. The receptor (receiver) identification is required for Factura Electronica but optional for Tiquete Electronico."
+  }
+};
+function registerIdTypesResource(server) {
+  server.resource(
+    "id-types",
+    "hacienda://reference/id-types",
+    {
+      description: "Reference data for Costa Rica identification types used in electronic invoicing. Includes type codes, expected lengths, descriptions, and examples.",
+      mimeType: "application/json"
+    },
+    async () => ({
+      contents: [
+        {
+          uri: "hacienda://reference/id-types",
+          mimeType: "application/json",
+          text: JSON.stringify(ID_TYPES_REFERENCE, null, 2)
+        }
+      ]
+    })
+  );
+}
+
+// src/resources/index.ts
+function registerResources(server) {
+  registerFacturaSchemaResource(server);
+  registerDocumentTypesResource(server);
+  registerTaxCodesResource(server);
+  registerIdTypesResource(server);
+}
+
+// src/server.ts
+var SERVER_NAME = "hacienda-cr";
+var SERVER_VERSION = "0.0.1";
+function createServer() {
+  const server = new McpServer(
+    {
+      name: SERVER_NAME,
+      version: SERVER_VERSION
+    },
+    {
+      capabilities: {
+        tools: {},
+        resources: {}
+      },
+      instructions: "Hacienda CR MCP Server \u2014 tools and reference data for Costa Rica electronic invoicing (comprobantes electronicos). Use the tools to create invoices, check document status, and look up reference data. Resources provide schemas and reference tables for document types, tax codes, and identification types."
+    }
+  );
+  registerTools(server);
+  registerResources(server);
+  return server;
+}
+
+export {
+  createServer
+};

package/dist/cli.d.ts

@@ -0,0 +1 @@
+#!/usr/bin/env node

package/dist/cli.js

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+import {
+  createServer
+} from "./chunk-YJYSROUZ.js";
+
+// src/cli.ts
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+async function main() {
+  const server = createServer();
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+}
+main().catch((error) => {
+  console.error("Fatal error starting MCP server:", error);
+  process.exit(1);
+});

package/dist/index.d.ts

@@ -0,0 +1,43 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+
+/**
+ * MCP Server for Costa Rica electronic invoicing.
+ *
+ * Sets up an McpServer instance with all tools and resources registered.
+ * This module is the primary export — consumers can either use the
+ * `createServer()` factory (e.g. for testing) or run the stdio transport
+ * via the CLI entry point.
+ *
+ * @module server
+ */
+
+/**
+ * Creates and configures the MCP server with all tools and resources.
+ *
+ * @returns A fully configured McpServer ready to be connected to a transport.
+ */
+declare function createServer(): McpServer;
+
+/**
+ * @dojocoding/hacienda-mcp
+ *
+ * MCP Server for Costa Rica electronic invoicing.
+ * Exposes SDK functionality as AI-accessible tools via the Model Context Protocol.
+ *
+ * Tools:
+ * - create_invoice — Build a Factura Electronica XML from structured input
+ * - check_status — Check document processing status by clave
+ * - list_documents — List recent electronic documents
+ * - get_document — Get full document details by clave
+ * - lookup_taxpayer — Look up taxpayer info by identification number
+ * - draft_invoice — Generate a draft invoice template with sensible defaults
+ *
+ * Resources:
+ * - hacienda://schemas/factura — JSON schema for invoice creation
+ * - hacienda://reference/document-types — Document types, codes, and descriptions
+ * - hacienda://reference/tax-codes — Tax codes, IVA rates, and units of measure
+ * - hacienda://reference/id-types — Identification types and validation rules
+ */
+declare const PACKAGE_NAME: "@dojocoding/hacienda-mcp";
+
+export { PACKAGE_NAME, createServer };

package/dist/index.js

@@ -0,0 +1,10 @@
+import {
+  createServer
+} from "./chunk-YJYSROUZ.js";
+
+// src/index.ts
+var PACKAGE_NAME = "@dojocoding/hacienda-mcp";
+export {
+  PACKAGE_NAME,
+  createServer
+};

package/package.json

@@ -0,0 +1 @@
+{"name": "@iflow-mcp/dojocodinglabs-hacienda-cr", "version": "0.2.0", "description": "MCP Server for Costa Rica electronic invoicing (AI-accessible tools)", "type": "module", "main": "./dist/index.js", "types": "./dist/index.d.ts", "bin": {"iflow-mcp-dojocodinglabs-hacienda-cr": "./dist/cli.js"}, "exports": {".": {"import": "./dist/index.js", "types": "./dist/index.d.ts"}}, "files": ["dist"], "keywords": ["costa-rica", "hacienda", "electronic-invoicing", "factura-electronica", "comprobantes-electronicos", "mcp", "model-context-protocol"], "scripts": {"build": "tsup", "prepublishOnly": "pnpm run build", "test": "vitest run", "lint": "eslint src/", "typecheck": "tsc --noEmit", "clean": "rm -rf dist"}, "dependencies": {"@dojocoding/hacienda-sdk": "workspace:*", "@dojocoding/hacienda-shared": "workspace:*", "@modelcontextprotocol/sdk": "^1.26.0", "zod": "^4.3.6"}, "license": "MIT", "author": "Dojo Coding Labs <dev@dojocoding.io> (https://dojocoding.io)"}