@palpluss/mcp 0.0.0-stage → 0.2.0

package/EMBEDDING.md

@@ -0,0 +1,72 @@
+# Embedding @palpluss/mcp in your app
+
+`createPalplussMcpServer()` returns a standard MCP server (`McpServer` from `@modelcontextprotocol/sdk`). You can connect it to any MCP transport: stdio, Streamable HTTP, or an in-memory pair inside your own process.
+
+## In-process with your own approval UI
+
+```ts
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { InMemoryTransport } from '@modelcontextprotocol/sdk/inMemory.js';
+import { createPalplussMcpServer, type ApprovalRequest } from '@palpluss/mcp';
+
+// Your own function that shows the request to the user and resolves true/false.
+declare function askUserToConfirm(req: ApprovalRequest): Promise<boolean>;
+
+const { server } = createPalplussMcpServer({
+  apiKey: process.env.PALPLUSS_API_KEY!,
+  toolsets: ['read', 'wallets', 'collect', 'channels', 'payouts'],
+  limits: {
+    maxPayout: 2000,
+    dailyPayoutTotal: 10000,
+    dailyPayoutCount: 10,
+    maxTopup: 50000,
+    maxStk: 150000,
+    payoutAllowlist: [],
+  },
+  approver: async (req) =>
+    (await askUserToConfirm(req))
+      ? { approved: true, via: 'host' }
+      : { approved: false, reason: 'declined', message: 'The user declined. Nothing was done.' },
+  onAudit: (event) => console.log(JSON.stringify(event)),
+});
+
+const client = new Client({ name: 'my-app', version: '1.0.0' });
+const [serverSide, clientSide] = InMemoryTransport.createLinkedPair();
+await Promise.all([server.connect(serverSide), client.connect(clientSide)]);
+
+const { tools } = await client.listTools(); // pass these to your model as tools
+const result = await client.callTool({ name: 'palpluss_get_wallet_balances', arguments: {} });
+```
+
+`ApprovalRequest` has `action` (a stable name such as `b2c_payout`), `title`, `details` (label → value, with phone numbers already masked) and `consequence`. Show all of it to the user.
+
+Without an `approver`, the server asks through MCP elicitation, and tools that need approval refuse when the connected client doesn't support elicitation.
+
+## Let PalPluss handle approvals
+
+If your app has no confirm dialog of its own, use an **MCP key** (created by the merchant under API Keys, or obtained by OAuth sign-in) and `approval: 'backend'`:
+
+```ts
+const { server } = createPalplussMcpServer({
+  apiKey: merchantMcpKey,
+  approval: 'backend',
+  toolsets: ['read', 'collect', 'payouts'],
+});
+```
+
+PalPluss then enforces the key's permissions and payout limits, and holds payouts and channel changes until the merchant approves them in the console. Tools return `status: "PENDING_APPROVAL"` with an `approvalId`; `palpluss_wait_for_approval` follows it. Standard (full-access) keys are refused in this mode.
+
+For a stateless HTTP endpoint (several instances, no sessions), use `handleStatelessMcpRequest(req, res, parsedBody, options)` with the same options.
+
+## Things to get right
+
+- **Keep the API key on your server.** Never send it to a browser, a mobile app, or an environment that runs untrusted code.
+- **Allowlist tools.** Expose only the tools your product needs, and add `palpluss_send_payout` deliberately.
+- **Show approvals to the account owner,** not to whoever happens to be using the AI.
+- **Keep the audit events** so users can see what was done on their account.
+- **Payout limits in `limits` are per server process.** They're held in memory (and in `stateFile` if you set one). If you run several processes, each enforces its own limits. Limits set on an MCP key are enforced by PalPluss for all of them.
+- **Test first.** A test key behaves the same with simulated money; `palpluss_get_guardrails` reports the mode.
+
+## Over HTTP
+
+See "HTTP mode" in the [README](./README.md). Sessions are bound to the PalPluss key that opened them, and every request needs the bearer token.

package/README.md

@@ -1,3 +1,166 @@
-# Temporary Holding Version
+# @palpluss/mcp
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The PalPluss [Model Context Protocol](https://modelcontextprotocol.io) server. It lets AI tools that support MCP — such as Claude Code, Cursor and VS Code — work with your PalPluss account: check wallet balances, look up transactions, manage payment channels, collect with M-Pesa STK Push and send B2C payouts.
+
+Anything that moves money or changes where money lands needs a human's yes: a prompt in your MCP client, or approval in the PalPluss console. The AI model never sees or answers either, so it can't approve its own actions.
+
+> Requires Node.js 18+ and a PalPluss API key from [console.palpluss.com](https://console.palpluss.com) → API Keys. For AI tools, choose **AI tools (MCP)** as the key type: PalPluss then enforces the permissions, payout limits and approvals you set on the key. A **test** key uses simulated money.
+
+**No install?** PalPluss also runs this server for you at `https://api.palpluss.com/mcp`. Clients with MCP sign-in (OAuth) open the PalPluss console to connect; others can send an MCP key as `Authorization: Bearer <key>`. See [docs.palpluss.com/sdks/mcp](https://docs.palpluss.com/sdks/mcp).
+
+## Quick start
+
+### Claude Code
+
+```bash
+claude mcp add palpluss -e PALPLUSS_API_KEY=your_api_key -- npx -y @palpluss/mcp
+```
+
+### Cursor — `.cursor/mcp.json`
+
+```json
+{
+  "mcpServers": {
+    "palpluss": {
+      "command": "npx",
+      "args": ["-y", "@palpluss/mcp"],
+      "env": { "PALPLUSS_API_KEY": "your_api_key" }
+    }
+  }
+}
+```
+
+### VS Code — `.vscode/mcp.json`
+
+```json
+{
+  "inputs": [{ "id": "palpluss-key", "type": "promptString", "description": "PalPluss API key", "password": true }],
+  "servers": {
+    "palpluss": {
+      "command": "npx",
+      "args": ["-y", "@palpluss/mcp"],
+      "env": { "PALPLUSS_API_KEY": "${input:palpluss-key}" }
+    }
+  }
+}
+```
+
+Then ask your assistant things like *"What's my PalPluss service wallet balance?"*, *"Show my latest failed STK payments"*, or *"Add my KCB Paybill 522522, account 1188990011, as a payment channel"*.
+
+## Tools
+
+| Tool | Toolset | What it does | Approval |
+|---|---|---|---|
+| `palpluss_list_transactions` | read | List STK and B2C transactions, filter by type/status | — |
+| `palpluss_get_transaction` | read | One transaction: status, amount, receipt | — |
+| `palpluss_get_wallet_balances` | read | Service wallet (fees) and B2C wallet (payout float) | — |
+| `palpluss_list_payment_channels` | read | Paybills/Tills money is collected into | — |
+| `palpluss_get_payment_channel` | read | One channel | — |
+| `palpluss_get_guardrails` | read | Enabled toolsets, limits, today's payout allowance | — |
+| `palpluss_integration_guide` | read | Accurate guidance for building PalPluss into an app | — |
+| `palpluss_get_wallet_history` | read | Charges, top-ups, refunds and payouts on both wallets | — |
+| `palpluss_estimate_fee` | read | Fee for an STK push or payout of a given amount | — |
+| `palpluss_list_payment_links` | read | Payment links | — |
+| `palpluss_get_payment_link` | read | One payment link | — |
+| `palpluss_list_approvals` | read | Requests held for, or past, console approval | — |
+| `palpluss_topup_service_wallet` | wallets | STK prompt to top up the service wallet | ✅ |
+| `palpluss_topup_b2c_wallet` | wallets | STK prompt to top up the B2C wallet | ✅ |
+| `palpluss_send_stk_push` | collect | Ask a customer to pay by M-Pesa PIN prompt | ✅ |
+| `palpluss_wait_for_payment` | collect | Wait up to 90s for a final status | — |
+| `palpluss_create_payment_link` | collect | Create a hosted payment page (live keys) | — |
+| `palpluss_disable_payment_link` | collect | Stop a link accepting payments (live keys) | ✅ |
+| `palpluss_create_payment_channel` | channels | Add a Paybill or Till (incl. a bank Paybill) | ✅ |
+| `palpluss_update_payment_channel` | channels | Rename or change a channel's numbers | ✅ |
+| `palpluss_set_default_payment_channel` | channels | Choose where STK payments go by default | ✅ |
+| `palpluss_delete_payment_channel` | channels | Remove a channel | ✅ |
+| `palpluss_send_payout` | payouts | Send money to an M-Pesa number | ✅ + limits |
+| `palpluss_wait_for_approval` | payouts / channels | Wait for the merchant's decision on a held request | — |
+
+**Toolsets.** `read` is always on. The default is `read,wallets,collect`. Channel changes and payouts are off until you switch them on:
+
+```bash
+PALPLUSS_MCP_TOOLSETS=read,wallets,collect,channels,payouts   # or: all
+```
+
+## Guardrails
+
+PalPluss's own protections always apply, because every call goes through the public API: rate limits, per-phone limits, STK abuse protection and the STK success-rate pause. On top of those, this server adds:
+
+- **A human's yes for every write.** Top-ups, STK pushes, payouts and channel changes send an approval request (MCP *elicitation*) that your client shows you, with the amount, the masked phone number and, for channels, what changes. If your client doesn't support elicitation, these tools refuse instead of going ahead. Two exceptions, both decided from the key itself (`GET /v1/api-key`, read fresh before every decision): with an **MCP key** whose payouts or channel changes PalPluss holds for console approval, the request goes to the console instead (the tool returns `PENDING_APPROVAL`; follow it with `palpluss_wait_for_approval`); with a **test key**, nothing is asked because the money is simulated.
+- **Payout limits** per API key: per payout, per day (total and count), and an optional allowlist of recipient numbers. They're checked before you're asked, and again just before the payout is sent. These are enforced by this server process, so if you run several copies each keeps its own tally. Limits set on an MCP key in the console are enforced by PalPluss itself, for every copy.
+- **No double payments.** Payouts and top-ups carry an idempotency key, so an AI retrying after a timeout can't pay twice. Give each separate payout its own `reference`.
+- **Prompt-injection defence.** Text written by customers or providers (references, descriptions, result messages) is returned marked `untrusted:`. The server's instructions tell the AI never to act on it.
+- **Privacy.** Phone numbers are masked in everything returned to the AI and in the audit log. The API key is never logged.
+- **Audit log.** Set `PALPLUSS_MCP_AUDIT_FILE` to get one JSON line per tool call, with tool, outcome, masked arguments and error codes.
+- **Kill switch.** `PALPLUSS_MCP_READ_ONLY=true` removes every tool that changes anything.
+
+## Configuration
+
+| Variable | Default | Meaning |
+|---|---|---|
+| `PALPLUSS_API_KEY` | — (required) | Your PalPluss API key |
+| `PALPLUSS_MCP_TOOLSETS` | `read,wallets,collect` | Add `channels`, `payouts`, or use `all` |
+| `PALPLUSS_MCP_READ_ONLY` | `false` | `true` turns off every write tool |
+| `PALPLUSS_MCP_APPROVAL` | `elicit` | `backend` relies on PalPluss: needs an MCP key (standard keys are refused) and acts within the key's permissions, with payouts and channel changes held for console approval when the key asks for it. `none` disables approval prompts: use it only for automated tests against a fake or local API, never with a live key |
+| `PALPLUSS_MCP_MAX_PAYOUT` | `5000` | Largest single payout (KES) |
+| `PALPLUSS_MCP_DAILY_PAYOUT_TOTAL` | `20000` | Payout total per Nairobi day (KES) |
+| `PALPLUSS_MCP_DAILY_PAYOUT_COUNT` | `20` | Payouts per Nairobi day |
+| `PALPLUSS_MCP_PAYOUT_ALLOWLIST` | empty (any) | Comma-separated numbers payouts may go to |
+| `PALPLUSS_MCP_MAX_TOPUP` | `50000` | Largest wallet top-up (KES) |
+| `PALPLUSS_MCP_MAX_STK` | `150000` | Largest STK push (KES) |
+| `PALPLUSS_MCP_AUDIT_FILE` | — | JSON-lines audit log path |
+| `PALPLUSS_MCP_STATE_FILE` | — | Keep today's payout tally across restarts |
+| `PALPLUSS_MCP_TIMEOUT_MS` | `30000` | API request timeout |
+| `PALPLUSS_BASE_URL` | `https://api.palpluss.com` | API base URL |
+
+## HTTP mode
+
+For apps that connect over the network instead of starting a local process, such as your own hosted deployment:
+
+```bash
+PALPLUSS_MCP_HTTP_TOKEN=$(openssl rand -hex 24) \
+PALPLUSS_API_KEY=your_api_key \
+npx @palpluss/mcp --http --port 3333            # → http://127.0.0.1:3333/mcp
+```
+
+- Every request needs `Authorization: Bearer <PALPLUSS_MCP_HTTP_TOKEN>`.
+- One session per MCP client. Approval prompts work across requests within it.
+- `PALPLUSS_MCP_HTTP_ALLOW_KEY_HEADER=true` lets one endpoint serve many merchants. Each session starts with the merchant's key in `X-PalPluss-Api-Key`, and the session is bound to that key.
+- Binds to `127.0.0.1` by default. Put it behind TLS if you expose it.
+
+## Stateless HTTP
+
+`handleStatelessMcpRequest(req, res, body, options)` serves one request without sessions, for hosts that run several instances behind a load balancer. Elicitation needs a session, so use `approval: 'backend'` with an MCP key, or pass your own `approver`.
+
+## Embedding in your own app
+
+Use `createPalplussMcpServer()` to run the server inside your own Node.js app and connect it to any MCP transport. Pass an `approver` to show approvals in your own interface. See [EMBEDDING.md](./EMBEDDING.md).
+
+```ts
+import { createPalplussMcpServer } from '@palpluss/mcp';
+
+const { server } = createPalplussMcpServer({
+  apiKey: process.env.PALPLUSS_API_KEY!,
+  toolsets: ['read', 'wallets', 'collect'],
+});
+await server.connect(transport); // stdio, Streamable HTTP, or an in-memory pair
+```
+
+## Development
+
+```bash
+pnpm --filter @palpluss/mcp test        # guardrails, approvals, HTTP sessions
+pnpm --filter @palpluss/mcp build
+PALPLUSS_API_KEY=your_api_key node packages/mcp/dist/cli.js
+```
+
+## Releasing
+
+The package is marked `"private": true`, so the SDK's changeset release can't publish it by accident. To release it manually:
+
+1. Bump `version` in `package.json` and `USER_AGENT` in `src/api/client.ts`; the script checks that they match.
+2. `npm login` (once), then `pnpm --filter @palpluss/mcp release:manual -- --otp=<code from your authenticator>`. This runs the tests and the build, lifts the private flag for the publish only, then puts it back. It publishes without provenance, which only works from CI. Use `-- --dry-run` to try it without publishing.
+
+## License
+
+MIT

package/dist/api/client.d.ts

@@ -0,0 +1,154 @@
+/**
+ * Minimal client for the PalPluss developer API (/v1). Every call goes through
+ * the public API, so PalPluss's own limits — rate limits, per-phone velocity
+ * limits, STK abuse protection, transaction health — always apply.
+ */
+export declare const USER_AGENT = "palpluss-mcp/0.2.0";
+export declare class PalplussApiError extends Error {
+    readonly status: number;
+    readonly code: string;
+    readonly details?: unknown | undefined;
+    readonly requestId?: string | undefined;
+    constructor(message: string, status: number, code: string, details?: unknown | undefined, requestId?: string | undefined);
+}
+export type FetchLike = (input: string, init: RequestInit) => Promise<Response>;
+export interface ClientOptions {
+    apiKey: string;
+    baseUrl: string;
+    timeoutMs: number;
+    fetch?: FetchLike;
+}
+export interface TransactionListQuery {
+    limit?: number;
+    cursor?: string;
+    status?: string;
+    type?: 'STK' | 'B2C';
+}
+export interface StkPushBody {
+    amount: number;
+    phone: string;
+    accountReference?: string;
+    transactionDesc?: string;
+    channelId?: string;
+    callbackUrl?: string;
+}
+export interface TopupBody {
+    amount: number;
+    phone: string;
+    accountReference?: string;
+    transactionDesc?: string;
+    callbackUrl?: string;
+}
+export interface PayoutBody {
+    amount: number;
+    phone: string;
+    currency?: 'KES';
+    reference?: string;
+    description?: string;
+    channelId?: string;
+    callbackUrl?: string;
+}
+export interface ChannelCreateBody {
+    name: string;
+    type: 'PAYBILL' | 'TILL' | 'SHORTCODE';
+    shortcode: string;
+    accountNumber?: string;
+    isDefault?: boolean;
+}
+export type ChannelUpdateBody = Partial<ChannelCreateBody> & {
+    accountNumber?: string | null;
+};
+export interface WalletHistoryQuery {
+    wallet?: 'service' | 'b2c';
+    category?: 'charge' | 'topup' | 'refund' | 'payout' | 'bonus' | 'other';
+    limit?: number;
+    cursor?: string;
+}
+export interface PaymentLinkBody {
+    amount?: number;
+    phone_number?: string;
+    customer_name?: string;
+    external_reference?: string;
+    channel_id?: string;
+    callbackUrl?: string;
+    expiry?: '1h' | '6h' | '24h' | '72h' | '168h' | '720h' | 'never';
+}
+/** GET /v1/api-key — the key this server runs with. */
+export interface KeyInfo {
+    id: string;
+    name: string;
+    kind: 'STANDARD' | 'MCP';
+    mode: 'live' | 'test';
+    livemode: boolean;
+    scopes: 'all' | {
+        scope: string;
+        label: string;
+    }[];
+    expiresAt: string | null;
+    connectedApp: string | null;
+    policy: null | {
+        payoutMax: number;
+        dailyPayoutTotal: number;
+        dailyPayoutCount: number;
+        payoutAllowlist: string[];
+        approvals: {
+            payouts: boolean;
+            channels: boolean;
+        };
+        payoutsToday: {
+            total: number;
+            count: number;
+            remainingTotal: number;
+            remainingCount: number;
+        };
+    };
+}
+/** Returned (HTTP 202) when PalPluss holds a request for the merchant's approval. */
+export interface PendingApproval {
+    status: 'PENDING_APPROVAL';
+    approvalId: string;
+    action: string;
+    expiresAt: string;
+    approveUrl: string;
+    message: string;
+}
+export declare function isPendingApproval(value: unknown): value is PendingApproval;
+type Json = Record<string, unknown>;
+export declare class PalplussClient {
+    private readonly opts;
+    private readonly fetchImpl;
+    constructor(opts: ClientOptions);
+    private request;
+    listTransactions(query?: TransactionListQuery): Promise<Json>;
+    getTransaction(id: string): Promise<Json>;
+    serviceWalletBalance(): Promise<Json>;
+    b2cWalletBalance(): Promise<Json>;
+    topupServiceWallet(body: TopupBody, idempotencyKey: string): Promise<Json>;
+    topupB2cWallet(body: TopupBody, idempotencyKey: string): Promise<Json>;
+    listChannels(): Promise<{
+        items?: Json[];
+    }>;
+    getChannel(id: string): Promise<Json>;
+    createChannel(body: ChannelCreateBody): Promise<Json>;
+    updateChannel(id: string, body: ChannelUpdateBody): Promise<Json>;
+    deleteChannel(id: string): Promise<Json>;
+    stkPush(body: StkPushBody): Promise<Json>;
+    b2cPayout(body: PayoutBody, idempotencyKey: string): Promise<Json>;
+    keyInfo(): Promise<KeyInfo>;
+    walletHistory(query?: WalletHistoryQuery): Promise<Json>;
+    estimateFee(service: 'STK' | 'B2C', amount: number): Promise<Json>;
+    listPaymentLinks(query?: {
+        limit?: number;
+        cursor?: string;
+    }): Promise<Json>;
+    getPaymentLink(id: string): Promise<Json>;
+    createPaymentLink(body: PaymentLinkBody): Promise<Json>;
+    disablePaymentLink(id: string): Promise<Json>;
+    getApproval(id: string): Promise<Json>;
+    listApprovals(query?: {
+        status?: string;
+        limit?: number;
+        cursor?: string;
+    }): Promise<Json>;
+}
+export {};

package/dist/api/client.js

@@ -0,0 +1,164 @@
+/**
+ * Minimal client for the PalPluss developer API (/v1). Every call goes through
+ * the public API, so PalPluss's own limits — rate limits, per-phone velocity
+ * limits, STK abuse protection, transaction health — always apply.
+ */
+export const USER_AGENT = 'palpluss-mcp/0.2.0';
+export class PalplussApiError extends Error {
+    status;
+    code;
+    details;
+    requestId;
+    constructor(message, status, code, details, requestId) {
+        super(message);
+        this.status = status;
+        this.code = code;
+        this.details = details;
+        this.requestId = requestId;
+        this.name = 'PalplussApiError';
+    }
+}
+export function isPendingApproval(value) {
+    return !!value && typeof value === 'object' && value.status === 'PENDING_APPROVAL' && 'approvalId' in value;
+}
+export class PalplussClient {
+    opts;
+    fetchImpl;
+    constructor(opts) {
+        this.opts = opts;
+        this.fetchImpl = opts.fetch ?? ((input, init) => fetch(input, init));
+    }
+    async request(method, path, options = {}) {
+        const url = new URL(`${this.opts.baseUrl}/v1${path}`);
+        for (const [k, v] of Object.entries(options.query ?? {})) {
+            if (v !== undefined && v !== null && v !== '')
+                url.searchParams.set(k, String(v));
+        }
+        const headers = {
+            Authorization: `Basic ${this.opts.apiKey}`,
+            Accept: 'application/json',
+            'User-Agent': USER_AGENT,
+        };
+        if (options.body !== undefined)
+            headers['Content-Type'] = 'application/json';
+        if (options.idempotencyKey)
+            headers['Idempotency-Key'] = options.idempotencyKey;
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), this.opts.timeoutMs);
+        let res;
+        try {
+            res = await this.fetchImpl(url.toString(), {
+                method,
+                headers,
+                body: options.body === undefined ? undefined : JSON.stringify(options.body),
+                signal: controller.signal,
+            });
+        }
+        catch (err) {
+            const aborted = err?.name === 'AbortError';
+            throw new PalplussApiError(aborted
+                ? `PalPluss did not answer within ${Math.round(this.opts.timeoutMs / 1000)}s.`
+                : `Could not reach PalPluss at ${this.opts.baseUrl}.`, 0, aborted ? 'TIMEOUT' : 'NETWORK_ERROR');
+        }
+        finally {
+            clearTimeout(timer);
+        }
+        const requestId = res.headers.get('x-request-id') ?? undefined;
+        if (res.status === 204)
+            return undefined;
+        // Never JSON.parse an HTML error page (proxies, gateways, maintenance).
+        const contentType = res.headers.get('content-type') ?? '';
+        const text = await res.text();
+        if (!contentType.includes('json')) {
+            throw new PalplussApiError(`PalPluss returned an unexpected ${res.status} response (${contentType || 'no content type'}).`, res.status, 'NON_JSON_RESPONSE', undefined, requestId);
+        }
+        let payload;
+        try {
+            payload = text ? JSON.parse(text) : {};
+        }
+        catch {
+            throw new PalplussApiError('PalPluss returned malformed JSON.', res.status, 'MALFORMED_RESPONSE', undefined, requestId);
+        }
+        if (!res.ok || payload.success === false) {
+            const e = (payload.error ?? {});
+            // The API's error filter reports `code` as HTTP_<status> and keeps the
+            // specific code (e.g. KYC_NOT_VERIFIED) in details.code — prefer that.
+            const details = e.details && typeof e.details === 'object' ? e.details : undefined;
+            const specific = typeof details?.code === 'string' ? details.code : undefined;
+            const code = specific && (!e.code || /^HTTP_\d+$/.test(e.code)) ? specific : e.code || `HTTP_${res.status}`;
+            // Validation errors arrive with message as an array of strings.
+            const message = Array.isArray(e.message) ? e.message.join('; ') : typeof e.message === 'string' ? e.message : '';
+            // The filter wraps the original body ({ message, code, details }) in
+            // error.details; surface the inner details (e.g. retryAfterSeconds) directly.
+            const inner = details && details.details && typeof details.details === 'object' ? details.details : undefined;
+            throw new PalplussApiError(message || `PalPluss request failed (${res.status}).`, res.status, code, inner ?? e.details, requestId);
+        }
+        return (payload.data ?? payload);
+    }
+    listTransactions(query = {}) {
+        return this.request('GET', '/transactions', { query: { ...query } });
+    }
+    getTransaction(id) {
+        return this.request('GET', `/transactions/${encodeURIComponent(id)}`);
+    }
+    serviceWalletBalance() {
+        return this.request('GET', '/wallets/service/balance');
+    }
+    b2cWalletBalance() {
+        return this.request('GET', '/wallets/b2c/balance');
+    }
+    topupServiceWallet(body, idempotencyKey) {
+        return this.request('POST', '/wallets/service/topups', { body, idempotencyKey });
+    }
+    topupB2cWallet(body, idempotencyKey) {
+        return this.request('POST', '/wallets/b2c/topups', { body, idempotencyKey });
+    }
+    listChannels() {
+        return this.request('GET', '/payment-wallet/channels');
+    }
+    getChannel(id) {
+        return this.request('GET', `/payment-wallet/channels/${encodeURIComponent(id)}`);
+    }
+    createChannel(body) {
+        return this.request('POST', '/payment-wallet/channels', { body });
+    }
+    updateChannel(id, body) {
+        return this.request('PATCH', `/payment-wallet/channels/${encodeURIComponent(id)}`, { body });
+    }
+    deleteChannel(id) {
+        return this.request('DELETE', `/payment-wallet/channels/${encodeURIComponent(id)}`);
+    }
+    stkPush(body) {
+        return this.request('POST', '/payments/stk', { body });
+    }
+    b2cPayout(body, idempotencyKey) {
+        return this.request('POST', '/b2c/payouts', { body, idempotencyKey });
+    }
+    keyInfo() {
+        return this.request('GET', '/api-key');
+    }
+    walletHistory(query = {}) {
+        return this.request('GET', '/wallets/history', { query: { ...query } });
+    }
+    estimateFee(service, amount) {
+        return this.request('GET', '/fees/estimate', { query: { service, amount } });
+    }
+    listPaymentLinks(query = {}) {
+        return this.request('GET', '/payment-links', { query: { ...query } });
+    }
+    getPaymentLink(id) {
+        return this.request('GET', `/payment-links/${encodeURIComponent(id)}`);
+    }
+    createPaymentLink(body) {
+        return this.request('POST', '/payment-links', { body });
+    }
+    disablePaymentLink(id) {
+        return this.request('DELETE', `/payment-links/${encodeURIComponent(id)}`);
+    }
+    getApproval(id) {
+        return this.request('GET', `/approvals/${encodeURIComponent(id)}`);
+    }
+    listApprovals(query = {}) {
+        return this.request('GET', '/approvals', { query: { ...query } });
+    }
+}

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,65 @@
+#!/usr/bin/env node
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { ConfigError, loadConfigFromEnv } from './config.js';
+import { startHttpServer } from './http.js';
+import { createPalplussMcpServer, SERVER_VERSION } from './server.js';
+const HELP = `palpluss-mcp ${SERVER_VERSION} — PalPluss MCP server
+
+Usage:
+  palpluss-mcp              Run over stdio (Claude Code, Cursor, VS Code, …)
+  palpluss-mcp --http       Run a Streamable HTTP endpoint at /mcp
+      --port <n>            Port (default 3333, or PORT)
+      --host <addr>         Bind address (default 127.0.0.1)
+
+Environment:
+  PALPLUSS_API_KEY               Required. Your PalPluss API key.
+  PALPLUSS_MCP_TOOLSETS          read,wallets,collect (default) · add channels,payouts · or all
+  PALPLUSS_MCP_READ_ONLY         true to switch off every tool that changes anything
+  PALPLUSS_MCP_APPROVAL          elicit (default) | none
+  PALPLUSS_MCP_MAX_PAYOUT        KES per payout (default 5000)
+  PALPLUSS_MCP_DAILY_PAYOUT_TOTAL / _COUNT   daily payout caps (default 20000 / 20)
+  PALPLUSS_MCP_PAYOUT_ALLOWLIST  comma-separated phone numbers payouts may go to
+  PALPLUSS_MCP_MAX_TOPUP / _MAX_STK          caps for top-ups and STK pushes
+  PALPLUSS_MCP_AUDIT_FILE        JSON-lines audit log path
+  PALPLUSS_MCP_STATE_FILE        where to keep today's payout tally
+  PALPLUSS_BASE_URL              API base (default https://api.palpluss.com)
+  PALPLUSS_MCP_HTTP_TOKEN        --http only: required bearer token (≥24 chars)
+  PALPLUSS_MCP_HTTP_ALLOW_KEY_HEADER  --http only: accept X-PalPluss-Api-Key per request
+`;
+function arg(name) {
+    const i = process.argv.indexOf(name);
+    return i >= 0 ? process.argv[i + 1] : undefined;
+}
+async function main() {
+    if (process.argv.includes('--help') || process.argv.includes('-h')) {
+        process.stdout.write(HELP);
+        return;
+    }
+    if (process.argv.includes('--version')) {
+        process.stdout.write(`${SERVER_VERSION}\n`);
+        return;
+    }
+    const httpMode = process.argv.includes('--http');
+    const allowKeyHeader = ['1', 'true', 'yes'].includes((process.env.PALPLUSS_MCP_HTTP_ALLOW_KEY_HEADER ?? '').toLowerCase());
+    // In HTTP multi-merchant mode the key may come per request instead of env.
+    const env = httpMode && allowKeyHeader && !process.env.PALPLUSS_API_KEY ? { ...process.env, PALPLUSS_API_KEY: '-' } : process.env;
+    const config = loadConfigFromEnv(env);
+    if (config.apiKey === '-')
+        config.apiKey = '';
+    if (httpMode) {
+        const port = Number(arg('--port') ?? process.env.PORT ?? 3333);
+        const host = arg('--host') ?? '127.0.0.1';
+        await startHttpServer({ config, port, host, token: process.env.PALPLUSS_MCP_HTTP_TOKEN ?? '', allowKeyHeader });
+        process.stderr.write(`[palpluss-mcp] listening on http://${host}:${port}/mcp (toolsets: ${config.toolsets.join(', ')})\n`);
+        return;
+    }
+    const { server } = createPalplussMcpServer(config);
+    await server.connect(new StdioServerTransport());
+    // stdout carries the protocol; status goes to stderr.
+    process.stderr.write(`[palpluss-mcp] ready (toolsets: ${config.toolsets.join(', ')}${config.readOnly ? ', read-only' : ''}, approval: ${config.approval})\n`);
+}
+main().catch((err) => {
+    const msg = err instanceof ConfigError ? err.message : `Failed to start: ${err?.message ?? err}`;
+    process.stderr.write(`[palpluss-mcp] ${msg}\n`);
+    process.exit(1);
+});