@stubbedev/trimit-mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 stubbedev
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,230 @@
+# TRIMIT Dev MCP
+
+An MCP server that helps you construct and validate [TRIMIT API](https://apidocs.trimit.com/) calls — the fashion/apparel ERP extension layered on Microsoft Dynamics 365 Business Central. No authentication required in the server itself.
+
+Tools are loaded on demand by resource category. Ask about sales orders and the salesdocs tools appear. Ask about masters and the products tools appear. The server starts lean and grows with your needs, and always knows the OAuth setup, URL templating, and OData conventions for every operation.
+
+## What it does
+
+- Constructs valid TRIMIT / Business Central API request URLs, methods, headers, and bodies
+- Validates required and optional parameters via Zod schemas
+- Returns the OAuth 2.0 / Microsoft Entra setup for every operation
+- Returns ready-to-use fetch code examples
+- Links to official documentation
+- Explains cross-cutting concepts: OAuth auth, base URL templating, OData queries, ETag concurrency, `$batch`, paging, sales document lifecycle
+- Loads resource categories on demand — only what you need
+
+## Tools
+
+### Always available
+
+These tools are loaded immediately — no setup required.
+
+| Tool | Description |
+|---|---|
+| `list_categories` | List all resource categories and which are currently loaded |
+| `load_category` | Load tools for a category; triggers `tools/list_changed` |
+| `search_trimit_api` | Search TRIMIT API endpoints by keyword; returns a `suggestedCategory` to load |
+| `trimit_build_batch` | Build a valid `/$batch` request body from any number of operations |
+| `trimit_explain_auth` | OAuth 2.0 client credentials against Microsoft Entra |
+| `trimit_explain_base_urls` | Base URL structure; `{tenant}`, `{environment}`, `{companyId}` substitution |
+| `trimit_explain_odata` | `$filter`, `$select`, `$expand`, `$orderby`, `$top`, `$count` with examples |
+| `trimit_explain_paging` | `@odata.nextLink` iteration and the BC 20 000-row page cap |
+| `trimit_explain_concurrency` | `@odata.etag`, `If-Match`, `IEEE754Compatible` decimals |
+| `trimit_explain_batch` | OData `$batch` envelope, `dependsOn`, response matching |
+| `trimit_explain_doc_lifecycle` | Sales Import Journal → processed → posted; `exportedDocuments` markers |
+| `trimit_explain_errors` | 400 / 401 / 403 / 404 / 409 / 412 / 429 and BC error codes |
+
+### Resource categories (loaded on demand)
+
+| Category | Tools | What you get |
+|---|---|---|
+| **standard** | 8 | Microsoft BC standard API: companies (incl. ODataV4 view), items, customers (GET + PATCH defaultDimensions), `$metadata` (API + ODataV4), entityDefinitions |
+| **masterdata** | 8 | Campaigns, customerPriceGroups, priceGroupParameters, VarDimCombinations, vardimtypes, vardimtypevalues, itemAttributes, collections |
+| **products** | 4 | TRIMIT Masters (style headers), Items (SKUs), Products feed, Categories — all with full expand defaults |
+| **inventory** | 2 | Locations, Inventories (incl. Future Delivers) |
+| **customers** | 5 | TRIMIT-enriched customers list, contacts, salespersons, POST customer, PATCH customer (additionalFields, If-Match, IEEE754Compatible) |
+| **salesdocs** | 11 | Quote / Order / Invoice / Credit Memo / Blanket Order / Return Order — list, list-processed, get-by-systemId, typed lists (orders/invoices/credit memos/return orders), POST return order, POST sales document (create + add-fields), `$batch` bulk insert |
+| **postedsales** | 5 | Posted documents (union), posted invoices, posted credit memos, posted return receipts, posted shipments (with tracking lines) |
+| **exported** | 3 | GET / POST / DELETE `exportedDocuments` markers — exclude already-processed docs from future polls |
+| **metadata** | 1 | TRIMIT integration API `$metadata` (EDMX) for codegen |
+
+### Example tool output
+
+Every tool returns a structured object with the full request details and auth requirements:
+
+```json
+{
+  "endpoint": "https://api.businesscentral.dynamics.com/v2.0/{tenant}/{environment}/api/trimit/integration/v1.1/companies({companyId})/masters?$expand=masterDescriptions,masterDefDims,...",
+  "method": "GET",
+  "headers": {
+    "Authorization": "Bearer {token}",
+    "Content-Type": "application/json",
+    "Accept": "application/json"
+  },
+  "pathParams": { "tenant": "{tenant}", "environment": "{environment}", "companyId": "{companyId}" },
+  "queryParams": { "$expand": "masterDescriptions,masterDefDims,..." },
+  "body": null,
+  "description": "TRIMIT Masters (style headers).",
+  "docsUrl": "https://apidocs.trimit.com/",
+  "codeExample": "const response = await fetch('...', { method: 'GET', headers: { Authorization: 'Bearer {token}' } });\nconst data = await response.json();",
+  "auth": {
+    "type": "OAuth 2.0 — Microsoft Entra (Azure AD) client credentials",
+    "tokenEndpoint": "https://login.microsoftonline.com/{tenant}/oauth2/v2.0/token",
+    "scope": "https://api.businesscentral.dynamics.com/.default",
+    "notes": "Customer-tenant Entra app registration with Business Central / TRIMIT integration consent."
+  },
+  "notes": "Key fields: number (master code), noSystem (SKU template), masterItems → SKU variants. Heavy payload — narrow with $select and trimmed $expand for production traffic."
+}
+```
+
+---
+
+## Installation
+
+The recommended way to run this server is via `npx` — no local install needed.
+
+```
+npx -y @stubbedev/trimit-mcp
+```
+
+### Claude Desktop
+
+Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
+
+```json
+{
+  "mcpServers": {
+    "trimit-dev": {
+      "command": "npx",
+      "args": ["-y", "@stubbedev/trimit-mcp"]
+    }
+  }
+}
+```
+
+### Claude Code (CLI)
+
+```bash
+claude mcp add trimit-dev -- npx -y @stubbedev/trimit-mcp
+```
+
+Or add to your project's `.mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "trimit-dev": {
+      "command": "npx",
+      "args": ["-y", "@stubbedev/trimit-mcp"]
+    }
+  }
+}
+```
+
+### Cursor
+
+Open **Settings → MCP** and add a new server, or edit `~/.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "trimit-dev": {
+      "command": "npx",
+      "args": ["-y", "@stubbedev/trimit-mcp"]
+    }
+  }
+}
+```
+
+### Windsurf
+
+Edit `~/.codeium/windsurf/mcp_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "trimit-dev": {
+      "command": "npx",
+      "args": ["-y", "@stubbedev/trimit-mcp"]
+    }
+  }
+}
+```
+
+### Zed
+
+Edit your `settings.json` (open via **Zed → Settings → Open Settings**):
+
+```json
+{
+  "context_servers": {
+    "trimit-dev": {
+      "command": {
+        "path": "npx",
+        "args": ["-y", "@stubbedev/trimit-mcp"]
+      }
+    }
+  }
+}
+```
+
+### OpenCode
+
+Edit `~/.config/opencode/config.json`:
+
+```json
+{
+  "mcp": {
+    "trimit-dev": {
+      "type": "local",
+      "command": ["npx", "-y", "@stubbedev/trimit-mcp"]
+    }
+  }
+}
+```
+
+### Codex (OpenAI)
+
+Edit `~/.codex/config.json`:
+
+```json
+{
+  "mcpServers": {
+    "trimit-dev": {
+      "command": "npx",
+      "args": ["-y", "@stubbedev/trimit-mcp"]
+    }
+  }
+}
+```
+
+---
+
+## Development
+
+```bash
+git clone https://github.com/stubbedev/trimit-mcp.git
+cd trimit-mcp
+npm install
+npm run build
+npm start
+```
+
+For live reload during development:
+
+```bash
+npm run dev
+```
+
+### Test with MCP Inspector
+
+```bash
+npx @modelcontextprotocol/inspector npx -y @stubbedev/trimit-mcp
+```
+
+---
+
+## License
+
+MIT

package/dist/categories/customers.js

@@ -0,0 +1,187 @@
+import { z } from "zod";
+import { TRIMIT_AUTH, buildHeaders, buildOdataQuery, fetchExample, trimitBase } from "../common.js";
+const CATEGORY = "customers";
+const CUSTOMERS_DEFAULT_EXPAND = [
+    "picture",
+    "defaultDimensions",
+    "priceGroupParameters",
+    "contactsInformation",
+    "customerFinancialDetail",
+    "configuredFields",
+].join(",");
+export const customersTools = [
+    {
+        name: "trimit_customers_list",
+        description: "List TRIMIT-enriched customers (picture, priceGroupParameters, contactsInformation, customerFinancialDetail, defaultDimensions, configuredFields).",
+        category: CATEGORY,
+        zodShape: {
+            filter: z.string().optional(),
+            select: z.array(z.string()).optional(),
+            expand: z.string().optional().describe(`Default expand: ${CUSTOMERS_DEFAULT_EXPAND}`),
+            top: z.number().optional(),
+            skip: z.number().optional(),
+        },
+        handler: (args) => {
+            const expand = args.expand ?? CUSTOMERS_DEFAULT_EXPAND;
+            const { qs, params } = buildOdataQuery({ ...args, expand });
+            const endpoint = `${trimitBase()}/customers${qs}`;
+            return {
+                endpoint,
+                method: "GET",
+                headers: buildHeaders(),
+                pathParams: { tenant: "{tenant}", environment: "{environment}", companyId: "{companyId}" },
+                queryParams: params,
+                body: null,
+                description: "TRIMIT customers list.",
+                docsUrl: "https://apidocs.trimit.com/",
+                codeExample: fetchExample(endpoint, "GET", null),
+                auth: TRIMIT_AUTH,
+                notes: null,
+            };
+        },
+    },
+    {
+        name: "trimit_customers_get_contacts",
+        description: "List BC Contacts with picture expanded.",
+        category: CATEGORY,
+        zodShape: {
+            filter: z.string().optional(),
+            select: z.array(z.string()).optional(),
+            expand: z.string().optional().describe("Default: 'picture'"),
+            top: z.number().optional(),
+            skip: z.number().optional(),
+        },
+        handler: (args) => {
+            const expand = args.expand ?? "picture";
+            const { qs, params } = buildOdataQuery({ ...args, expand });
+            const endpoint = `${trimitBase()}/contacts${qs}`;
+            return {
+                endpoint,
+                method: "GET",
+                headers: buildHeaders(),
+                pathParams: { tenant: "{tenant}", environment: "{environment}", companyId: "{companyId}" },
+                queryParams: params,
+                body: null,
+                description: "Contacts.",
+                docsUrl: "https://apidocs.trimit.com/",
+                codeExample: fetchExample(endpoint, "GET", null),
+                auth: TRIMIT_AUTH,
+                notes: "Fields: companyName, addressLine1/2, city, salespersonCode, phoneNo, email, …",
+            };
+        },
+    },
+    {
+        name: "trimit_customers_get_salespersons",
+        description: "List salespersons (returns {code, name, email, phoneNo, commissionPercent, globalDimension1Code, globalDimension2Code}).",
+        category: CATEGORY,
+        zodShape: {
+            filter: z.string().optional(),
+            select: z.array(z.string()).optional(),
+            top: z.number().optional(),
+            skip: z.number().optional(),
+        },
+        handler: (args) => {
+            const { qs, params } = buildOdataQuery(args);
+            const endpoint = `${trimitBase()}/salespersons${qs}`;
+            return {
+                endpoint,
+                method: "GET",
+                headers: buildHeaders(),
+                pathParams: { tenant: "{tenant}", environment: "{environment}", companyId: "{companyId}" },
+                queryParams: params,
+                body: null,
+                description: "Salespersons list.",
+                docsUrl: "https://apidocs.trimit.com/",
+                codeExample: fetchExample(endpoint, "GET", null),
+                auth: TRIMIT_AUTH,
+                notes: null,
+            };
+        },
+    },
+    {
+        name: "trimit_customers_create",
+        description: "Create a TRIMIT customer. 201 on success. 409 if customer number already exists.",
+        category: CATEGORY,
+        zodShape: {
+            number: z.string().describe("Customer number (unique)"),
+            displayName: z.string(),
+            type: z.string().describe("e.g. 'Company' or 'Person'"),
+            addressLine1: z.string(),
+            city: z.string(),
+            country: z.string().describe("Country/region code (ISO)"),
+            postalCode: z.string(),
+            email: z.string(),
+            phoneNumber: z.string().optional(),
+            addressLine2: z.string().optional(),
+            state: z.string().optional(),
+            website: z.string().optional(),
+            salespersonCode: z.string().optional(),
+            salespersonCode2: z.string().optional(),
+            salespersonCode3: z.string().optional(),
+            creditLimit: z.number().optional(),
+            blocked: z.string().optional().describe(" ' ', 'Ship', 'Invoice', 'All'"),
+            chain: z.string().optional(),
+            companyGroup: z.string().optional(),
+            selltoGroup: z.string().optional(),
+            selltoType: z.string().optional(),
+            commissionGroup: z.string().optional(),
+            bonusGroup: z.string().optional(),
+            allocationPriority: z.number().optional(),
+            additionalFields: z
+                .array(z.object({ name: z.string(), value: z.string() }))
+                .optional()
+                .describe("Custom configuredFields"),
+        },
+        handler: (args) => {
+            const endpoint = `${trimitBase()}/customers`;
+            const body = Object.fromEntries(Object.entries(args).filter(([, v]) => v !== undefined));
+            return {
+                endpoint,
+                method: "POST",
+                headers: buildHeaders(),
+                pathParams: { tenant: "{tenant}", environment: "{environment}", companyId: "{companyId}" },
+                queryParams: {},
+                body,
+                description: "Create a new customer.",
+                docsUrl: "https://apidocs.trimit.com/",
+                codeExample: fetchExample(endpoint, "POST", body),
+                auth: TRIMIT_AUTH,
+                notes: "201 returns the created customer with @odata.etag + systemId. 409 'EntityWithSameKeyExists' means number is taken. additionalFields targets BC configuredFields table.",
+            };
+        },
+    },
+    {
+        name: "trimit_customers_patch",
+        description: "Patch a TRIMIT customer (typically additionalFields). Sends If-Match for OData concurrency and IEEE754Compatible: true for decimal handling.",
+        category: CATEGORY,
+        zodShape: {
+            customerId: z.string().describe("Customer systemId GUID"),
+            ifMatch: z.string().default("*").describe("ETag from a prior GET, or '*' for unconditional"),
+            additionalFields: z
+                .array(z.object({ name: z.string(), value: z.string() }))
+                .optional()
+                .describe("Replacement set of additionalFields"),
+            patch: z.record(z.string(), z.unknown()).optional().describe("Other fields to PATCH (e.g. { creditLimit: 5000 })"),
+        },
+        handler: (args) => {
+            const endpoint = `${trimitBase()}/customers(${args.customerId})?$expand=additionalFields`;
+            const body = { ...(args.patch ?? {}) };
+            if (args.additionalFields)
+                body.additionalFields = args.additionalFields;
+            const extraHeaders = { "If-Match": args.ifMatch ?? "*", "IEEE754Compatible": "true" };
+            return {
+                endpoint,
+                method: "PATCH",
+                headers: buildHeaders(extraHeaders),
+                pathParams: { tenant: "{tenant}", environment: "{environment}", companyId: "{companyId}", customerId: args.customerId },
+                queryParams: { $expand: "additionalFields" },
+                body,
+                description: "Patch a customer.",
+                docsUrl: "https://apidocs.trimit.com/",
+                codeExample: fetchExample(endpoint, "PATCH", body, extraHeaders),
+                auth: TRIMIT_AUTH,
+                notes: "If-Match: '*' bypasses optimistic concurrency. Use the @odata.etag value from a prior GET for safe concurrent updates. IEEE754Compatible: true forces decimals to be sent/received as JSON strings (BC convention) to avoid precision loss.",
+            };
+        },
+    },
+];

package/dist/categories/exported.js

@@ -0,0 +1,105 @@
+import { z } from "zod";
+import { TRIMIT_AUTH, buildHeaders, fetchExample, trimitBase } from "../common.js";
+const CATEGORY = "exported";
+const DOC_TYPES = [
+    "Quote",
+    "Order",
+    "Invoice",
+    "Credit Memo",
+    "Blanket Order",
+    "Return Order",
+    "Posted Invoice",
+    "Posted Credit Memo",
+    "Posted Shipment",
+    "Posted Return Receipt",
+];
+export const exportedTools = [
+    {
+        name: "trimit_exported_get",
+        description: "Check whether a specific document has been marked exported (and is therefore excluded from default sales document polls).",
+        category: CATEGORY,
+        zodShape: {
+            documentType: z.enum(DOC_TYPES).describe("Case-sensitive doc type"),
+            documentNumber: z.string(),
+        },
+        handler: (args) => {
+            const endpoint = `${trimitBase()}/exportedDocuments('${encodeURIComponent(args.documentType)}','${encodeURIComponent(args.documentNumber)}')`;
+            return {
+                endpoint,
+                method: "GET",
+                headers: buildHeaders(),
+                pathParams: {
+                    tenant: "{tenant}",
+                    environment: "{environment}",
+                    companyId: "{companyId}",
+                    documentType: args.documentType,
+                    documentNumber: args.documentNumber,
+                },
+                queryParams: {},
+                body: null,
+                description: "Lookup an exported document marker.",
+                docsUrl: "https://apidocs.trimit.com/",
+                codeExample: fetchExample(endpoint, "GET", null),
+                auth: TRIMIT_AUTH,
+                notes: "404 means the doc has not been marked exported. documentType is case-sensitive — match the doc-type string exactly.",
+            };
+        },
+    },
+    {
+        name: "trimit_exported_create",
+        description: "Mark a document as exported. After this, subsequent GET /salesDocuments calls will exclude the doc (until it is un-marked).",
+        category: CATEGORY,
+        zodShape: {
+            type: z.enum(DOC_TYPES),
+            number: z.string(),
+        },
+        handler: (args) => {
+            const endpoint = `${trimitBase()}/exportedDocuments`;
+            const body = { type: args.type, number: args.number };
+            return {
+                endpoint,
+                method: "POST",
+                headers: buildHeaders(),
+                pathParams: { tenant: "{tenant}", environment: "{environment}", companyId: "{companyId}" },
+                queryParams: {},
+                body,
+                description: "Mark a document exported.",
+                docsUrl: "https://apidocs.trimit.com/",
+                codeExample: fetchExample(endpoint, "POST", body),
+                auth: TRIMIT_AUTH,
+                notes: "One call per document — there is no batch variant. Idempotent: re-marking an already-exported doc returns the existing record.",
+            };
+        },
+    },
+    {
+        name: "trimit_exported_delete",
+        description: "Un-mark exported (error recovery — re-includes the doc in future polls). Returns 204.",
+        category: CATEGORY,
+        zodShape: {
+            documentType: z.enum(DOC_TYPES),
+            documentNumber: z.string(),
+        },
+        handler: (args) => {
+            const endpoint = `${trimitBase()}/exportedDocuments('${encodeURIComponent(args.documentType)}','${encodeURIComponent(args.documentNumber)}')`;
+            return {
+                endpoint,
+                method: "DELETE",
+                headers: buildHeaders(),
+                pathParams: {
+                    tenant: "{tenant}",
+                    environment: "{environment}",
+                    companyId: "{companyId}",
+                    documentType: args.documentType,
+                    documentNumber: args.documentNumber,
+                },
+                queryParams: {},
+                body: null,
+                description: "Delete an exported-document marker.",
+                docsUrl: "https://apidocs.trimit.com/",
+                codeExample: fetchExample(endpoint, "DELETE", null),
+                auth: TRIMIT_AUTH,
+                notes: "204 No Content on success. Use to re-import a doc you previously marked exported by mistake.",
+            };
+        },
+    },
+];

package/dist/categories/index.js

@@ -0,0 +1,9 @@
+export { standardTools } from "./standard.js";
+export { masterdataTools } from "./masterdata.js";
+export { productsTools } from "./products.js";
+export { inventoryTools } from "./inventory.js";
+export { customersTools } from "./customers.js";
+export { salesdocsTools } from "./salesdocs.js";
+export { postedsalesTools } from "./postedsales.js";
+export { exportedTools } from "./exported.js";
+export { metadataTools } from "./metadata.js";

package/dist/categories/inventory.js

@@ -0,0 +1,63 @@
+import { z } from "zod";
+import { TRIMIT_AUTH, buildHeaders, buildOdataQuery, fetchExample, trimitBase } from "../common.js";
+const CATEGORY = "inventory";
+export const inventoryTools = [
+    {
+        name: "trimit_inventory_get_locations",
+        description: "List warehouse locations.",
+        category: CATEGORY,
+        zodShape: {
+            filter: z.string().optional(),
+            select: z.array(z.string()).optional(),
+            top: z.number().optional(),
+            skip: z.number().optional(),
+        },
+        handler: (args) => {
+            const { qs, params } = buildOdataQuery(args);
+            const endpoint = `${trimitBase()}/locations${qs}`;
+            return {
+                endpoint,
+                method: "GET",
+                headers: buildHeaders(),
+                pathParams: { tenant: "{tenant}", environment: "{environment}", companyId: "{companyId}" },
+                queryParams: params,
+                body: null,
+                description: "Warehouse / location master.",
+                docsUrl: "https://apidocs.trimit.com/",
+                codeExample: fetchExample(endpoint, "GET", null),
+                auth: TRIMIT_AUTH,
+                notes: null,
+            };
+        },
+    },
+    {
+        name: "trimit_inventory_get_inventories",
+        description: "Get inventory / availability per (item, location). When TRIMIT 'Export Future Delivers' is enabled, includes pre-order stock.",
+        category: CATEGORY,
+        zodShape: {
+            filter: z.string().optional().describe("e.g. \"itemNo eq '20002036'\" or filter on locationCode"),
+            select: z.array(z.string()).optional(),
+            top: z.number().optional(),
+            skip: z.number().optional(),
+            readOnly: z.boolean().optional().describe("Send Data-Access-Intent: ReadOnly. Default true."),
+        },
+        handler: (args) => {
+            const { qs, params } = buildOdataQuery(args);
+            const endpoint = `${trimitBase()}/inventories${qs}`;
+            const extra = args.readOnly !== false ? { "Data-Access-Intent": "ReadOnly" } : undefined;
+            return {
+                endpoint,
+                method: "GET",
+                headers: buildHeaders(extra),
+                pathParams: { tenant: "{tenant}", environment: "{environment}", companyId: "{companyId}" },
+                queryParams: params,
+                body: null,
+                description: "Inventory availability per (item, location).",
+                docsUrl: "https://apidocs.trimit.com/",
+                codeExample: fetchExample(endpoint, "GET", null, extra),
+                auth: TRIMIT_AUTH,
+                notes: "For frequent inventory polling prefer narrow filters + Data-Access-Intent: ReadOnly. Heavy aggregations should use $top/$skip pagination.",
+            };
+        },
+    },
+];