leo-proluxe-mcp

Proluxe ERP as a Leo package, over MCP — customers, orders, invoices, AR aging, bills of materials, the product catalog, focus priorities and projects, from the Proluxe API gateway.

The same integration as the compiled leo-proluxe package, reachable as a package the hub installs at runtime rather than one it has to be rebuilt for.

Tools

The compiled package exposed one proluxe tool with a fifteen-value action enum and a nine-field union schema. MCP names tools, so each action is its own tool with only its own parameters — the same fifteen names, the same paths.

Everything downstream keys on the 18-character Salesforce id, so find_customer comes first and its id goes into find_orders and find_invoices.

bom_inspect is two requests when it has to be: the MRP service keeps some parts under a Main_ prefix and some not, and which is which is not knowable from the part number. The bare form is tried first, the prefix is the fallback, and a failure names both — "SL1266TBAU not found" would send you looking for a part that is right there under a name nobody mentioned.

project_cards branches on absence: with a project id you get that project's cards, without one you get every card. A blank id is an absent one.

Responses are forwarded as the upstream JSON text, unparsed.

Related MCP server: odoo-mcp-server

Authentication

An Auth0 machine-to-machine client-credentials grant. This server POSTs client_id, client_secret, audience and grant_type=client_credentials to https://{domain}/oauth/token, then sends the token as Authorization: Bearer alongside X-User-Email, which is what scopes user-facing requests.

The token is cached and reused for the lifetime Auth0 reports, minus five minutes so none expires in flight. If the gateway answers 401 or 403 the cached token is dropped and the request is retried exactly once with a fresh one — without that, a token that dies early (rotated secret, revoked grant, clock skew) wedges every Proluxe call until the process restarts; with more than one, a genuinely bad credential becomes an unbounded stream of token requests. A second refusal says the credentials and audience are the thing to look at.

Configuration

Six settings. Leo hands them to this process under their settings keys, verbatim and lower-case, so the descriptor's settings_read and process.env.<key> have to agree or the credential silently never arrives.

Without the four required ones the server still starts and lists its tools; every call answers with the missing keys named and where to enter them.

Development

npm install
node test.js        # no network needed

The test covers what fails quietly, with an injected fetch and an injected clock:

• The token body. Omit audience and Auth0 returns a 200 with a real but opaque token, which the gateway then declines — that reads as a wrong secret. clientId for client_id is not a malformed request, it is a request with no client id.

• The cache and its arithmetic. That one token serves many calls; that it expires when Auth0 said it would; that an unreported expires_in falls back to an hour rather than to forever; that a lifetime shorter than the buffer floors instead of re-minting on every call.

• A bad token, told apart from an empty result. 401/403 retries once and only once, 500 is not retried at all, an Auth0 refusal and a 200 with no access_token both raise rather than return nothing. Every one of these otherwise arrives as an empty page, indistinguishable from a customer who has no invoices.

• Path and query building. Absent stays absent — an undeclared filter interpolated into a URL is the literal text undefined, which the gateway honours as a real customer id. Empty means no ? at all; limit is read as the Rust read it (as_u64, so the string "200" silently falls back); the per-action defaults are pinned; / escapes, so an id cannot walk sideways into another endpoint.

• The Main_ fallback, driven both ways round — a retry that re-requested the bare path would pass on every part that already worked and fail on exactly the parts the fallback exists for.

Faithfulness notes

Two places where this is deliberately not a byte-for-byte port:

• Non-ASCII percent-encoding. The Rust wrote %{:02X} of the code point, so é went out as Latin-1 %E9 and € as the malformed five-character %20AC. Here it is UTF-8. ASCII — which is all a Salesforce id or a part number contains — is byte-identical, including + for a space in path segments as well as query values, which is the Rust's spelling and the one the gateway has been answering.

• A non-string required argument. The Rust's require_str! refused a numeric query; here the schema asks for a string and a number is stringified, matching the reference servers.

Publishing

./store/publish.sh          # live
./store/publish.sh draft    # stage for review at admin.leoconnect.io

Needs a Cloudflare login with D1:Edit on the leo-store database. The script refuses unless the pinned commit is both real and pushed — a SHA that resolves nowhere installs cleanly and then fails on every hub at first launch.