splitwise-mcp 2.1.6 → 2.2.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": "2.1.6"
+    "version": "2.2.0"
   },
   "plugins": [
     {
@@ -15,7 +15,7 @@
       "displayName": "Splitwise",
       "source": "./",
       "description": "MCP server for Splitwise — manage expenses, groups, and friends via natural language",
-      "version": "2.1.6",
+      "version": "2.2.0",
       "author": {
         "name": "Chris Hall"
       },

package/.claude-plugin/plugin.json

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

package/.mcp.json

@@ -2,9 +2,12 @@
   "mcpServers": {
     "splitwise": {
       "command": "node",
-      "args": ["${CLAUDE_PLUGIN_ROOT}/dist/index.js"],
+      "args": [
+        "${CLAUDE_PLUGIN_ROOT}/dist/index.js"
+      ],
       "env": {
-        "SPLITWISE_API_KEY": "${SPLITWISE_API_KEY}"
+        "SPLITWISE_API_KEY": "${SPLITWISE_API_KEY}",
+        "SPLITWISE_OUTPUT_DIR": "${SPLITWISE_OUTPUT_DIR}"
       }
     }
   }

package/README.md

@@ -20,6 +20,7 @@ Ask Claude things like:
 - *"Add Meredith to the household group"*
 - *"Show me recent expenses"*
 - *"Delete that duplicate expense"*
+- *"Download the receipt from that hotel expense"*
 
 ## Requirements
 
@@ -112,10 +113,11 @@ Add to Claude Desktop config:
 | Env var | Required | Notes |
 |---------|----------|-------|
 | `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. Defaults to the current working directory. |
 
 ## Available tools
 
-20 tools across 5 domains. All tools are prefixed `sw_`.
+26 tools across 6 domains. All tools are prefixed `sw_`.
 
 ### User
 
@@ -123,6 +125,7 @@ Add to Claude Desktop config:
 |------|-------------|
 | `sw_get_current_user` | Get the authenticated user's profile |
 | `sw_get_user` | Get another user's profile by ID |
+| `sw_update_user` | Update the current user's profile fields |
 
 ### Groups
 
@@ -158,6 +161,12 @@ Add to Claude Desktop config:
 | `sw_create_comment` | Add a comment to an expense |
 | `sw_delete_comment` | Delete a comment |
 
+### Receipts
+
+| Tool | What it does |
+|------|-------------|
+| `sw_get_receipt` | Download an expense's receipt image/PDF with the server's credentials and write it to a file |
+
 ### Utilities
 
 | Tool | What it does |
@@ -170,6 +179,8 @@ Add to Claude Desktop config:
 
 **"SPLITWISE_API_KEY is required"** -- set the environment variable in your MCP config or a `.env` file.
 
+**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.
+
 **429 rate limit** -- Splitwise has undocumented rate limits. Wait a moment and retry.
 
 **Tools not appearing in Claude** -- go to **Claude Desktop > Settings > Developer** to see connected servers. Make sure you fully quit and relaunched after editing the config.
@@ -191,8 +202,9 @@ src/
     user.ts         sw_get_current_user, sw_get_user
     groups.ts       group CRUD and membership
     friends.ts      friend list and management
-    expenses.ts     expense CRUD, comments
-    utilities.ts    notifications, categories, currencies
+    expenses.ts     expense CRUD
+    receipts.ts     authenticated receipt download
+    utilities.ts    notifications, categories, currencies, comments
 ```
 
 ## License

package/dist/bundle.js

@@ -2984,7 +2984,7 @@ var require_compile = __commonJS({
       const schOrFunc = root.refs[ref];
       if (schOrFunc)
         return schOrFunc;
-      let _sch = resolve.call(this, root, ref);
+      let _sch = resolve2.call(this, root, ref);
       if (_sch === void 0) {
         const schema = (_a3 = root.localRefs) === null || _a3 === void 0 ? void 0 : _a3[ref];
         const { schemaId } = this.opts;
@@ -3011,7 +3011,7 @@ var require_compile = __commonJS({
     function sameSchemaEnv(s1, s2) {
       return s1.schema === s2.schema && s1.root === s2.root && s1.baseId === s2.baseId;
     }
-    function resolve(root, ref) {
+    function resolve2(root, ref) {
       let sch;
       while (typeof (sch = this.refs[ref]) == "string")
         ref = sch;
@@ -3642,7 +3642,7 @@ var require_fast_uri = __commonJS({
       }
       return uri;
     }
-    function resolve(baseURI, relativeURI, options) {
+    function resolve2(baseURI, relativeURI, options) {
       const schemelessOptions = options ? Object.assign({ scheme: "null" }, options) : { scheme: "null" };
       const { parsed: baseParsed, malformedAuthorityOrPort: baseMalformed } = parseWithStatus(baseURI, schemelessOptions);
       const { parsed: relativeParsed, malformedAuthorityOrPort: relativeMalformed } = parseWithStatus(relativeURI, schemelessOptions);
@@ -3926,7 +3926,7 @@ var require_fast_uri = __commonJS({
     var fastUri = {
       SCHEMES,
       normalize,
-      resolve,
+      resolve: resolve2,
       resolveComponent,
       equal,
       serialize,
@@ -28873,7 +28873,7 @@ var Protocol = class {
           return;
         }
         const pollInterval = task2.pollInterval ?? this._options?.defaultTaskPollInterval ?? 1e3;
-        await new Promise((resolve) => setTimeout(resolve, pollInterval));
+        await new Promise((resolve2) => setTimeout(resolve2, pollInterval));
         options?.signal?.throwIfAborted();
       }
     } catch (error51) {
@@ -28890,7 +28890,7 @@ var Protocol = class {
    */
   request(request, resultSchema, options) {
     const { relatedRequestId, resumptionToken, onresumptiontoken, task, relatedTask } = options ?? {};
-    return new Promise((resolve, reject) => {
+    return new Promise((resolve2, reject) => {
       const earlyReject = (error51) => {
         reject(error51);
       };
@@ -28968,7 +28968,7 @@ var Protocol = class {
           if (!parseResult.success) {
             reject(parseResult.error);
           } else {
-            resolve(parseResult.data);
+            resolve2(parseResult.data);
           }
         } catch (error51) {
           reject(error51);
@@ -29229,12 +29229,12 @@ var Protocol = class {
       }
     } catch {
     }
-    return new Promise((resolve, reject) => {
+    return new Promise((resolve2, reject) => {
       if (signal.aborted) {
         reject(new McpError(ErrorCode.InvalidRequest, "Request cancelled"));
         return;
       }
-      const timeoutId = setTimeout(resolve, interval);
+      const timeoutId = setTimeout(resolve2, interval);
       signal.addEventListener("abort", () => {
         clearTimeout(timeoutId);
         reject(new McpError(ErrorCode.InvalidRequest, "Request cancelled"));
@@ -30325,7 +30325,7 @@ var McpServer = class {
     let task = createTaskResult.task;
     const pollInterval = task.pollInterval ?? 5e3;
     while (task.status !== "completed" && task.status !== "failed" && task.status !== "cancelled") {
-      await new Promise((resolve) => setTimeout(resolve, pollInterval));
+      await new Promise((resolve2) => setTimeout(resolve2, pollInterval));
       const updatedTask = await extra.taskStore.getTask(taskId);
       if (!updatedTask) {
         throw new McpError(ErrorCode.InternalError, `Task ${taskId} not found during polling`);
@@ -30989,12 +30989,12 @@ var StdioServerTransport = class {
     this.onclose?.();
   }
   send(message) {
-    return new Promise((resolve) => {
+    return new Promise((resolve2) => {
       const json2 = serializeMessage(message);
       if (this._stdout.write(json2)) {
-        resolve();
+        resolve2();
       } else {
-        this._stdout.once("drain", resolve);
+        this._stdout.once("drain", resolve2);
       }
     });
   }
@@ -31090,8 +31090,23 @@ function textResult(data) {
     content: [{ type: "text", text: JSON.stringify(data, null, 2) }]
   };
 }
+function imageResult(base643, mimeType) {
+  return {
+    content: [{ type: "image", data: base643, mimeType }]
+  };
+}
+function pruneUndefined(obj) {
+  const out = {};
+  for (const key of Object.keys(obj)) {
+    if (obj[key] !== void 0)
+      out[key] = obj[key];
+  }
+  return out;
+}
 
 // node_modules/@chrischall/mcp-utils/dist/config/index.js
+import { homedir } from "node:os";
+import { isAbsolute, join, resolve } from "node:path";
 var PLACEHOLDER_RE = /^\$\{[^}]*\}$/;
 function readEnvVar(key, opts = {}) {
   const env = opts.env ?? process.env;
@@ -31104,6 +31119,15 @@ function readEnvVar(key, opts = {}) {
   }
   return opts.default;
 }
+function expandPath(p) {
+  let expanded = p;
+  if (p === "~") {
+    expanded = homedir();
+  } else if (p.startsWith("~/")) {
+    expanded = join(homedir(), p.slice(2));
+  }
+  return isAbsolute(expanded) ? expanded : resolve(expanded);
+}
 async function loadDotenvSafely(opts = {}) {
   try {
     const mod = await import(
@@ -31121,6 +31145,64 @@ async function loadDotenvSafely(opts = {}) {
   }
 }
 
+// node_modules/@chrischall/mcp-utils/dist/fs/output.js
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { join as join2 } from "node:path";
+function resolveOutputDir(perCall, envVar, opts = {}) {
+  const raw = perCall ?? readEnvVar(envVar, opts.env ? { env: opts.env } : {});
+  if (!raw)
+    return process.cwd();
+  const dir = expandPath(raw);
+  mkdirSync(dir, { recursive: true });
+  return dir;
+}
+function sanitizeBaseName(base) {
+  const safe = base.replace(/[/\\]+/g, "_").replace(/\.\.+/g, "_").replace(/^\.+/, "").trim();
+  return safe.length > 0 ? safe : "file";
+}
+function uniquePath(dir, base, ext) {
+  const safe = sanitizeBaseName(base);
+  const first = join2(dir, `${safe}.${ext}`);
+  if (!existsSync(first))
+    return first;
+  for (let n = 2; ; n++) {
+    const candidate = join2(dir, `${safe}-${n}.${ext}`);
+    if (!existsSync(candidate))
+      return candidate;
+  }
+}
+var MIME_EXT = {
+  "image/png": "png",
+  "image/jpeg": "jpg",
+  "image/webp": "webp",
+  "image/gif": "gif",
+  "application/pdf": "pdf",
+  "application/json": "json"
+};
+function writeBinaryOutput(opts) {
+  const ext = opts.extension ?? (opts.mimeType ? MIME_EXT[opts.mimeType] : void 0) ?? "bin";
+  mkdirSync(opts.dir, { recursive: true });
+  const path = uniquePath(opts.dir, opts.baseName, ext);
+  writeFileSync(path, Buffer.from(opts.base64, "base64"));
+  return path;
+}
+function sniffMimeBytes(bytes) {
+  const buf = Buffer.from(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+  if (buf.length >= 8 && buf.subarray(0, 8).equals(Buffer.from([137, 80, 78, 71, 13, 10, 26, 10]))) {
+    return "image/png";
+  }
+  if (buf.length >= 3 && buf[0] === 255 && buf[1] === 216 && buf[2] === 255) {
+    return "image/jpeg";
+  }
+  if (buf.length >= 12 && buf.subarray(0, 4).toString("latin1") === "RIFF" && buf.subarray(8, 12).toString("latin1") === "WEBP") {
+    return "image/webp";
+  }
+  if (buf.length >= 4 && buf.subarray(0, 4).toString("latin1") === "GIF8") {
+    return "image/gif";
+  }
+  return void 0;
+}
+
 // node_modules/@chrischall/mcp-utils/dist/http/net-atoms.js
 function parseRetryAfterMs(header, opts = {}) {
   const defaultMs = opts.defaultMs ?? 2e3;
@@ -31328,19 +31410,44 @@ var pageSchema = {
 };
 
 // src/client.ts
-import { dirname, join } from "path";
+import { dirname, join as join3 } from "path";
 import { fileURLToPath } from "url";
 try {
   const dir = dirname(fileURLToPath(import.meta.url));
-  await loadDotenvSafely({ path: join(dir, "..", ".env"), override: false });
+  await loadDotenvSafely({ path: join3(dir, "..", ".env"), override: false });
 } catch {
 }
 var BASE_URL = "https://secure.splitwise.com/api/v3.0";
 var SERVICE_NAME = "Splitwise";
+var SPLITWISE_DOMAIN = "splitwise.com";
+function isSplitwiseHost(hostname3) {
+  const host = hostname3.toLowerCase();
+  return host === SPLITWISE_DOMAIN || host.endsWith(`.${SPLITWISE_DOMAIN}`);
+}
+function parseAssetUrl(url2) {
+  let parsed;
+  try {
+    parsed = new URL(url2);
+  } catch {
+    throw new Error("Splitwise returned an asset URL that could not be parsed");
+  }
+  if (parsed.protocol !== "https:") {
+    throw new Error(`Refusing to fetch an asset over ${parsed.protocol}// \u2014 https only`);
+  }
+  return parsed;
+}
+function redactAssetQuery(err, search) {
+  if (!(err instanceof Error) || !search) return err;
+  const message = err.message.split(search).join("?<redacted>");
+  if (message === err.message) return err;
+  return err instanceof ApiError ? new ApiError(err.status, message) : new Error(message);
+}
 var SplitwiseClient = class {
   apiKey;
   configError;
   api;
+  /** Per-origin clients for asset hosts, built on first use by `fetchAsset`. */
+  assetClients = /* @__PURE__ */ new Map();
   /**
    * Defer the config error so the server can still start (and respond to the
    * host's install-time smoke test) when SPLITWISE_API_KEY isn't set yet.
@@ -31360,14 +31467,26 @@ var SplitwiseClient = class {
       this.apiKey = key;
       this.configError = null;
     }
-    this.api = createApiClient({
-      baseUrl: BASE_URL,
-      getToken: () => this.requireKey(),
-      serviceName: SERVICE_NAME,
+    this.api = this.buildApiClient(BASE_URL, true);
+  }
+  /**
+   * One API client per origin, sharing the fleet's retry/timeout/error policy.
+   * `authenticated` decides whether the API key is attached: `getToken` defers
+   * config errors to request time, and on* handlers preserve Splitwise's
+   * documented 401/429 messages.
+   */
+  buildApiClient(baseUrl, authenticated) {
+    const service = authenticated ? SERVICE_NAME : new URL(baseUrl).host;
+    return createApiClient({
+      baseUrl,
+      serviceName: service,
       retry: { count: 1, delayMs: 2e3 },
       timeout: 3e4,
-      onUnauthorized: () => new Error("SPLITWISE_API_KEY is invalid or missing"),
-      onRateLimited: () => new Error("Rate limited by Splitwise API")
+      ...authenticated ? { getToken: () => this.requireKey() } : {},
+      onUnauthorized: () => new Error(
+        authenticated ? "SPLITWISE_API_KEY is invalid or missing" : "The asset URL was rejected (401) \u2014 presigned URLs are short-lived, so re-run to get a fresh one"
+      ),
+      onRateLimited: () => new Error(`Rate limited by ${authenticated ? "Splitwise API" : service}`)
     });
   }
   requireKey() {
@@ -31377,6 +31496,31 @@ var SplitwiseClient = class {
   async request(method, path, body) {
     return this.api.fetchJson(method, path, body !== void 0 ? { body } : {});
   }
+  /**
+   * 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:
+   * from its own API (`https://www.splitwise.com/api/v4.0/expenses/{id}/receipt`),
+   * which 401s without the key, and from a presigned S3 URL, which carries its
+   * own signature and must NOT be sent the key. `isSplitwiseHost` picks.
+   *
+   * A cross-origin redirect (API → S3) is safe: per the Fetch standard the
+   * `Authorization` header is dropped when a redirect changes origin.
+   */
+  async fetchAsset(url2) {
+    const target = parseAssetUrl(url2);
+    const authenticated = isSplitwiseHost(target.hostname);
+    const cacheKey = `${target.origin}|${authenticated ? "auth" : "anon"}`;
+    let api = this.assetClients.get(cacheKey);
+    if (!api) {
+      api = this.buildApiClient(target.origin, authenticated);
+      this.assetClients.set(cacheKey, api);
+    }
+    try {
+      return await api.fetchRaw("GET", `${target.pathname}${target.search}`);
+    } catch (err) {
+      throw redactAssetQuery(err, target.search);
+    }
+  }
 };
 var client = new SplitwiseClient();
 
@@ -31425,13 +31569,7 @@ function registerUserTools(server, client2) {
       confirm: schemaConfirm
     }
   }, async ({ id, first_name, last_name, email: email3, password, locale, default_currency, confirm }) => {
-    const body = {};
-    if (first_name !== void 0) body.first_name = first_name;
-    if (last_name !== void 0) body.last_name = last_name;
-    if (email3 !== void 0) body.email = email3;
-    if (password !== void 0) body.password = password;
-    if (locale !== void 0) body.locale = locale;
-    if (default_currency !== void 0) body.default_currency = default_currency;
+    const body = pruneUndefined({ first_name, last_name, email: email3, password, locale, default_currency });
     const previewBody = { ...body, ...password !== void 0 ? { password: "[hidden]" } : {} };
     const gate = previewUnlessConfirmed(confirm, `Update current Splitwise user ${id} profile`, "POST", `/update_user/${id}`, previewBody);
     if (gate) return gate;
@@ -31469,9 +31607,7 @@ function registerGroupTools(server, client2) {
       confirm: schemaConfirm
     }
   }, async ({ name, group_type, simplify_by_default, confirm }) => {
-    const body = { name };
-    if (group_type !== void 0) body.group_type = group_type;
-    if (simplify_by_default !== void 0) body.simplify_by_default = simplify_by_default;
+    const body = pruneUndefined({ name, group_type, simplify_by_default });
     const gate = previewUnlessConfirmed(confirm, `Create Splitwise group "${name}"`, "POST", "/create_group", body);
     if (gate) return gate;
     const data = await client2.request("POST", "/create_group", body);
@@ -31559,9 +31695,7 @@ function registerFriendTools(server, client2) {
       confirm: schemaConfirm
     }
   }, async ({ user_email, user_first_name, user_last_name, confirm }) => {
-    const body = { user_email };
-    if (user_first_name !== void 0) body.user_first_name = user_first_name;
-    if (user_last_name !== void 0) body.user_last_name = user_last_name;
+    const body = pruneUndefined({ user_email, user_first_name, user_last_name });
     const gate = previewUnlessConfirmed(confirm, `Add ${user_email} as a Splitwise friend`, "POST", "/create_friend", body);
     if (gate) return gate;
     const data = await client2.request("POST", "/create_friend", body);
@@ -31715,6 +31849,89 @@ function registerExpenseTools(server, client2) {
   });
 }
 
+// src/tools/receipts.ts
+var MAX_INLINE_BYTES = 4 * 1024 * 1024;
+var GENERIC_TYPES = /* @__PURE__ */ new Set(["application/octet-stream", "binary/octet-stream"]);
+function isPdf(bytes) {
+  return bytes.length >= 5 && Buffer.from(bytes.subarray(0, 5)).toString("latin1") === "%PDF-";
+}
+function resolveMimeType(contentType, bytes) {
+  const declared = (contentType ?? "").split(";")[0].trim().toLowerCase();
+  if (declared && !GENERIC_TYPES.has(declared)) return declared;
+  return sniffMimeBytes(bytes) ?? (isPdf(bytes) ? "application/pdf" : void 0);
+}
+function extensionFromUrl(url2) {
+  const match = /\.([a-z0-9]{1,5})$/i.exec(new URL(url2).pathname);
+  return match ? match[1].toLowerCase() : void 0;
+}
+function extensionFor(mimeType, url2) {
+  const subtype = mimeType?.split("/")[1];
+  if (subtype === "jpeg") return "jpg";
+  if (subtype && /^[a-z0-9]{1,5}$/.test(subtype)) return subtype;
+  return extensionFromUrl(url2) ?? "bin";
+}
+function registerReceiptTools(server, client2) {
+  server.registerTool("sw_get_receipt", {
+    description: "Download the receipt image or PDF attached to a Splitwise expense. The receipt URLs returned by sw_get_expense need the server's credentials \u2014 fetching them directly returns 401 \u2014 so use this tool instead. It writes the authenticated bytes to a file and returns the path; set inline:true to also get an image receipt back in the result. Files go to output_dir, else $SPLITWISE_OUTPUT_DIR, else the current directory, and an existing file is never overwritten.",
+    // Not read-only: this writes a file into a caller-supplied directory, and
+    // `readOnlyHint` is what a host reads when deciding to skip its approval
+    // prompt. Not destructive either — `uniquePath` always picks a filename
+    // that doesn't exist, so an existing file is never touched.
+    annotations: { readOnlyHint: false, destructiveHint: false },
+    inputSchema: {
+      id: external_exports.number().describe("Expense ID (the same id sw_get_expense takes)"),
+      size: external_exports.enum(["original", "large"]).describe("Which stored rendition to fetch. Defaults to 'original' (full quality, and the only one a PDF receipt has). Falls back to the other rendition when the requested one is absent.").optional(),
+      output_dir: external_exports.string().describe("Directory to write the receipt into. Defaults to $SPLITWISE_OUTPUT_DIR, else the current working directory.").optional(),
+      inline: external_exports.boolean().describe(`Also return the receipt as a base64 image in the result. Image receipts only, and only under ${MAX_INLINE_BYTES} bytes.`).optional()
+    }
+  }, async ({ id, size, output_dir, inline }) => {
+    const wanted = size ?? "original";
+    const fallback = wanted === "original" ? "large" : "original";
+    const expense = await client2.request(
+      "GET",
+      `/get_expense/${id}`
+    );
+    const receipt = expense?.expense?.receipt;
+    const url2 = receipt?.[wanted] || receipt?.[fallback];
+    if (!url2) {
+      throw new Error(`Splitwise expense ${id} has no receipt attached.`);
+    }
+    const served = receipt?.[wanted] ? wanted : fallback;
+    const asset = await client2.fetchAsset(url2);
+    if (asset.bytes.length === 0) {
+      throw new Error(`Splitwise returned an empty receipt body for expense ${id}.`);
+    }
+    const mimeType = resolveMimeType(asset.contentType, asset.bytes);
+    const base643 = Buffer.from(asset.bytes).toString("base64");
+    const path = writeBinaryOutput({
+      dir: resolveOutputDir(output_dir, "SPLITWISE_OUTPUT_DIR"),
+      baseName: `splitwise-receipt-${id}`,
+      base64: base643,
+      extension: extensionFor(mimeType, url2)
+    });
+    const imageMime = mimeType?.startsWith("image/") ? mimeType : void 0;
+    const inlined = inline === true && imageMime !== void 0 && asset.bytes.length <= MAX_INLINE_BYTES;
+    const result = textResult({
+      expense_id: id,
+      size: served,
+      ...served !== wanted ? { requested_size: wanted, note: `Expense ${id} has no ${wanted} rendition; fetched ${served}.` } : {},
+      path,
+      bytes: asset.bytes.length,
+      content_type: mimeType ?? "unknown",
+      // The receipt URL itself is a signed capability, so report only its host.
+      source_host: new URL(url2).host,
+      inline: inlined,
+      ...inline === true && !inlined ? {
+        inline_skipped: imageMime ? `Receipt is ${asset.bytes.length} bytes, over the ${MAX_INLINE_BYTES}-byte inline limit \u2014 open the file at the path above.` : "Only image receipts can be returned inline \u2014 open the file at the path above."
+      } : {}
+    });
+    if (inlined && imageMime) {
+      result.content.push(...imageResult(base643, imageMime).content);
+    }
+    return result;
+  });
+}
+
 // src/tools/utilities.ts
 function registerUtilityTools(server, client2) {
   server.registerTool("sw_get_notifications", {
@@ -31780,7 +31997,7 @@ function registerUtilityTools(server, client2) {
 // src/index.ts
 await runMcp({
   name: "splitwise-mcp",
-  version: "2.1.6",
+  version: "2.2.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.",
@@ -31789,6 +32006,7 @@ await runMcp({
     registerGroupTools,
     registerFriendTools,
     registerExpenseTools,
+    registerReceiptTools,
     registerUtilityTools
   ]
 });

package/dist/client.js

@@ -1,6 +1,6 @@
 import { dirname, join } from 'path';
 import { fileURLToPath } from 'url';
-import { loadDotenvSafely, readEnvVar, createApiClient } from '@chrischall/mcp-utils';
+import { loadDotenvSafely, readEnvVar, createApiClient, ApiError, } from '@chrischall/mcp-utils';
 // Load .env for local dev; silently skip if dotenv is unavailable (e.g. mcpb
 // bundle). `loadDotenvSafely` swallows a missing dotenv module and never lets
 // .env override a host-provided value.
@@ -16,10 +16,55 @@ catch {
 }
 const BASE_URL = 'https://secure.splitwise.com/api/v3.0';
 const SERVICE_NAME = 'Splitwise';
+const SPLITWISE_DOMAIN = 'splitwise.com';
+/**
+ * Whether a hostname belongs to Splitwise, and may therefore be sent the API
+ * key. Receipt bytes are served either from a Splitwise host (which requires
+ * the key) or from a presigned third-party URL (S3), which must never see it.
+ */
+export function isSplitwiseHost(hostname) {
+    const host = hostname.toLowerCase();
+    return host === SPLITWISE_DOMAIN || host.endsWith(`.${SPLITWISE_DOMAIN}`);
+}
+/** Parse an asset URL handed back by the API, rejecting anything not https. */
+function parseAssetUrl(url) {
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        // Deliberately not echoing the URL: it can carry a signed token.
+        throw new Error('Splitwise returned an asset URL that could not be parsed');
+    }
+    if (parsed.protocol !== 'https:') {
+        throw new Error(`Refusing to fetch an asset over ${parsed.protocol}// — https only`);
+    }
+    return parsed;
+}
+/**
+ * Strip the asset URL's signed query string out of an error message. A failed
+ * `fetchRaw` names the path it requested, and a receipt URL's query carries a
+ * signed, capability-bearing token that must not reach a tool result.
+ *
+ * Matches the exact query bytes we sent rather than a pattern for the message
+ * shape: that keeps working whatever an upstream formatter does with the URL
+ * (relative path today, absolute URL tomorrow), and it can't mangle an error
+ * body that happens to contain a `?`.
+ */
+function redactAssetQuery(err, search) {
+    if (!(err instanceof Error) || !search)
+        return err;
+    const message = err.message.split(search).join('?<redacted>');
+    if (message === err.message)
+        return err;
+    return err instanceof ApiError ? new ApiError(err.status, message) : new Error(message);
+}
 export class SplitwiseClient {
     apiKey;
     configError;
     api;
+    /** Per-origin clients for asset hosts, built on first use by `fetchAsset`. */
+    assetClients = new Map();
     /**
      * Defer the config error so the server can still start (and respond to the
      * host's install-time smoke test) when SPLITWISE_API_KEY isn't set yet.
@@ -44,15 +89,28 @@ export class SplitwiseClient {
             this.apiKey = key;
             this.configError = null;
         }
-        // `getToken` defers config errors to request time; on* handlers preserve Splitwise's documented 401/429 messages.
-        this.api = createApiClient({
-            baseUrl: BASE_URL,
-            getToken: () => this.requireKey(),
-            serviceName: SERVICE_NAME,
+        this.api = this.buildApiClient(BASE_URL, true);
+    }
+    /**
+     * One API client per origin, sharing the fleet's retry/timeout/error policy.
+     * `authenticated` decides whether the API key is attached: `getToken` defers
+     * config errors to request time, and on* handlers preserve Splitwise's
+     * documented 401/429 messages.
+     */
+    buildApiClient(baseUrl, authenticated) {
+        // An anonymous asset origin isn't Splitwise, so name it accurately in
+        // errors rather than blaming the Splitwise API for a third party's 429.
+        const service = authenticated ? SERVICE_NAME : new URL(baseUrl).host;
+        return createApiClient({
+            baseUrl,
+            serviceName: service,
             retry: { count: 1, delayMs: 2000 },
             timeout: 30_000,
-            onUnauthorized: () => new Error('SPLITWISE_API_KEY is invalid or missing'),
-            onRateLimited: () => new Error('Rate limited by Splitwise API'),
+            ...(authenticated ? { getToken: () => this.requireKey() } : {}),
+            onUnauthorized: () => new Error(authenticated
+                ? 'SPLITWISE_API_KEY is invalid or missing'
+                : 'The asset URL was rejected (401) — presigned URLs are short-lived, so re-run to get a fresh one'),
+            onRateLimited: () => new Error(`Rate limited by ${authenticated ? 'Splitwise API' : service}`),
         });
     }
     requireKey() {
@@ -63,6 +121,35 @@ export class SplitwiseClient {
     async request(method, path, body) {
         return this.api.fetchJson(method, path, body !== undefined ? { body } : {});
     }
+    /**
+     * 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:
+     * from its own API (`https://www.splitwise.com/api/v4.0/expenses/{id}/receipt`),
+     * which 401s without the key, and from a presigned S3 URL, which carries its
+     * own signature and must NOT be sent the key. `isSplitwiseHost` picks.
+     *
+     * A cross-origin redirect (API → S3) is safe: per the Fetch standard the
+     * `Authorization` header is dropped when a redirect changes origin.
+     */
+    async fetchAsset(url) {
+        const target = parseAssetUrl(url);
+        const authenticated = isSplitwiseHost(target.hostname);
+        const cacheKey = `${target.origin}|${authenticated ? 'auth' : 'anon'}`;
+        let api = this.assetClients.get(cacheKey);
+        if (!api) {
+            api = this.buildApiClient(target.origin, authenticated);
+            this.assetClients.set(cacheKey, api);
+        }
+        try {
+            // `pathname + search` verbatim rather than the client's `query` option:
+            // a presigned signature covers the exact encoding, so re-encoding it
+            // would invalidate the URL.
+            return await api.fetchRaw('GET', `${target.pathname}${target.search}`);
+        }
+        catch (err) {
+            throw redactAssetQuery(err, target.search);
+        }
+    }
 }
 /**
  * Module-level singleton shared by every tool module. Constructing it here (not

package/dist/index.js

@@ -5,6 +5,7 @@ import { registerUserTools } from './tools/user.js';
 import { registerGroupTools } from './tools/groups.js';
 import { registerFriendTools } from './tools/friends.js';
 import { registerExpenseTools } from './tools/expenses.js';
+import { registerReceiptTools } from './tools/receipts.js';
 import { registerUtilityTools } from './tools/utilities.js';
 // runMcp builds the McpServer, applies the registrars (threading `client`
 // through as deps), prints the banner to stderr, wires graceful shutdown, and
@@ -17,7 +18,7 @@ import { registerUtilityTools } from './tools/utilities.js';
 // client into the same registrars instead of this singleton.
 await runMcp({
     name: 'splitwise-mcp',
-    version: '2.1.6', // x-release-please-version
+    version: '2.2.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: [
@@ -25,6 +26,7 @@ await runMcp({
         registerGroupTools,
         registerFriendTools,
         registerExpenseTools,
+        registerReceiptTools,
         registerUtilityTools,
     ],
 });

package/dist/tools/friends.js

@@ -1,5 +1,5 @@
 import { z } from 'zod';
-import { textResult } from '@chrischall/mcp-utils';
+import { textResult, pruneUndefined } from '@chrischall/mcp-utils';
 import { previewUnlessConfirmed, schemaConfirm } from './_confirm.js';
 export function registerFriendTools(server, client) {
     server.registerTool('sw_list_friends', {
@@ -19,11 +19,7 @@ export function registerFriendTools(server, client) {
             confirm: schemaConfirm,
         },
     }, async ({ user_email, user_first_name, user_last_name, confirm }) => {
-        const body = { user_email };
-        if (user_first_name !== undefined)
-            body.user_first_name = user_first_name;
-        if (user_last_name !== undefined)
-            body.user_last_name = user_last_name;
+        const body = pruneUndefined({ user_email, user_first_name, user_last_name });
         const gate = previewUnlessConfirmed(confirm, `Add ${user_email} as a Splitwise friend`, 'POST', '/create_friend', body);
         if (gate)
             return gate;

package/dist/tools/groups.js

@@ -1,5 +1,5 @@
 import { z } from 'zod';
-import { textResult } from '@chrischall/mcp-utils';
+import { textResult, pruneUndefined } from '@chrischall/mcp-utils';
 import { previewUnlessConfirmed, schemaConfirm } from './_confirm.js';
 export function registerGroupTools(server, client) {
     server.registerTool('sw_list_groups', {
@@ -29,11 +29,7 @@ export function registerGroupTools(server, client) {
             confirm: schemaConfirm,
         },
     }, async ({ name, group_type, simplify_by_default, confirm }) => {
-        const body = { name };
-        if (group_type !== undefined)
-            body.group_type = group_type;
-        if (simplify_by_default !== undefined)
-            body.simplify_by_default = simplify_by_default;
+        const body = pruneUndefined({ name, group_type, simplify_by_default });
         const gate = previewUnlessConfirmed(confirm, `Create Splitwise group "${name}"`, 'POST', '/create_group', body);
         if (gate)
             return gate;

package/dist/tools/receipts.js

@@ -0,0 +1,111 @@
+import { z } from 'zod';
+import { textResult, imageResult, resolveOutputDir, writeBinaryOutput, sniffMimeBytes, } from '@chrischall/mcp-utils';
+/** Cap on bytes returned as base64 in the tool result; the file is written regardless. */
+const MAX_INLINE_BYTES = 4 * 1024 * 1024;
+/** Content types that carry no information about the actual format. */
+const GENERIC_TYPES = new Set(['application/octet-stream', 'binary/octet-stream']);
+/** `%PDF-` magic bytes — `sniffMimeBytes` only knows the image formats. */
+function isPdf(bytes) {
+    return bytes.length >= 5 && Buffer.from(bytes.subarray(0, 5)).toString('latin1') === '%PDF-';
+}
+/**
+ * Best-effort MIME type for the downloaded bytes: the response's Content-Type
+ * when it says something useful, else the magic bytes, else undefined.
+ */
+function resolveMimeType(contentType, bytes) {
+    const declared = (contentType ?? '').split(';')[0].trim().toLowerCase();
+    if (declared && !GENERIC_TYPES.has(declared))
+        return declared;
+    return sniffMimeBytes(bytes) ?? (isPdf(bytes) ? 'application/pdf' : 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';
+}
+export function registerReceiptTools(server, client) {
+    server.registerTool('sw_get_receipt', {
+        description: "Download the receipt image or PDF attached to a Splitwise expense. The receipt URLs returned by sw_get_expense need the server's credentials — fetching them directly returns 401 — so use this tool instead. It writes the authenticated bytes to a file and returns the path; set inline:true to also get an image receipt back in the result. Files go to output_dir, else $SPLITWISE_OUTPUT_DIR, else the current directory, and an existing file is never overwritten.",
+        // Not read-only: this writes a file into a caller-supplied directory, and
+        // `readOnlyHint` is what a host reads when deciding to skip its approval
+        // prompt. Not destructive either — `uniquePath` always picks a filename
+        // that doesn't exist, so an existing file is never touched.
+        annotations: { readOnlyHint: false, destructiveHint: false },
+        inputSchema: {
+            id: z.number().describe('Expense ID (the same id sw_get_expense takes)'),
+            size: z
+                .enum(['original', 'large'])
+                .describe("Which stored rendition to fetch. Defaults to 'original' (full quality, and the only one a PDF receipt has). Falls back to the other rendition when the requested one is absent.")
+                .optional(),
+            output_dir: z
+                .string()
+                .describe('Directory to write the receipt into. Defaults to $SPLITWISE_OUTPUT_DIR, else the current working directory.')
+                .optional(),
+            inline: z
+                .boolean()
+                .describe(`Also return the receipt as a base64 image in the result. Image receipts only, and only under ${MAX_INLINE_BYTES} bytes.`)
+                .optional(),
+        },
+    }, async ({ id, size, output_dir, inline }) => {
+        const wanted = size ?? 'original';
+        const fallback = wanted === 'original' ? 'large' : 'original';
+        const expense = await client.request('GET', `/get_expense/${id}`);
+        const receipt = expense?.expense?.receipt;
+        const url = receipt?.[wanted] || receipt?.[fallback];
+        if (!url) {
+            throw new Error(`Splitwise expense ${id} has no receipt attached.`);
+        }
+        const served = receipt?.[wanted] ? wanted : fallback;
+        const asset = await client.fetchAsset(url);
+        if (asset.bytes.length === 0) {
+            throw new Error(`Splitwise returned an empty receipt body for expense ${id}.`);
+        }
+        const mimeType = resolveMimeType(asset.contentType, asset.bytes);
+        const base64 = Buffer.from(asset.bytes).toString('base64');
+        const path = writeBinaryOutput({
+            dir: resolveOutputDir(output_dir, 'SPLITWISE_OUTPUT_DIR'),
+            baseName: `splitwise-receipt-${id}`,
+            base64,
+            extension: extensionFor(mimeType, url),
+        });
+        const imageMime = mimeType?.startsWith('image/') ? mimeType : undefined;
+        const inlined = inline === true && imageMime !== undefined && asset.bytes.length <= MAX_INLINE_BYTES;
+        const result = textResult({
+            expense_id: id,
+            size: served,
+            ...(served !== wanted
+                ? { requested_size: wanted, note: `Expense ${id} has no ${wanted} rendition; fetched ${served}.` }
+                : {}),
+            path,
+            bytes: asset.bytes.length,
+            content_type: mimeType ?? 'unknown',
+            // The receipt URL itself is a signed capability, so report only its host.
+            source_host: new URL(url).host,
+            inline: inlined,
+            ...(inline === true && !inlined
+                ? {
+                    inline_skipped: imageMime
+                        ? `Receipt is ${asset.bytes.length} bytes, over the ${MAX_INLINE_BYTES}-byte inline limit — open the file at the path above.`
+                        : 'Only image receipts can be returned inline — open the file at the path above.',
+                }
+                : {}),
+        });
+        if (inlined && imageMime) {
+            result.content.push(...imageResult(base64, imageMime).content);
+        }
+        return result;
+    });
+}

package/dist/tools/user.js

@@ -1,5 +1,5 @@
 import { z } from 'zod';
-import { textResult } from '@chrischall/mcp-utils';
+import { textResult, pruneUndefined } from '@chrischall/mcp-utils';
 import { previewUnlessConfirmed, schemaConfirm } from './_confirm.js';
 export function registerUserTools(server, client) {
     server.registerTool('sw_get_current_user', {
@@ -32,19 +32,7 @@ export function registerUserTools(server, client) {
             confirm: schemaConfirm,
         },
     }, async ({ id, first_name, last_name, email, password, locale, default_currency, confirm }) => {
-        const body = {};
-        if (first_name !== undefined)
-            body.first_name = first_name;
-        if (last_name !== undefined)
-            body.last_name = last_name;
-        if (email !== undefined)
-            body.email = email;
-        if (password !== undefined)
-            body.password = password;
-        if (locale !== undefined)
-            body.locale = locale;
-        if (default_currency !== undefined)
-            body.default_currency = default_currency;
+        const body = pruneUndefined({ first_name, last_name, email, password, locale, default_currency });
         // Never echo the password in the dry-run preview.
         const previewBody = { ...body, ...(password !== undefined ? { password: '[hidden]' } : {}) };
         const gate = previewUnlessConfirmed(confirm, `Update current Splitwise user ${id} profile`, 'POST', `/update_user/${id}`, previewBody);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "splitwise-mcp",
-  "version": "2.1.6",
+  "version": "2.2.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": "2.1.6",
+  "version": "2.2.0",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "splitwise-mcp",
-      "version": "2.1.6",
+      "version": "2.2.0",
       "transport": {
         "type": "stdio"
       },
@@ -22,6 +22,13 @@
           "isRequired": true,
           "format": "string",
           "isSecret": true
+        },
+        {
+          "name": "SPLITWISE_OUTPUT_DIR",
+          "description": "Directory sw_get_receipt writes downloaded receipts into (default: the working directory)",
+          "isRequired": false,
+          "format": "string",
+          "isSecret": false
         }
       ]
     }

package/skills/splitwise-mcp/SKILL.md

@@ -95,6 +95,12 @@ API key auth — no login flow or token rotation. The key is attached to every r
 | `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_delete_expense(id)` | Soft-delete an expense |
+| `sw_undelete_expense(id)` | Restore a soft-deleted expense |
+
+### Receipts
+| Tool | Description |
+|------|-------------|
+| `sw_get_receipt(id, size?, output_dir?, inline?)` | Download the receipt attached to an expense and write it to a file. Returns the path, byte count, and content type; `inline: true` also returns an image receipt in the result |
 
 ### Utilities
 | Tool | Description |
@@ -128,6 +134,12 @@ sw_create_expense(group_id, "Hotel", "200.00", users: [
 ])
 ```
 
+**Get the receipt for an expense:**
+```
+sw_list_expenses(...) → find expense ID
+sw_get_receipt(id) → writes e.g. ./splitwise-receipt-4644814211.pdf
+```
+
 **Search and edit an expense:**
 ```
 sw_list_expenses(group_id, dated_after: "2026-01-01") → find expense ID
@@ -139,5 +151,7 @@ sw_update_expense(expense_id, description: "Corrected description", cost: "95.00
 - `cost` is always a decimal string (e.g. `"25.00"`)
 - `split_equally: true` and `users` array are mutually exclusive
 - For custom split updates, the **full `users` array is required** — the API replaces the entire split
-- `sw_delete_expense` is a soft delete; restoration requires the Splitwise web app
+- `sw_delete_expense` is a soft delete — restore with `sw_undelete_expense`
+- The `receipt.original` / `receipt.large` URLs on an expense are **not public** — fetching them without the API key returns 401. Always use `sw_get_receipt`, which fetches them with the server's own credentials
+- `sw_get_receipt` writes into `output_dir`, else `$SPLITWISE_OUTPUT_DIR`, else the working directory, and never overwrites an existing file
 - API default for `sw_list_expenses` is 20 results when `limit` is omitted