# mcp-el-salvador-dte

A small, focused [Model Context Protocol (MCP)](https://modelcontextprotocol.io) server that exposes **El Salvador electronic invoicing (DTE) and fiscal helpers** as tools an LLM can call: IVA calculation, the official DTE document-type catalog, and DUI / NIT validation.

Built with the official [`@modelcontextprotocol/sdk`](https://www.npmjs.com/package/@modelcontextprotocol/sdk) for TypeScript, ESM, Node 18+, and the stdio transport.

- **Author:** Gerar Arévalo — [github.com/Gerar12](https://github.com/Gerar12) · [gcoder.dev](https://gcoder.dev)
- **License:** MIT

## What it is

The [Documento Tributario Electrónico (DTE)](https://www.mh.gob.sv/) is El Salvador's mandatory electronic invoicing standard, administered by the Ministerio de Hacienda. This server bundles a few pure, deterministic helpers that come up constantly when building DTE integrations, and makes them available to any MCP-capable client (Claude Desktop, Claude Code, etc.).

## Tools

| Tool | Input | Output |
| --- | --- | --- |
| `calculate_iva` | `{ amount: number, includesIva?: boolean }` | `{ subtotal, iva, total }` |
| `list_dte_types` | _(none)_ | `{ types: [{ code, name }] }` |
| `validate_dui` | `{ dui: string }` | `{ valid, reason? }` |
| `validate_nit` | `{ nit: string }` | `{ valid, normalized, reason? }` |

### `calculate_iva`

El Salvador IVA (VAT) is **13%**.

- `includesIva = false` (default): `amount` is the net subtotal; IVA is added on top.
- `includesIva = true`: `amount` already includes IVA; it is broken out.

Values are rounded to 2 decimals, and `subtotal + iva === total` always holds.

```jsonc
// input
{ "amount": 100 }
// output
{ "subtotal": 100, "iva": 13, "total": 113 }
```

```jsonc
// input
{ "amount": 113, "includesIva": true }
// output
{ "subtotal": 100, "iva": 13, "total": 113 }
```

### `list_dte_types`

Returns the 11 official DTE document types (code — name):

| Code | Name |
| --- | --- |
| 01 | Factura (Consumidor Final) |
| 03 | Comprobante de Crédito Fiscal (CCF) |
| 04 | Nota de Remisión |
| 05 | Nota de Crédito |
| 06 | Nota de Débito |
| 07 | Comprobante de Retención |
| 08 | Comprobante de Liquidación |
| 09 | Documento Contable de Liquidación |
| 11 | Factura de Exportación |
| 14 | Factura de Sujeto Excluido |
| 15 | Comprobante de Donación |

```jsonc
// output (abridged)
{ "types": [ { "code": "01", "name": "Factura (Consumidor Final)" }, ... ] }
```

### `validate_dui`

Validates a Salvadoran **DUI** (Documento Único de Identidad): 8 digits, a hyphen, then 1 check digit (e.g. `01234567-8`).

It checks the format **and** the modulo-10 check digit. The 8 base digits are weighted `9, 8, 7, 6, 5, 4, 3, 2` (left to right); the expected check digit is `(10 - (weightedSum % 10)) % 10`.

```jsonc
// input
{ "dui": "01234567-8" }
// output
{ "valid": true }
```

```jsonc
// input
{ "dui": "01234567-9" }
// output
{ "valid": false, "reason": "Invalid check digit: expected 8, got 9" }
```

> **Honesty note on the DUI check digit.** The modulo-10 algorithm above is a
> widely-used community algorithm and was verified in this repo against known-valid
> DUIs (`00016297-5`, `01234567-8`). It is **not** reproduced from an official,
> government-published specification. If your use case is high-stakes (e.g. legally
> rejecting a real person's ID), treat a `valid: false` from the check-digit test as
> "likely a typo, please re-check" rather than an authoritative rejection. The format
> check (`^\d{8}-\d$`) is unambiguous; the check-digit step is best-effort.

### `validate_nit`

Validates the **format only** of an El Salvador **NIT** (Número de Identificación Tributaria): 14 digits, commonly formatted `NNNN-NNNNNN-NNN-N`. Input is accepted with or without hyphens/whitespace, and a canonically hyphenated `normalized` value is returned.

```jsonc
// input
{ "nit": "06141234560012" }
// output
{ "valid": true, "normalized": "0614-123456-001-2" }
```

> **Honesty note on NIT.** This is **format/length validation only** — it does not
> verify a check digit. NIT check-digit rules are not consistently documented in
> public sources, so shipping a check-digit validator here would imply a correctness
> guarantee that cannot be honestly backed up. A `valid: true` means "well-formed",
> not "issued by Hacienda".

## Install

Requires Node.js 18+.

```bash
# clone, then:
npm install
npm run build
```

Run the tests (unit tests for the pure functions + an stdio smoke test that boots the server and performs a full MCP handshake):

```bash
npm test
```

Start the server manually (it speaks JSON-RPC over stdio and waits for a client):

```bash
npm start
# or
node build/index.js
```

### Run with npx (after publishing to npm)

```bash
npx mcp-el-salvador-dte
```

## Add to Claude Desktop

Edit your `claude_desktop_config.json`:

- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`

```jsonc
{
  "mcpServers": {
    "el-salvador-dte": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-el-salvador-dte/build/index.js"]
    }
  }
}
```

Once published to npm you can instead use:

```jsonc
{
  "mcpServers": {
    "el-salvador-dte": {
      "command": "npx",
      "args": ["-y", "mcp-el-salvador-dte"]
    }
  }
}
```

Restart Claude Desktop, and the four tools will appear.

## Add to Claude Code

```bash
# local build
claude mcp add el-salvador-dte -- node /absolute/path/to/mcp-el-salvador-dte/build/index.js

# or, after publishing to npm
claude mcp add el-salvador-dte -- npx -y mcp-el-salvador-dte
```

## Project layout

```
src/lib.ts     Pure, side-effect-free domain logic (unit-tested directly)
src/index.ts   MCP server: registers the 4 tools over stdio
test/          node:test unit tests + stdio smoke test
```

## License

MIT © 2026 Gerar Arévalo