bimp-mcp 0.3.1 → 0.4.0

package/README.md

@@ -1,24 +1,43 @@
-# bimp-mcp
+<p align="center">
+  <img src="assets/header.png" alt="HEYLOVE x BIMP" width="480" />
+</p>
 
-MCP server for [BIMP ERP](https://bimpsoft.com) -- a Ukrainian cloud-based ERP system for small and medium businesses covering sales, inventory, finance, manufacturing, and procurement.
+<h1 align="center">BIMP MCP</h1>
 
-This server enables LLMs to interact with BIMP data through the [Model Context Protocol](https://modelcontextprotocol.io): read, create, update entities, perform bulk operations, and analyze business data.
+<p align="center">
+  MCP server for <a href="https://bimpsoft.com">BIMP ERP</a> — a Ukrainian cloud ERP for small and medium businesses
+</p>
+
+<p align="center">
+  <a href="https://github.com/dutchakdev/bimp-mcp/actions/workflows/ci.yml"><img src="https://github.com/dutchakdev/bimp-mcp/actions/workflows/ci.yml/badge.svg" alt="CI" /></a>
+  <a href="https://github.com/dutchakdev/bimp-mcp/actions/workflows/release.yml"><img src="https://github.com/dutchakdev/bimp-mcp/actions/workflows/release.yml/badge.svg" alt="Release" /></a>
+  <a href="https://www.npmjs.com/package/bimp-mcp"><img src="https://img.shields.io/npm/v/bimp-mcp" alt="npm" /></a>
+  <a href="https://nodejs.org"><img src="https://img.shields.io/node/v/bimp-mcp" alt="Node.js" /></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT" /></a>
+</p>
+
+<p align="center">
+  Enable LLMs to interact with BIMP data through the <a href="https://modelcontextprotocol.io">Model Context Protocol</a>:<br/>
+  read, create, update entities, perform bulk operations, and analyze business data.
+</p>
+
+---
 
 ## Features
 
-- **~135 auto-generated tools** from OpenAPI 3.1 spec -- adding a new endpoint requires only editing `bimp-api.json` and restarting
+- **~135 auto-generated tools** from OpenAPI 3.1 spec — edit `bimp-api.json`, restart, done
 - **3 utility tools** for bulk operations: `bimp_fetch_all`, `bimp_batch_read`, `bimp_bulk_update`
-- **6 MCP prompts** providing ERP domain context, workflow guides, and data analysis instructions
-- **Auto-authentication** with token refresh -- login triggered on first API call, tokens refreshed transparently on 401
+- **6 MCP prompts** with ERP domain context, workflow guides, and data analysis patterns
+- **Auto-authentication** — login on first call, transparent token refresh on 401
 
 ## Quick Start
 
 ### Prerequisites
 
 - Node.js 20+
-- A BIMP ERP account with API access
+- A [BIMP ERP](https://bimpsoft.com) account with API access
 
-### Environment Variables
+### 1. Configure environment
 
 Create a `.env` file (see `.env.example`):
 
@@ -29,22 +48,22 @@ BIMP_PASSWORD=your-password
 BIMP_COMPANY_CODE=000001398
 ```
 
-### Install and Run
+### 2. Install and run
 
 ```bash
 npm install
 npm start
 ```
 
-The server starts on stdio transport. For development with auto-reload:
+For development with auto-reload:
 
 ```bash
 npm run dev
 ```
 
-### MCP Client Configuration
+### 3. Connect your MCP client
 
-Add to your `claude_desktop_config.json` (Claude Desktop) or equivalent MCP client config:
+Add to `claude_desktop_config.json` (Claude Desktop) or equivalent:
 
 ```json
 {
@@ -63,14 +82,14 @@ Add to your `claude_desktop_config.json` (Claude Desktop) or equivalent MCP clie
 }
 ```
 
-## Available Tools
+## Tools
 
-### Auto-Generated (~135 tools)
+### Auto-generated (~135 tools)
 
-Tools are generated from `bimp-api.json` at startup. Naming convention: `bimp_{entity}_{action}`.
+Generated from `bimp-api.json` at startup. Naming: `bimp_{entity}_{action}`.
 
 | Domain | Examples |
-|--------|----------|
+|---|---|
 | **Sales** | `bimp_salesInvoice_readList`, `bimp_salesInvoice_create`, `bimp_invoiceForCustomerPayment_readList` |
 | **Inventory** | `bimp_nomenclature_readList`, `bimp_inventory_readList_cursor`, `bimp_movementOfInventories_create` |
 | **Finance** | `bimp_customerPayment_readList`, `bimp_supplierPayment_create`, `bimp_cashBox_readList` |
@@ -79,20 +98,20 @@ Tools are generated from `bimp-api.json` at startup. Naming convention: `bimp_{e
 | **Reference Data** | `bimp_counterparty_readList`, `bimp_employee_readList`, `bimp_warehouse_readList` |
 | **Auth** | `bimp_auth_listCompanies`, `bimp_auth_switchCompany` |
 
-### Utility Tools
+### Utility tools
 
 | Tool | Purpose |
-|------|---------|
-| `bimp_fetch_all` | Auto-paginate any readList endpoint. Supports offset/count, cursor, and page/pageSize pagination. Optional `enrich` mode fetches full details for each record. |
+|---|---|
+| `bimp_fetch_all` | Auto-paginate any readList. Supports offset/count, cursor, page/pageSize. Optional `enrich` mode fetches full details per record. |
 | `bimp_batch_read` | Parallel read of full details for an array of UUIDs with configurable concurrency. |
 | `bimp_bulk_update` | Mass update records with batched concurrency and per-item error reporting. |
 
-## Available Prompts
+## Prompts
 
 | Prompt | Description |
-|--------|-------------|
+|---|---|
 | `bimp_erp_context` | Entity structure, relationships, Ukrainian terminology mapping |
-| `bimp_data_analysis` | How to analyze BIMP data effectively, pagination quirks, enrichment |
+| `bimp_data_analysis` | Data analysis patterns, pagination quirks, enrichment strategies |
 | `bimp_bulk_operations` | Mass operation patterns: price updates, bulk edits, imports |
 | `bimp_sales_workflow` | Sales process: order, realization, payment, returns |
 | `bimp_production_workflow` | Production: specification, order, assembly, material write-offs |

package/dist/client.js

@@ -17,7 +17,7 @@ export class BimpClient {
     async request(method, path, params = {}, options) {
         await this.ensureAuthenticated();
         const result = await this.executeRequest(method, path, params, options?.timeout);
-        if (result.status === 401) {
+        if (result.status === 401 || result.status === 498) {
             await this.refreshAuth();
             const retry = await this.executeRequest(method, path, params, options?.timeout);
             if (!retry.ok) {
@@ -110,8 +110,8 @@ export class BimpClient {
     }
     async executeRequest(method, pathTemplate, params, timeout) {
         const resp = await this.rawFetch(method, pathTemplate, params, { "access-token": this.tokens.companyAccessToken }, timeout);
-        if (resp.status === 401) {
-            return { ok: false, status: 401, data: null };
+        if (resp.status === 401 || resp.status === 498) {
+            return { ok: false, status: resp.status, data: null };
         }
         const json = (await resp.json());
         return { ok: resp.ok, status: resp.status, data: json };

package/dist/index.js

@@ -12,6 +12,58 @@ import { createUtilityTools } from "./utilities.js";
 import { createNomenclaturesTools } from "./nomenclatures-extended.js";
 import { PROMPT_TEXTS } from "./prompts.js";
 const __dirname = dirname(fileURLToPath(import.meta.url));
+/**
+ * Maximum response size in characters.
+ * MCP clients (Claude Code, Claude Desktop) have tool result size limits.
+ * We truncate large responses to stay within safe bounds.
+ */
+const MAX_RESPONSE_SIZE = 80_000;
+/**
+ * Truncate a tool result if its JSON representation exceeds MAX_RESPONSE_SIZE.
+ * For array-based results (items/data), uses binary search to fit max items.
+ */
+function truncateResponse(result) {
+    const json = JSON.stringify(result, null, 2);
+    if (json.length <= MAX_RESPONSE_SIZE)
+        return json;
+    if (typeof result === "object" && result !== null) {
+        const obj = result;
+        const arrayKey = ["items", "data"].find((k) => Array.isArray(obj[k]));
+        if (arrayKey) {
+            const arr = obj[arrayKey];
+            const totalCount = arr.length;
+            // Binary search for max number of items that fit
+            let lo = 0;
+            let hi = arr.length;
+            while (lo < hi) {
+                const mid = Math.ceil((lo + hi) / 2);
+                const test = JSON.stringify({ ...obj, [arrayKey]: arr.slice(0, mid), count: mid, _truncated: { total: totalCount, returned: mid } }, null, 2);
+                if (test.length <= MAX_RESPONSE_SIZE) {
+                    lo = mid;
+                }
+                else {
+                    hi = mid - 1;
+                }
+            }
+            return JSON.stringify({
+                ...obj,
+                [arrayKey]: arr.slice(0, lo),
+                count: lo,
+                _truncated: {
+                    total: totalCount,
+                    returned: lo,
+                    message: `Response truncated: showing ${lo} of ${totalCount} items. ` +
+                        `To get all data, re-call with limit=${lo} and iterate using skip parameter: ` +
+                        `skip=0 limit=${lo}, then skip=${lo} limit=${lo}, etc. ` +
+                        `For bimp_fetch_all: recommended limit is 50 with enrich=true, 200 without.`,
+                },
+            }, null, 2);
+        }
+    }
+    // Fallback: hard truncate for non-array responses
+    return (json.slice(0, MAX_RESPONSE_SIZE) +
+        "\n\n... [TRUNCATED: response exceeded size limit. Use limit parameter or filters to reduce result size.]");
+}
 const config = {
     email: process.env.BIMP_EMAIL ?? "",
     password: process.env.BIMP_PASSWORD ?? "",
@@ -38,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.1" }, { 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 }, () => ({
@@ -175,7 +227,7 @@ lowLevelServer.setRequestHandler(CallToolRequestSchema, async (request) => {
             const result = await utilityTool.handler(params);
             return {
                 content: [
-                    { type: "text", text: JSON.stringify(result, null, 2) },
+                    { type: "text", text: truncateResponse(result) },
                 ],
             };
         }
@@ -185,7 +237,7 @@ lowLevelServer.setRequestHandler(CallToolRequestSchema, async (request) => {
             const result = await nomenclaturesTool.handler(params);
             return {
                 content: [
-                    { type: "text", text: JSON.stringify(result, null, 2) },
+                    { type: "text", text: truncateResponse(result) },
                 ],
             };
         }
@@ -206,7 +258,7 @@ lowLevelServer.setRequestHandler(CallToolRequestSchema, async (request) => {
             const result = await client.request(toolDef.metadata.method, toolDef.metadata.path, callParams);
             return {
                 content: [
-                    { type: "text", text: JSON.stringify(result, null, 2) },
+                    { type: "text", text: truncateResponse(result) },
                 ],
             };
         }
@@ -221,7 +273,7 @@ lowLevelServer.setRequestHandler(CallToolRequestSchema, async (request) => {
         const result = await client.request(toolDef.metadata.method, toolDef.metadata.path, params);
         return {
             content: [
-                { type: "text", text: JSON.stringify(result, null, 2) },
+                { type: "text", text: truncateResponse(result) },
             ],
         };
     }

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,54 @@ 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.",
+            "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.",
         inputSchema: {
             type: "object",
             properties: {
@@ -57,9 +99,13 @@ function createFetchAllTool(client, toolMap) {
                     type: "string",
                     description: "Name of a readList tool to paginate (e.g. bimp_nomenclature_readList)",
                 },
+                skip: {
+                    type: "number",
+                    description: "Number of items to skip from the beginning (default: 0). Use with limit to paginate: skip=0 limit=50, then skip=50 limit=50, etc.",
+                },
                 limit: {
                     type: "number",
-                    description: "Maximum number of items to return (default: unlimited)",
+                    description: "Maximum number of items to return. RECOMMENDED: 50 with enrich=true, 200 without enrich. Avoid omitting to prevent response truncation.",
                 },
                 enrich: {
                     type: "boolean",
@@ -67,16 +113,23 @@ 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"],
         },
         handler: async (params) => {
             const toolName = params.tool;
+            const skip = params.skip ?? 0;
             const limit = params.limit;
             const enrich = params.enrich;
-            const filters = (params.filters ?? {});
+            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}`);
@@ -87,14 +140,14 @@ 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));
                     const page = response.data ?? [];
                     allItems.push(...page);
-                    if (limit && allItems.length >= limit) {
-                        allItems = allItems.slice(0, limit);
+                    if (fetchLimit && allItems.length >= fetchLimit) {
+                        allItems = allItems.slice(0, fetchLimit);
                         break;
                     }
                     if (page.length < PAGE_SIZE) {
@@ -107,15 +160,15 @@ function createFetchAllTool(client, toolMap) {
                 let cursor;
                 while (true) {
                     const requestParams = {
-                        ...filters,
+                        ...serverFilters,
                         ...(cursor ? { cursor } : {}),
                         count: PAGE_SIZE,
                     };
                     const response = (await client.request(toolDef.metadata.method, toolDef.metadata.path, requestParams));
                     const page = response.data ?? [];
                     allItems.push(...page);
-                    if (limit && allItems.length >= limit) {
-                        allItems = allItems.slice(0, limit);
+                    if (fetchLimit && allItems.length >= fetchLimit) {
+                        allItems = allItems.slice(0, fetchLimit);
                         break;
                     }
                     cursor = response.cursor;
@@ -128,15 +181,15 @@ function createFetchAllTool(client, toolMap) {
                 let page = 1;
                 while (true) {
                     const requestParams = {
-                        ...filters,
+                        ...serverFilters,
                         page,
                         pageSize: PAGE_SIZE,
                     };
                     const response = (await client.request(toolDef.metadata.method, toolDef.metadata.path, requestParams));
                     const items = response.data ?? [];
                     allItems.push(...items);
-                    if (limit && allItems.length >= limit) {
-                        allItems = allItems.slice(0, limit);
+                    if (fetchLimit && allItems.length >= fetchLimit) {
+                        allItems = allItems.slice(0, fetchLimit);
                         break;
                     }
                     if (items.length < PAGE_SIZE) {
@@ -147,14 +200,27 @@ 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);
-                if (limit && allItems.length > limit) {
-                    allItems = allItems.slice(0, limit);
+                if (fetchLimit && allItems.length > fetchLimit) {
+                    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);
@@ -166,9 +232,19 @@ function createFetchAllTool(client, toolMap) {
                     .map((item) => item.uuid)
                     .filter(Boolean);
                 const { items: enrichedItems } = await batchReadUuids(client, readToolDef, uuids, 10);
-                return { items: enrichedItems, count: enrichedItems.length };
+                return {
+                    items: enrichedItems,
+                    count: enrichedItems.length,
+                    skip,
+                    hasMore: totalFetched > skip + enrichedItems.length,
+                };
             }
-            return { items: allItems, count: allItems.length };
+            return {
+                items: allItems,
+                count: allItems.length,
+                skip,
+                hasMore: totalFetched > skip + allItems.length,
+            };
         },
     };
 }
@@ -261,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.1",
+  "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",