@procurementexpress.com/mcp 1.0.0 → 2.0.0

package/dist/tools/invoices.js

@@ -1,46 +1,88 @@
 import { z } from "zod";
 import { jsonResponse, withErrorHandling } from "../tool-helpers.js";
+const customFieldValueSchema = z.object({
+    id: z.number().int().optional().describe("Custom field value ID (for updates)"),
+    value: z.string().describe("Custom field value"),
+    custom_field_id: z.number().int().describe("Custom field ID"),
+});
 const invoiceLineItemSchema = z.object({
-    description: z.string().describe("Line item description"),
-    unit_price: z.number().describe("Unit price"),
-    quantity: z.number().describe("Quantity"),
-    vat: z.number().optional().describe("VAT amount"),
+    id: z.number().int().optional().describe("Line item ID (for updates)"),
+    description: z.string().optional().describe("Line item description"),
+    unit_price: z.number().optional().describe("Unit price"),
+    quantity: z.number().optional().describe("Quantity"),
+    vat: z.number().optional().describe("VAT/tax percentage"),
     net_amount: z.number().optional().describe("Net amount"),
-    purchase_order_id: z.number().int().optional().describe("Related PO ID"),
-    purchase_order_item_id: z.number().int().optional().describe("Related PO item ID"),
+    sequence_no: z.number().int().optional().describe("Sequence number for ordering"),
+    tax_rate_id: z.number().int().optional().describe("Tax rate ID"),
+    chart_of_account_id: z.number().int().optional().describe("Chart of account ID (GL code)"),
+    qbo_customer_id: z.number().int().optional().describe("QuickBooks customer ID"),
+    quickbooks_class_id: z.number().int().optional().describe("QuickBooks class ID"),
+    qbo_line_description: z.string().optional().describe("QuickBooks line description override"),
+    purchase_order_id: z.number().int().optional().describe("Related purchase order ID"),
+    purchase_order_item_id: z.number().int().optional().describe("Related PO line item ID"),
+    billable_status: z.string().optional().describe("Billable status for QuickBooks"),
+    _destroy: z.boolean().optional().describe("Set true to remove this line item on update"),
+    custom_field_values_attributes: z.array(customFieldValueSchema).optional().describe("Custom field values for this line item"),
 });
 export function registerInvoiceTools(server, apiClient) {
     server.registerTool("list_invoices", {
-        description: "List invoices with pagination and filters (100 per page)",
+        description: "List invoices with pagination and filters. Returns paginated results with meta info (current_page, next_page, prev_page, total_pages, total_count). Per-page count is controlled by company settings (default 10, allowed: 10, 20, 50, 100).",
         inputSchema: {
-            page: z.number().int().positive().optional().describe("Page number"),
-            archived: z.boolean().optional().describe("Filter by archived status"),
-            requester_id: z.number().int().optional().describe("Filter by requester ID"),
-            approver_id: z.number().int().optional().describe("Filter by approver ID"),
+            page: z.number().int().positive().optional().describe("Page number (default: 1)"),
+            per_page: z.number().int().optional().describe("Results per page (allowed: 10, 20, 50, 100)"),
+            search: z.string().optional().describe("Search term — matches invoice number, supplier name"),
+            invoice_statuses_filter: z
+                .enum(["awaiting_review", "outstanding", "ready_to_pay", "settled", "cancelled"])
+                .optional()
+                .describe("Filter by invoice status"),
+            archived: z.boolean().optional().describe("Filter by archived status (default: false)"),
             supplier_id: z.number().int().optional().describe("Filter by supplier ID"),
-            invoice_date_filter: z.string().optional().describe("Date filter (e.g. 'last 7days')"),
+            requester_id: z.number().int().optional().describe("Filter by requester/creator user ID"),
+            approver_id: z.number().int().optional().describe("Filter by approver user ID"),
+            department_id: z.number().int().optional().describe("Filter by department ID (via linked POs)"),
+            invoice_date_filter: z
+                .enum(["last 7days", "last 30days", "last 60days", "last 90days", "last 180days", "last 1year", "current_month", "current_year", "last_month", "last_year"])
+                .optional()
+                .describe("Predefined date range filter"),
+            sage_exported: z.boolean().optional().describe("Filter by Sage export status"),
+            sort: z.string().optional().describe("Sort column (e.g. 'invoices.created_at', 'invoices.issue_date')"),
+            direction: z.enum(["asc", "desc"]).optional().describe("Sort direction (default: desc)"),
         },
     }, withErrorHandling(async (args) => {
         const params = new URLSearchParams();
         if (args.page)
             params.set("page", String(args.page));
+        if (args.per_page)
+            params.set("per_page", String(args.per_page));
+        if (args.search)
+            params.set("search[query]", args.search);
+        if (args.invoice_statuses_filter)
+            params.set("invoice_statuses_filter", args.invoice_statuses_filter);
         if (args.archived !== undefined)
             params.set("archived", String(args.archived));
+        if (args.supplier_id)
+            params.set("supplier_id", String(args.supplier_id));
         if (args.requester_id)
             params.set("requester_id", String(args.requester_id));
         if (args.approver_id)
             params.set("approver_id", String(args.approver_id));
-        if (args.supplier_id)
-            params.set("supplier_id", String(args.supplier_id));
+        if (args.department_id)
+            params.set("department_id", String(args.department_id));
         if (args.invoice_date_filter)
             params.set("invoice_date_filter", args.invoice_date_filter);
+        if (args.sage_exported !== undefined)
+            params.set("sage_exported", String(args.sage_exported));
+        if (args.sort)
+            params.set("sort", args.sort);
+        if (args.direction)
+            params.set("direction", args.direction);
         const query = params.toString();
         const path = `${apiClient.buildPath("/invoices")}${query ? `?${query}` : ""}`;
         const result = await apiClient.get(path);
         return jsonResponse(result);
     }));
     server.registerTool("get_invoice", {
-        description: "Get invoice details by ID",
+        description: "Get invoice details by ID, including line items, linked POs, and comments",
         inputSchema: {
             id: z.number().int().positive().describe("Invoice ID"),
         },
@@ -49,24 +91,29 @@ export function registerInvoiceTools(server, apiClient) {
         return jsonResponse(invoice);
     }));
     server.registerTool("create_invoice", {
-        description: "Create a new invoice",
+        description: "Create a new invoice. If the company has 'create invoice in awaiting review' enabled, the invoice starts in awaiting_review status.",
         inputSchema: {
-            invoice_number: z.string().optional().describe("Invoice number"),
-            issue_date: z.string().optional().describe("Issue date"),
-            supplier_id: z.number().int().optional().describe("Supplier ID"),
+            invoice_number: z.string().optional().describe("Invoice number/reference"),
+            issue_date: z.string().optional().describe("Issue date (format depends on company date_format)"),
+            uploaded_date: z.string().optional().describe("Upload date"),
             received_date: z.string().optional().describe("Received date"),
             due_date: z.string().optional().describe("Due date"),
-            gross_amount: z.number().describe("Gross amount"),
-            currency_id: z.number().int().describe("Currency ID"),
-            company_id: z.number().int().describe("Company ID"),
+            gross_amount: z.number().optional().describe("Gross amount"),
+            currency_id: z.number().int().optional().describe("Currency ID"),
+            supplier_id: z.number().int().optional().describe("Supplier ID"),
+            standalone_invoice: z.boolean().optional().describe("True if invoice is not linked to any PO"),
+            payment_term_id: z.number().int().optional().describe("Payment term ID"),
+            selected_purchase_order_ids: z.array(z.number().int()).optional().describe("PO IDs to link this invoice to"),
             line_items: z.array(invoiceLineItemSchema).optional().describe("Invoice line items"),
+            custom_field_values_attributes: z.array(customFieldValueSchema).optional().describe("Invoice-level custom field values"),
         },
     }, withErrorHandling(async (args) => {
-        const { line_items, ...invoiceData } = args;
+        const { line_items, custom_field_values_attributes, ...invoiceData } = args;
         const body = {
             invoice: {
                 ...invoiceData,
                 ...(line_items ? { invoice_line_items_attributes: line_items } : {}),
+                ...(custom_field_values_attributes ? { custom_field_values_attributes } : {}),
             },
         };
         const invoice = await apiClient.post(apiClient.buildPath("/invoices"), body);
@@ -78,45 +125,60 @@ export function registerInvoiceTools(server, apiClient) {
             id: z.number().int().positive().describe("Invoice ID"),
             invoice_number: z.string().optional().describe("Invoice number"),
             issue_date: z.string().optional().describe("Issue date"),
-            supplier_id: z.number().int().optional().describe("Supplier ID"),
+            uploaded_date: z.string().optional().describe("Upload date"),
+            received_date: z.string().optional().describe("Received date"),
             due_date: z.string().optional().describe("Due date"),
             gross_amount: z.number().optional().describe("Gross amount"),
+            currency_id: z.number().int().optional().describe("Currency ID"),
+            supplier_id: z.number().int().optional().describe("Supplier ID"),
+            standalone_invoice: z.boolean().optional().describe("Standalone invoice flag"),
+            payment_term_id: z.number().int().optional().describe("Payment term ID"),
+            selected_purchase_order_ids: z.array(z.number().int()).optional().describe("PO IDs to link"),
+            line_items: z.array(invoiceLineItemSchema).optional().describe("Invoice line items (include id to update, _destroy to remove)"),
+            custom_field_values_attributes: z.array(customFieldValueSchema).optional().describe("Invoice-level custom field values"),
         },
     }, withErrorHandling(async (args) => {
-        const { id, ...data } = args;
-        const invoice = await apiClient.put(apiClient.buildPath(`/invoices/${id}`), { invoice: data });
+        const { id, line_items, custom_field_values_attributes, ...data } = args;
+        const body = {
+            invoice: {
+                ...data,
+                ...(line_items ? { invoice_line_items_attributes: line_items } : {}),
+                ...(custom_field_values_attributes ? { custom_field_values_attributes } : {}),
+            },
+        };
+        const invoice = await apiClient.put(apiClient.buildPath(`/invoices/${id}`), body);
         return jsonResponse(invoice);
     }));
     server.registerTool("accept_invoice", {
-        description: "Accept an invoice that is awaiting review",
+        description: "Accept an invoice that is in awaiting_review status",
         inputSchema: { id: z.number().int().positive().describe("Invoice ID") },
     }, withErrorHandling(async (args) => {
         const result = await apiClient.put(apiClient.buildPath(`/invoices/${args.id}/accept`));
         return jsonResponse(result);
     }));
     server.registerTool("approve_invoice", {
-        description: "Approve an invoice",
+        description: "Approve an invoice (requires invoice approval permission)",
         inputSchema: { id: z.number().int().positive().describe("Invoice ID") },
     }, withErrorHandling(async (args) => {
         const result = await apiClient.put(apiClient.buildPath(`/invoices/${args.id}/approve`));
         return jsonResponse(result);
     }));
     server.registerTool("reject_invoice", {
-        description: "Reject an invoice",
+        description: "Reject an invoice (requires invoice approval permission)",
         inputSchema: { id: z.number().int().positive().describe("Invoice ID") },
     }, withErrorHandling(async (args) => {
         const result = await apiClient.put(apiClient.buildPath(`/invoices/${args.id}/reject`));
         return jsonResponse(result);
     }));
     server.registerTool("cancel_invoice", {
-        description: "Cancel an invoice",
+        description: "Cancel an invoice (requires cancel permission)",
         inputSchema: { id: z.number().int().positive().describe("Invoice ID") },
     }, withErrorHandling(async (args) => {
         const result = await apiClient.put(apiClient.buildPath(`/invoices/${args.id}/cancel`));
         return jsonResponse(result);
     }));
     server.registerTool("archive_invoice", {
-        description: "Archive an invoice",
+        description: "Archive an invoice (requires archive permission)",
         inputSchema: { id: z.number().int().positive().describe("Invoice ID") },
     }, withErrorHandling(async (args) => {
         const result = await apiClient.put(apiClient.buildPath(`/invoices/${args.id}/archive`));
@@ -129,4 +191,11 @@ export function registerInvoiceTools(server, apiClient) {
         const result = await apiClient.put(apiClient.buildPath(`/invoices/${args.id}/dearchive`));
         return jsonResponse(result);
     }));
+    server.registerTool("rerun_invoice_approval_flow", {
+        description: "Rerun the approval flow for an invoice. Useful when approval flow rules have changed.",
+        inputSchema: { id: z.number().int().positive().describe("Invoice ID") },
+    }, withErrorHandling(async (args) => {
+        const result = await apiClient.post(apiClient.buildPath(`/invoices/${args.id}/rerun_approval_flow`));
+        return jsonResponse(result);
+    }));
 }

package/dist/tools/payments.js

@@ -1,11 +1,19 @@
 import { z } from "zod";
 import { jsonResponse, withErrorHandling } from "../tool-helpers.js";
 export function registerPaymentTools(server, apiClient) {
+    server.registerTool("get_payment", {
+        description: "Get payment details by ID",
+        inputSchema: {
+            id: z.number().int().positive().describe("Payment ID"),
+        },
+    }, withErrorHandling(async (args) => {
+        const payment = await apiClient.get(apiClient.buildPath(`/npayments/${args.id}`));
+        return jsonResponse(payment);
+    }));
     server.registerTool("create_payment", {
-        description: "Create a payment (feature flagged). ptype values: bank_transfer, card, credit_card, check, cash, one_time_card, letter_of_credit, other",
+        description: "Create a payment to settle invoices and/or purchase orders (feature flagged — contact sales to enable). The payment date must match the company's date_format setting.",
         inputSchema: {
-            user_id: z.number().int().describe("Payment creator user ID"),
-            reference: z.string().optional().describe("Reference number"),
+            reference: z.string().optional().describe("Payment reference number"),
             supplier_id: z.number().int().describe("Supplier ID"),
             ptype: z
                 .enum([
@@ -19,44 +27,68 @@ export function registerPaymentTools(server, apiClient) {
                 "other",
             ])
                 .describe("Payment type"),
-            date: z.string().describe("Payment date"),
+            payment_mode: z.string().optional().describe("Payment mode"),
+            status: z.string().optional().describe("Payment status"),
+            date: z.string().describe("Payment date (must match company date_format setting)"),
             currency_id: z.number().int().describe("Currency ID"),
-            amount: z.number().describe("Total amount (must match sum of invoice amounts)"),
+            amount: z.number().describe("Total payment amount"),
             invoices: z
                 .array(z.object({
                 invoice_id: z.number().int().describe("Invoice ID"),
-                gross_amount: z.number().describe("Amount for this invoice"),
+                gross_amount: z.number().describe("Amount to apply to this invoice"),
+            }))
+                .optional()
+                .describe("Invoices to pay with amounts"),
+            purchase_orders: z
+                .array(z.object({
+                purchase_order_id: z.number().int().describe("Purchase Order ID"),
+                budget_id: z.number().int().optional().describe("Budget ID"),
+                gross_amount: z.number().describe("Amount to apply to this PO"),
+            }))
+                .optional()
+                .describe("Purchase orders to pay with amounts"),
+            comments: z
+                .array(z.object({
+                comment: z.string().describe("Comment text"),
             }))
-                .describe("Invoices to pay"),
+                .optional()
+                .describe("Payment comments"),
         },
     }, withErrorHandling(async (args) => {
-        const { invoices, ...paymentData } = args;
+        const { invoices, purchase_orders, comments, ...paymentData } = args;
         const body = {
             npayment: {
                 ...paymentData,
-                npayment_invoices_attributes: invoices,
+                ...(invoices ? { npayment_invoices_attributes: invoices } : {}),
+                ...(purchase_orders ? { npayment_link_orders_attributes: purchase_orders } : {}),
+                ...(comments ? { npayment_comments_attributes: comments } : {}),
             },
         };
         const payment = await apiClient.post(apiClient.buildPath("/npayments"), body);
         return jsonResponse(payment);
     }));
     server.registerTool("create_po_payment", {
-        description: "Create a payment for a purchase order",
+        description: "Create a payment for a specific purchase order with optional item-level breakdown. Marks PO items as paid.",
         inputSchema: {
             purchase_order_id: z.number().int().positive().describe("Purchase Order ID"),
+            amount: z.number().optional().describe("Total payment amount (if not using item-level payments)"),
             note: z.string().optional().describe("Payment note"),
             item_payments: z
                 .array(z.object({
-                purchase_order_item_id: z.number().int().describe("PO item ID"),
+                purchase_order_item_id: z.number().int().describe("PO line item ID"),
                 amount: z.number().describe("Payment amount for this item"),
             }))
+                .optional()
                 .describe("Item-level payment amounts"),
         },
     }, withErrorHandling(async (args) => {
         const body = {
             payment: {
-                note: args.note,
-                purchase_order_item_payments_attributes: args.item_payments,
+                ...(args.amount !== undefined ? { amount: args.amount } : {}),
+                ...(args.note ? { note: args.note } : {}),
+                ...(args.item_payments
+                    ? { purchase_order_item_payments_attributes: args.item_payments }
+                    : {}),
             },
         };
         const result = await apiClient.post(apiClient.buildPath(`/purchase_orders/${args.purchase_order_id}/payments`), body);

package/dist/tools/products.js

@@ -2,13 +2,19 @@ import { z } from "zod";
 import { jsonResponse, withErrorHandling } from "../tool-helpers.js";
 export function registerProductTools(server, apiClient) {
     server.registerTool("list_products", {
-        description: "List products with optional filters for supplier and archived status",
+        description: "List products. When page param is provided, returns paginated response with meta. Without page param, returns all products as an array. Can filter by supplier and archived status.",
         inputSchema: {
+            page: z.number().int().positive().optional().describe("Page number — enables pagination"),
+            per_page: z.number().int().positive().optional().describe("Results per page (default: 20)"),
             supplier_id: z.number().int().optional().describe("Filter by supplier ID"),
-            archived: z.boolean().optional().describe("Filter by archived status"),
+            archived: z.boolean().optional().describe("Filter by archived status (default: false)"),
         },
     }, withErrorHandling(async (args) => {
         const params = new URLSearchParams();
+        if (args.page)
+            params.set("page", String(args.page));
+        if (args.per_page)
+            params.set("per_page", String(args.per_page));
         if (args.supplier_id)
             params.set("supplier_id", String(args.supplier_id));
         if (args.archived !== undefined)
@@ -28,12 +34,12 @@ export function registerProductTools(server, apiClient) {
         return jsonResponse(product);
     }));
     server.registerTool("create_product", {
-        description: "Create a new product",
+        description: "Create a new product and associate it with a supplier",
         inputSchema: {
             description: z.string().describe("Product description (required)"),
+            supplier_id: z.number().int().describe("Supplier ID (required — product is associated with this supplier)"),
             sku: z.string().optional().describe("SKU code"),
             unit_price: z.number().optional().describe("Unit price"),
-            supplier_id: z.number().int().optional().describe("Supplier ID"),
         },
     }, withErrorHandling(async (args) => {
         const product = await apiClient.post(apiClient.buildPath("/products"), { product: args });
@@ -47,7 +53,6 @@ export function registerProductTools(server, apiClient) {
             sku: z.string().optional().describe("SKU code"),
             unit_price: z.number().optional().describe("Unit price"),
             supplier_id: z.number().int().optional().describe("Supplier ID"),
-            archived: z.boolean().optional().describe("Archive status"),
         },
     }, withErrorHandling(async (args) => {
         const { id, ...data } = args;