splitwise-mcp 3.3.1 → 3.4.1

package/dist/client.js

@@ -128,7 +128,9 @@ export class SplitwiseClient {
      * Optional constructor seam: a hosted per-user deployment builds one client
      * per request with that user's `apiKey` injected. The stdio path passes no
      * options, so the key resolves from the environment exactly as before —
-     * byte-for-byte identical behaviour.
+     * byte-for-byte identical behaviour. `baseUrl` points the API at another
+     * origin (the HTTP integration tests' fake Splitwise); it defaults to the
+     * real API.
      */
     constructor(opts) {
         // Injected apiKey (hosted per-user path) takes precedence; otherwise fall
@@ -153,7 +155,7 @@ export class SplitwiseClient {
             this.apiKey = key;
             this.configError = null;
         }
-        this.api = this.buildApiClient(BASE_URL, true);
+        this.api = this.buildApiClient(opts?.baseUrl ?? BASE_URL, true);
     }
     /**
      * Which source supplied the API key, for `sw_healthcheck`. Returns a LABEL
@@ -197,6 +199,16 @@ export class SplitwiseClient {
             assertWriteSucceeded(data);
         return data;
     }
+    /**
+     * A write sent as multipart/form-data — the only encoding Splitwise accepts
+     * for an expense that carries a receipt file. Same auth, retry and
+     * write-rejection handling as `request`.
+     */
+    async requestMultipart(method, path, formData) {
+        const data = await this.api.fetchJson(method, path, { formData });
+        assertWriteSucceeded(data);
+        return data;
+    }
     /**
      * Fetch the raw bytes behind an absolute asset URL the API handed back (an
      * expense receipt). Splitwise serves receipts two ways and this covers both:

package/dist/index.js

@@ -19,7 +19,7 @@ import { registerUtilityTools } from './tools/utilities.js';
 // client into the same registrars instead of this singleton.
 await runMcp({
     name: 'splitwise-mcp',
-    version: '3.3.1', // x-release-please-version
+    version: '3.4.1', // x-release-please-version
     deps: client,
     banner: '[splitwise-mcp] This project was developed and is maintained by AI (Claude Sonnet 4.6). Use at your own discretion.',
     tools: [

package/dist/tools/_receipt.js

@@ -0,0 +1,173 @@
+import { createHash } from 'crypto';
+import { readEnvVar } from '@chrischall/mcp-utils';
+import { z } from 'zod';
+/**
+ * Splitwise does not document an upload cap, so this is a conservative 10 MiB:
+ * comfortably above a phone photo or a multi-page PDF receipt, and small
+ * enough that the base64 form (≈13.4 MiB) stays a reasonable tool argument.
+ */
+export const MAX_RECEIPT_BYTES = 10 * 1024 * 1024;
+const LIMIT_LABEL = '10 MiB';
+/** The types the Splitwise web UI offers ("Attach an image or PDF"). */
+const RECEIPT_TYPES = [
+    { mime: 'image/png', ext: 'png', magic: [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a] },
+    { mime: 'image/jpeg', ext: 'jpg', magic: [0xff, 0xd8, 0xff] },
+    { mime: 'image/gif', ext: 'gif', magic: [0x47, 0x49, 0x46, 0x38] },
+    { mime: 'application/pdf', ext: 'pdf', magic: [0x25, 0x50, 0x44, 0x46, 0x2d] },
+];
+/** Spellings a caller may reasonably send for a detected type. */
+const MIME_ALIASES = { 'image/jpg': 'image/jpeg', 'image/pjpeg': 'image/jpeg' };
+export const receiptSchema = z
+    .object({
+    base64: z
+        .string()
+        .min(1)
+        .describe('The file bytes, base64-encoded (a data: URL prefix is accepted and stripped). The normal way to pass a receipt.')
+        .optional(),
+    path: z
+        .string()
+        .min(1)
+        .describe('A file inside SPLITWISE_INPUT_DIR on the machine running this server (relative to it, or absolute). Only works when that variable is set — never on a hosted server; use base64 there.')
+        .optional(),
+    filename: z.string().min(1).max(200).describe('Name to store the file under, e.g. "receipt.pdf".'),
+    mime_type: z
+        .string()
+        .describe('Optional. If given, it must match the type detected from the file contents.')
+        .optional(),
+})
+    .describe(`Receipt to attach: PNG, JPEG, GIF or PDF, up to ${LIMIT_LABEL}. Give exactly one of base64 or path. The type is detected from the file contents. Replaces any receipt already on the expense.`);
+export const receiptParam = receiptSchema.optional();
+const tooBig = (size) => new Error(`Receipt is ${size} bytes, over the ${LIMIT_LABEL} limit (${MAX_RECEIPT_BYTES} bytes)`);
+function sniff(bytes) {
+    return RECEIPT_TYPES.find((t) => t.magic.every((b, i) => bytes[i] === b));
+}
+function decodeBase64(input) {
+    const stripped = input.replace(/^data:[^;,]*;base64,/i, '').replace(/\s+/g, '');
+    // Refuse on the encoded length so an oversized argument is never decoded.
+    const decodedSize = Math.floor((stripped.length * 3) / 4) - (stripped.match(/=*$/)?.[0].length ?? 0);
+    if (decodedSize > MAX_RECEIPT_BYTES)
+        throw tooBig(decodedSize);
+    // Never echo the input: it is the caller's file.
+    if (!/^[A-Za-z0-9+/]*={0,2}$/.test(stripped) || stripped.length % 4 === 1) {
+        throw new Error('receipt.base64 is not valid base64');
+    }
+    return Uint8Array.from(Buffer.from(stripped, 'base64'));
+}
+/** Keep the stored name to a plain basename: no directories, no control characters. */
+function cleanFilename(name) {
+    const base = name.split(/[\\/]/).pop() ?? '';
+    return base.replace(/[\u0000-\u001f\u007f"]/g, '').trim();
+}
+/**
+ * Read a receipt from SPLITWISE_INPUT_DIR. Unset means no filesystem access at
+ * all — the hosted case, where the caller's files are not on this machine and
+ * the server's own files must not be reachable. Both the dir and the target
+ * are realpath-resolved, so `..` and symlinks (to a file or through a
+ * directory) that lead out of the dir are refused; the bytes are then read
+ * through the handle that was checked, not by re-opening the name.
+ */
+async function readSandboxed(requested) {
+    const dir = readEnvVar('SPLITWISE_INPUT_DIR');
+    if (!dir) {
+        throw new Error('receipt.path is disabled: SPLITWISE_INPUT_DIR is not set on this server (and a hosted server cannot see your files). Pass the file as receipt.base64 instead.');
+    }
+    const { open, realpath } = await import('fs/promises');
+    const { constants } = await import('fs');
+    const { isAbsolute, relative, resolve, sep } = await import('path');
+    let root;
+    try {
+        root = await realpath(dir);
+    }
+    catch (err) {
+        throw new Error(`SPLITWISE_INPUT_DIR (${dir}) is not readable: ${err.message}`);
+    }
+    let target;
+    try {
+        target = await realpath(resolve(root, requested));
+    }
+    catch (err) {
+        throw new Error(`Cannot read receipt file ${requested}: ${err.code ?? err.message}`);
+    }
+    const rel = relative(root, target);
+    if (rel === '' || rel === '..' || rel.startsWith(`..${sep}`) || isAbsolute(rel)) {
+        throw new Error(`receipt.path ${requested} resolves outside SPLITWISE_INPUT_DIR`);
+    }
+    // O_NOFOLLOW: a symlink swapped in after the realpath check is refused.
+    const handle = await open(target, constants.O_RDONLY | constants.O_NOFOLLOW);
+    try {
+        const info = await handle.stat();
+        if (!info.isFile())
+            throw new Error(`Cannot read receipt file ${requested}: not a regular file`);
+        if (info.size > MAX_RECEIPT_BYTES)
+            throw tooBig(info.size);
+        return Uint8Array.from(await handle.readFile());
+    }
+    finally {
+        await handle.close();
+    }
+}
+/**
+ * Read and validate a receipt before the confirmation gate, so a bad file is
+ * refused on the first call and the preview can name exactly what will be sent.
+ */
+export async function loadReceipt(input) {
+    const hasPath = input.path !== undefined;
+    const hasBase64 = input.base64 !== undefined;
+    if (hasPath === hasBase64) {
+        throw new Error('receipt needs exactly one of path or base64');
+    }
+    const bytes = hasPath ? await readSandboxed(input.path) : decodeBase64(input.base64);
+    if (bytes.length === 0)
+        throw new Error('Receipt file is empty');
+    if (bytes.length > MAX_RECEIPT_BYTES)
+        throw tooBig(bytes.length);
+    const type = sniff(bytes);
+    if (!type) {
+        throw new Error('Receipt must be a PNG, JPEG, GIF or PDF (detected from the file contents)');
+    }
+    if (input.mime_type !== undefined) {
+        const claimed = input.mime_type.trim().toLowerCase();
+        if ((MIME_ALIASES[claimed] ?? claimed) !== type.mime) {
+            throw new Error(`receipt.mime_type ${claimed} does not match the file contents (${type.mime})`);
+        }
+    }
+    const filename = cleanFilename(input.filename) || `receipt.${type.ext}`;
+    const sha256 = createHash('sha256').update(bytes).digest('hex');
+    return {
+        bytes,
+        filename,
+        mimeType: type.mime,
+        summary: { filename, mime_type: type.mime, bytes: bytes.length, sha256 },
+    };
+}
+/**
+ * Build the multipart body Splitwise takes when an expense carries a file:
+ * every expense field as a form field (the same flat `users__N__*` keys the
+ * JSON path sends), plus the file under `receipt`.
+ */
+export function buildReceiptForm(fields, receipt) {
+    const form = new FormData();
+    for (const [key, value] of Object.entries(fields)) {
+        if (value === undefined || value === null)
+            continue;
+        form.append(key, String(value));
+    }
+    form.append('receipt', new Blob([receipt.bytes], { type: receipt.mimeType }), receipt.filename);
+    return form;
+}
+/**
+ * After a receipt write, confirm Splitwise actually stored the file. It can
+ * answer 200 with the expense saved and `receipt.original` still null; that is
+ * a failure the caller must hear about, not a success. Returns the response
+ * with `receipt_attached` and the expense's `receipt` lifted to the top.
+ */
+export function verifyReceiptStored(data, expenseId) {
+    const expense = data
+        ?.expenses?.[0];
+    const id = expense?.id ?? expenseId;
+    if (!expense?.receipt?.original) {
+        throw new Error(`Splitwise saved expense ${id ?? '(unknown id)'} but did not attach the receipt (receipt.original is empty). ` +
+            `The expense itself was written — do not re-create it; retry the file with sw_attach_receipt on expense ${id ?? '<id>'}.`);
+    }
+    return { receipt_attached: true, receipt: expense.receipt, ...data };
+}

package/dist/tools/expenses.js

@@ -3,6 +3,7 @@ import { SW_VIEWS, viewExpense, viewExpenses } from '../project.js';
 import { buildQueryString, minifiedResult, resolveView, viewParam } from '@chrischall/mcp-utils';
 import { CONFIRM_NOTE, confirmTokenParam, confirmWrite } from './_confirm.js';
 import { UNTRUSTED_DESCRIPTION_SUFFIX, swUntrustedResult } from './_untrusted.js';
+import { buildReceiptForm, loadReceipt, receiptParam, receiptSchema, verifyReceiptStored, } from './_receipt.js';
 /** Flattens a users array into Splitwise's flat-param JSON format. */
 export function flattenUsers(users) {
     const flat = {};
@@ -14,8 +15,9 @@ export function flattenUsers(users) {
     return flat;
 }
 function buildExpenseBody(args) {
-    // `confirmToken` is a tool-gate input, not part of the Splitwise expense payload.
-    const { split_equally, users, expense_id: _id, confirmToken: _confirmToken, ...rest } = args;
+    // `confirmToken` is a tool-gate input and `receipt` is sent as a file part,
+    // so neither belongs in the expense fields.
+    const { split_equally, users, expense_id: _id, confirmToken: _confirmToken, receipt: _receipt, ...rest } = args;
     if (split_equally && users) {
         throw new Error('Provide either split_equally or users, not both');
     }
@@ -28,6 +30,22 @@ function buildExpenseBody(args) {
     }
     return body;
 }
+/**
+ * Send a create/update. With a receipt the whole expense goes as multipart
+ * (Splitwise only takes a file that way) and the response must show the file
+ * stored; without one it stays JSON and the response passes through, exactly
+ * as before.
+ */
+async function sendExpenseWrite(client, path, body, receipt, expenseId) {
+    if (!receipt)
+        return client.request('POST', path, body);
+    const data = await client.requestMultipart('POST', path, buildReceiptForm(body, receipt));
+    return verifyReceiptStored(data, expenseId);
+}
+/** The body the confirmation preview shows: the fields, plus the file's identity in place of its bytes. */
+function previewBody(body, receipt) {
+    return receipt ? { ...body, receipt: receipt.summary } : body;
+}
 const userShareSchema = z.object({
     user_id: z.number(),
     paid_share: z.string().describe('Amount this user paid, e.g. "25.00"'),
@@ -92,7 +110,7 @@ export function registerExpenseTools(server, client) {
         return swUntrustedResult(viewExpense(resolveView(view, SW_VIEWS), data));
     });
     server.registerTool('sw_create_expense', {
-        description: `Create a Splitwise expense. Use split_equally:true to split evenly among group members, or provide a users array for custom per-person splits (paid_share and owed_share as decimal strings like "25.00"). cost must be a decimal string. This puts charges on every participant's balance and notifies them. ${CONFIRM_NOTE}`,
+        description: `Create a Splitwise expense. Use split_equally:true to split evenly among group members, or provide a users array for custom per-person splits (paid_share and owed_share as decimal strings like "25.00"). cost must be a decimal string. Pass receipt to attach an image or PDF in the same call. This puts charges on every participant's balance and notifies them. ${CONFIRM_NOTE}`,
         annotations: { readOnlyHint: false, destructiveHint: true, openWorldHint: true },
         inputSchema: z.object({
             group_id: z.number().describe('Group to add expense to (use 0 for no group)'),
@@ -113,28 +131,30 @@ export function registerExpenseTools(server, client) {
             date: z.string().describe('ISO 8601 datetime').optional(),
             category_id: z.number().describe('Category id from sw_get_categories').optional(),
             details: z.string().describe('Notes').optional(),
+            receipt: receiptParam,
             confirmToken: confirmTokenParam,
         }),
     }, async (args, ctx) => {
         const body = buildExpenseBody(args);
+        const receipt = args.receipt ? await loadReceipt(args.receipt) : undefined;
         const gate = await confirmWrite(ctx, {
             tool: 'sw_create_expense',
             action: 'expense.create',
-            summary: `Create a Splitwise expense "${args.description}" (${args.cost}) — notifies group members`,
+            summary: `Create a Splitwise expense "${args.description}" (${args.cost})${receipt ? ` with receipt ${receipt.filename}` : ''} — notifies group members`,
             method: 'POST',
             path: '/create_expense',
-            body,
+            body: previewBody(body, receipt),
             target: args.group_id,
             confirmToken: args.confirmToken,
             args,
         });
         if (gate)
             return gate;
-        const data = await client.request('POST', '/create_expense', body);
+        const data = await sendExpenseWrite(client, '/create_expense', body, receipt);
         return minifiedResult(data);
     });
     server.registerTool('sw_update_expense', {
-        description: `Edit an existing Splitwise expense. Provide expense_id and any fields to change. For custom split updates, the full users array must be provided (the API replaces the entire split). ${CONFIRM_NOTE}`,
+        description: `Edit an existing Splitwise expense. Provide expense_id and any fields to change. For custom split updates, the full users array must be provided (the API replaces the entire split). To attach or replace the receipt on an existing expense, pass expense_id and receipt alone. ${CONFIRM_NOTE}`,
         annotations: { readOnlyHint: false, destructiveHint: true, openWorldHint: true },
         inputSchema: z.object({
             expense_id: z.number().describe('ID of the expense to update'),
@@ -149,25 +169,55 @@ export function registerExpenseTools(server, client) {
             date: z.string().optional(),
             category_id: z.number().optional(),
             details: z.string().optional(),
+            receipt: receiptParam,
             confirmToken: confirmTokenParam,
         }),
     }, async (args, ctx) => {
         const { expense_id } = args;
         const body = buildExpenseBody(args);
+        const receipt = args.receipt ? await loadReceipt(args.receipt) : undefined;
         const gate = await confirmWrite(ctx, {
             tool: 'sw_update_expense',
             action: 'expense.update',
-            summary: `Update Splitwise expense ${expense_id} — notifies group members`,
+            summary: `Update Splitwise expense ${expense_id}${receipt ? ` (attach receipt ${receipt.filename})` : ''} — notifies group members`,
             method: 'POST',
             path: `/update_expense/${expense_id}`,
-            body,
+            body: previewBody(body, receipt),
+            target: expense_id,
+            confirmToken: args.confirmToken,
+            args,
+        });
+        if (gate)
+            return gate;
+        const data = await sendExpenseWrite(client, `/update_expense/${expense_id}`, body, receipt, expense_id);
+        return minifiedResult(data);
+    });
+    server.registerTool('sw_attach_receipt', {
+        description: `Attach (or replace) the receipt image or PDF on an existing Splitwise expense. Changes nothing else on the expense — cost, split and description are not sent. Pass the file as receipt.base64. Fails if Splitwise does not store the file. ${CONFIRM_NOTE}`,
+        annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: true },
+        inputSchema: z.object({
+            expense_id: z.number().describe('ID of the expense to attach the receipt to'),
+            receipt: receiptSchema,
+            confirmToken: confirmTokenParam,
+        }),
+    }, async (args, ctx) => {
+        const { expense_id } = args;
+        const receipt = await loadReceipt(args.receipt);
+        const path = `/update_expense/${expense_id}`;
+        const gate = await confirmWrite(ctx, {
+            tool: 'sw_attach_receipt',
+            action: 'expense.attach_receipt',
+            summary: `Attach receipt ${receipt.filename} to Splitwise expense ${expense_id} (replaces any existing receipt)`,
+            method: 'POST',
+            path,
+            body: previewBody({}, receipt),
             target: expense_id,
             confirmToken: args.confirmToken,
             args,
         });
         if (gate)
             return gate;
-        const data = await client.request('POST', `/update_expense/${expense_id}`, body);
+        const data = await sendExpenseWrite(client, path, {}, receipt, expense_id);
         return minifiedResult(data);
     });
     server.registerTool('sw_delete_expense', {

package/dist/tools/receipts.js

@@ -1,5 +1,5 @@
 import { z } from 'zod';
-import { minifiedResult, imageResult, readEnvVar, resolveOutputDir, writeBinaryOutput, sniffMimeBytes, } from '@chrischall/mcp-utils';
+import { minifiedResult, imageResult, readEnvVar, resolveOutputDir, writeBinaryOutput, sniffMimeBytes, extensionForMime, } from '@chrischall/mcp-utils';
 import { UNTRUSTED_DESCRIPTION_SUFFIX, swUntrustedEnvelope } from './_untrusted.js';
 /** Cap on bytes returned as base64 in the tool result. */
 const MAX_INLINE_BYTES = 4 * 1024 * 1024;
@@ -49,24 +49,6 @@ function resolveMimeType(contentType, bytes) {
     const declared = (contentType ?? '').split(';')[0].trim().toLowerCase();
     return declared && !GENERIC_TYPES.has(declared) ? declared : undefined;
 }
-/** Extension from a URL path (`…/receipt.jpg?sig=…` → `jpg`), when it has one. */
-function extensionFromUrl(url) {
-    const match = /\.([a-z0-9]{1,5})$/i.exec(new URL(url).pathname);
-    return match ? match[1].toLowerCase() : undefined;
-}
-/**
- * File extension for the receipt: the MIME subtype when it looks like a plain
- * one (`application/pdf` → `pdf`, `image/heic` → `heic`), else the URL's own
- * extension, else `bin`.
- */
-function extensionFor(mimeType, url) {
-    const subtype = mimeType?.split('/')[1];
-    if (subtype === 'jpeg')
-        return 'jpg';
-    if (subtype && /^[a-z0-9]{1,5}$/.test(subtype))
-        return subtype;
-    return extensionFromUrl(url) ?? 'bin';
-}
 /**
  * Extract a PDF's text layer. `unpdf` is imported lazily so the cost lands only
  * on calls that ask for text — it is a sizable pdf.js build, and every other
@@ -162,7 +144,8 @@ export function registerReceiptTools(server, client) {
                     }),
                     baseName: `splitwise-receipt-${id}`,
                     base64,
-                    extension: extensionFor(mimeType, url),
+                    // The MIME type, else the receipt URL's own extension, else `bin`.
+                    extension: extensionForMime(mimeType, { url }),
                     mode: RECEIPT_FILE_MODE,
                 });
             }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "splitwise-mcp",
-  "version": "3.3.1",
+  "version": "3.4.1",
   "mcpName": "io.github.chrischall/splitwise-mcp",
   "description": "Splitwise MCP server for Claude — developed and maintained by AI (Claude Code)",
   "author": "Claude Code (AI) <https://www.anthropic.com/claude>",
@@ -45,7 +45,7 @@
     "typecheck": "tsc -p tsconfig.json --noEmit"
   },
   "dependencies": {
-    "@chrischall/mcp-utils": "^3.0.0",
+    "@chrischall/mcp-utils": "^3.0.3",
     "@modelcontextprotocol/server": "^2.3.0",
     "dotenv": "^18.0.2",
     "unpdf": "^1.8.1",

package/server.json

@@ -6,12 +6,12 @@
     "url": "https://github.com/chrischall/splitwise-mcp",
     "source": "github"
   },
-  "version": "3.3.1",
+  "version": "3.4.1",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "splitwise-mcp",
-      "version": "3.3.1",
+      "version": "3.4.1",
       "transport": {
         "type": "stdio"
       },
@@ -29,6 +29,13 @@
           "isRequired": false,
           "format": "string",
           "isSecret": false
+        },
+        {
+          "name": "SPLITWISE_INPUT_DIR",
+          "description": "Directory receipt.path may read uploads from (unset: receipts are accepted as base64 only)",
+          "isRequired": false,
+          "format": "string",
+          "isSecret": false
         }
       ]
     }

package/skills/splitwise-mcp/SKILL.md

@@ -92,10 +92,11 @@ API key auth — no login flow or token rotation. The key is attached to every r
 |------|-------------|
 | `sw_list_expenses(group_id?, friend_id?, dated_after?, dated_before?, limit?, offset?, view?)` | List or search expenses |
 | `sw_get_expense(id, view?)` | Get full details of a single expense |
-| `sw_create_expense(group_id, description, cost, split_equally? \| users?)` | Create an expense — equal split or custom per-person split |
-| `sw_update_expense(expense_id, ...)` | Edit an existing expense (custom split requires full `users` array) |
+| `sw_create_expense(group_id, description, cost, split_equally? \| users?, receipt?)` | Create an expense — equal split or custom per-person split; `receipt` attaches an image/PDF in the same call |
+| `sw_update_expense(expense_id, ..., receipt?)` | Edit an existing expense (custom split requires full `users` array). `expense_id` + `receipt` alone attaches or replaces the receipt |
 | `sw_delete_expense(id)` | Soft-delete an expense |
 | `sw_undelete_expense(id)` | Restore a soft-deleted expense |
+| `sw_attach_receipt(expense_id, receipt)` | Attach or replace the receipt on an existing expense; changes nothing else |
 
 ### Receipts
 | Tool | Description |
@@ -173,8 +174,8 @@ The other eighteen tools take no `view`, each for its own reason:
 - **`sw_get_categories` and `sw_get_currencies`** are static reference lists —
   already narrow, no media, and every field on them is the answer.
 - **`sw_healthcheck`** answers reachability and auth.
-- **The fourteen writes** (`sw_create_expense`, `sw_update_expense`,
-  `sw_delete_expense`, `sw_undelete_expense`, `sw_create_group`,
+- **The fifteen writes** (`sw_create_expense`, `sw_update_expense`,
+  `sw_attach_receipt`, `sw_delete_expense`, `sw_undelete_expense`, `sw_create_group`,
   `sw_delete_group`, `sw_undelete_group`, `sw_add_user_to_group`,
   `sw_remove_user_from_group`, `sw_create_friend`, `sw_delete_friend`,
   `sw_create_comment`, `sw_delete_comment`, `sw_update_user`) return receipts —
@@ -205,6 +206,16 @@ sw_create_expense(group_id, "Hotel", "200.00", users: [
 ])
 ```
 
+**Attach a receipt (proof of purchase):**
+
+```
+sw_create_expense(group_id, "Band camp water jug", "54.11", split_equally: true,
+                  receipt: { base64: "<png/jpeg/gif/pdf bytes>", filename: "amazon-order.png" })
+sw_attach_receipt(expense_id, receipt: { base64: "<png/jpeg/gif/pdf bytes>", filename: "order.pdf" })
+```
+
+`receipt` takes `filename` plus exactly one of `base64` (the normal input) or `path` (only on a local server with `SPLITWISE_INPUT_DIR` set, and only inside that directory). PNG, JPEG, GIF or PDF, ≤ 10 MiB, type detected from the bytes. It replaces any existing receipt. Use `sw_attach_receipt` to add a file to an existing expense — it sends nothing but the file. If Splitwise saves the expense but drops the file, the tool returns an error naming the expense: do not re-create it, retry with `sw_attach_receipt`.
+
 **Get the receipt for an expense:**
 ```
 sw_list_expenses(...) → find expense ID