@azur.com.ec/mcp 1.0.0

package/README.md

@@ -0,0 +1,82 @@
+# Servidor MCP de AZUR
+
+Deja que un asistente de IA (Claude, Cursor, VS Code, n8n, la API de OpenAI o de Anthropic…) **busque clientes y
+productos, consulte existencias, el plan y los comprobantes, y prepare comprobantes** en AZUR, el sistema de facturación
+electrónica del SRI de Ecuador.
+
+## 1. Cree su credencial
+
+Entre a AZUR con la cuenta del **dueño** → menú de usuario → **Credenciales API** → *Nueva credencial*.
+
+- Elija el **punto de emisión**. Si está en pruebas, la credencial empieza con `azur_test_`; si está en producción, con
+  `azur_live_` (lo que guarde es real).
+- Elija los **permisos**. Para un asistente recomendamos: *Consultar comprobantes*, *Crear y editar borradores* y *Ver
+  clientes y productos*. **No** le dé *Enviar al SRI y anular* salvo que lo necesite de verdad.
+- Opcional: IP autorizadas y fecha de vencimiento.
+- Copie la credencial: **solo se muestra una vez**.
+
+## 2a. Opción recomendada: servidor remoto (sin instalar nada)
+
+URL del servidor: `https://azur.com.ec/mcp` (transporte *Streamable HTTP*), autenticación con la cabecera
+`Authorization: Bearer azur_live_…`.
+
+**Claude Code**
+
+```bash
+claude mcp add --transport http azur https://azur.com.ec/mcp --header "Authorization: Bearer azur_live_..."
+```
+
+**Cursor / VS Code / Windsurf** (configuración MCP):
+
+```json
+{
+  "mcpServers": {
+    "azur": {
+      "url": "https://azur.com.ec/mcp",
+      "headers": { "Authorization": "Bearer azur_live_..." }
+    }
+  }
+}
+```
+
+**API de Anthropic (conector MCP)**: `url: https://azur.com.ec/mcp`, `authorization_token: azur_live_...`.
+**API de OpenAI (herramienta MCP remota)**: `server_url: https://azur.com.ec/mcp`, `headers: { "Authorization": "Bearer azur_live_..." }`.
+
+> Las aplicaciones web de Claude.ai y ChatGPT, por ahora, solo agregan conectores con inicio de sesión OAuth; para ellas
+> use la opción local (2b) desde la app de escritorio.
+
+## 2b. Opción local (Claude Desktop y otros clientes por *stdio*)
+
+Requiere Node.js 18 o superior. En el archivo de configuración del cliente:
+
+```json
+{
+  "mcpServers": {
+    "azur": {
+      "command": "npx",
+      "args": ["-y", "@azur.com.ec/mcp"],
+      "env": { "AZUR_API_KEY": "azur_live_..." }
+    }
+  }
+}
+```
+
+Variables: `AZUR_API_KEY` (obligatoria), `AZUR_URL` (por defecto `https://azur.com.ec`) y `AZUR_PERMITIR_ENVIO=1`
+(solo si quiere que el asistente pueda enviar al SRI).
+
+## Lo que puede y lo que no
+
+Puede buscar clientes, productos y proveedores, ver existencias, bodegas y kardex, consultar el plan, el resumen de ventas
+y los comprobantes, descargar el PDF, crear clientes y **preparar** facturas, notas de venta y proformas como **borrador**.
+
+**No envía nada al SRI** por defecto: el asistente prepara y una persona revisa y envía desde AZUR. En el servidor remoto
+el envío solo aparece si la URL lleva `?envio=1`, y aun así la credencial debe tener el permiso *Enviar al SRI y anular*.
+
+Todo pasa por la API normal de AZUR con **su** credencial: se respetan sus permisos, sus IP autorizadas, su ambiente y
+sus límites. Si una búsqueda devuelve varios candidatos, el asistente recibe el aviso de que **debe preguntar** cuál es
+antes de facturar.
+
+Las herramientas no están escritas a mano: salen de la propia API (`/plataforma/api/v2/herramientas`), así que cuando
+AZUR agrega una, aparece sola.
+
+Documentación de la API: https://azur.com.ec/api/referencia

package/package.json

@@ -0,0 +1,13 @@
+{
+  "name": "@azur.com.ec/mcp",
+  "version": "1.0.0",
+  "description": "Servidor MCP de AZUR: deja que un asistente de IA consulte y prepare comprobantes electrónicos del SRI (Ecuador)",
+  "license": "MIT",
+  "type": "module",
+  "bin": { "azur-mcp": "./servidor.js" },
+  "files": ["servidor.js", "README.md"],
+  "keywords": ["mcp", "model-context-protocol", "azur", "sri", "ecuador", "facturacion-electronica", "factura"],
+  "homepage": "https://azur.com.ec/api",
+  "dependencies": { "@modelcontextprotocol/sdk": "^1.17.0" },
+  "engines": { "node": ">=18" }
+}

package/servidor.js

@@ -0,0 +1,154 @@
+#!/usr/bin/env node
+/**
+ * SERVIDOR MCP DE AZUR
+ *
+ * Deja que un asistente busque clientes y productos, mire existencias y **prepare** facturas
+ * en AZUR. Las herramientas no están escritas a mano: se leen de `/api/v2/herramientas`, que
+ * a su vez sale del OpenAPI. Si mañana se añade un endpoint, aparece aquí sin tocar nada.
+ *
+ * ── LO QUE NO PUEDE HACER, Y ES A PROPÓSITO ───────────────────────────────────────────────
+ *
+ * No puede **enviar** nada al SRI. Prepara el borrador y ahí se para: quien lo revisa y lo
+ * manda es una persona. Un comprobante autorizado por equivocación no se borra, hay que
+ * anularlo, y eso se le explica al cliente. Si de verdad se quiere abrir esa puerta, se
+ * arranca con AZUR_PERMITIR_ENVIO=1, pero que sea una decisión de alguien.
+ *
+ * Uso:
+ *   AZUR_URL=https://azur.com.ec AZUR_API_KEY=azur_live_... npx azur-mcp
+ */
+
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+} from "@modelcontextprotocol/sdk/types.js";
+
+const URL_BASE = (process.env.AZUR_URL || "https://azur.com.ec").replace(/\/$/, "");
+const API = `${URL_BASE}/plataforma/api/v2`;
+const CREDENCIAL = process.env.AZUR_API_KEY;
+const PERMITIR_ENVIO = process.env.AZUR_PERMITIR_ENVIO === "1";
+
+if (!CREDENCIAL) {
+  console.error("Falta AZUR_API_KEY. Debe empezar por azur_live_ o azur_test_.");
+  process.exit(1);
+}
+
+// Un aviso que conviene ver antes de facturarle a alguien de verdad.
+if (CREDENCIAL.startsWith("azur_live_")) {
+  console.error("AVISO: credencial de PRODUCCIÓN. Lo que se guarde es real.");
+}
+
+const cabeceras = {
+  "X-Api-Key": CREDENCIAL,
+  "Accept": "application/json",
+  "Content-Type": "application/json",
+};
+
+/** Las herramientas salen de la propia API, que las genera del OpenAPI. */
+async function cargarHerramientas() {
+  const r = await fetch(`${API}/herramientas?envio=${PERMITIR_ENVIO ? 1 : 0}`, {
+    headers: cabeceras,
+  });
+  if (!r.ok) throw new Error(`No se pudo leer el catálogo de herramientas (HTTP ${r.status})`);
+  const { herramientas } = await r.json();
+  return herramientas;
+}
+
+/** Sustituye {id} en la ruta y deja el resto como parámetros. */
+function armarLlamada(meta, argumentos) {
+  let ruta = meta.ruta;
+  const resto = { ...argumentos };
+
+  for (const trozo of ruta.match(/\{(\w+)\}/g) || []) {
+    const clave = trozo.slice(1, -1);
+    ruta = ruta.replace(trozo, encodeURIComponent(resto[clave] ?? ""));
+    delete resto[clave];
+  }
+  return { ruta, resto };
+}
+
+const herramientas = await cargarHerramientas();
+const porNombre = new Map(herramientas.map((h) => [h.name, h]));
+
+const servidor = new Server(
+  { name: "azur", version: "1.0.0" },
+  { capabilities: { tools: {} } }
+);
+
+servidor.setRequestHandler(ListToolsRequestSchema, async () => ({
+  tools: herramientas.map(({ name, description, inputSchema }) => ({
+    name,
+    description,
+    inputSchema,
+  })),
+}));
+
+servidor.setRequestHandler(CallToolRequestSchema, async (peticion) => {
+  const h = porNombre.get(peticion.params.name);
+  if (!h) {
+    return {
+      isError: true,
+      content: [{ type: "text", text: `No existe la herramienta ${peticion.params.name}.` }],
+    };
+  }
+
+  const meta = h["x-azur"];
+  const { ruta, resto } = armarLlamada(meta, peticion.params.arguments || {});
+
+  let url = `${API}${ruta}`;
+  const opciones = { method: meta.metodo, headers: { ...cabeceras } };
+
+  if (meta.metodo === "GET") {
+    const q = new URLSearchParams(
+      Object.entries(resto).filter(([, v]) => v !== undefined && v !== null)
+    );
+    if (q.toString()) url += `?${q}`;
+  } else {
+    // Idempotencia: si el modelo repite la llamada porque no entendió la respuesta, no se
+    // crea un segundo documento.
+    opciones.headers["Idempotency-Key"] = `mcp-${Date.now()}-${Math.random().toString(36).slice(2)}`;
+    opciones.body = JSON.stringify(resto);
+  }
+
+  try {
+    const r = await fetch(url, opciones);
+    const cuerpo = await r.json();
+
+    // Los errores se devuelven como texto legible: el modelo tiene que poder entender qué
+    // falló y decidir. Un JSON de error crudo lo despista.
+    if (!r.ok || cuerpo.ok === false) {
+      const e = cuerpo.error || {};
+      let texto = `No se pudo: ${e.mensaje || r.statusText}`;
+      if (e.detalle?.motivos) texto += `\n\nMotivos:\n- ${e.detalle.motivos.join("\n- ")}`;
+      if (e.reintentable) texto += `\n\n(Se puede reintentar.)`;
+      return { isError: true, content: [{ type: "text", text: texto }] };
+    }
+
+    let texto = JSON.stringify(cuerpo.datos, null, 2);
+
+    // Si la búsqueda dejó varios candidatos, se dice CLARO. Es la diferencia entre ayudar a
+    // facturar y facturarle a quien no era.
+    if (cuerpo.datos?.unico === false) {
+      texto =
+        `Hay ${cuerpo.datos.total} resultados: NO se puede dar por bueno ninguno sin ` +
+        `preguntar cuál es.\n\n` + texto;
+    }
+    if (cuerpo.avisos?.length) {
+      texto += `\n\nAvisos:\n- ${cuerpo.avisos.join("\n- ")}`;
+    }
+
+    return { content: [{ type: "text", text: texto }] };
+  } catch (err) {
+    return {
+      isError: true,
+      content: [{ type: "text", text: `No se pudo hablar con AZUR: ${err.message}` }],
+    };
+  }
+});
+
+await servidor.connect(new StdioServerTransport());
+console.error(
+  `AZUR MCP en marcha · ${herramientas.length} herramientas · ` +
+  `envío al SRI ${PERMITIR_ENVIO ? "PERMITIDO" : "bloqueado"}`
+);