splitwise-mcp 2.2.0 → 2.2.1

package/dist/index.js

@@ -18,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.2.0', // 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: [

package/dist/tools/receipts.js

@@ -1,7 +1,10 @@
 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. */
+/** 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. */
@@ -9,14 +12,25 @@ 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.
+ * 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();
-    if (declared && !GENERIC_TYPES.has(declared))
-        return declared;
-    return sniffMimeBytes(bytes) ?? (isPdf(bytes) ? 'application/pdf' : undefined);
+    return declared && !GENERIC_TYPES.has(declared) ? declared : undefined;
 }
 /** Extension from a URL path (`…/receipt.jpg?sig=…` → `jpg`), when it has one. */
 function extensionFromUrl(url) {
@@ -36,9 +50,32 @@ function extensionFor(mimeType, url) {
         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. 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.",
+        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
@@ -50,16 +87,24 @@ export function registerReceiptTools(server, client) {
                 .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(),
-            inline: z
+            write: z
                 .boolean()
-                .describe(`Also return the receipt as a base64 image in the result. Image receipts only, and only under ${MAX_INLINE_BYTES} bytes.`)
+                .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, output_dir, inline }) => {
+    }, 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}`);
@@ -75,36 +120,127 @@ export function registerReceiptTools(server, client) {
         }
         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;
+        // 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,
+            ...(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 && !inlined
+            ...(inline === true && oversized
                 ? {
-                    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.',
+                    // 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 && imageMime) {
-            result.content.push(...imageResult(base64, imageMime).content);
+        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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "splitwise-mcp",
-  "version": "2.2.0",
+  "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.2.0",
+  "version": "2.2.1",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "splitwise-mcp",
-      "version": "2.2.0",
+      "version": "2.2.1",
       "transport": {
         "type": "stdio"
       },

package/skills/splitwise-mcp/SKILL.md

@@ -100,7 +100,7 @@ API key auth — no login flow or token rotation. The key is attached to every r
 ### 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 |
+| `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 |
@@ -137,7 +137,9 @@ 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
+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:**
@@ -154,4 +156,6 @@ sw_update_expense(expense_id, description: "Corrected description", cost: "95.00
 - `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