pleaxy-mcp 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Pleaxy
+
+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,185 @@
+# pleaxy-mcp
+
+MCP server exposing the Pleaxy purchase-order and invoice API as tools for any
+MCP-compatible AI agent (Claude Desktop, Claude Code, or your own internal
+assistant). It's a thin wrapper - every tool call is a single authenticated
+HTTP request to the same `/v1/workspaces/:regionId/...` REST API the console and
+SDKs use. No business logic lives here.
+
+## Install
+
+```bash
+npx -y pleaxy-mcp --version   # Node.js 22.18 or later; nothing else to install
+```
+
+Add it to your MCP client with one of the two ways of signing in below. For Claude
+Code, in one line:
+
+```bash
+claude mcp add pleaxy -e PLEAXY_API_BASE_URL=https://api.pleaxy.ai -e PLEAXY_WORKSPACE_ID=<Workspace ID> -- npx -y pleaxy-mcp
+```
+
+The package carries a [`server.json`](server.json) for the official MCP Registry (`ai.pleaxy/pleaxy-mcp`).
+
+## Sign in as yourself
+
+> Not switched on at `api.pleaxy.ai` yet: until it is, `login` there says the
+> deployment doesn't offer agent sign-in, and the API-key setup below is the way in.
+
+Signed in as you, the server acts as you: it sees what you see in Pleaxy and its
+changes are recorded as yours. Decisions stay yours: approving or rejecting an
+invoice, recording a payment, creating or approving a purchase order, confirming a
+receipt and deciding a service entry sheet are sent to you as **agent requests**,
+which you confirm or cancel in Pleaxy within 24 hours. Nothing happens until you do.
+Rejecting a purchase order whose step names you happens at once, as it does in the
+Pleaxy Assistant.
+
+```bash
+export PLEAXY_API_BASE_URL="https://api.pleaxy.ai"
+npx pleaxy-mcp login     # opens your browser to sign in; lists the workspaces it can reach
+npx pleaxy-mcp whoami    # who the server acts as
+npx pleaxy-mcp logout    # signs the agent out (also: Pleaxy → Security & Sign-in → Agents)
+```
+
+Then configure the server as below, with `PLEAXY_WORKSPACE_ID` and without
+`PLEAXY_API_KEY`. The sign-in is stored in `~/.config/pleaxy-mcp/credentials.json`
+(`%APPDATA%\pleaxy-mcp` on Windows), readable by you only, and lasts at most 7 days;
+then run `login` again. Resetting your password signs every agent out. A workspace
+whose company requires single sign-on isn't reachable by an agent.
+
+## Setup with an API key
+
+For unattended integrations that act as the workspace rather than a person.
+
+1. Mint a scoped API key from your workspace (`POST /v1/workspaces/:regionId/api-keys`,
+   requires a signed-in session; see [API keys](https://pleaxy.ai/api-reference/api-keys)).
+   Only a workspace administrator can mint one. The key is revoked automatically
+   if that person is removed from the workspace or changed to a role other than
+   Administrator, so mint keys for long-running agents from an administrator who
+   will keep that role, and replace the key before they leave. Re-adding or
+   re-promoting the person doesn't restore a revoked key; mint a new one.
+2. Set the three required environment variables. `PLEAXY_API_BASE_URL` is the
+   API's origin only, `https://api.pleaxy.ai` - the server appends the `/v1`
+   version prefix itself, so do not include it here. `PLEAXY_WORKSPACE_ID` is the **Workspace ID** shown
+   in the Pleaxy console under **Company profile → Workspace ID** (one per
+   workspace, e.g. `reg_01k5x8p9j3q7vn2mhb4tzc6rde.buyer`); copy it as-is:
+
+```bash
+export PLEAXY_API_BASE_URL="https://api.pleaxy.ai"
+export PLEAXY_API_KEY="<keyId>.<secret>"
+export PLEAXY_WORKSPACE_ID="<Company profile → Workspace ID>"
+```
+
+3. Point your MCP client at it. For Claude Desktop, Cursor and most clients, add to
+   the MCP config (Claude Code: `claude mcp add` as above, with `-e PLEAXY_API_KEY=...`):
+
+```json
+{
+  "mcpServers": {
+    "pleaxy": {
+      "command": "npx",
+      "args": ["-y", "pleaxy-mcp"],
+      "env": {
+        "PLEAXY_API_BASE_URL": "https://api.pleaxy.ai",
+        "PLEAXY_API_KEY": "<keyId>.<secret>",
+        "PLEAXY_WORKSPACE_ID": "<Company profile → Workspace ID>"
+      }
+    }
+  }
+}
+```
+
+   Your client prefixes the tool IDs with the key you give the server in this
+   config (`mcp__pleaxy__*` for `"pleaxy"`).
+
+One server process is scoped to exactly one workspace (one API key, one
+Workspace ID) - the same boundary the API key itself enforces. Use the Workspace
+ID of the side the key was minted for: a buyer key with a `.supplier` Workspace ID
+is refused. Buyer-scoped keys
+and supplier-scoped keys see the same tool list, but calls outside their role
+(e.g. a supplier key calling `approve_purchase_order`) are refused exactly as the
+REST API refuses them.
+
+## Tools
+
+| Tool | Side | Wraps |
+|---|---|---|
+| `get_buyer_workspace` | Buyer | `GET /v1/workspaces/:regionId/buyer` |
+| `get_supplier_workspace` | Supplier | `GET /v1/workspaces/:regionId/supplier` |
+| `list_catalog_suppliers` | Buyer | `GET .../catalog/browse/suppliers` |
+| `list_supplier_catalog` | Buyer | `GET .../catalog/browse/items` |
+| `get_purchase_order` | Both | `GET .../purchase-orders/:poId` |
+| `create_purchase_order` | Buyer | `POST /v1/workspaces/:regionId/purchase-orders` |
+| `approve_purchase_order` | Buyer | `POST .../purchase-orders/:poId/approve` |
+| `reject_purchase_order` | Buyer | `POST .../purchase-orders/:poId/reject` |
+| `flip_purchase_order_to_invoice` | Supplier | `POST .../purchase-orders/:poId/flip-to-invoice` |
+| `list_purchase_requests` | Buyer | `GET .../purchase-requests` |
+| `get_purchase_request` | Buyer | `GET .../purchase-requests/:requestId` |
+| `create_purchase_request` | Buyer | `POST .../purchase-requests` (any member may ask) |
+| `submit_purchase_request` | Buyer | `POST .../purchase-requests/:requestId/submit` |
+| `cancel_purchase_request` | Buyer | `POST .../purchase-requests/:requestId/cancel` |
+| `convert_purchase_request` | Buyer | `POST .../purchase-requests/:requestId/convert` (API key only; refused signed in) |
+| `check_budget` | Buyer | `POST .../budget-control/check` |
+| `get_budget_status` | Buyer | `GET .../budget-control/status` |
+| `list_receipts` | Both | `GET .../purchase-orders/:poId/receipts` |
+| `confirm_receipt` | Buyer | `POST .../purchase-orders/:poId/receipts` |
+| `submit_service_entry_sheet` | Supplier | `POST .../purchase-orders/:poId/receipts` |
+| `record_receipt_return` | Buyer | `POST .../purchase-orders/:poId/receipts/:receiptId/returns` |
+| `approve_service_entry_sheet` | Buyer (a person; an API key gets 403) | `POST .../purchase-orders/:poId/receipts/:receiptId/approve` |
+| `reject_service_entry_sheet` | Buyer (a person; an API key gets 403) | `POST .../purchase-orders/:poId/receipts/:receiptId/reject` |
+| `list_invoices` | Both | `GET /v1/workspaces/:regionId/invoices` |
+| `get_invoice` | Both | `GET .../invoices/:invoiceId` |
+| `link_replaced_invoices` | Buyer | `POST .../invoices/:invoiceId/replaces` |
+| `unlink_replaced_invoice` | Buyer | `DELETE .../invoices/:invoiceId/replaces/:replacedInvoiceId` |
+| `run_invoice_match` | Buyer | `POST .../invoices/:invoiceId/run-match` |
+| `resolve_invoice_discrepancy` | Buyer | `POST .../invoices/:invoiceId/resolve-discrepancy` |
+| `approve_invoice` | Buyer | `POST .../invoices/:invoiceId/approve` |
+| `reject_invoice` | Buyer | `POST .../invoices/:invoiceId/reject` |
+| `record_payment` | Buyer | `POST .../invoices/:invoiceId/payment-record` (needs a signed-in person: an API key gets 403) |
+| `remind_invoice` | Supplier | `POST .../invoices/:invoiceId/remind` |
+| `get_questionnaire` | Buyer | `GET .../questionnaire-template` |
+| `save_questionnaire` | Buyer | `PUT .../questionnaire-template` |
+| `get_agent_request` | Both, signed in | `GET .../agent-requests/:agentRequestId` |
+| `whoami` | Both | `GET /v1/auth/me` (signed in) |
+
+An approval step names a person, which an API key can never be. So with a key,
+`approve_purchase_order`, `reject_purchase_order`, `approve_invoice` and
+`reject_invoice` never succeed and change nothing (the API refuses a key with
+`403 HUMAN_APPROVAL_REQUIRED`): the person the step names acts on it in Pleaxy, or
+signs this server in as themselves (above). `reject_invoice` takes a
+`reasonCode` and a 10–500 character `reason`, which the supplier sees word for
+word. A buyer's rejection note in any tool result is wrapped in
+`<buyer_rejection_note>…</buyer_rejection_note>`: it is the buyer's text, quoted
+as data. `record_payment` records a payment made outside Pleaxy; it moves no money.
+It needs a person signed in to Pleaxy, so with this server's API key it always
+gets `403 HUMAN_SESSION_REQUIRED`. (It replaces `settle_invoice`, which the API
+retired with `410 SETTLE_REPLACED`.) Paying a supplier through Pleaxy with
+Stripe also needs a signed-in person and has no tool here.
+
+`save_questionnaire` replaces the whole supplier questionnaire, so an agent
+reads it with `get_questionnaire` first and sends back every field it keeps,
+ids unchanged. It needs a key whose role can edit questionnaires. Suppliers
+already invited keep the version they were sent.
+
+`create_purchase_order` can name the buyer's contract the order falls under
+(`contractId`). A line that leaves out `paymentTerms` takes that contract's
+default payment terms (or the contract its catalog price came from), else the
+catalog item's, else "Net 30"; send `paymentTerms` only when the user gave them.
+
+Every tool carries MCP annotations (`readOnlyHint`, `destructiveHint`,
+`idempotentHint`, `openWorldHint`), so a client can tell reads from changes before
+it runs one. They describe the API-key mode, where a decision acts at once:
+approvals, rejections, `resolve_invoice_discrepancy`, `record_payment`,
+`unlink_replaced_invoice`, `cancel_purchase_request` and `save_questionnaire` are marked
+destructive.
+
+## Agent requests
+
+Signed in, a decision tool answers with `status: "awaiting_confirmation"`, the
+request's id, a one-line summary and a link to it in Pleaxy. `get_agent_request`
+says where one stands (pending, done, failed, cancelled or expired). An agent request
+can't name a `contractId` yet; create an order under a contract in Pleaxy.
+
+## Support
+
+Questions and problems: support@pleaxy.ai. Docs: https://pleaxy.ai/docs#agent.

package/dist/api.js

@@ -0,0 +1,75 @@
+import { assertSafeOrigin } from "./auth/oauth.js";
+import { LOGIN_HINT, SignedInSession } from "./auth/session.js";
+const API_VERSION_PREFIX = "/v1";
+let cached;
+function config() {
+    cached ??= readConfig();
+    return cached;
+}
+function readConfig() {
+    const env = (name) => process.env[name] || undefined;
+    const apiKey = env("PLEAXY_API_KEY");
+    return {
+        baseUrl: required(env("PLEAXY_API_BASE_URL"), "PLEAXY_API_BASE_URL").replace(/\/+$/, ""),
+        ...(apiKey ? { apiKey } : {}),
+    };
+}
+function workspaceId() {
+    config();
+    return required(process.env.PLEAXY_WORKSPACE_ID || undefined, "PLEAXY_WORKSPACE_ID");
+}
+function required(value, name) {
+    if (!value)
+        throw new Error(`Missing required environment variable ${name}`);
+    return value;
+}
+export function isSignedIn() {
+    return !config().apiKey;
+}
+export function apiOrigin() {
+    return assertSafeOrigin(config().baseUrl, "PLEAXY_API_BASE_URL");
+}
+let session;
+function signedInSession() {
+    session ??= new SignedInSession(apiOrigin());
+    return session;
+}
+async function authHeaders(force) {
+    const { apiKey } = config();
+    if (apiKey)
+        return { "x-api-key": apiKey };
+    return { authorization: `Bearer ${await signedInSession().accessToken(force)}` };
+}
+export function pleaxyUrl(path) {
+    return `${config().baseUrl}${API_VERSION_PREFIX}/workspaces/${workspaceId()}${path}`;
+}
+export async function pleaxyRequest(path, options = {}) {
+    return requestUrl(pleaxyUrl(path), path, options);
+}
+export async function pleaxyAccountRequest(path) {
+    return requestUrl(`${config().baseUrl}${API_VERSION_PREFIX}${path}`, path, {});
+}
+async function requestUrl(url, path, options) {
+    const send = async (force) => fetch(url, {
+        method: options.method ?? "GET",
+        headers: { "content-type": "application/json", ...(await authHeaders(force)) },
+        body: options.body !== undefined ? JSON.stringify(options.body) : undefined,
+    });
+    let res = await send(false);
+    let data = await bodyOf(res);
+    if (res.status === 401 && isSignedIn()) {
+        if (data?.code === "AGENT_SESSION_REVOKED" || data?.code === "SESSION_REVOKED")
+            throw new Error(`${data.message ?? "This agent was signed out of Pleaxy."} ${LOGIN_HINT}`);
+        res = await send(true);
+        data = await bodyOf(res);
+    }
+    if (!res.ok) {
+        const message = data?.message ?? res.statusText;
+        throw new Error(`Pleaxy API ${options.method ?? "GET"} ${path} failed (${res.status}): ${message}`);
+    }
+    return data;
+}
+async function bodyOf(res) {
+    const text = await res.text();
+    return text ? JSON.parse(text) : undefined;
+}

package/dist/auth/credentials.js

@@ -0,0 +1,52 @@
+import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, statSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+export function credentialsPath(env = process.env) {
+    if (env.PLEAXY_MCP_CREDENTIALS)
+        return env.PLEAXY_MCP_CREDENTIALS;
+    const base = process.platform === "win32" ? (env.APPDATA ?? join(homedir(), "AppData", "Roaming")) : (env.XDG_CONFIG_HOME ?? join(homedir(), ".config"));
+    return join(base, "pleaxy-mcp", "credentials.json");
+}
+function assertPrivate(path) {
+    if (process.platform === "win32")
+        return;
+    const mode = statSync(path).mode & 0o777;
+    if (mode & 0o077)
+        throw new Error(`${path} can be read by other users (mode ${mode.toString(8)}). Delete it and run \`npx pleaxy-mcp login\` again.`);
+}
+function read(path) {
+    if (!existsSync(path))
+        return { version: 1, signIns: {} };
+    assertPrivate(path);
+    const parsed = JSON.parse(readFileSync(path, "utf8"));
+    return { version: 1, signIns: parsed.signIns ?? {} };
+}
+function write(path, file) {
+    mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+    if (process.platform !== "win32")
+        chmodSync(dirname(path), 0o700);
+    const temporary = `${path}.${process.pid}.tmp`;
+    writeFileSync(temporary, `${JSON.stringify(file, null, 2)}\n`, { mode: 0o600 });
+    renameSync(temporary, path);
+}
+export class CredentialStore {
+    path;
+    constructor(path = credentialsPath()) {
+        this.path = path;
+    }
+    get(apiOrigin) {
+        return read(this.path).signIns[apiOrigin];
+    }
+    put(signIn) {
+        const file = read(this.path);
+        file.signIns[signIn.apiOrigin] = signIn;
+        write(this.path, file);
+    }
+    delete(apiOrigin) {
+        const file = read(this.path);
+        if (!(apiOrigin in file.signIns))
+            return;
+        delete file.signIns[apiOrigin];
+        write(this.path, file);
+    }
+}

package/dist/auth/oauth.js

@@ -0,0 +1,164 @@
+import { createHash, randomBytes } from "node:crypto";
+import { createServer } from "node:http";
+export const CALLBACK_PORTS = [47615, 47616, 47617];
+export const SCOPES = "openid email api/agent";
+const LOGIN_TIMEOUT_MS = 5 * 60 * 1000;
+export class SignInExpiredError extends Error {
+}
+export function base64url(buffer) {
+    return buffer.toString("base64url");
+}
+export function pkcePair() {
+    const verifier = base64url(randomBytes(32));
+    return { verifier, challenge: base64url(createHash("sha256").update(verifier).digest()) };
+}
+export function claimsOf(jwt) {
+    const payload = jwt.split(".")[1];
+    if (!payload)
+        throw new Error("Malformed token");
+    return JSON.parse(Buffer.from(payload, "base64url").toString("utf8"));
+}
+export function assertSafeOrigin(url, what) {
+    const parsed = new URL(url);
+    const local = parsed.hostname === "localhost" || parsed.hostname === "127.0.0.1";
+    if (parsed.protocol !== "https:" && !(parsed.protocol === "http:" && local))
+        throw new Error(`${what} must be https (got ${parsed.origin})`);
+    return parsed.origin;
+}
+export async function fetchAgentConfig(apiOrigin) {
+    const res = await fetch(`${apiOrigin}/v1/auth/agent-config`);
+    if (res.status === 404)
+        throw new Error("This Pleaxy deployment doesn't offer agent sign-in. Use an API key (PLEAXY_API_KEY) instead.");
+    if (!res.ok)
+        throw new Error(`Couldn't read the agent sign-in settings (${res.status}).`);
+    const body = (await res.json());
+    if (!body.clientId || !body.authDomain)
+        throw new Error("The agent sign-in settings are incomplete.");
+    return { clientId: body.clientId, authDomain: assertSafeOrigin(body.authDomain, "The sign-in domain") };
+}
+function tokenSetFrom(body, now) {
+    if (typeof body.access_token !== "string")
+        throw new Error("The sign-in answered without an access token.");
+    const expiresIn = typeof body.expires_in === "number" ? body.expires_in : 900;
+    return {
+        accessToken: body.access_token,
+        ...(typeof body.id_token === "string" ? { idToken: body.id_token } : {}),
+        ...(typeof body.refresh_token === "string" ? { refreshToken: body.refresh_token } : {}),
+        accessExpiresAt: Math.floor(now / 1000) + expiresIn,
+    };
+}
+async function tokenRequest(config, form) {
+    const res = await fetch(`${config.authDomain}/oauth2/token`, {
+        method: "POST",
+        headers: { "content-type": "application/x-www-form-urlencoded" },
+        body: new URLSearchParams({ client_id: config.clientId, ...form }).toString(),
+    });
+    const text = await res.text();
+    let body = {};
+    try {
+        body = text ? JSON.parse(text) : {};
+    }
+    catch {
+        body = {};
+    }
+    return { status: res.status, body };
+}
+export async function refreshTokens(config, refreshToken, now = Date.now()) {
+    const { status, body } = await tokenRequest(config, { grant_type: "refresh_token", refresh_token: refreshToken });
+    if (status === 400 && (body.error === "invalid_grant" || body.error === "invalid_client"))
+        throw new SignInExpiredError("The agent's sign-in has ended.");
+    if (status !== 200)
+        throw new Error(`Refreshing the agent's sign-in failed (${status}${typeof body.error === "string" ? `: ${body.error}` : ""}).`);
+    return tokenSetFrom(body, now);
+}
+export async function revokeRefreshToken(config, refreshToken) {
+    const res = await fetch(`${config.authDomain}/oauth2/revoke`, {
+        method: "POST",
+        headers: { "content-type": "application/x-www-form-urlencoded" },
+        body: new URLSearchParams({ client_id: config.clientId, token: refreshToken }).toString(),
+    }).catch(() => undefined);
+    return res?.ok ?? false;
+}
+const PAGE = (text) => `<!doctype html><meta charset="utf-8"><title>Pleaxy</title><body style="font-family:system-ui,sans-serif;max-width:32rem;margin:4rem auto;padding:0 1rem"><p>${text}</p></body>`;
+function reply(res, status, body, headers = {}) {
+    res.writeHead(status, { "content-type": "text/html; charset=utf-8", connection: "close", "cache-control": "no-store", ...headers });
+    res.end(body);
+}
+async function listen(handler) {
+    for (const port of CALLBACK_PORTS) {
+        const v4 = createServer(handler);
+        const bound = await new Promise((resolve) => {
+            v4.once("error", () => resolve(false));
+            v4.listen(port, "127.0.0.1", () => resolve(true));
+        });
+        if (!bound)
+            continue;
+        const v6 = createServer(handler);
+        await new Promise((resolve) => {
+            v6.once("error", () => resolve());
+            v6.listen(port, "::1", () => resolve());
+        });
+        return {
+            port,
+            close: () => {
+                v4.close();
+                v6.close();
+                v4.closeAllConnections?.();
+                v6.closeAllConnections?.();
+            },
+        };
+    }
+    throw new Error(`Ports ${CALLBACK_PORTS.join(", ")} are all in use; close whatever holds them and try again.`);
+}
+export async function signInWithBrowser(config, open, now = Date.now) {
+    const { verifier, challenge } = pkcePair();
+    const state = base64url(randomBytes(16));
+    let redirectUri = "";
+    let authorizeUrl = "";
+    let settle;
+    const codePromise = new Promise((resolve, reject) => (settle = { resolve, reject }));
+    const server = await listen((req, res) => {
+        const url = new URL(req.url ?? "/", "http://localhost");
+        if (url.pathname === "/signed-out")
+            return reply(res, 302, "", { location: authorizeUrl });
+        if (url.pathname !== "/callback")
+            return reply(res, 404, PAGE("Not found."));
+        if (url.searchParams.get("state") !== state)
+            return reply(res, 400, PAGE("This sign-in link is out of date. Run the sign-in again."));
+        const error = url.searchParams.get("error");
+        const code = url.searchParams.get("code");
+        if (error || !code) {
+            reply(res, 400, PAGE("The sign-in didn't finish. You can close this window and try again."));
+            return settle.reject(new Error(`The sign-in didn't finish${error ? ` (${error})` : ""}.`));
+        }
+        reply(res, 200, PAGE("Your agent is signed in to Pleaxy. You can close this window."));
+        settle.resolve(code);
+    });
+    redirectUri = `http://localhost:${server.port}/callback`;
+    authorizeUrl = `${config.authDomain}/oauth2/authorize?${new URLSearchParams({
+        response_type: "code",
+        client_id: config.clientId,
+        redirect_uri: redirectUri,
+        scope: SCOPES,
+        state,
+        code_challenge: challenge,
+        code_challenge_method: "S256",
+    }).toString()}`;
+    const startUrl = `${config.authDomain}/logout?${new URLSearchParams({ client_id: config.clientId, logout_uri: `http://localhost:${server.port}/signed-out` }).toString()}`;
+    const timer = setTimeout(() => settle.reject(new Error("The sign-in took longer than 5 minutes. Run it again.")), LOGIN_TIMEOUT_MS);
+    try {
+        open(startUrl);
+        const code = await codePromise;
+        const { status, body } = await tokenRequest(config, { grant_type: "authorization_code", code, redirect_uri: redirectUri, code_verifier: verifier });
+        if (status !== 200)
+            throw new Error(`The sign-in couldn't be completed (${status}${typeof body.error === "string" ? `: ${body.error}` : ""}).`);
+        const tokens = tokenSetFrom(body, now());
+        if (!tokens.refreshToken)
+            throw new Error("The sign-in answered without a refresh token.");
+        return tokens;
+    }
+    finally {
+        clearTimeout(timer);
+        server.close();
+    }
+}

package/dist/auth/session.js

@@ -0,0 +1,41 @@
+import { CredentialStore } from "./credentials.js";
+import { refreshTokens, SignInExpiredError } from "./oauth.js";
+const EARLY_REFRESH_SECONDS = 60;
+export const LOGIN_HINT = "Run `npx pleaxy-mcp login` to sign the agent in again.";
+export class SignedInSession {
+    apiOrigin;
+    store;
+    now;
+    refreshing;
+    constructor(apiOrigin, store = new CredentialStore(), now = Date.now) {
+        this.apiOrigin = apiOrigin;
+        this.store = store;
+        this.now = now;
+    }
+    signIn() {
+        const signIn = this.store.get(this.apiOrigin);
+        if (!signIn)
+            throw new SignInExpiredError(`This agent isn't signed in to Pleaxy at ${this.apiOrigin}. ${LOGIN_HINT}`);
+        return signIn;
+    }
+    async accessToken(force = false) {
+        const signIn = this.signIn();
+        const nowSeconds = Math.floor(this.now() / 1000);
+        if (!force && signIn.accessToken && (signIn.accessExpiresAt ?? 0) - EARLY_REFRESH_SECONDS > nowSeconds)
+            return signIn.accessToken;
+        this.refreshing ??= this.refresh(signIn).finally(() => (this.refreshing = undefined));
+        return this.refreshing;
+    }
+    async refresh(signIn) {
+        try {
+            const tokens = await refreshTokens({ clientId: signIn.clientId, authDomain: signIn.authDomain }, signIn.refreshToken, this.now());
+            this.store.put({ ...signIn, refreshToken: tokens.refreshToken ?? signIn.refreshToken, accessToken: tokens.accessToken, accessExpiresAt: tokens.accessExpiresAt });
+            return tokens.accessToken;
+        }
+        catch (err) {
+            if (err instanceof SignInExpiredError)
+                throw new SignInExpiredError(`The agent's sign-in to Pleaxy has ended. ${LOGIN_HINT}`);
+            throw err;
+        }
+    }
+}

package/dist/cli.js

@@ -0,0 +1,76 @@
+import { execFile } from "node:child_process";
+import { apiOrigin, isSignedIn, pleaxyAccountRequest } from "./api.js";
+import { CredentialStore } from "./auth/credentials.js";
+import { claimsOf, fetchAgentConfig, revokeRefreshToken, signInWithBrowser } from "./auth/oauth.js";
+export const CLI_COMMANDS = new Set(["login", "logout", "whoami"]);
+const say = (line) => process.stderr.write(`${line}\n`);
+function openBrowser(url) {
+    say(`\nSign in to Pleaxy in your browser. If no window opened, open this address:\n\n  ${url}\n`);
+    const opener = process.platform === "darwin" ? "open" : process.platform === "win32" ? "explorer.exe" : "xdg-open";
+    execFile(opener, [url], () => undefined);
+}
+async function login(store) {
+    const origin = apiOrigin();
+    const config = await fetchAgentConfig(origin);
+    const tokens = await signInWithBrowser(config, openBrowser);
+    const email = tokens.idToken ? claimsOf(tokens.idToken).email : undefined;
+    store.put({
+        apiOrigin: origin,
+        clientId: config.clientId,
+        authDomain: config.authDomain,
+        refreshToken: tokens.refreshToken,
+        accessToken: tokens.accessToken,
+        accessExpiresAt: tokens.accessExpiresAt,
+        ...(typeof email === "string" ? { email } : {}),
+    });
+    say(`Signed in to Pleaxy at ${origin}${typeof email === "string" ? ` as ${email}` : ""}.`);
+    await whoami();
+    return 0;
+}
+async function logout(store) {
+    const origin = apiOrigin();
+    const signIn = store.get(origin);
+    if (!signIn) {
+        say(`This agent isn't signed in to Pleaxy at ${origin}.`);
+        return 0;
+    }
+    const revoked = await revokeRefreshToken({ clientId: signIn.clientId, authDomain: signIn.authDomain }, signIn.refreshToken);
+    store.delete(origin);
+    say(revoked ? `Signed out of Pleaxy at ${origin}.` : `Signed out on this machine. Pleaxy couldn't be reached to end the sign-in there too: sign the agent out in Pleaxy, under Security & Sign-in → Agents.`);
+    return 0;
+}
+async function whoami() {
+    if (!isSignedIn()) {
+        say("PLEAXY_API_KEY is set: this server acts as that API key, not as a person.");
+        return 0;
+    }
+    const me = await pleaxyAccountRequest("/auth/me");
+    const who = me.employee?.name ?? me.employee?.email ?? "you";
+    say(`Acting as ${who}${me.agentSession ? `, signed in ${me.agentSession.signedInAt}` : ""}.`);
+    const workspaces = me.workspaces ?? [];
+    if (workspaces.length) {
+        say("Workspaces it can reach (set one as PLEAXY_WORKSPACE_ID):");
+        for (const w of workspaces) {
+            const name = w.companyName ?? w.regionName;
+            const locked = w.locked ? `  - not reachable by an agent (${w.locked.reason ?? "locked"})` : "";
+            say(`  ${w.workspaceId ?? w.regionId ?? "?"}${name ? `  ${name}` : ""}${w.role ? ` (${w.role})` : ""}${locked}`);
+        }
+    }
+    else {
+        say("It can't reach any workspace yet.");
+    }
+    return 0;
+}
+export async function runCli(command, store = new CredentialStore()) {
+    try {
+        if (command === "login")
+            return await login(store);
+        if (command === "logout")
+            return await logout(store);
+        return await whoami();
+    }
+    catch (err) {
+        say(err instanceof Error ? err.message : String(err));
+        return 1;
+    }
+}

package/dist/ids.js

@@ -0,0 +1,15 @@
+import { z } from "zod";
+export const resourceId = z.string().regex(/^[A-Za-z0-9_-]+$/, "must be a plain resource id (letters, digits, hyphen, underscore)");
+export function pathSegment(value) {
+    if (/^\.+$/.test(value))
+        throw new Error("must be a plain resource id (letters, digits, hyphen, underscore)");
+    return encodeURIComponent(value);
+}
+export const buyerQualifier = z
+    .string()
+    .regex(/^[A-Za-z0-9_-]+(\.buyer)?$/, "must be a buyer Workspace ID (ending in .buyer) or region id")
+    .optional()
+    .describe("Only when the API answered that more than one of your buyers has this id: that buyer's Workspace ID (ending in .buyer), from the error's list.");
+export function withBuyer(path, buyer) {
+    return buyer ? `${path}?${new URLSearchParams({ buyer }).toString()}` : path;
+}

package/dist/index.js

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CLI_COMMANDS, runCli } from "./cli.js";
+import { createServer, VERSION } from "./server.js";
+const command = process.argv[2];
+if (command === "--version" || command === "-v") {
+    process.stdout.write(`${VERSION}\n`);
+}
+else if (command && CLI_COMMANDS.has(command)) {
+    process.exitCode = await runCli(command);
+}
+else {
+    await createServer().connect(new StdioServerTransport());
+}