bimp-mcp 0.3.3 → 0.4.0

package/dist/index.js

@@ -90,7 +90,7 @@ for (const tool of generatedTools) {
 }
 const utilityTools = createUtilityTools(client, toolMap);
 const nomenclaturesTools = createNomenclaturesTools(client);
-const server = new McpServer({ name: "bimp-mcp", version: "0.3.3" }, { capabilities: { logging: {} } });
+const server = new McpServer({ name: "bimp-mcp", version: "0.4.0" }, { capabilities: { logging: {} } });
 // Register prompts via McpServer (uses Zod, type-safe)
 for (const [name, prompt] of Object.entries(PROMPT_TEXTS)) {
     server.registerPrompt(name, { description: prompt.description }, () => ({

package/dist/nomenclatures-extended.d.ts

@@ -1,6 +1,12 @@
 import type { BimpClient } from "./client.js";
 import type { UtilityTool } from "./utilities.js";
 export declare const FIELD_MAP: Record<string, string>;
+/**
+ * Encode a UUID into BIMP's `Ссылка` format: base64 of the UUID bytes
+ * reordered using 1C "inside-out" layout (clock_seq + node + time_hi + time_mid + time_low).
+ * The server silently accepts payloads with missing/wrong Ссылка but kit composition breaks.
+ */
+export declare function uuidToReference(uuidStr: string): string;
 export declare function toEnglish(obj: Record<string, unknown>): Record<string, unknown>;
 export declare function toCyrillic(obj: Record<string, unknown>): Record<string, unknown>;
 export declare function createNomenclaturesTools(client: BimpClient): UtilityTool[];

package/dist/nomenclatures-extended.js

@@ -25,6 +25,29 @@ export const FIELD_MAP = {
     inventoryAccountUuid: "СчетУчетаЗапасов.GUID",
     docType: "ТипДокумента",
 };
+/**
+ * Encode a UUID into BIMP's `Ссылка` format: base64 of the UUID bytes
+ * reordered using 1C "inside-out" layout (clock_seq + node + time_hi + time_mid + time_low).
+ * The server silently accepts payloads with missing/wrong Ссылка but kit composition breaks.
+ */
+export function uuidToReference(uuidStr) {
+    const hex = uuidStr.replace(/-/g, "").toLowerCase();
+    if (hex.length !== 32) {
+        throw new Error(`Invalid UUID: ${uuidStr}`);
+    }
+    const bytes = new Uint8Array(16);
+    for (let i = 0; i < 16; i++) {
+        bytes[i] = parseInt(hex.slice(i * 2, i * 2 + 2), 16);
+    }
+    // Inside-out: bytes[8..10] + bytes[10..16] + bytes[6..8] + bytes[4..6] + bytes[0..4]
+    const reordered = new Uint8Array(16);
+    reordered.set(bytes.subarray(8, 10), 0);
+    reordered.set(bytes.subarray(10, 16), 2);
+    reordered.set(bytes.subarray(6, 8), 8);
+    reordered.set(bytes.subarray(4, 6), 10);
+    reordered.set(bytes.subarray(0, 4), 12);
+    return Buffer.from(reordered).toString("base64");
+}
 const REVERSE_MAP = Object.fromEntries(Object.entries(FIELD_MAP).map(([en, cyrillic]) => [cyrillic, en]));
 export function toEnglish(obj) {
     const result = {};
@@ -63,14 +86,44 @@ function createNomenclaturesReadTool(client) {
         },
     };
 }
+async function buildKitCompositionItem(client, component) {
+    const read = (await client.request("POST", "/org2/nomenclatures/read", {
+        lang: "ru",
+        uid: component.nomenclatureUuid,
+    }));
+    const n = read.data ?? {};
+    return {
+        Номенклатура: {
+            Ссылка: uuidToReference(component.nomenclatureUuid),
+            GUID: component.nomenclatureUuid,
+            Наименование: n["Наименование"] ?? "",
+            Артикул: n["Артикул"] ?? "",
+            Код: n["Код"] ?? "",
+            ЕдиницаИзмерения: n["ЕдиницаИзмерения"] ?? null,
+            ЭтоНабор: false,
+            ЭтоУслуга: n["ЭтоУслуга"] ?? false,
+            ЭтоХарактеристика: false,
+        },
+        Характеристика: component.characteristicUuid
+            ? { GUID: component.characteristicUuid }
+            : null,
+        Количество: component.quantity,
+        leftover: 0,
+        ОстатокНаСкладах: 0,
+    };
+}
 function createNomenclaturesUpsertTool(client) {
     return {
         name: "bimp_nomenclatures_upsert",
-        description: "Create or update a product with planning/accounting fields. " +
+        description: "Create or update a product via /org2/nomenclatures/upsert (plural). " +
             "For update: uuid is required. For create: uuid is optional. " +
-            "Supports: minStock, maxStock, speedOfDemand, insuranceReserve, deliveryTerm, and all standard fields.",
+            "Supports planning fields (minStock, maxStock, speedOfDemand, insuranceReserve, deliveryTerm), " +
+            "kit creation (isKit + kitComposition), and direct passthrough of Russian/1C fields. " +
+            "When kitComposition is provided, the tool fetches each component via /org2/nomenclatures/read " +
+            "to populate the Ссылка and other required fields.",
         inputSchema: {
             type: "object",
+            additionalProperties: true,
             properties: {
                 uuid: { type: "string", description: "Product UUID (required for update, optional for create)" },
                 name: { type: "string", description: "Product name (required for create)" },
@@ -82,11 +135,47 @@ function createNomenclaturesUpsertTool(client) {
                 deliveryTerm: { type: "number", description: "Delivery time in days" },
                 unitOfMeasurementUuid: { type: "string", description: "Unit of measurement UUID" },
                 type: { type: "number", description: "Product type: 1=goods, 2=service" },
+                isKit: { type: "boolean", description: "Mark as kit (набір). Requires kitComposition when true." },
+                kitComposition: {
+                    type: "array",
+                    description: "Kit components — the tool resolves each UUID to a full 1C component block.",
+                    items: {
+                        type: "object",
+                        properties: {
+                            nomenclatureUuid: { type: "string", description: "Component product UUID" },
+                            quantity: { type: "number", description: "Quantity of this component in the kit" },
+                            characteristicUuid: { type: "string", description: "Optional product characteristic UUID" },
+                        },
+                        required: ["nomenclatureUuid", "quantity"],
+                    },
+                },
+                vatRateUuid: { type: "string", description: "VAT rate UUID (maps to СтавкаНДС.GUID)" },
+                expenseAccountUuid: { type: "string", description: "Expense account UUID (maps to СчетУчетаЗатрат.GUID)" },
+                inventoryAccountUuid: { type: "string", description: "Inventory account UUID" },
             },
         },
         handler: async (params) => {
-            const { docType: _ignored, ...fields } = params;
-            const body = toCyrillic(fields);
+            const { docType: _docType, unitOfMeasurementUuid, expenseAccountUuid, inventoryAccountUuid, vatRateUuid, isKit, kitComposition, ...rest } = params;
+            const body = toCyrillic(rest);
+            if (unitOfMeasurementUuid) {
+                body["ЕдиницаИзмерения"] = { GUID: unitOfMeasurementUuid };
+            }
+            if (expenseAccountUuid) {
+                body["СчетУчетаЗатрат"] = { GUID: expenseAccountUuid };
+            }
+            if (inventoryAccountUuid) {
+                body["СчетУчетаЗапасов"] = { GUID: inventoryAccountUuid };
+            }
+            if (vatRateUuid) {
+                body["СтавкаНДС"] = { GUID: vatRateUuid };
+            }
+            if (isKit === true || Array.isArray(kitComposition)) {
+                body["ЭтоНабор"] = true;
+                if (Array.isArray(kitComposition)) {
+                    const composition = await Promise.all(kitComposition.map((c) => buildKitCompositionItem(client, c)));
+                    body["СоставНабора"] = composition;
+                }
+            }
             body["ТипДокумента"] = "101";
             const response = (await client.request("POST", "/org2/nomenclatures/upsert", body));
             return { uuid: response.data.GUID };

package/dist/utilities.d.ts

@@ -7,6 +7,7 @@ export interface UtilityTool {
         type: "object";
         properties: Record<string, unknown>;
         required?: string[];
+        additionalProperties?: boolean;
     };
     handler: (params: Record<string, unknown>) => Promise<unknown>;
 }

package/dist/utilities.js

@@ -44,12 +44,51 @@ async function batchReadUuids(client, toolDef, uuids, concurrency) {
     }
     return { items, errors };
 }
+// Filters the BIMP server ignores on /org2/nomenclature/api-readList (confirmed by
+// integration testing). We paginate unfiltered and apply these locally. Other keys
+// (nameContains, periodable, etc.) still flow through to the API.
+const CLIENT_FILTER_KEYS = ["article", "articleContains", "isKit"];
+function splitFilters(filters) {
+    const serverFilters = {};
+    const clientFilters = {};
+    for (const [key, value] of Object.entries(filters)) {
+        if (CLIENT_FILTER_KEYS.includes(key)) {
+            clientFilters[key] = value;
+        }
+        else {
+            serverFilters[key] = value;
+        }
+    }
+    return { serverFilters, clientFilters };
+}
+function matchesClientFilters(item, filters) {
+    if (Object.keys(filters).length === 0)
+        return true;
+    const article = String(item.article ?? item["Артикул"] ?? "").toLowerCase();
+    const isKit = item.isKit ?? item["ЭтоНабор"];
+    if (typeof filters.article === "string") {
+        if (article !== filters.article.toLowerCase())
+            return false;
+    }
+    if (typeof filters.articleContains === "string") {
+        if (!article.includes(filters.articleContains.toLowerCase()))
+            return false;
+    }
+    if (typeof filters.isKit === "boolean") {
+        if (Boolean(isKit) !== filters.isKit)
+            return false;
+    }
+    return true;
+}
 function createFetchAllTool(client, toolMap) {
     return {
         name: "bimp_fetch_all",
         description: "Auto-paginate any readList endpoint to fetch all items. " +
             "Supports offset, cursor, page, and none pagination types. " +
             "Use enrich=true to call the corresponding read endpoint for full details on each item.\n\n" +
+            "Client-side filters (applied AFTER pagination, because the server ignores them on /org2/nomenclature/*): " +
+            "filters.article (exact), filters.articleContains, filters.isKit. " +
+            "Other filter keys (nameContains, periodable, etc.) are passed through to the API as-is.\n\n" +
             "IMPORTANT: Always set limit (recommended: 50 with enrich, 200 without) to avoid response truncation. " +
             "Use skip to paginate through results: first call skip=0 limit=50, then skip=50 limit=50, etc. " +
             "If the response contains _truncated, use skip and limit to get remaining items.",
@@ -74,7 +113,7 @@ function createFetchAllTool(client, toolMap) {
                 },
                 filters: {
                     type: "object",
-                    description: "Additional filter parameters to pass through to the API",
+                    description: "Filter parameters. Known client-side keys (article, articleContains, name, nameContains, isKit) are applied locally after pagination. All others are passed to the API.",
                 },
             },
             required: ["tool"],
@@ -84,9 +123,13 @@ function createFetchAllTool(client, toolMap) {
             const skip = params.skip ?? 0;
             const limit = params.limit;
             const enrich = params.enrich;
-            const filters = (params.filters ?? {});
-            // Effective limit accounts for skip: fetch skip+limit items, then slice
-            const fetchLimit = limit ? skip + limit : undefined;
+            const rawFilters = (params.filters ?? {});
+            const { serverFilters, clientFilters } = splitFilters(rawFilters);
+            const hasClientFilters = Object.keys(clientFilters).length > 0;
+            // Effective limit accounts for skip: fetch skip+limit items, then slice.
+            // With client-side filters we can't pre-limit the API fetch because the
+            // server returns unfiltered pages — we have to paginate fully then filter.
+            const fetchLimit = limit && !hasClientFilters ? skip + limit : undefined;
             const toolDef = toolMap.get(toolName);
             if (!toolDef) {
                 throw new Error(`Tool not found: ${toolName}`);
@@ -97,7 +140,7 @@ function createFetchAllTool(client, toolMap) {
                 let offset = 0;
                 while (true) {
                     const requestParams = {
-                        ...filters,
+                        ...serverFilters,
                         pagination: { offset, count: PAGE_SIZE },
                     };
                     const response = (await client.request(toolDef.metadata.method, toolDef.metadata.path, requestParams));
@@ -117,7 +160,7 @@ function createFetchAllTool(client, toolMap) {
                 let cursor;
                 while (true) {
                     const requestParams = {
-                        ...filters,
+                        ...serverFilters,
                         ...(cursor ? { cursor } : {}),
                         count: PAGE_SIZE,
                     };
@@ -138,7 +181,7 @@ function createFetchAllTool(client, toolMap) {
                 let page = 1;
                 while (true) {
                     const requestParams = {
-                        ...filters,
+                        ...serverFilters,
                         page,
                         pageSize: PAGE_SIZE,
                     };
@@ -157,7 +200,7 @@ function createFetchAllTool(client, toolMap) {
             }
             else {
                 // paginationType === "none" — single request
-                const requestParams = { ...filters };
+                const requestParams = { ...serverFilters };
                 const response = (await client.request(toolDef.metadata.method, toolDef.metadata.path, requestParams));
                 const items = response.data ?? [];
                 allItems.push(...items);
@@ -165,11 +208,19 @@ function createFetchAllTool(client, toolMap) {
                     allItems = allItems.slice(0, fetchLimit);
                 }
             }
+            // Apply client-side filters before skip/limit
+            if (hasClientFilters) {
+                allItems = allItems.filter((item) => matchesClientFilters(item, clientFilters));
+            }
             // Apply skip — slice off the first `skip` items
             const totalFetched = allItems.length;
             if (skip > 0) {
                 allItems = allItems.slice(skip);
             }
+            // When client filters were applied we didn't pre-limit the API fetch; trim now.
+            if (hasClientFilters && limit && allItems.length > limit) {
+                allItems = allItems.slice(0, limit);
+            }
             // Enrich: call the read endpoint for each item
             if (enrich && allItems.length > 0) {
                 const readToolName = deriveReadToolName(toolName);
@@ -286,10 +337,68 @@ function createBulkUpdateTool(client, toolMap) {
         },
     };
 }
+function createFindByArticleTool(client, toolMap) {
+    return {
+        name: "bimp_nomenclature_findByArticle",
+        description: "Find nomenclature records by article (SKU). Server-side article filtering on " +
+            "/org2/nomenclature/api-readList is unreliable, so this tool paginates and filters " +
+            "locally. Use exact=false for substring match.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                article: { type: "string", description: "Article value to match" },
+                exact: {
+                    type: "boolean",
+                    description: "When true (default), only exact case-insensitive matches are returned; when false, substring.",
+                },
+                limit: {
+                    type: "number",
+                    description: "Max matching items to return (default 50).",
+                },
+            },
+            required: ["article"],
+        },
+        handler: async (params) => {
+            const article = String(params.article ?? "").trim();
+            if (!article) {
+                throw new Error("article is required");
+            }
+            const exact = params.exact ?? true;
+            const limit = params.limit ?? 50;
+            const toolDef = toolMap.get("bimp_nomenclature_readList");
+            if (!toolDef) {
+                throw new Error("bimp_nomenclature_readList not available");
+            }
+            const needle = article.toLowerCase();
+            const matches = [];
+            let offset = 0;
+            while (matches.length < limit) {
+                const response = (await client.request(toolDef.metadata.method, toolDef.metadata.path, { pagination: { offset, count: PAGE_SIZE } }));
+                const page = response.data ?? [];
+                if (page.length === 0)
+                    break;
+                for (const item of page) {
+                    const itemArticle = String(item.article ?? item["Артикул"] ?? "").toLowerCase();
+                    const hit = exact ? itemArticle === needle : itemArticle.includes(needle);
+                    if (hit) {
+                        matches.push(item);
+                        if (matches.length >= limit)
+                            break;
+                    }
+                }
+                if (page.length < PAGE_SIZE)
+                    break;
+                offset += PAGE_SIZE;
+            }
+            return { items: matches, count: matches.length };
+        },
+    };
+}
 export function createUtilityTools(client, toolMap) {
     return [
         createFetchAllTool(client, toolMap),
         createBatchReadTool(client, toolMap),
         createBulkUpdateTool(client, toolMap),
+        createFindByArticleTool(client, toolMap),
     ];
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bimp-mcp",
-  "version": "0.3.3",
+  "version": "0.4.0",
   "description": "MCP server for BIMP ERP API — ~140 tools dynamically generated from OpenAPI spec, plus planning/accounting fields and bulk operations",
   "type": "module",
   "main": "dist/index.js",