splitwise-mcp 3.3.1 → 3.4.0

package/.claude-plugin/marketplace.json

@@ -7,7 +7,7 @@
   },
   "metadata": {
     "description": "MCP server for Splitwise — natural-language expense and group management via the Splitwise API",
-    "version": "3.3.1"
+    "version": "3.4.0"
   },
   "plugins": [
     {
@@ -15,7 +15,7 @@
       "displayName": "Splitwise",
       "source": "./",
       "description": "MCP server for Splitwise — manage expenses, groups, and friends via natural language",
-      "version": "3.3.1",
+      "version": "3.4.0",
       "author": {
         "name": "Chris Hall"
       },

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "splitwise-mcp",
   "displayName": "Splitwise",
-  "version": "3.3.1",
+  "version": "3.4.0",
   "description": "MCP server for Splitwise — natural-language expense and group management via the Splitwise API",
   "author": {
     "name": "Chris Hall",

package/.mcp.json

@@ -7,7 +7,8 @@
       ],
       "env": {
         "SPLITWISE_API_KEY": "${SPLITWISE_API_KEY}",
-        "SPLITWISE_OUTPUT_DIR": "${SPLITWISE_OUTPUT_DIR}"
+        "SPLITWISE_OUTPUT_DIR": "${SPLITWISE_OUTPUT_DIR}",
+        "SPLITWISE_INPUT_DIR": "${SPLITWISE_INPUT_DIR}"
       }
     }
   }

package/README.md

@@ -21,6 +21,7 @@ Ask Claude things like:
 - *"Show me recent expenses"*
 - *"Delete that duplicate expense"*
 - *"Download the receipt from that hotel expense"*
+- *"Add that Amazon order screenshot as the receipt on the water-jug expense"*
 
 ## Requirements
 
@@ -114,6 +115,7 @@ Add to Claude Desktop config:
 |---------|----------|-------|
 | `SPLITWISE_API_KEY` | Yes | API key from [splitwise.com/apps/register](https://secure.splitwise.com/apps/register) |
 | `SPLITWISE_OUTPUT_DIR` | No | Where `sw_get_receipt` writes downloaded receipts (owner-only, mode 0600). Defaults to `~/Downloads/splitwise-mcp`, never the working directory. When set, a per-call `output_dir` must be inside it. |
+| `SPLITWISE_INPUT_DIR` | No | The only directory `receipt.path` may read from (`..` and symlinks out of it are refused). Unset — always the case on a hosted server — means receipts are accepted as `base64` only. |
 
 ## Confirmations
 
@@ -165,10 +167,11 @@ Every Splitwise write (creating, editing or deleting expenses, groups, friends,
 |------|-------------|
 | `sw_list_expenses` | List or search expenses with filters |
 | `sw_get_expense` | Full details of a single expense |
-| `sw_create_expense` | Create an expense (equal or custom split) |
-| `sw_update_expense` | Edit an existing expense |
+| `sw_create_expense` | Create an expense (equal or custom split), optionally with a receipt image/PDF |
+| `sw_update_expense` | Edit an existing expense, or attach/replace its receipt |
 | `sw_delete_expense` | Soft-delete an expense |
 | `sw_undelete_expense` | Restore a deleted expense |
+| `sw_attach_receipt` | Attach or replace the receipt on an existing expense, changing nothing else |
 | `sw_get_comments` | Get comments on an expense |
 | `sw_create_comment` | Add a comment to an expense |
 | `sw_delete_comment` | Delete a comment |
@@ -191,6 +194,8 @@ Every Splitwise write (creating, editing or deleting expenses, groups, friends,
 
 **"SPLITWISE_API_KEY is required"** -- set the environment variable in your MCP config or a `.env` file.
 
+**Attaching a receipt** -- `sw_create_expense`, `sw_update_expense` and `sw_attach_receipt` take `receipt: { base64, filename, mime_type? }` (works everywhere, including a hosted server) or, on a local server with `SPLITWISE_INPUT_DIR` set, `receipt: { path, filename }` for a file inside that directory. PNG, JPEG, GIF or PDF up to 10 MiB (Splitwise documents no limit); the type is detected from the bytes, and a `mime_type` that disagrees is refused. The confirmation preview shows the file's name, type, size and SHA-256 instead of its contents, and the token is bound to those bytes. After the write the tool checks Splitwise actually stored the file (`receipt.original`) and returns an error naming the expense if it did not. A receipt replaces any receipt already on the expense.
+
 **401 when opening a receipt URL** -- the `receipt.original` / `receipt.large` URLs on an expense are not public; they need the API key. Use `sw_get_receipt` instead of fetching them directly.
 
 **Receipt lands somewhere you can't read it** -- `sw_get_receipt` writes to the *server's* filesystem, which is not the caller's when the server is hosted or containerised. Pass `inline: true` for the bytes (an image block for images, an embedded resource for PDFs) or `extract_text: true` for a PDF's text. With `inline` or `extract_text` and no `output_dir`, nothing is written unless you also pass `write: true`. Pass `write: false` to skip the write in any case; if it fails on its own (read-only filesystem), the call still succeeds and reports `write_error` as long as you asked for content.

package/dist/bundle.js

@@ -1948,10 +1948,10 @@ var require_checks = __commonJS({
         const size = input2.size;
         if (size === def.size)
           return;
-        const tooBig = size > def.size;
+        const tooBig2 = size > def.size;
         payload.issues.push({
           origin: util.getSizableOrigin(input2),
-          ...tooBig ? { code: "too_big", maximum: def.size } : { code: "too_small", minimum: def.size },
+          ...tooBig2 ? { code: "too_big", maximum: def.size } : { code: "too_small", minimum: def.size },
           inclusive: true,
           exact: true,
           input: payload.value,
@@ -2015,10 +2015,10 @@ var require_checks = __commonJS({
         if (length === def.length)
           return;
         const origin = util.getLengthableOrigin(input2);
-        const tooBig = length > def.length;
+        const tooBig2 = length > def.length;
         payload.issues.push({
           origin,
-          ...tooBig ? { code: "too_big", maximum: def.length } : { code: "too_small", minimum: def.length },
+          ...tooBig2 ? { code: "too_big", maximum: def.length } : { code: "too_small", minimum: def.length },
           inclusive: true,
           exact: true,
           input: payload.value,
@@ -63308,7 +63308,7 @@ function declaredDialect(schema, remedy) {
   throw new Error(`JSON Schema declares an unsupported dialect ("$schema": "${schema.$schema.slice(0, 200)}"). The default validator supports JSON Schema 2020-12, 2019-09, draft-07, and draft-06; ${remedy}`);
 }
 
-// node_modules/@modelcontextprotocol/core/dist/auth-BNDyLTqp.mjs
+// node_modules/@modelcontextprotocol/server/node_modules/@modelcontextprotocol/core/dist/auth-BNDyLTqp.mjs
 var z = __toESM(require_v4(), 1);
 var LATEST_PROTOCOL_VERSION = "2025-11-25";
 var SUPPORTED_PROTOCOL_VERSIONS = [
@@ -80524,10 +80524,10 @@ var $ZodCheckSizeEquals = /* @__PURE__ */ $constructor("$ZodCheckSizeEquals", (i
     const size = input2.size;
     if (size === def.size)
       return;
-    const tooBig = size > def.size;
+    const tooBig2 = size > def.size;
     payload.issues.push({
       origin: getSizableOrigin(input2),
-      ...tooBig ? { code: "too_big", maximum: def.size } : { code: "too_small", minimum: def.size },
+      ...tooBig2 ? { code: "too_big", maximum: def.size } : { code: "too_small", minimum: def.size },
       inclusive: true,
       exact: true,
       input: payload.value,
@@ -80591,10 +80591,10 @@ var $ZodCheckLengthEquals = /* @__PURE__ */ $constructor("$ZodCheckLengthEquals"
     if (length === def.length)
       return;
     const origin = getLengthableOrigin(input2);
-    const tooBig = length > def.length;
+    const tooBig2 = length > def.length;
     payload.issues.push({
       origin,
-      ...tooBig ? { code: "too_big", maximum: def.length } : { code: "too_small", minimum: def.length },
+      ...tooBig2 ? { code: "too_big", maximum: def.length } : { code: "too_small", minimum: def.length },
       inclusive: true,
       exact: true,
       input: payload.value,
@@ -99842,7 +99842,9 @@ var SplitwiseClient = class {
    * 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) {
     const injected = opts?.apiKey;
@@ -99855,7 +99857,7 @@ var SplitwiseClient = class {
       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
@@ -99895,6 +99897,16 @@ var SplitwiseClient = class {
     if (method.toUpperCase() !== "GET") 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:
@@ -100617,6 +100629,129 @@ function swUntrustedEnvelope(payload) {
   return untrustedEnvelope(payload, { note: SW_UNTRUSTED_NOTE });
 }
 
+// src/tools/_receipt.ts
+import { createHash as createHash4 } from "crypto";
+var MAX_RECEIPT_BYTES = 10 * 1024 * 1024;
+var LIMIT_LABEL = "10 MiB";
+var RECEIPT_TYPES = [
+  { mime: "image/png", ext: "png", magic: [137, 80, 78, 71, 13, 10, 26, 10] },
+  { mime: "image/jpeg", ext: "jpg", magic: [255, 216, 255] },
+  { mime: "image/gif", ext: "gif", magic: [71, 73, 70, 56] },
+  { mime: "application/pdf", ext: "pdf", magic: [37, 80, 68, 70, 45] }
+];
+var MIME_ALIASES = { "image/jpg": "image/jpeg", "image/pjpeg": "image/jpeg" };
+var receiptSchema = external_exports.object({
+  base64: external_exports.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: external_exports.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 \u2014 never on a hosted server; use base64 there."
+  ).optional(),
+  filename: external_exports.string().min(1).max(200).describe('Name to store the file under, e.g. "receipt.pdf".'),
+  mime_type: external_exports.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.`
+);
+var receiptParam = receiptSchema.optional();
+var tooBig = (size) => new Error(`Receipt is ${size} bytes, over the ${LIMIT_LABEL} limit (${MAX_RECEIPT_BYTES} bytes)`);
+function sniff(bytes) {
+  return RECEIPT_TYPES.find((t2) => t2.magic.every((b2, i2) => bytes[i2] === b2));
+}
+function decodeBase64(input2) {
+  const stripped = input2.replace(/^data:[^;,]*;base64,/i, "").replace(/\s+/g, "");
+  const decodedSize = Math.floor(stripped.length * 3 / 4) - (stripped.match(/=*$/)?.[0].length ?? 0);
+  if (decodedSize > MAX_RECEIPT_BYTES) throw tooBig(decodedSize);
+  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"));
+}
+function cleanFilename(name) {
+  const base = name.split(/[\\/]/).pop() ?? "";
+  return base.replace(/[\u0000-\u001f\u007f"]/g, "").trim();
+}
+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: open2, realpath } = await import("fs/promises");
+  const { constants } = await import("fs");
+  const { isAbsolute: isAbsolute4, relative: relative2, resolve: resolve4, sep: sep2 } = 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(resolve4(root, requested));
+  } catch (err) {
+    throw new Error(`Cannot read receipt file ${requested}: ${err.code ?? err.message}`);
+  }
+  const rel = relative2(root, target);
+  if (rel === "" || rel === ".." || rel.startsWith(`..${sep2}`) || isAbsolute4(rel)) {
+    throw new Error(`receipt.path ${requested} resolves outside SPLITWISE_INPUT_DIR`);
+  }
+  const handle = await open2(target, constants.O_RDONLY | constants.O_NOFOLLOW);
+  try {
+    const info2 = await handle.stat();
+    if (!info2.isFile()) throw new Error(`Cannot read receipt file ${requested}: not a regular file`);
+    if (info2.size > MAX_RECEIPT_BYTES) throw tooBig(info2.size);
+    return Uint8Array.from(await handle.readFile());
+  } finally {
+    await handle.close();
+  }
+}
+async function loadReceipt(input2) {
+  const hasPath = input2.path !== void 0;
+  const hasBase64 = input2.base64 !== void 0;
+  if (hasPath === hasBase64) {
+    throw new Error("receipt needs exactly one of path or base64");
+  }
+  const bytes = hasPath ? await readSandboxed(input2.path) : decodeBase64(input2.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 (input2.mime_type !== void 0) {
+    const claimed = input2.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(input2.filename) || `receipt.${type.ext}`;
+  const sha256 = createHash4("sha256").update(bytes).digest("hex");
+  return {
+    bytes,
+    filename,
+    mimeType: type.mime,
+    summary: { filename, mime_type: type.mime, bytes: bytes.length, sha256 }
+  };
+}
+function buildReceiptForm(fields, receipt) {
+  const form = new FormData();
+  for (const [key, value] of Object.entries(fields)) {
+    if (value === void 0 || value === null) continue;
+    form.append(key, String(value));
+  }
+  form.append("receipt", new Blob([receipt.bytes], { type: receipt.mimeType }), receipt.filename);
+  return form;
+}
+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 \u2014 do not re-create it; retry the file with sw_attach_receipt on expense ${id ?? "<id>"}.`
+    );
+  }
+  return { receipt_attached: true, receipt: expense.receipt, ...data };
+}
+
 // src/tools/expenses.ts
 function flattenUsers(users) {
   const flat = {};
@@ -100633,6 +100768,7 @@ function buildExpenseBody(args) {
     users,
     expense_id: _id,
     confirmToken: _confirmToken,
+    receipt: _receipt,
     ...rest
   } = args;
   if (split_equally && users) {
@@ -100646,6 +100782,14 @@ function buildExpenseBody(args) {
   }
   return body;
 }
+async function sendExpenseWrite(client2, path, body, receipt, expenseId) {
+  if (!receipt) return client2.request("POST", path, body);
+  const data = await client2.requestMultipart("POST", path, buildReceiptForm(body, receipt));
+  return verifyReceiptStored(data, expenseId);
+}
+function previewBody(body, receipt) {
+  return receipt ? { ...body, receipt: receipt.summary } : body;
+}
 var userShareSchema = external_exports.object({
   user_id: external_exports.number(),
   paid_share: external_exports.string().describe('Amount this user paid, e.g. "25.00"'),
@@ -100708,7 +100852,7 @@ function registerExpenseTools(server, client2) {
   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: external_exports.object({
         group_id: external_exports.number().describe("Group to add expense to (use 0 for no group)"),
@@ -100722,31 +100866,33 @@ function registerExpenseTools(server, client2) {
         date: external_exports.string().describe("ISO 8601 datetime").optional(),
         category_id: external_exports.number().describe("Category id from sw_get_categories").optional(),
         details: external_exports.string().describe("Notes").optional(),
+        receipt: receiptParam,
         confirmToken: confirmTokenParam
       })
     },
     async (args, ctx) => {
       const body = buildExpenseBody(args);
+      const receipt = args.receipt ? await loadReceipt(args.receipt) : void 0;
       const gate = await confirmWrite(ctx, {
         tool: "sw_create_expense",
         action: "expense.create",
-        summary: `Create a Splitwise expense "${args.description}" (${args.cost}) \u2014 notifies group members`,
+        summary: `Create a Splitwise expense "${args.description}" (${args.cost})${receipt ? ` with receipt ${receipt.filename}` : ""} \u2014 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 client2.request("POST", "/create_expense", body);
+      const data = await sendExpenseWrite(client2, "/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: external_exports.object({
         expense_id: external_exports.number().describe("ID of the expense to update"),
@@ -100760,25 +100906,58 @@ function registerExpenseTools(server, client2) {
         date: external_exports.string().optional(),
         category_id: external_exports.number().optional(),
         details: external_exports.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) : void 0;
       const gate = await confirmWrite(ctx, {
         tool: "sw_update_expense",
         action: "expense.update",
-        summary: `Update Splitwise expense ${expense_id} \u2014 notifies group members`,
+        summary: `Update Splitwise expense ${expense_id}${receipt ? ` (attach receipt ${receipt.filename})` : ""} \u2014 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(client2, `/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 \u2014 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: external_exports.object({
+        expense_id: external_exports.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 client2.request("POST", `/update_expense/${expense_id}`, body);
+      const data = await sendExpenseWrite(client2, path, {}, receipt, expense_id);
       return minifiedResult(data);
     }
   );
@@ -100845,7 +101024,7 @@ var MAX_INLINE_BYTES = 4 * 1024 * 1024;
 var MAX_TEXT_CHARS = 1e5;
 var PDF_MIME = "application/pdf";
 var OUTPUT_DIR_NAME = "splitwise-mcp";
-var MAX_RECEIPT_BYTES = 25 * 1024 * 1024;
+var MAX_RECEIPT_BYTES2 = 25 * 1024 * 1024;
 var RECEIPT_FILE_MODE = 384;
 var GENERIC_TYPES = /* @__PURE__ */ new Set(["application/octet-stream", "binary/octet-stream"]);
 function isPdf(bytes) {
@@ -100918,7 +101097,7 @@ function registerReceiptTools(server, client2) {
         throw new Error(`Splitwise expense ${id} has no receipt attached.`);
       }
       const served = receipt?.[wanted] ? wanted : fallback;
-      const asset = await client2.fetchAsset(url4, { maxBytes: MAX_RECEIPT_BYTES });
+      const asset = await client2.fetchAsset(url4, { maxBytes: MAX_RECEIPT_BYTES2 });
       if (asset.bytes.length === 0) {
         throw new Error(`Splitwise returned an empty receipt body for expense ${id}.`);
       }
@@ -101144,7 +101323,7 @@ function registerUtilityTools(server, client2) {
 // src/index.ts
 await runMcp({
   name: "splitwise-mcp",
-  version: "3.3.1",
+  version: "3.4.0",
   // 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.",

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.0', // 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "splitwise-mcp",
-  "version": "3.3.1",
+  "version": "3.4.0",
   "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>",

package/server.json

@@ -6,12 +6,12 @@
     "url": "https://github.com/chrischall/splitwise-mcp",
     "source": "github"
   },
-  "version": "3.3.1",
+  "version": "3.4.0",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "splitwise-mcp",
-      "version": "3.3.1",
+      "version": "3.4.0",
       "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