@cgalaviz/easysell-mcp 0.4.0

package/dist/tools.js

@@ -0,0 +1,150 @@
+import { z } from "zod";
+import { apiRequest } from "./client.js";
+function fieldToZod(field) {
+    let schema;
+    switch (field.type) {
+        case "string":
+            schema = field.enum ? z.enum(field.enum) : z.string();
+            break;
+        case "number":
+            schema = z.number();
+            break;
+        case "boolean":
+            schema = z.boolean();
+            break;
+        case "array":
+            // El elemento de un array nunca es "opcional": `required` en `field.items`
+            // no tiene sentido ahí (no es una propiedad con nombre) y, sin forzarlo,
+            // `fieldToZod` lo envolvía en `.optional()` por default y zod-to-json-schema
+            // lo convertía en `anyOf:[{not:{}},{...}]` — cualquier tool con un array
+            // (tags, variantes, líneas) quedaba con un schema roto.
+            schema = z.array(fieldToZod({ ...field.items, required: true }));
+            break;
+        case "object":
+            schema = z.object(objectFieldsToZodShape(field.fields));
+            break;
+        case "any":
+            schema = z.any();
+            break;
+        default: {
+            // Exhaustividad: si alguien añade un tipo nuevo a `Field` (en
+            // registry/types.ts) sin tocar este switch, el compilador lo señala
+            // aquí (`never` no asignable a `string`) en vez de dejar salir un
+            // `undefined` como schema, que MCP aceptaría silenciosamente.
+            const _exhaustive = field;
+            throw new Error(`Tipo de Field no soportado: ${JSON.stringify(_exhaustive)}`);
+        }
+    }
+    if (field.description)
+        schema = schema.describe(field.description);
+    return field.required ? schema : schema.optional();
+}
+function objectFieldsToZodShape(fields) {
+    const shape = {};
+    for (const [key, field] of Object.entries(fields))
+        shape[key] = fieldToZod(field);
+    return shape;
+}
+/** `ZodRawShape` de entrada de la tool: path params (siempre requeridos), query y body, todo al mismo nivel. */
+export function routeInputShape(route) {
+    const shape = {};
+    for (const [key, field] of Object.entries(route.pathParams ?? {})) {
+        shape[key] = fieldToZod({ ...field, required: true });
+    }
+    for (const [key, field] of Object.entries(route.query ?? {})) {
+        shape[key] = fieldToZod(field);
+    }
+    for (const [key, field] of Object.entries(route.body ?? {})) {
+        // Un nombre presente tanto en query como en body (no pasa en este registro,
+        // pero si pasara) pisaría la entrada anterior: se documenta aquí para que
+        // quien añada una ruta nueva lo note en la revisión, no en producción.
+        shape[key] = fieldToZod(field);
+    }
+    return shape;
+}
+function buildPath(route, args) {
+    let path = route.path;
+    for (const key of Object.keys(route.pathParams ?? {})) {
+        path = path.replace(`:${key}`, encodeURIComponent(String(args[key])));
+    }
+    return path;
+}
+function buildQuery(route, args) {
+    const query = {};
+    for (const key of Object.keys(route.query ?? {})) {
+        const value = args[key];
+        if (value !== undefined)
+            query[key] = typeof value === "string" ? value : JSON.stringify(value);
+    }
+    return query;
+}
+function buildBody(route, args) {
+    if (!route.body)
+        return undefined;
+    const body = {};
+    for (const key of Object.keys(route.body)) {
+        if (args[key] !== undefined)
+            body[key] = args[key];
+    }
+    return body;
+}
+function toCallToolResult(status, ok, data) {
+    return {
+        isError: !ok,
+        content: [
+            {
+                type: "text",
+                text: JSON.stringify({ status, data }, null, 2),
+            },
+        ],
+    };
+}
+/**
+ * Pistas para el cliente MCP (Claude Desktop, Claude Code, cualquier otro):
+ * un cliente que respeta `ToolAnnotations` puede pedir confirmación antes de
+ * llamar una tool destructiva, o mostrarla distinto de una de solo lectura.
+ * El servidor NUNCA bloquea nada con esto — es información, no un permiso;
+ * el único candado real sigue siendo el scope de la API key en commerce-api.
+ *
+ *  - readOnlyHint: GET nunca escribe nada.
+ *  - destructiveHint: DELETE siempre (borra o revoca); el resto solo si
+ *    `route.destructiveHint` lo marca a mano (cobra dinero, cancela,
+ *    desactiva, o manda un mensaje real que no se puede des-enviar).
+ *  - openWorldHint: true siempre — esto habla con un sistema externo real
+ *    (commerce-api en producción), nunca un sandbox.
+ */
+function routeAnnotations(route) {
+    const readOnlyHint = route.method === "GET";
+    const destructiveHint = readOnlyHint ? false : (route.destructiveHint ?? route.method === "DELETE");
+    return {
+        readOnlyHint,
+        destructiveHint,
+        idempotentHint: route.method === "DELETE" || route.method === "PATCH",
+        openWorldHint: true,
+    };
+}
+export function registerRoute(server, route) {
+    const scopeNote = route.scopes.length > 0 ? ` Requiere scope(s): ${route.scopes.join(", ")}.` : "";
+    server.registerTool(route.name, {
+        description: `${route.description}${scopeNote}`,
+        inputSchema: routeInputShape(route),
+        annotations: routeAnnotations(route),
+    }, async (args) => {
+        const path = buildPath(route, args);
+        const query = buildQuery(route, args);
+        const body = buildBody(route, args);
+        const result = await apiRequest(route.method, path, { query, body });
+        return toCallToolResult(result.status, result.ok, result.data);
+    });
+}
+export function registerRoutes(server, routes) {
+    const seen = new Set();
+    for (const route of routes) {
+        if (seen.has(route.name)) {
+            throw new Error(`Nombre de tool duplicado en el registro: ${route.name}`);
+        }
+        seen.add(route.name);
+        registerRoute(server, route);
+    }
+}
+//# sourceMappingURL=tools.js.map

package/dist/tools.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tools.js","sourceRoot":"","sources":["../src/tools.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAGzC,SAAS,UAAU,CAAC,KAAY;IAC9B,IAAI,MAAoB,CAAC;IACzB,QAAQ,KAAK,CAAC,IAAI,EAAE,CAAC;QACnB,KAAK,QAAQ;YACX,MAAM,GAAG,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,IAA6B,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC;YAC/E,MAAM;QACR,KAAK,QAAQ;YACX,MAAM,GAAG,CAAC,CAAC,MAAM,EAAE,CAAC;YACpB,MAAM;QACR,KAAK,SAAS;YACZ,MAAM,GAAG,CAAC,CAAC,OAAO,EAAE,CAAC;YACrB,MAAM;QACR,KAAK,OAAO;YACV,2EAA2E;YAC3E,yEAAyE;YACzE,6EAA6E;YAC7E,yEAAyE;YACzE,wDAAwD;YACxD,MAAM,GAAG,CAAC,CAAC,KAAK,CAAC,UAAU,CAAC,EAAE,GAAG,KAAK,CAAC,KAAK,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC;YACjE,MAAM;QACR,KAAK,QAAQ;YACX,MAAM,GAAG,CAAC,CAAC,MAAM,CAAC,sBAAsB,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC;YACxD,MAAM;QACR,KAAK,KAAK;YACR,MAAM,GAAG,CAAC,CAAC,GAAG,EAAE,CAAC;YACjB,MAAM;QACR,OAAO,CAAC,CAAC,CAAC;YACR,8DAA8D;YAC9D,oEAAoE;YACpE,kEAAkE;YAClE,8DAA8D;YAC9D,MAAM,WAAW,GAAU,KAAK,CAAC;YACjC,MAAM,IAAI,KAAK,CAAC,+BAA+B,IAAI,CAAC,SAAS,CAAC,WAAW,CAAC,EAAE,CAAC,CAAC;QAChF,CAAC;IACH,CAAC;IACD,IAAI,KAAK,CAAC,WAAW;QAAE,MAAM,GAAG,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,WAAW,CAAC,CAAC;IACnE,OAAO,KAAK,CAAC,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,QAAQ,EAAE,CAAC;AACrD,CAAC;AAED,SAAS,sBAAsB,CAAC,MAA6B;IAC3D,MAAM,KAAK,GAAkB,EAAE,CAAC;IAChC,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC;QAAE,KAAK,CAAC,GAAG,CAAC,GAAG,UAAU,CAAC,KAAK,CAAC,CAAC;IAClF,OAAO,KAAK,CAAC;AACf,CAAC;AAED,gHAAgH;AAChH,MAAM,UAAU,eAAe,CAAC,KAAe;IAC7C,MAAM,KAAK,GAAkB,EAAE,CAAC;IAChC,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,UAAU,IAAI,EAAE,CAAC,EAAE,CAAC;QAClE,KAAK,CAAC,GAAG,CAAC,GAAG,UAAU,CAAC,EAAE,GAAG,KAAK,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC;IACxD,CAAC;IACD,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,KAAK,IAAI,EAAE,CAAC,EAAE,CAAC;QAC7D,KAAK,CAAC,GAAG,CAAC,GAAG,UAAU,CAAC,KAAK,CAAC,CAAC;IACjC,CAAC;IACD,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,IAAI,EAAE,CAAC,EAAE,CAAC;QAC5D,4EAA4E;QAC5E,0EAA0E;QAC1E,uEAAuE;QACvE,KAAK,CAAC,GAAG,CAAC,GAAG,UAAU,CAAC,KAAK,CAAC,CAAC;IACjC,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,SAAS,SAAS,CAAC,KAAe,EAAE,IAA6B;IAC/D,IAAI,IAAI,GAAG,KAAK,CAAC,IAAI,CAAC;IACtB,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,UAAU,IAAI,EAAE,CAAC,EAAE,CAAC;QACtD,IAAI,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,GAAG,EAAE,EAAE,kBAAkB,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;IACxE,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED,SAAS,UAAU,CAAC,KAAe,EAAE,IAA6B;IAChE,MAAM,KAAK,GAA2B,EAAE,CAAC;IACzC,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,IAAI,EAAE,CAAC,EAAE,CAAC;QACjD,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC;QACxB,IAAI,KAAK,KAAK,SAAS;YAAE,KAAK,CAAC,GAAG,CAAC,GAAG,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;IAClG,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,SAAS,SAAS,CAAC,KAAe,EAAE,IAA6B;IAC/D,IAAI,CAAC,KAAK,CAAC,IAAI;QAAE,OAAO,SAAS,CAAC;IAClC,MAAM,IAAI,GAA4B,EAAE,CAAC;IACzC,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;QAC1C,IAAI,IAAI,CAAC,GAAG,CAAC,KAAK,SAAS;YAAE,IAAI,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC;IACrD,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED,SAAS,gBAAgB,CAAC,MAAc,EAAE,EAAW,EAAE,IAAa;IAClE,OAAO;QACL,OAAO,EAAE,CAAC,EAAE;QACZ,OAAO,EAAE;YACP;gBACE,IAAI,EAAE,MAAM;gBACZ,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,EAAE,MAAM,EAAE,IAAI,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC;aAChD;SACF;KACF,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,SAAS,gBAAgB,CAAC,KAAe;IAMvC,MAAM,YAAY,GAAG,KAAK,CAAC,MAAM,KAAK,KAAK,CAAC;IAC5C,MAAM,eAAe,GAAG,YAAY,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,eAAe,IAAI,KAAK,CAAC,MAAM,KAAK,QAAQ,CAAC,CAAC;IACpG,OAAO;QACL,YAAY;QACZ,eAAe;QACf,cAAc,EAAE,KAAK,CAAC,MAAM,KAAK,QAAQ,IAAI,KAAK,CAAC,MAAM,KAAK,OAAO;QACrE,aAAa,EAAE,IAAI;KACpB,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,aAAa,CAAC,MAAiB,EAAE,KAAe;IAC9D,MAAM,SAAS,GAAG,KAAK,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,uBAAuB,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;IACnG,MAAM,CAAC,YAAY,CACjB,KAAK,CAAC,IAAI,EACV;QACE,WAAW,EAAE,GAAG,KAAK,CAAC,WAAW,GAAG,SAAS,EAAE;QAC/C,WAAW,EAAE,eAAe,CAAC,KAAK,CAAC;QACnC,WAAW,EAAE,gBAAgB,CAAC,KAAK,CAAC;KACrC,EACD,KAAK,EAAE,IAA6B,EAAE,EAAE;QACtC,MAAM,IAAI,GAAG,SAAS,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;QACpC,MAAM,KAAK,GAAG,UAAU,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;QACtC,MAAM,IAAI,GAAG,SAAS,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;QACpC,MAAM,MAAM,GAAG,MAAM,UAAU,CAAC,KAAK,CAAC,MAAM,EAAE,IAAI,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;QACrE,OAAO,gBAAgB,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,EAAE,MAAM,CAAC,IAAI,CAAC,CAAC;IACjE,CAAC,CACF,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,cAAc,CAAC,MAAiB,EAAE,MAAkB;IAClE,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;IAC/B,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;QAC3B,IAAI,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;YACzB,MAAM,IAAI,KAAK,CAAC,4CAA4C,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC;QAC5E,CAAC;QACD,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QACrB,aAAa,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;IAC/B,CAAC;AACH,CAAC"}

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@cgalaviz/easysell-mcp",
+  "version": "0.4.0",
+  "description": "Servidor MCP sobre la API de Easy Sell: catálogo, clientes, cotizaciones, pedidos, pagos, envíos, reportes, notificaciones, integraciones, conversaciones de WhatsApp, auditoría y administración de plataforma, autenticado con tu API key.",
+  "keywords": ["mcp", "model-context-protocol", "easysell", "whatsapp", "ecommerce"],
+  "license": "MIT",
+  "author": "Tupla (https://tupla.dev)",
+  "type": "module",
+  "engines": { "node": ">=18" },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": ["dist", "README.md", "LICENSE"],
+  "bin": {
+    "easysell-mcp": "./dist/main.js"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "dev": "tsx src/main.ts",
+    "start": "node dist/main.js",
+    "typecheck": "tsc -p tsconfig.test.json",
+    "lint": "eslint .",
+    "test": "vitest run",
+    "prepublishOnly": "npm run typecheck && npm run lint && npm run test && npm run build"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "1.30.1",
+    "zod": "3.25.76"
+  },
+  "devDependencies": {
+    "@eslint/js": "9.17.0",
+    "@types/node": "22.10.5",
+    "@typescript-eslint/eslint-plugin": "8.18.2",
+    "@typescript-eslint/parser": "8.18.2",
+    "eslint": "9.17.0",
+    "globals": "15.14.0",
+    "tsx": "4.19.2",
+    "typescript": "5.6.3",
+    "vitest": "2.1.8"
+  }
+}