@palpluss/mcp 0.0.0-stage → 0.1.0

package/EMBEDDING.md

@@ -0,0 +1,55 @@
+# 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.
+
+## 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 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.
+
+## 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,154 @@
-# 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 **asks you to approve it first**. The approval request goes to your MCP client's interface, not to the AI model, so the model 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.
+
+## 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}" }
+    }
+  }
+}
+```
+
+> **Before it's on npm:** build it (`pnpm --filter @palpluss/mcp build`) and use `node /path/to/palpluss-sdk/packages/mcp/dist/cli.js` in place of `npx -y @palpluss/mcp`.
+
+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_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_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 |
+
+**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:
+
+- **Your approval 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.
+- **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. The limits are enforced by this server process, not by PalPluss, so if you run several copies each keeps its own tally.
+- **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` | `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.
+
+## 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,83 @@
+/**
+ * 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.1.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' | 'BUYGOODS';
+    shortcode: string;
+    accountNumber?: string;
+    isDefault?: boolean;
+}
+export type ChannelUpdateBody = Partial<ChannelCreateBody> & {
+    accountNumber?: string | null;
+};
+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>;
+}
+export {};

package/dist/api/client.js

@@ -0,0 +1,131 @@
+/**
+ * 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.1.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 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 : '';
+            throw new PalplussApiError(message || `PalPluss request failed (${res.status}).`, res.status, code, 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 });
+    }
+}

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);
+});

package/dist/config.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Groups of tools. `read` is always on; the rest are switched on explicitly.
+ * Payouts and channel changes are off unless you name them.
+ */
+export declare const TOOLSETS: readonly ["read", "wallets", "collect", "channels", "payouts"];
+export type Toolset = (typeof TOOLSETS)[number];
+export declare const DEFAULT_TOOLSETS: Toolset[];
+/**
+ * How money-moving and channel-changing tools get a human's yes:
+ * - `elicit` (default): the MCP client shows the person an approval prompt;
+ *   the AI never sees or answers it. Clients without that support are refused.
+ * - `none`: no prompt. Only for automated tests against a fake or local API, never a live key.
+ */
+export type ApprovalMode = 'elicit' | 'none';
+export interface Limits {
+    /** Largest single B2C payout, KES. */
+    maxPayout: number;
+    /** Total B2C payouts per Nairobi calendar day, KES. */
+    dailyPayoutTotal: number;
+    /** Number of B2C payouts per Nairobi calendar day. */
+    dailyPayoutCount: number;
+    /** Largest wallet top-up, KES. */
+    maxTopup: number;
+    /** Largest STK push request, KES. */
+    maxStk: number;
+    /** If non-empty, payouts may only go to these numbers (254XXXXXXXXX). */
+    payoutAllowlist: string[];
+}
+export interface PalplussMcpConfig {
+    apiKey: string;
+    baseUrl: string;
+    timeoutMs: number;
+    toolsets: Toolset[];
+    /** Kill switch: when true, every tool that changes anything is refused. */
+    readOnly: boolean;
+    approval: ApprovalMode;
+    limits: Limits;
+    /** Where to keep the daily payout tally between restarts (stdio installs). */
+    stateFile?: string;
+    /** Append-only JSON-lines audit log of every tool call. */
+    auditFile?: string;
+}
+export declare const DEFAULT_BASE_URL = "https://api.palpluss.com";
+export declare const DEFAULT_LIMITS: Limits;
+export declare class ConfigError extends Error {
+}
+export declare function parseToolsets(raw: string | undefined): Toolset[];
+export declare function parseAllowlist(raw: string | undefined): string[];
+/** Build the configuration from environment variables (the CLI path). */
+export declare function loadConfigFromEnv(env?: NodeJS.ProcessEnv): PalplussMcpConfig;
+/** Fill in defaults for programmatic use (embedding in another app). */
+export declare function resolveConfig(input: Partial<PalplussMcpConfig> & {
+    apiKey: string;
+}): PalplussMcpConfig;

package/dist/config.js

@@ -0,0 +1,119 @@
+import { normalizePhone } from './safety/redact.js';
+/**
+ * Groups of tools. `read` is always on; the rest are switched on explicitly.
+ * Payouts and channel changes are off unless you name them.
+ */
+export const TOOLSETS = ['read', 'wallets', 'collect', 'channels', 'payouts'];
+export const DEFAULT_TOOLSETS = ['read', 'wallets', 'collect'];
+export const DEFAULT_BASE_URL = 'https://api.palpluss.com';
+export const DEFAULT_LIMITS = {
+    maxPayout: 5_000,
+    dailyPayoutTotal: 20_000,
+    dailyPayoutCount: 20,
+    maxTopup: 50_000,
+    maxStk: 150_000,
+    payoutAllowlist: [],
+};
+export class ConfigError extends Error {
+}
+function num(env, key, fallback) {
+    const raw = env[key];
+    if (raw === undefined || raw.trim() === '')
+        return fallback;
+    const n = Number(raw);
+    if (!Number.isFinite(n) || n < 0) {
+        throw new ConfigError(`${key} must be a non-negative number (got "${raw}").`);
+    }
+    return n;
+}
+function bool(env, key, fallback) {
+    const raw = env[key]?.trim().toLowerCase();
+    if (!raw)
+        return fallback;
+    if (['1', 'true', 'yes', 'on'].includes(raw))
+        return true;
+    if (['0', 'false', 'no', 'off'].includes(raw))
+        return false;
+    throw new ConfigError(`${key} must be true or false (got "${env[key]}").`);
+}
+export function parseToolsets(raw) {
+    if (!raw || !raw.trim())
+        return [...DEFAULT_TOOLSETS];
+    const wanted = raw
+        .split(',')
+        .map((s) => s.trim().toLowerCase())
+        .filter(Boolean);
+    if (wanted.includes('all'))
+        return [...TOOLSETS];
+    const unknown = wanted.filter((t) => !TOOLSETS.includes(t));
+    if (unknown.length) {
+        throw new ConfigError(`Unknown toolset(s): ${unknown.join(', ')}. Use any of: ${TOOLSETS.join(', ')} (or "all").`);
+    }
+    return [...new Set(['read', ...wanted])];
+}
+export function parseAllowlist(raw) {
+    if (!raw || !raw.trim())
+        return [];
+    const out = [];
+    for (const part of raw.split(',').map((s) => s.trim()).filter(Boolean)) {
+        const phone = normalizePhone(part);
+        if (!phone)
+            throw new ConfigError(`PALPLUSS_MCP_PAYOUT_ALLOWLIST has an invalid phone number: "${part}".`);
+        out.push(phone);
+    }
+    return [...new Set(out)];
+}
+/** Build the configuration from environment variables (the CLI path). */
+export function loadConfigFromEnv(env = process.env) {
+    const apiKey = env.PALPLUSS_API_KEY?.trim();
+    if (!apiKey) {
+        throw new ConfigError('PALPLUSS_API_KEY is not set. Create a key at console.palpluss.com → API Keys and pass it as an environment variable.');
+    }
+    const approval = (env.PALPLUSS_MCP_APPROVAL?.trim().toLowerCase() || 'elicit');
+    if (approval !== 'elicit' && approval !== 'none') {
+        throw new ConfigError('PALPLUSS_MCP_APPROVAL must be "elicit" or "none".');
+    }
+    return {
+        apiKey,
+        baseUrl: (env.PALPLUSS_BASE_URL?.trim() || DEFAULT_BASE_URL).replace(/\/+$/, ''),
+        timeoutMs: num(env, 'PALPLUSS_MCP_TIMEOUT_MS', 30_000),
+        toolsets: parseToolsets(env.PALPLUSS_MCP_TOOLSETS),
+        readOnly: bool(env, 'PALPLUSS_MCP_READ_ONLY', false),
+        approval,
+        limits: {
+            maxPayout: num(env, 'PALPLUSS_MCP_MAX_PAYOUT', DEFAULT_LIMITS.maxPayout),
+            dailyPayoutTotal: num(env, 'PALPLUSS_MCP_DAILY_PAYOUT_TOTAL', DEFAULT_LIMITS.dailyPayoutTotal),
+            dailyPayoutCount: num(env, 'PALPLUSS_MCP_DAILY_PAYOUT_COUNT', DEFAULT_LIMITS.dailyPayoutCount),
+            maxTopup: num(env, 'PALPLUSS_MCP_MAX_TOPUP', DEFAULT_LIMITS.maxTopup),
+            maxStk: num(env, 'PALPLUSS_MCP_MAX_STK', DEFAULT_LIMITS.maxStk),
+            payoutAllowlist: parseAllowlist(env.PALPLUSS_MCP_PAYOUT_ALLOWLIST),
+        },
+        stateFile: env.PALPLUSS_MCP_STATE_FILE?.trim() || undefined,
+        auditFile: env.PALPLUSS_MCP_AUDIT_FILE?.trim() || undefined,
+    };
+}
+/** Fill in defaults for programmatic use (embedding in another app). */
+export function resolveConfig(input) {
+    if (!input.apiKey?.trim())
+        throw new ConfigError('apiKey is required.');
+    return {
+        apiKey: input.apiKey.trim(),
+        baseUrl: (input.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, ''),
+        timeoutMs: input.timeoutMs ?? 30_000,
+        toolsets: input.toolsets ? [...new Set(['read', ...input.toolsets])] : [...DEFAULT_TOOLSETS],
+        readOnly: input.readOnly ?? false,
+        approval: input.approval ?? 'elicit',
+        limits: {
+            ...DEFAULT_LIMITS,
+            ...input.limits,
+            payoutAllowlist: (input.limits?.payoutAllowlist ?? []).map((p) => {
+                const n = normalizePhone(p);
+                if (!n)
+                    throw new ConfigError(`Invalid allowlist phone number: "${p}".`);
+                return n;
+            }),
+        },
+        stateFile: input.stateFile,
+        auditFile: input.auditFile,
+    };
+}