bimp-mcp 0.3.0 → 0.3.3

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.0" }, { capabilities: { logging: {} } });
+const server = new McpServer({ name: "bimp-mcp", version: "0.3.3" }, { 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/utilities.js

@@ -49,7 +49,10 @@ function createFetchAllTool(client, toolMap) {
         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" +
+            "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 +60,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",
@@ -74,9 +81,12 @@ function createFetchAllTool(client, toolMap) {
         },
         handler: async (params) => {
             const toolName = params.tool;
+            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 toolDef = toolMap.get(toolName);
             if (!toolDef) {
                 throw new Error(`Tool not found: ${toolName}`);
@@ -93,8 +103,8 @@ function createFetchAllTool(client, toolMap) {
                     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) {
@@ -114,8 +124,8 @@ function createFetchAllTool(client, toolMap) {
                     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;
@@ -135,8 +145,8 @@ function createFetchAllTool(client, toolMap) {
                     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) {
@@ -151,10 +161,15 @@ function createFetchAllTool(client, toolMap) {
                 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 skip — slice off the first `skip` items
+            const totalFetched = allItems.length;
+            if (skip > 0) {
+                allItems = allItems.slice(skip);
+            }
             // Enrich: call the read endpoint for each item
             if (enrich && allItems.length > 0) {
                 const readToolName = deriveReadToolName(toolName);
@@ -166,9 +181,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,
+            };
         },
     };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bimp-mcp",
-  "version": "0.3.0",
+  "version": "0.3.3",
   "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",
@@ -21,7 +21,11 @@
     "test:functional": "vitest run --project functional",
     "test:all": "vitest run",
     "test:watch": "vitest --project unit",
-    "demo:nomenclatures": "tsx scripts/demo-nomenclatures.ts"
+    "demo:nomenclatures": "tsx scripts/demo-nomenclatures.ts",
+    "release": "./scripts/release.sh",
+    "release:patch": "./scripts/release.sh patch",
+    "release:minor": "./scripts/release.sh minor",
+    "release:major": "./scripts/release.sh major"
   },
   "keywords": [
     "mcp",