pleaxy-mcp 0.1.1

package/dist/server.js

@@ -0,0 +1,479 @@
+import { readFileSync } from "node:fs";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { isSignedIn, pleaxyAccountRequest, pleaxyRequest } from "./api.js";
+import { buyerQualifier, pathSegment, resourceId, withBuyer } from "./ids.js";
+import { createPurchaseOrderShape } from "./purchase-order-shape.js";
+import { quoteRejectionNotes, rejectInvoiceShape } from "./rejection.js";
+import { saveQuestionnaireShape } from "./questionnaire-shape.js";
+import { createReceiptShape, rejectReceiptShape, returnReceiptShape } from "./receipt-shape.js";
+import { convertPurchaseRequestShape, createPurchaseRequestShape } from "./purchase-request-shape.js";
+import { z } from "zod";
+export const VERSION = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version;
+const reads = { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false };
+const adds = (idempotentHint) => ({ readOnlyHint: false, destructiveHint: false, idempotentHint, openWorldHint: false });
+const changes = (idempotentHint) => ({ readOnlyHint: false, destructiveHint: true, idempotentHint, openWorldHint: false });
+function ok(data) {
+    return { content: [{ type: "text", text: JSON.stringify(quoteRejectionNotes(data), null, 2) }] };
+}
+function failed(error) {
+    return { isError: true, content: [{ type: "text", text: error instanceof Error ? error.message : String(error) }] };
+}
+async function decide(tool, params, withApiKey) {
+    try {
+        if (!isSignedIn())
+            return ok(await withApiKey());
+        const created = await pleaxyRequest("/agent-requests", { method: "POST", body: { tool, params } });
+        return ok({
+            ...created,
+            note: `Nothing has been done yet. This was sent to the user to confirm in Pleaxy${created.reviewUrl ? ` (${created.reviewUrl})` : ""} before ${created.expiresAt}. Tell them it's waiting for them; don't say it's done, and don't send it again. get_agent_request says where it stands.`,
+        });
+    }
+    catch (e) {
+        return failed(e);
+    }
+}
+export function createServer() {
+    const server = new McpServer({ name: "pleaxy", title: "Pleaxy", version: VERSION });
+    server.registerTool("get_buyer_workspace", {
+        title: "Get buyer workspace",
+        description: "Buyer: an overview of this workspace's purchase orders and invoices. Start here to find ids and what needs attention on the buyer side.",
+        annotations: reads,
+    }, async () => {
+        try {
+            return ok(await pleaxyRequest("/buyer"));
+        }
+        catch (e) {
+            return failed(e);
+        }
+    });
+    server.registerTool("get_supplier_workspace", {
+        title: "Get supplier workspace",
+        description: "Supplier: an overview of the purchase orders you received and the invoices you issued in this workspace. Start here to find ids on the supplier side.",
+        annotations: reads,
+    }, async () => {
+        try {
+            return ok(await pleaxyRequest("/supplier"));
+        }
+        catch (e) {
+            return failed(e);
+        }
+    });
+    server.registerTool("list_catalog_suppliers", {
+        title: "List suppliers with an open catalog",
+        description: "Buyer: which of your approved suppliers have an open catalog you can order from, with each one's item count and how many items are priced in your currency. Gives the connectionId list_supplier_catalog needs.",
+        annotations: reads,
+    }, async () => {
+        try {
+            return ok(await pleaxyRequest("/catalog/browse/suppliers"));
+        }
+        catch (e) {
+            return failed(e);
+        }
+    });
+    server.registerTool("list_supplier_catalog", {
+        title: "Search one supplier's catalog",
+        description: "Buyer: find items to order in one connected supplier's catalog, priced for you - your contracted rate where your org recorded one, otherwise the supplier's list price. An item not priced in your region's currency has no unitPrice: Pleaxy never converts currencies.",
+        inputSchema: {
+            connectionId: resourceId.describe("From list_catalog_suppliers."),
+            q: z.string().optional().describe("Case-insensitive substring over sku, name, description and category."),
+        },
+        annotations: reads,
+    }, async ({ connectionId, q }) => {
+        try {
+            const query = new URLSearchParams({ connectionId, ...(q ? { q } : {}) });
+            return ok(await pleaxyRequest(`/catalog/browse/items?${query.toString()}`));
+        }
+        catch (e) {
+            return failed(e);
+        }
+    });
+    server.registerTool("get_purchase_order", {
+        title: "Get a purchase order",
+        description: "One purchase order by id: its lines, what was invoiced against it, and how its invoices are matched. `matching` is two_way (against the order and its contract) or three_way (also against what was received), with `received` per line, `receiptState` (none, partial or full), `receiptRequired` (whether invoices wait for receipts) and `readyToInvoice` (received but not invoiced yet). A cloud provider's order is matched against usage and has none of these. If several of your buyers use this id, the call fails listing them; call again with `buyer`.",
+        inputSchema: { poId: resourceId, buyer: buyerQualifier },
+        annotations: reads,
+    }, async ({ poId, buyer }) => {
+        try {
+            return ok(await pleaxyRequest(withBuyer(`/purchase-orders/${pathSegment(poId)}`, buyer)));
+        }
+        catch (e) {
+            return failed(e);
+        }
+    });
+    server.registerTool("create_purchase_order", {
+        title: "Create a purchase order",
+        description: "Buyer: raise a new purchase order to a supplier or cloud provider. `supplier` is who you buy from (e.g. \"aws\"), not your own org. With an API key the order is created at once. Signed in as the user (`npx pleaxy-mcp login`), this sends them an agent request to confirm in Pleaxy and changes nothing until they do. An agent request can't name a contractId yet: if the order must fall under a contract, ask the user to create it in Pleaxy.",
+        inputSchema: createPurchaseOrderShape,
+        annotations: adds(false),
+    }, async (args) => decide("create_purchase_order", args, () => pleaxyRequest("/purchase-orders", { method: "POST", body: args })));
+    server.registerTool("approve_purchase_order", {
+        title: "Approve a purchase order",
+        description: "Buyer: approve a purchase order at its current approval step. Only the person that step names can. Signed in as the user (`npx pleaxy-mcp login`), this sends them an agent request to confirm in Pleaxy and changes nothing until they do. With an API key this never succeeds and changes nothing (the API refuses a key with HUMAN_APPROVAL_REQUIRED): ask that person to approve it in Pleaxy.",
+        inputSchema: { poId: resourceId },
+        annotations: changes(false),
+    }, async ({ poId }) => decide("approve_purchase_order", { poId }, () => pleaxyRequest(`/purchase-orders/${pathSegment(poId)}/approve`, { method: "POST" })));
+    server.registerTool("reject_purchase_order", {
+        title: "Reject a purchase order",
+        description: "Buyer: reject a purchase order at its current approval step, sending it back to whoever raised it to change and send again. Only the person that step names can, the same as approving it, and only when the user asked you to. Signed in as that person (`npx pleaxy-mcp login`), this rejects it at once, recorded as them. With an API key this never succeeds and changes nothing (the API refuses a key with HUMAN_APPROVAL_REQUIRED): ask that person to reject it in Pleaxy.",
+        inputSchema: { poId: resourceId },
+        annotations: changes(false),
+    }, async ({ poId }) => {
+        try {
+            return ok(await pleaxyRequest(`/purchase-orders/${pathSegment(poId)}/reject`, { method: "POST" }));
+        }
+        catch (e) {
+            return failed(e);
+        }
+    });
+    server.registerTool("flip_purchase_order_to_invoice", {
+        title: "Invoice a whole purchase order",
+        description: "Supplier: invoice a purchase order for its whole amount in one step, starting the buyer's match and approval. Only an awaiting-fulfillment PO with nothing invoiced against it yet flips; any other comes back unchanged, including one the buyer imported with an amount already invoiced in their previous system (its `priorInvoiced`). If several of your buyers use this id, the call fails listing them; call again with `buyer`.",
+        inputSchema: { poId: resourceId, buyer: buyerQualifier },
+        annotations: adds(true),
+    }, async ({ poId, buyer }) => {
+        try {
+            return ok(await pleaxyRequest(withBuyer(`/purchase-orders/${pathSegment(poId)}/flip-to-invoice`, buyer), { method: "POST" }));
+        }
+        catch (e) {
+            return failed(e);
+        }
+    });
+    server.registerTool("list_purchase_requests", {
+        title: "List purchase requests",
+        description: "Buyer: the purchase requests you can see - what people asked to buy before there is an order - newest first: your own, everyone's if you can view purchase orders, and any waiting on your approval. Each has its status (draft, pending_approval, approved, ordered, rejected, canceled), amount, cost center, budgetCheck and, once ordered, poId.",
+        inputSchema: {
+            status: z.enum(["draft", "pending_approval", "approved", "ordered", "rejected", "canceled"]).optional(),
+            mine: z.boolean().optional().describe("true: only your own requests."),
+            awaitingMe: z.boolean().optional().describe("true: only the requests waiting on your approval."),
+        },
+        annotations: reads,
+    }, async ({ status, mine, awaitingMe }) => {
+        try {
+            const query = new URLSearchParams({ ...(status ? { status } : {}), ...(mine ? { mine: "true" } : {}), ...(awaitingMe ? { awaitingMe: "true" } : {}) });
+            const qs = query.toString();
+            return ok(await pleaxyRequest(`/purchase-requests${qs ? `?${qs}` : ""}`));
+        }
+        catch (e) {
+            return failed(e);
+        }
+    });
+    server.registerTool("get_purchase_request", {
+        title: "Get a purchase request",
+        description: "Buyer: one purchase request by id (PR-...): what was asked for and why, its approval chain, its budget check, and the purchase order it became.",
+        inputSchema: { requestId: resourceId },
+        annotations: reads,
+    }, async ({ requestId }) => {
+        try {
+            return ok(await pleaxyRequest(`/purchase-requests/${pathSegment(requestId)}`));
+        }
+        catch (e) {
+            return failed(e);
+        }
+    });
+    server.registerTool("create_purchase_request", {
+        title: "Raise a purchase request",
+        description: "Buyer: ask for something to be bought. Anyone in the workspace may ask; it commits nothing, and procurement orders it once it is approved. Ask the user, one question at a time, what is needed, why, roughly how much (lines with quantity and price) and the cost center; never invent them. Use check_budget first to tell them whether it fits. With submit: true it goes for approval at once (refused with 409 over budget when the workspace enforces budgets); otherwise it's a draft.",
+        inputSchema: createPurchaseRequestShape,
+        annotations: adds(false),
+    }, async (args) => {
+        try {
+            return ok(await pleaxyRequest("/purchase-requests", { method: "POST", body: args }));
+        }
+        catch (e) {
+            return failed(e);
+        }
+    });
+    server.registerTool("submit_purchase_request", {
+        title: "Submit a purchase request",
+        description: "Buyer: send your own draft purchase request for approval. It needs a reason (description) and, when the workspace keeps a cost center list, a cost center.",
+        inputSchema: { requestId: resourceId },
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+    }, async ({ requestId }) => {
+        try {
+            return ok(await pleaxyRequest(`/purchase-requests/${pathSegment(requestId)}/submit`, { method: "POST" }));
+        }
+        catch (e) {
+            return failed(e);
+        }
+    });
+    server.registerTool("cancel_purchase_request", {
+        title: "Cancel a purchase request",
+        description: "Buyer: withdraw your own purchase request (an administrator may withdraw anyone's) while it is a draft, waiting for approval or approved. It can't be undone; make sure the user asked for it.",
+        inputSchema: { requestId: resourceId },
+        annotations: changes(true),
+    }, async ({ requestId }) => {
+        try {
+            return ok(await pleaxyRequest(`/purchase-requests/${pathSegment(requestId)}/cancel`, { method: "POST" }));
+        }
+        catch (e) {
+            return failed(e);
+        }
+    });
+    server.registerTool("convert_purchase_request", {
+        title: "Order a purchase request",
+        description: "Buyer, with an API key: turn an approved purchase request into a purchase order from its lines, cost center, GL account and quote. Within the approved amount, on the same cost center and GL account, the order keeps the request's approval and is issued at once; otherwise it is approved as a new order. A request becomes one order at most. Signed in as a person (`npx pleaxy-mcp login`) this is always refused: ordering creates a purchase order, which an agent only asks for - order it in Pleaxy, or use create_purchase_order.",
+        inputSchema: { requestId: resourceId, ...convertPurchaseRequestShape },
+        annotations: adds(true),
+    }, async ({ requestId, ...body }) => {
+        try {
+            return ok(await pleaxyRequest(`/purchase-requests/${pathSegment(requestId)}/convert`, { method: "POST", body }));
+        }
+        catch (e) {
+            return failed(e);
+        }
+    });
+    server.registerTool("check_budget", {
+        title: "Check a cost center's budget",
+        description: "Buyer: whether an amount fits a cost center's budget for the current period, without saving anything: within, over (overBy says by how much), no_budget (nothing budgeted, not checked), no_rate (no exchange rate) or off (budgets aren't checked). mode says whether the workspace warns (an over-budget order is still approved by a person) or blocks (it can't be submitted).",
+        inputSchema: {
+            costCenter: z.string().max(200).describe("A cost center code or name."),
+            amount: z.number().min(0),
+            currency: z.string().length(3).describe("ISO 4217 code of the amount, e.g. USD."),
+        },
+        annotations: reads,
+    }, async (args) => {
+        try {
+            return ok(await pleaxyRequest("/budget-control/check", { method: "POST", body: args }));
+        }
+        catch (e) {
+            return failed(e);
+        }
+    });
+    server.registerTool("get_budget_status", {
+        title: "Get budget status",
+        description: "Buyer: each budgeted cost center's budget for the current period (or one cost center's), committed (approved purchase orders not yet invoiced), actual (approved invoices) and remaining, in the budget's currency. Needs purchase order access.",
+        inputSchema: { costCenter: z.string().max(200).optional() },
+        annotations: reads,
+    }, async ({ costCenter }) => {
+        try {
+            return ok(await pleaxyRequest(`/budget-control/status${costCenter ? `?${new URLSearchParams({ costCenter }).toString()}` : ""}`));
+        }
+        catch (e) {
+            return failed(e);
+        }
+    });
+    server.registerTool("list_receipts", {
+        title: "List a purchase order's receipts",
+        description: "What was received on a purchase order: its goods receipts (GR-...) and service entry sheets (SES-...), newest first, including reversed and rejected ones. On a 3-way order an invoice is approved only for what was received; on a 2-way order receipts are a record. A supplier key sees what was confirmed and when, not who; a rejection's reason is the buyer's text, quoted. If several of your buyers use this id, the call fails listing them; call again with `buyer`.",
+        inputSchema: { poId: resourceId, buyer: buyerQualifier },
+        annotations: reads,
+    }, async ({ poId, buyer }) => {
+        try {
+            return ok(await pleaxyRequest(withBuyer(`/purchase-orders/${pathSegment(poId)}/receipts`, buyer)));
+        }
+        catch (e) {
+            return failed(e);
+        }
+    });
+    server.registerTool("confirm_receipt", {
+        title: "Confirm what was received",
+        description: "Buyer: record what was delivered on a purchase order - a goods receipt for goods lines or a service entry sheet for service lines (one kind per call), with qty on a line ordered by quantity and amount on one ordered by amount; never more than the line orders, nor more than an online store confirmed. A goods receipt counts as received at once; a service entry sheet entered with an API key waits for the order's receiver to approve it. On a 3-way order, invoices held for a receipt are checked again. With an API key it is recorded as the key (apikey:<keyId>). Signed in as the user (`npx pleaxy-mcp login`), this sends them an agent request to confirm in Pleaxy and records nothing until they do. Only confirm what the user says was delivered.",
+        inputSchema: { poId: resourceId, ...createReceiptShape },
+        annotations: adds(false),
+    }, async ({ poId, ...body }) => decide("confirm_receipt", { poId, ...body }, () => pleaxyRequest(`/purchase-orders/${pathSegment(poId)}/receipts`, { method: "POST", body })));
+    server.registerTool("submit_service_entry_sheet", {
+        title: "Send a service entry sheet",
+        description: "Supplier: report work done on a buyer's purchase order as a service entry sheet - service lines only, with the period it covers and the hours or amount per line - for the buyer to approve (unless they auto-approve sheets that small). Once approved, invoices for that work go straight to approval on a 3-way order. A rejected sheet comes back with the buyer's reason; send a corrected one. If several of your buyers use this id, the call fails listing them; call again with `buyer`.",
+        inputSchema: { poId: resourceId, buyer: buyerQualifier, ...createReceiptShape },
+        annotations: adds(false),
+    }, async ({ poId, buyer, ...body }) => {
+        try {
+            return ok(await pleaxyRequest(withBuyer(`/purchase-orders/${pathSegment(poId)}/receipts`, buyer), { method: "POST", body }));
+        }
+        catch (e) {
+            return failed(e);
+        }
+    });
+    server.registerTool("record_receipt_return", {
+        title: "Record a return to the supplier",
+        description: "Buyer: record goods sent back to the supplier from a goods receipt (GR-...), per line, with the date, the reason and what you ask for (a replacement, a credit note, or nothing). What goes back stops counting as received, so on a 3-way order invoices for it wait for a replacement, and the supplier is told what and why. Never more than the receipt has left on a line. Only record what the user says was sent back.",
+        inputSchema: { poId: resourceId, receiptId: resourceId, ...returnReceiptShape },
+        annotations: adds(false),
+    }, async ({ poId, receiptId, ...body }) => {
+        try {
+            return ok(await pleaxyRequest(`/purchase-orders/${pathSegment(poId)}/receipts/${pathSegment(receiptId)}/returns`, { method: "POST", body }));
+        }
+        catch (e) {
+            return failed(e);
+        }
+    });
+    server.registerTool("approve_service_entry_sheet", {
+        title: "Approve a service entry sheet",
+        description: "Buyer: approve a supplier's service entry sheet (SES-...) at its current approval step. Only the person that step names can. Signed in as the user (`npx pleaxy-mcp login`), this sends them an agent request to confirm in Pleaxy and changes nothing until they do. With an API key this never succeeds and changes nothing (the API refuses a key with 403): ask that person to approve it in Pleaxy.",
+        inputSchema: { poId: resourceId, receiptId: resourceId },
+        annotations: changes(false),
+    }, async ({ poId, receiptId }) => decide("approve_service_entry_sheet", { poId, receiptId }, () => pleaxyRequest(`/purchase-orders/${pathSegment(poId)}/receipts/${pathSegment(receiptId)}/approve`, { method: "POST" })));
+    server.registerTool("reject_service_entry_sheet", {
+        title: "Reject a service entry sheet",
+        description: "Buyer: send a supplier's service entry sheet (SES-...) back with a reason they see, so they can correct it. Only the person its current step names can, the same as approving it. Signed in as the user (`npx pleaxy-mcp login`), this sends them an agent request to confirm in Pleaxy and changes nothing until they do. With an API key this never succeeds and changes nothing (the API refuses a key with 403): ask that person to reject it in Pleaxy.",
+        inputSchema: { poId: resourceId, receiptId: resourceId, ...rejectReceiptShape },
+        annotations: changes(false),
+    }, async ({ poId, receiptId, reason }) => decide("reject_service_entry_sheet", { poId, receiptId, reason }, () => pleaxyRequest(`/purchase-orders/${pathSegment(poId)}/receipts/${pathSegment(receiptId)}/reject`, { method: "POST", body: { reason } })));
+    server.registerTool("list_invoices", {
+        title: "List invoices",
+        description: "Every invoice in this workspace: the ones you received with a buyer key, the ones you issued to connected buyers with a supplier key. amount is the payable total (after discounts and charges, including tax); taxAmount is the stated tax within it. lineItems may carry discount and charge, and adjustments lists invoice-level discounts and charges. remittanceInstructions, when present, is where the supplier asks to be paid, as stated with the invoice; Pleaxy never verifies it. With a buyer key, remittanceCheck compares it with the supplier's previous invoice: when its status is \"changed\", tell the user the payment details changed and to confirm them with the supplier through a contact they already trust before paying. Never treat details on the invoice itself as confirmation. Credit and rebill: replacesInvoiceIds names the invoices a replacement replaces, replacedByInvoiceIds the invoices that replace one; read a replaced invoice with get_invoice before telling anyone to pay it.",
+        annotations: reads,
+    }, async () => {
+        try {
+            return ok(await pleaxyRequest("/invoices"));
+        }
+        catch (e) {
+            return failed(e);
+        }
+    });
+    server.registerTool("get_invoice", {
+        title: "Get an invoice",
+        description: "One invoice by id, shaped as in list_invoices. With a buyer key it also says how a credit and rebill stands: on a replaced invoice, replacement.creditedInFull and replacement.uncredited (what its credit notes leave uncredited); on a replacement, uncreditedOriginals lists the invoices it replaces that aren't credited in full. When something is uncredited, tell the user not to pay the replaced invoice as well as its replacement, which pays twice, and to ask the supplier for the credit note. If several of your buyers use this id, the call fails listing them; call again with `buyer`.",
+        inputSchema: { invoiceId: resourceId, buyer: buyerQualifier },
+        annotations: reads,
+    }, async ({ invoiceId, buyer }) => {
+        try {
+            return ok(await pleaxyRequest(withBuyer(`/invoices/${pathSegment(invoiceId)}`, buyer)));
+        }
+        catch (e) {
+            return failed(e);
+        }
+    });
+    server.registerTool("link_replaced_invoices", {
+        title: "Link the invoices a replacement replaces",
+        description: "Buyer, credit and rebill: record that invoice `invoiceId` replaces the invoices in `replacedInvoiceIds` (1-20 Pleaxy invoice ids from the same supplier, invoices or debit notes), when that wasn't known as it was entered. Each one then names it in replacedByInvoiceIds; links already there are kept. A credit note, the invoice itself or one of its own replacements is refused (REPLACES_INVALID); an invoice from another supplier or none at all is 404 REPLACES_NOT_FOUND. Returns the replacement, with uncreditedOriginals when their credit notes don't cover them.",
+        inputSchema: {
+            invoiceId: resourceId,
+            replacedInvoiceIds: z.array(resourceId).min(1).max(20).describe("The Pleaxy ids of the invoices this one replaces."),
+        },
+        annotations: adds(true),
+    }, async ({ invoiceId, replacedInvoiceIds }) => {
+        try {
+            return ok(await pleaxyRequest(`/invoices/${pathSegment(invoiceId)}/replaces`, { method: "POST", body: { invoiceIds: replacedInvoiceIds } }));
+        }
+        catch (e) {
+            return failed(e);
+        }
+    });
+    server.registerTool("unlink_replaced_invoice", {
+        title: "Undo a replacement link",
+        description: "Buyer: remove a replacement link entered wrongly, so invoice `invoiceId` no longer replaces `replacedInvoiceId`, on both invoices. The rejected invoice an invoice corrects on its purchase order stays linked (REPLACES_INVALID). Only undo a link the user says is wrong.",
+        inputSchema: { invoiceId: resourceId, replacedInvoiceId: resourceId },
+        annotations: changes(true),
+    }, async ({ invoiceId, replacedInvoiceId }) => {
+        try {
+            return ok(await pleaxyRequest(`/invoices/${pathSegment(invoiceId)}/replaces/${pathSegment(replacedInvoiceId)}`, { method: "DELETE" }));
+        }
+        catch (e) {
+            return failed(e);
+        }
+    });
+    server.registerTool("run_invoice_match", {
+        title: "Run invoice match",
+        description: "Buyer: check an invoice against what backs it and move it on. A cloud provider's invoice has its amount (the payable total, after discounts and charges, including tax) reconciled against reported usage. Pleaxy doesn't convert currencies: usage in another currency than the invoice is never compared, and the invoice becomes a discrepancy with discrepancyReason \"currency\"; check it against the provider's bill before resolve_invoice_discrepancy. An invoice with no live billing connection for its provider is unverified (unverifiedReason \"no_billing_connection\"), never matched, and gets 400 here. An invoice against any other purchase order is checked against that PO and its contract, and its approval chain starts. Approval always needs a human approver; autonomy never approves it. Recorded as the API key (apikey:<keyId>) or the signed-in user, never as a name passed in.",
+        inputSchema: { invoiceId: resourceId },
+        annotations: adds(false),
+    }, async ({ invoiceId }) => {
+        try {
+            return ok(await pleaxyRequest(`/invoices/${pathSegment(invoiceId)}/run-match`, { method: "POST" }));
+        }
+        catch (e) {
+            return failed(e);
+        }
+    });
+    server.registerTool("resolve_invoice_discrepancy", {
+        title: "Resolve an invoice discrepancy",
+        description: "Buyer: after reviewing an invoice with an amount or currency discrepancy, send it into the approval chain anyway; the chain's steps can then only be acted on by the employees they name. An unverified invoice (no purchase order, or no billing connection, to match against) can't be resolved with an API key: the API returns 403 HUMAN_REVIEW_REQUIRED, and a person reviews it in Pleaxy. With an API key it is recorded as the key (apikey:<keyId>), never as a name passed in. Signed in as the user (`npx pleaxy-mcp login`), this sends them an agent request to confirm in Pleaxy and changes nothing until they do.",
+        inputSchema: { invoiceId: resourceId },
+        annotations: changes(false),
+    }, async ({ invoiceId }) => decide("resolve_invoice_discrepancy", { invoiceId }, () => pleaxyRequest(`/invoices/${pathSegment(invoiceId)}/resolve-discrepancy`, { method: "POST" })));
+    server.registerTool("approve_invoice", {
+        title: "Approve an invoice",
+        description: "Buyer: approve an invoice at its current approval step. Only the person that step names can. Signed in as the user (`npx pleaxy-mcp login`), this sends them an agent request to confirm in Pleaxy and changes nothing until they do. With an API key this never succeeds and changes nothing (the API refuses a key with HUMAN_APPROVAL_REQUIRED): ask that person to approve it in Pleaxy.",
+        inputSchema: { invoiceId: resourceId },
+        annotations: changes(false),
+    }, async ({ invoiceId }) => decide("approve_invoice", { invoiceId }, () => pleaxyRequest(`/invoices/${pathSegment(invoiceId)}/approve`, { method: "POST" })));
+    server.registerTool("reject_invoice", {
+        title: "Reject an invoice",
+        description: "Buyer: reject an invoice with a reason code and a note the supplier sees word for word. Rejecting a PO-backed invoice reopens its purchase order for a corrected invoice. Signed in as the user (`npx pleaxy-mcp login`), this sends them an agent request to confirm in Pleaxy and changes nothing until they do. With an API key this always returns HUMAN_APPROVAL_REQUIRED.",
+        inputSchema: { invoiceId: resourceId, ...rejectInvoiceShape },
+        annotations: changes(false),
+    }, async ({ invoiceId, reasonCode, reason }) => decide("reject_invoice", { invoiceId, reasonCode, reason }, () => pleaxyRequest(`/invoices/${pathSegment(invoiceId)}/reject`, { method: "POST", body: { reasonCode, reason } })));
+    server.registerTool("record_payment", {
+        title: "Record a payment made outside Pleaxy",
+        description: "Buyer: record that an approved invoice was paid outside Pleaxy, with the method, date and reference; the supplier is told the buyer recorded it. This moves no money and doesn't check that the payment happened. Recording is the person's decision. Signed in as the user (`npx pleaxy-mcp login`), this sends them an agent request to confirm in Pleaxy and records nothing until they do. With an API key this always returns HUMAN_SESSION_REQUIRED and changes nothing, so ask that person to record it in Pleaxy.",
+        inputSchema: {
+            invoiceId: resourceId,
+            method: z.enum(["ach", "wire", "check", "card", "other"]).describe("How the payment was sent."),
+            paymentDate: z
+                .string()
+                .regex(/^\d{4}-\d{2}-\d{2}$/)
+                .describe("YYYY-MM-DD the payment was sent. Not in the future, and not before the invoice date."),
+            reference: z.string().min(1).max(64).describe("The bank or payment tool's reference, such as an ACH trace or check number. The supplier sees it. Never a bank account number."),
+        },
+        annotations: changes(false),
+    }, async ({ invoiceId, method, paymentDate, reference }) => decide("record_payment", { invoiceId, method, paymentDate, reference }, () => pleaxyRequest(`/invoices/${pathSegment(invoiceId)}/payment-record`, { method: "POST", body: { method, paymentDate, reference } })));
+    server.registerTool("remind_invoice", {
+        title: "Send an invoice reminder",
+        description: "Supplier: nudge whoever is holding up an invoice's approval chain, or remind the buyer to pay an approved, unpaid invoice (saying so when it's overdue). One reminder per invoice every 24 hours; a refusal says when the next one is allowed. If several of your buyers use this id, the call fails listing them; call again with `buyer`.",
+        inputSchema: { invoiceId: resourceId, buyer: buyerQualifier },
+        annotations: adds(false),
+    }, async ({ invoiceId, buyer }) => {
+        try {
+            return ok(await pleaxyRequest(withBuyer(`/invoices/${pathSegment(invoiceId)}/remind`, buyer), { method: "POST" }));
+        }
+        catch (e) {
+            return failed(e);
+        }
+    });
+    server.registerTool("get_questionnaire", {
+        title: "Get the supplier questionnaire",
+        description: "Buyer: the onboarding questionnaire every supplier you invite answers. fields lists the requested documents (kind standard) and the questions (kind custom) in order, with their ids, answer options (by id), the section each sits under, follow-up conditions (showIf: shown only after one of the given answers of an earlier question) and the answers that flag a response for review (flagIf). Read it before save_questionnaire.",
+        annotations: reads,
+    }, async () => {
+        try {
+            return ok(await pleaxyRequest("/questionnaire-template"));
+        }
+        catch (e) {
+            return failed(e);
+        }
+    });
+    server.registerTool("save_questionnaire", {
+        title: "Save the supplier questionnaire",
+        description: "Buyer: replace the whole supplier questionnaire with `fields`, in order. Start from get_questionnaire and send back every field you keep, with its id and option ids unchanged; a field you leave out is removed. A follow-up's showIf must point at a Yes/No or choice question earlier in the list; a document's may point at any. Suppliers already invited keep the version they were sent; new invites get this one. The API refuses an invalid questionnaire with a message saying what to fix.",
+        inputSchema: saveQuestionnaireShape,
+        annotations: changes(true),
+    }, async ({ fields }) => {
+        try {
+            return ok(await pleaxyRequest("/questionnaire-template", { method: "PUT", body: { fields } }));
+        }
+        catch (e) {
+            return failed(e);
+        }
+    });
+    server.registerTool("get_agent_request", {
+        title: "Check an agent request",
+        description: "Signed in as the user only: whether the user confirmed an agent request a decision tool sent - pending (waiting for them), done, failed, cancelled or expired (24 hours passed) - with its outcome. Takes the agentRequestId the decision tool answered with.",
+        inputSchema: { agentRequestId: resourceId },
+        annotations: reads,
+    }, async ({ agentRequestId }) => {
+        try {
+            if (!isSignedIn())
+                throw new Error("Agent requests need this server signed in as the user (`npx pleaxy-mcp login`); it is using an API key.");
+            return ok(await pleaxyRequest(`/agent-requests/${pathSegment(agentRequestId)}`));
+        }
+        catch (e) {
+            return failed(e);
+        }
+    });
+    server.registerTool("whoami", {
+        title: "Who this server acts as",
+        description: "Whose account this server uses: the user who signed it in (`npx pleaxy-mcp login`), when they did and the workspaces it reaches, or an API key. Use it when the user asks whose account you're using.",
+        annotations: reads,
+    }, async () => {
+        try {
+            if (!isSignedIn())
+                return ok({ actingAs: "apiKey", note: "This server uses an API key (PLEAXY_API_KEY): every call is recorded as that key, not as a person." });
+            return ok({ actingAs: "user", ...(await pleaxyAccountRequest("/auth/me")) });
+        }
+        catch (e) {
+            return failed(e);
+        }
+    });
+    return server;
+}

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "pleaxy-mcp",
+  "version": "0.1.1",
+  "description": "MCP server for Pleaxy: purchase orders, receipts and invoices as tools for AI agents (Claude, ChatGPT, Cursor and any MCP client)",
+  "mcpName": "ai.pleaxy/pleaxy-mcp",
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "mcp-server",
+    "pleaxy",
+    "procurement",
+    "purchase-orders",
+    "invoices",
+    "accounts-payable",
+    "ai-agents"
+  ],
+  "homepage": "https://pleaxy.ai/docs",
+  "bugs": {
+    "email": "support@pleaxy.ai"
+  },
+  "license": "MIT",
+  "author": "Pleaxy <support@pleaxy.ai>",
+  "type": "module",
+  "bin": {
+    "pleaxy-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "server.json"
+  ],
+  "scripts": {
+    "test": "node --test src/__tests__/*.test.ts",
+    "build": "tsc -p .",
+    "prepack": "npm run build",
+    "start": "node dist/index.js"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.30.0",
+    "zod": "^4.6.5"
+  },
+  "devDependencies": {
+    "@types/node": "^22.20.3",
+    "typescript": "^7.0.2"
+  },
+  "engines": {
+    "node": ">=22.18.0"
+  }
+}

package/server.json

@@ -0,0 +1,40 @@
+{
+  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
+  "name": "ai.pleaxy/pleaxy-mcp",
+  "title": "Pleaxy",
+  "description": "Purchase orders, receipts and invoices in Pleaxy: read them, raise them, and route approvals.",
+  "version": "0.1.1",
+  "websiteUrl": "https://pleaxy.ai/docs",
+  "packages": [
+    {
+      "registryType": "npm",
+      "registryBaseUrl": "https://registry.npmjs.org",
+      "identifier": "pleaxy-mcp",
+      "version": "0.1.1",
+      "runtimeHint": "npx",
+      "transport": {
+        "type": "stdio"
+      },
+      "environmentVariables": [
+        {
+          "name": "PLEAXY_API_BASE_URL",
+          "description": "The Pleaxy API's origin, without /v1.",
+          "default": "https://api.pleaxy.ai",
+          "isRequired": true
+        },
+        {
+          "name": "PLEAXY_WORKSPACE_ID",
+          "description": "Your Workspace ID, from Company profile → Workspace ID in Pleaxy.",
+          "placeholder": "reg_....buyer",
+          "isRequired": true
+        },
+        {
+          "name": "PLEAXY_API_KEY",
+          "description": "A workspace API key (<keyId>.<secret>). Leave unset to act as yourself after `npx pleaxy-mcp login`.",
+          "isRequired": false,
+          "isSecret": true
+        }
+      ]
+    }
+  ]
+}