splitwise-mcp 2.1.6 → 2.2.1

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.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: [
@@ -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,247 @@
+import { z } from 'zod';
+import { textResult, imageResult, resolveOutputDir, writeBinaryOutput, sniffMimeBytes, } from '@chrischall/mcp-utils';
+/** Cap on bytes returned as base64 in the tool result. */
+const MAX_INLINE_BYTES = 4 * 1024 * 1024;
+/** Cap on extracted characters, so a long PDF can't flood the result. */
+const MAX_TEXT_CHARS = 100_000;
+const PDF_MIME = 'application/pdf';
+/** 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 magic bytes win over the declared Content-Type: the header is a hint an
+ * object store often gets wrong (`application/force-download`, `application/
+ * x-pdf`, `application/octet-stream`), while the signature describes what the
+ * bytes actually are. Sniffing only recognises the handful of formats a
+ * receipt arrives in, so anything it can't place falls back to what the server
+ * claimed — and a claim of nothing-in-particular falls back to undefined.
+ *
+ * Everything downstream reads this one value, so getting it right here is what
+ * keeps the file extension, the inline block's type, and the text-extraction
+ * gate agreeing with each other.
+ */
+function resolveMimeType(contentType, bytes) {
+    const sniffed = sniffMimeBytes(bytes) ?? (isPdf(bytes) ? PDF_MIME : undefined);
+    if (sniffed)
+        return sniffed;
+    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
+ * receipt path (download, inline, write) must not pay for it at startup.
+ *
+ * Returns `''` for a PDF with no text layer, which is the normal case for a
+ * photographed or scanned receipt.
+ */
+async function extractPdfText(bytes) {
+    const { extractText, getDocumentProxy } = await import('unpdf');
+    // Copy: pdf.js transfers/detaches the buffer it is handed, and the caller
+    // still needs these bytes for the base64 and the file write.
+    const doc = await getDocumentProxy(Uint8Array.from(bytes));
+    const { text } = await extractText(doc, { mergePages: true });
+    return (Array.isArray(text) ? text.join('\n') : text).trim();
+}
+/** An MCP embedded-resource block — how non-image bytes ride back in a result. */
+function resourceBlock(uri, mimeType, base64) {
+    return { type: 'resource', resource: { uri, mimeType, blob: base64 } };
+}
+function describeError(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+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. Set inline:true to get the bytes back in the result (images AND PDFs), or extract_text:true to get a PDF's text without the binary at all — both work when the caller can't see this server's filesystem. It also writes the file and returns the path, unless write:false or the filesystem is read-only.",
+        // 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(),
+            inline: z
+                .boolean()
+                .describe(`Return the receipt bytes in the result — an image block for images, an embedded resource for PDFs and everything else. Only for receipts under ${MAX_INLINE_BYTES} bytes.`)
+                .optional(),
+            extract_text: z
+                .boolean()
+                .describe("Also return the PDF's text layer as `text`. Ideal for looking up line items or totals without transferring the file. PDFs only; a scanned receipt has no text layer to extract.")
+                .optional(),
+            output_dir: z
+                .string()
+                .describe('Directory to write the receipt into. Defaults to $SPLITWISE_OUTPUT_DIR, else the current working directory.')
+                .optional(),
+            write: z
+                .boolean()
+                .describe('Write the receipt to disk. Defaults to true. Pass false when the caller cannot reach this server\'s filesystem, or when the server runs read-only.')
+                .optional(),
+        },
+    }, async ({ id, size, inline, extract_text, output_dir, write }) => {
+        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');
+        // The write is best-effort: a hosted server often runs on a read-only
+        // filesystem, and failing the whole call there would strand a caller who
+        // only wanted the content. Report it and carry on — unless nothing else
+        // was requested, in which case there is no result to return (below).
+        let path;
+        let writeError;
+        if (write !== false) {
+            try {
+                path = writeBinaryOutput({
+                    dir: resolveOutputDir(output_dir, 'SPLITWISE_OUTPUT_DIR'),
+                    baseName: `splitwise-receipt-${id}`,
+                    base64,
+                    extension: extensionFor(mimeType, url),
+                });
+            }
+            catch (err) {
+                writeError = describeError(err);
+            }
+        }
+        const oversized = asset.bytes.length > MAX_INLINE_BYTES;
+        const inlined = inline === true && !oversized;
+        // Diagnosis and suggestion are kept apart: the diagnosis is always true,
+        // while the suggestion is only worth making if that route is still open.
+        // Folding them into one string is how a caller ends up being told to use a
+        // flag they already passed.
+        let text;
+        let textDiagnosis;
+        let textSuggestion;
+        if (extract_text === true) {
+            if (mimeType !== PDF_MIME) {
+                textDiagnosis = `Text extraction covers PDFs only; this receipt is ${mimeType ?? 'of an unknown type'}.`;
+                textSuggestion = 'Use inline:true to get the bytes.';
+            }
+            else {
+                try {
+                    const extracted = await extractPdfText(asset.bytes);
+                    if (extracted.length === 0) {
+                        textDiagnosis = 'This PDF has no text layer — it is probably a scan or photo.';
+                        textSuggestion = 'Use inline:true to read the receipt itself.';
+                    }
+                    else if (extracted.length > MAX_TEXT_CHARS) {
+                        text = extracted.slice(0, MAX_TEXT_CHARS);
+                        textDiagnosis = `Text truncated to the first ${MAX_TEXT_CHARS} characters.`;
+                    }
+                    else {
+                        text = extracted;
+                    }
+                }
+                catch (err) {
+                    textDiagnosis = `Could not extract text: ${describeError(err)}.`;
+                    textSuggestion = 'Use inline:true to get the bytes.';
+                }
+            }
+        }
+        // Gate the suggestion on the FLAG, not the outcome — the same test the
+        // throw path's `routes` uses below. `inlined` conflates "never asked for
+        // inline" with "asked, and it was refused for size"; suggesting it in the
+        // second case contradicts the `inline_skipped` note in the same result.
+        const textNote = [textDiagnosis, inline === true ? undefined : textSuggestion].filter(Boolean).join(' ') ||
+            undefined;
+        // Nothing reached the caller: no file, no bytes, no text. Fail loudly and
+        // name the way out rather than reporting a success with an empty result.
+        if (path === undefined && !inlined && text === undefined) {
+            const reason = writeError
+                ? `could not be written (${writeError})`
+                : 'was not written (write:false)';
+            // Name every blocker — more than one can apply at once — then offer only
+            // the routes still open. A flag the caller already passed is not a
+            // suggestion; when `inline` was requested it can only have been rejected
+            // for size, so it never belongs in the list.
+            const blockers = [
+                textDiagnosis,
+                inline === true && oversized
+                    ? `The receipt is ${asset.bytes.length} bytes, over the ${MAX_INLINE_BYTES}-byte inline limit.`
+                    : undefined,
+            ].filter((b) => b !== undefined);
+            const routes = [];
+            if (inline !== true)
+                routes.push('inline:true for the bytes');
+            if (extract_text !== true && mimeType === PDF_MIME)
+                routes.push("extract_text:true for the PDF's text");
+            const advice = routes.length > 0
+                ? `Re-run with ${routes.join(' or ')}.`
+                : 'Point output_dir somewhere this server can write.';
+            throw new Error([
+                `The receipt for expense ${id} ${reason}, and nothing was returned in its place.`,
+                ...blockers,
+                advice,
+            ].join(' '));
+        }
+        const result = textResult({
+            expense_id: id,
+            size: served,
+            ...(served !== wanted
+                ? { requested_size: wanted, note: `Expense ${id} has no ${wanted} rendition; fetched ${served}.` }
+                : {}),
+            ...(path !== undefined ? { path } : {}),
+            ...(writeError !== undefined ? { write_error: writeError } : {}),
+            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 && oversized
+                ? {
+                    // The write outcome is already known, so don't advise `write:true`
+                    // to someone who either has the file or just watched the write fail.
+                    inline_skipped: `Receipt is ${asset.bytes.length} bytes, over the ${MAX_INLINE_BYTES}-byte inline limit — ` +
+                        (path !== undefined
+                            ? 'read it from the path above.'
+                            : 'get it on disk instead, with write:true and an output_dir this server can write to.'),
+                }
+                : {}),
+            ...(text !== undefined ? { text } : {}),
+            ...(textNote !== undefined ? { text_note: textNote } : {}),
+        });
+        if (inlined) {
+            const type = mimeType ?? 'application/octet-stream';
+            result.content.push(type.startsWith('image/')
+                ? imageResult(base64, type).content[0]
+                : resourceBlock(`splitwise://expenses/${id}/receipt`, type, base64));
+        }
+        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.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>",
@@ -46,6 +46,7 @@
     "@chrischall/mcp-utils": "^0.14.0",
     "@modelcontextprotocol/sdk": "^1.29.0",
     "dotenv": "^17.4.0",
+    "unpdf": "^1.8.1",
     "zod": "^4.4.2"
   },
   "devDependencies": {

package/server.json

@@ -6,12 +6,12 @@
     "url": "https://github.com/chrischall/splitwise-mcp",
     "source": "github"
   },
-  "version": "2.1.6",
+  "version": "2.2.1",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "splitwise-mcp",
-      "version": "2.1.6",
+      "version": "2.2.1",
       "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?, inline?, extract_text?, output_dir?, write?)` | Download the receipt attached to an expense. `inline: true` returns the bytes in the result (images **and** PDFs); `extract_text: true` returns a PDF's text layer; by default it also writes the file and returns the path |
 
 ### Utilities
 | Tool | Description |
@@ -128,6 +134,14 @@ 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, extract_text: true) → line items and totals as text
+sw_get_receipt(id, inline: true)       → the actual bytes, when you need to see it
+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 +153,9 @@ 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
+- That path is on the **server's** filesystem. If you can't read it — a hosted or containerised server — use `inline: true` (bytes) or `extract_text: true` (PDF text) instead of the path
+- `extract_text` only works on PDFs, and only when the PDF has a text layer; a scanned or photographed receipt returns `text_note` instead, and needs `inline: true` to read
 - API default for `sw_list_expenses` is 20 results when `limit` is omitted