splitwise-mcp 3.4.1 → 3.5.1

package/dist/tools/_split.js

@@ -0,0 +1,61 @@
+/**
+ * The shares for "`payer` paid it all, everyone in `participants` owes an
+ * equal part". Built here rather than with Splitwise's `split_equally`, which
+ * always makes the CALLER the payer — the 50/50 case where the other parent
+ * paid had to be hand-built as a users[] array.
+ *
+ * Arithmetic is in minor units at the precision the cost string was written
+ * with ("25.01" → cents, "1001" → whole units), so the shares always sum to
+ * the cost exactly. Leftover units go one each to the first participants in
+ * order — deterministic, and shown in the preview before anything is sent.
+ */
+export function equalSplit(cost, payer, participants) {
+    const match = /^(\d+)(?:\.(\d+))?$/.exec(cost);
+    if (!match)
+        throw new Error(`cost must be a plain decimal string like "25.00" for an equal split (got "${cost}")`);
+    const ids = [...new Set(participants)];
+    if (ids.length === 0)
+        throw new Error('split_among must name at least one participant');
+    const decimals = match[2]?.length ?? 0;
+    const total = BigInt(match[1] + (match[2] ?? ''));
+    const count = BigInt(ids.length);
+    const base = total / count;
+    const leftover = Number(total % count);
+    const fmt = (units) => formatUnits(units, decimals);
+    const shares = ids.map((id, i) => ({
+        user_id: id,
+        paid_share: fmt(id === payer ? total : 0n),
+        owed_share: fmt(base + (i < leftover ? 1n : 0n)),
+    }));
+    if (!ids.includes(payer)) {
+        shares.push({ user_id: payer, paid_share: fmt(total), owed_share: fmt(0n) });
+    }
+    return shares;
+}
+function formatUnits(units, decimals) {
+    if (decimals === 0)
+        return units.toString();
+    const digits = units.toString().padStart(decimals + 1, '0');
+    return `${digits.slice(0, -decimals)}.${digits.slice(-decimals)}`;
+}
+const fullName = (m) => [m.first_name, m.last_name].filter(Boolean).join(' ');
+/**
+ * A member named by id, full name, email or a first name only they have.
+ * `field` names the argument in the error, so the caller knows which to fix.
+ */
+export function resolveMember(who, members, field) {
+    if (typeof who === 'number') {
+        if (members.some((m) => m.id === who))
+            return who;
+        throw new Error(`${field}: user ${who} is not a member of this group`);
+    }
+    const want = who.trim().toLowerCase();
+    const exact = members.filter((m) => fullName(m).toLowerCase() === want || (m.email ?? '').toLowerCase() === want);
+    const candidates = exact.length > 0 ? exact : members.filter((m) => (m.first_name ?? '').toLowerCase() === want);
+    if (candidates.length === 1)
+        return candidates[0].id;
+    if (candidates.length > 1) {
+        throw new Error(`${field}: "${who}" is ambiguous — ${candidates.map((m) => `${fullName(m)} (${m.id})`).join(', ')}. Pass the user id.`);
+    }
+    throw new Error(`${field}: "${who}" is not a member of this group (members: ${members.map((m) => `${fullName(m)} (${m.id})`).join(', ')})`);
+}

package/dist/tools/batch.js

@@ -0,0 +1,22 @@
+import { registerBatchTool, registerConfirmTool } from '@chrischall/mcp-utils';
+/**
+ * `sw_confirm` and `sw_batch` — the two ways to spend fewer calls on Splitwise
+ * writes from a client that cannot show a confirmation prompt (claude.ai).
+ *
+ * - `sw_confirm({confirmToken})` finishes any gated write's two-step
+ *   confirmation with the token alone: the server kept the phase-1 arguments,
+ *   so a base64 receipt does not cross the conversation a second time.
+ * - `sw_batch({ops})` previews and approves several expense/comment writes at
+ *   once — "log the expense, comment on it, attach the receipt" in one
+ *   approval, with the new expense's id fed forward through `refs`.
+ *
+ * Both come from `@chrischall/mcp-utils` (docs/CONFIRM-TOKEN.md §13–14).
+ * Registered LAST: the batch tool lists the writes registered before it.
+ */
+export function registerBatchTools(server, _client) {
+    registerConfirmTool(server, { name: 'sw_confirm' });
+    registerBatchTool(server, {
+        name: 'sw_batch',
+        description: 'Several Splitwise writes in one go, e.g. create an expense, then sw_create_comment / sw_attach_receipt on it with refs {"expense_id": "0.expense_id"}.',
+    });
+}

package/dist/tools/expenses.js

@@ -1,9 +1,11 @@
 import { z } from 'zod';
-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 { EXPENSE_LIST_VIEWS, SW_VIEWS, viewExpense, viewExpenses } from '../project.js';
+import { buildQueryString, defineWrite, minifiedResult, registerWrite, resolveView, viewParam, } from '@chrischall/mcp-utils';
 import { UNTRUSTED_DESCRIPTION_SUFFIX, swUntrustedResult } from './_untrusted.js';
 import { buildReceiptForm, loadReceipt, receiptParam, receiptSchema, verifyReceiptStored, } from './_receipt.js';
+import { attachComments, decodeCursor, encodeCursor, hasLocalFilters, projectForList, scanExpenses, MAX_COMMENT_ROWS, SCAN_BUDGET, } from './_list.js';
+import { findDuplicates, inferCategory, resolveCategory, resolveEqualSplit } from './_create.js';
+import { assertNotDeleted, explainForbidden, verifyRestored, withPostState } from './_expense-state.js';
 /** Flattens a users array into Splitwise's flat-param JSON format. */
 export function flattenUsers(users) {
     const flat = {};
@@ -14,10 +16,36 @@ export function flattenUsers(users) {
     });
     return flat;
 }
+/** A full unfiltered page may have more behind it: hand back a cursor to it. */
+function withCursor(out, page, offset, want, q, filters) {
+    if (!Array.isArray(page) || page.length < want || out === null || typeof out !== 'object')
+        return out;
+    return { ...out, next_cursor: encodeCursor(offset + page.length, q, filters) };
+}
+function commentNote(note) {
+    return note?.truncated
+        ? { comments_note: `Comments were inlined for the first ${MAX_COMMENT_ROWS} expenses that have any; narrow the filters or page with a smaller limit for the rest.` }
+        : {};
+}
+/**
+ * One API key per SplitwiseClient (the hosted path builds a client per user),
+ * so there is no account switch inside a server to bind — said explicitly,
+ * as `confirmWrite` requires.
+ */
+const SINGLE_ACCOUNT = { account: undefined };
+/** The id of the expense a create returned — what sw_batch feeds into a later op. */
+function createdExpenseId(result) {
+    const id = result?.expenses?.[0]?.id;
+    if (typeof id !== 'number')
+        throw new Error('Splitwise returned no id for the created expense');
+    return id;
+}
 function buildExpenseBody(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;
+    const { split_equally, users, expense_id: _id, confirmToken: _confirmToken, receipt: _receipt, 
+    // Resolved by the create handler into category_id / users[].
+    category: _category, split: _split, paid_by: _paidBy, split_among: _splitAmong, ...rest } = args;
     if (split_equally && users) {
         throw new Error('Provide either split_equally or users, not both');
     }
@@ -53,12 +81,13 @@ const userShareSchema = z.object({
 });
 export function registerExpenseTools(server, client) {
     server.registerTool('sw_list_expenses', {
-        description: `List or search Splitwise expenses. All filters are optional. Use group_id to filter by group, dated_after/dated_before for date ranges. ${UNTRUSTED_DESCRIPTION_SUFFIX}`,
+        description: `List or search Splitwise expenses. All filters are optional. group_id / friend_id / dated_after / dated_before / updated_after / updated_before are applied by Splitwise; description_contains, include_deleted, created_by, min_cost / max_cost and category are applied here while paging through the history (up to ${SCAN_BUDGET} records per call), returning up to \`limit\` matches and a next_cursor to continue. For reconciliation use view:"rows" (one flat line per expense: id, date, description, cost, created_by, deleted_at, deleted_by, comments_count, has_receipt) and include_comments:true to see why entries were deleted. Deleted expenses are included unless include_deleted is false. ${UNTRUSTED_DESCRIPTION_SUFFIX}`,
         annotations: { readOnlyHint: true, openWorldHint: true },
         inputSchema: z.object({
-            view: viewParam(SW_VIEWS, {
-                note: 'compact keeps the share breakdown, repayments and receipt presence and drops the avatars and the repeat/reminder/transaction block; "full" returns Splitwise\'s whole records.',
-            }),
+            view: z
+                .enum(EXPENSE_LIST_VIEWS)
+                .describe('Response shape. "compact" (default) keeps the share breakdown, repayments and receipt presence and drops the avatars and the repeat/reminder/transaction block; "rows" is one flat line per expense for reconciling long histories; "full" returns Splitwise\'s whole records.')
+                .optional(),
             group_id: z.number().describe('Only expenses in this group').optional(),
             friend_id: z.number().describe('Only expenses with this friend').optional(),
             dated_after: z
@@ -71,6 +100,33 @@ export function registerExpenseTools(server, client) {
                 .optional(),
             updated_after: z.string().describe('ISO 8601 datetime').optional(),
             updated_before: z.string().describe('ISO 8601 datetime').optional(),
+            description_contains: z
+                .string()
+                .min(1)
+                .describe('Only expenses whose description contains this text (case-insensitive)')
+                .optional(),
+            include_deleted: z
+                .union([z.boolean(), z.literal('only')])
+                .describe('true (default): live and deleted; false: live only; "only": deleted only')
+                .optional(),
+            created_by: z
+                .union([z.number(), z.string().min(1)])
+                .describe('Only expenses created by this user: a user id, or part of their name / their email')
+                .optional(),
+            min_cost: z.number().describe('Only expenses costing at least this much').optional(),
+            max_cost: z.number().describe('Only expenses costing at most this much').optional(),
+            category: z
+                .union([z.number(), z.string().min(1)])
+                .describe('Only expenses in this category: a category id, or its name (any case)')
+                .optional(),
+            include_comments: z
+                .boolean()
+                .describe(`Inline each matched expense's comments (only those that have any; at most ${MAX_COMMENT_ROWS} expenses per call)`)
+                .optional(),
+            cursor: z
+                .string()
+                .describe('next_cursor from a previous call with the same filters, to continue where it stopped')
+                .optional(),
             // Bounded: Splitwise reads limit=0 as "return everything", an
             // unbounded result the host refuses.
             limit: z
@@ -78,23 +134,57 @@ export function registerExpenseTools(server, client) {
                 .int()
                 .min(1)
                 .max(200)
-                .describe('Max results, 1-200 (API default: 20). Page with offset for more.')
+                .describe('Max results, 1-200 (default 20). With the local filters, the max number of MATCHES returned.')
                 .optional(),
-            offset: z.number().int().min(0).describe('Pagination offset').optional(),
+            offset: z.number().int().min(0).describe('Pagination offset (prefer cursor)').optional(),
         }),
     }, async (args) => {
-        const qs = buildQueryString({
+        const view = args.view ?? 'compact';
+        const q = {
             group_id: args.group_id,
             friend_id: args.friend_id,
             dated_after: args.dated_after,
             dated_before: args.dated_before,
             updated_after: args.updated_after,
             updated_before: args.updated_before,
-            limit: args.limit,
-            offset: args.offset,
+        };
+        const filters = {
+            description_contains: args.description_contains,
+            include_deleted: args.include_deleted,
+            created_by: args.created_by,
+            min_cost: args.min_cost,
+            max_cost: args.max_cost,
+            category: args.category,
+        };
+        const want = args.limit ?? 20;
+        if (!hasLocalFilters(filters) && args.cursor === undefined) {
+            // No local filtering: one request, exactly as before.
+            const qs = buildQueryString({ ...q, limit: args.limit, offset: args.offset });
+            const data = await client.request('GET', `/get_expenses${qs}`);
+            const page = data?.expenses;
+            if (view === 'compact' && !args.include_comments) {
+                const out = viewExpenses('compact', data);
+                return swUntrustedResult(withCursor(out, page, (args.offset ?? 0), want, q, filters));
+            }
+            if (!Array.isArray(page))
+                return swUntrustedResult(data);
+            const rows = page.map((e) => projectForList(view, e));
+            const note = args.include_comments ? await attachComments(client, page, rows) : undefined;
+            return swUntrustedResult(withCursor({ expenses: rows, ...commentNote(note) }, page, args.offset ?? 0, want, q, filters));
+        }
+        const start = args.cursor !== undefined ? decodeCursor(args.cursor, q, filters) : (args.offset ?? 0);
+        const scan = await scanExpenses(client, q, filters, start, want);
+        const rows = scan.expenses.map((e) => projectForList(view, e));
+        const note = args.include_comments ? await attachComments(client, scan.expenses, rows) : undefined;
+        return swUntrustedResult({
+            expenses: rows,
+            scanned: scan.scanned,
+            ...(scan.nextOffset !== undefined ? { next_cursor: encodeCursor(scan.nextOffset, q, filters) } : {}),
+            ...(scan.nextOffset !== undefined && scan.expenses.length < want
+                ? { note: `Stopped after reading ${scan.scanned} records; pass next_cursor to keep searching older expenses.` }
+                : {}),
+            ...commentNote(note),
         });
-        const data = await client.request('GET', `/get_expenses${qs}`);
-        return swUntrustedResult(viewExpenses(resolveView(args.view, SW_VIEWS), data));
     });
     server.registerTool('sw_get_expense', {
         description: `Get full details of a single Splitwise expense by id. ${UNTRUSTED_DESCRIPTION_SUFFIX}`,
@@ -109,9 +199,9 @@ export function registerExpenseTools(server, client) {
         const data = await client.request('GET', `/get_expense/${id}`);
         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. 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 },
+    registerWrite(server, defineWrite({
+        name: 'sw_create_expense',
+        description: `Create a Splitwise expense. Splits: split_equally:true (you paid, everyone in the group owes an equal part); split:"equal" with paid_by (someone — e.g. the other parent — paid, split equally among split_among or the whole group); or 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 category by name (or category_id); with neither, the most common category of similar expenses in the group is used and shown in the preview as inferred_category. The preview also lists possible_duplicates — expenses in the group, live or deleted, with the same cost, a similar description and a date within a day; check them before confirming. Pass receipt to attach an image or PDF in the same call. This puts charges on every participant's balance and notifies them. In sw_batch it produces expense_id.`,
         inputSchema: z.object({
             group_id: z.number().describe('Group to add expense to (use 0 for no group)'),
             description: z.string().describe('Short description of the expense'),
@@ -124,38 +214,96 @@ export function registerExpenseTools(server, client) {
                 .array(userShareSchema)
                 .describe('Custom split (mutually exclusive with split_equally). Full list of participants required.')
                 .optional(),
+            split: z
+                .literal('equal')
+                .describe('"equal": paid_by paid the whole cost and everyone in split_among owes an equal part (odd cents go to the first participants). Use instead of split_equally (which always makes YOU the payer) or users.')
+                .optional(),
+            paid_by: z
+                .union([z.number(), z.string().min(1)])
+                .describe('With split:"equal" — who paid: a user id, or a group member\'s name or email')
+                .optional(),
+            split_among: z
+                .array(z.union([z.number(), z.string().min(1)]))
+                .min(1)
+                .describe('With split:"equal" — who shares the cost (ids, names or emails). Default: every group member.')
+                .optional(),
             currency_code: z
                 .string()
                 .describe('Currency code, e.g. "USD". Defaults to group/user default.')
                 .optional(),
             date: z.string().describe('ISO 8601 datetime').optional(),
             category_id: z.number().describe('Category id from sw_get_categories').optional(),
+            category: z
+                .string()
+                .min(1)
+                .describe('Category by name, e.g. "Education" or "Medical expenses" (any case). Mutually exclusive with category_id. Omit both and the most common category of similar expenses in the group is used.')
+                .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})${receipt ? ` with receipt ${receipt.filename}` : ''} — notifies group members`,
-            method: 'POST',
-            path: '/create_expense',
-            body: previewBody(body, receipt),
-            target: args.group_id,
-            confirmToken: args.confirmToken,
-            args,
-        });
-        if (gate)
-            return gate;
-        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). 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 },
+        plan: async (args) => {
+            if (args.category !== undefined && args.category_id !== undefined) {
+                throw new Error('Provide either category or category_id, not both');
+            }
+            if (args.split === 'equal') {
+                if (args.paid_by === undefined)
+                    throw new Error('split:"equal" needs paid_by (who paid the whole cost)');
+                if (args.split_equally)
+                    throw new Error('split:"equal" replaces split_equally — pass one or the other');
+                if (args.users)
+                    throw new Error('split:"equal" builds users for you — pass split or users, not both');
+            }
+            else if (args.paid_by !== undefined || args.split_among !== undefined) {
+                throw new Error('paid_by and split_among only apply with split:"equal"');
+            }
+            const body = buildExpenseBody(args);
+            if (args.split === 'equal') {
+                Object.assign(body, flattenUsers(await resolveEqualSplit(client, {
+                    group_id: args.group_id,
+                    cost: args.cost,
+                    paid_by: args.paid_by,
+                    split_among: args.split_among,
+                })));
+            }
+            const extra = {};
+            if (args.category !== undefined) {
+                body.category_id = (await resolveCategory(client, args.category)).id;
+            }
+            else if (args.category_id === undefined && args.group_id > 0) {
+                const inferred = await inferCategory(client, args.group_id, args.description);
+                if (inferred) {
+                    body.category_id = inferred.id;
+                    extra.inferred_category = inferred;
+                }
+            }
+            const receipt = args.receipt ? await loadReceipt(args.receipt, client) : undefined;
+            const duplicates = args.group_id > 0
+                ? await findDuplicates(client, { group_id: args.group_id, cost: args.cost, description: args.description, date: args.date })
+                : [];
+            if (duplicates.length > 0)
+                extra.possible_duplicates = duplicates;
+            return {
+                gate: {
+                    action: 'expense.create',
+                    summary: `Create a Splitwise expense "${args.description}" (${args.cost})${receipt ? ` with receipt ${receipt.filename}` : ''} — notifies group members` +
+                        (duplicates.length > 0
+                            ? ` — WARNING: ${duplicates.length} possible duplicate${duplicates.length > 1 ? 's' : ''} already in the group (see possible_duplicates)`
+                            : ''),
+                    ...SINGLE_ACCOUNT,
+                    target: args.group_id,
+                    request: { method: 'POST', path: '/create_expense', body: previewBody(body, receipt) },
+                    preview: extra,
+                },
+                state: { body, receipt },
+            };
+        },
+        execute: async ({ body, receipt }) => withPostState(await sendExpenseWrite(client, '/create_expense', body, receipt)),
+        render: minifiedResult,
+        produces: { expense_id: (result) => createdExpenseId(result) },
+    }));
+    registerWrite(server, defineWrite({
+        name: '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). To attach or replace the receipt on an existing expense, pass expense_id and receipt alone.',
         inputSchema: z.object({
             expense_id: z.number().describe('ID of the expense to update'),
             description: z.string().optional(),
@@ -170,104 +318,93 @@ export function registerExpenseTools(server, client) {
             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}${receipt ? ` (attach receipt ${receipt.filename})` : ''} — notifies group members`,
-            method: 'POST',
-            path: `/update_expense/${expense_id}`,
-            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}`,
+        plan: async (args) => {
+            const { expense_id } = args;
+            const body = buildExpenseBody(args);
+            const receipt = args.receipt ? await loadReceipt(args.receipt, client) : undefined;
+            await assertNotDeleted(client, expense_id);
+            return {
+                gate: {
+                    action: 'expense.update',
+                    summary: `Update Splitwise expense ${expense_id}${receipt ? ` (attach receipt ${receipt.filename})` : ''} — notifies group members`,
+                    ...SINGLE_ACCOUNT,
+                    target: expense_id,
+                    request: { method: 'POST', path: `/update_expense/${expense_id}`, body: previewBody(body, receipt) },
+                },
+                state: { expense_id, body, receipt },
+            };
+        },
+        execute: async ({ expense_id, body, receipt }) => withPostState(await explainForbidden(client, expense_id, () => sendExpenseWrite(client, `/update_expense/${expense_id}`, body, receipt, expense_id))),
+        render: minifiedResult,
+    }));
+    registerWrite(server, defineWrite({
+        name: '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.upload_id (hosted: upload it first via sw_get_upload_url — no bytes in the tool call), receipt.path (local) or receipt.base64. Fails if Splitwise does not store the file.',
         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 sendExpenseWrite(client, path, {}, receipt, expense_id);
-        return minifiedResult(data);
-    });
-    server.registerTool('sw_delete_expense', {
-        description: `Soft-delete a Splitwise expense by id. Returns {success: true} on success. Use sw_undelete_expense to restore. ${CONFIRM_NOTE}`,
-        annotations: { readOnlyHint: false, destructiveHint: true, openWorldHint: true },
+        plan: async (args) => {
+            const { expense_id } = args;
+            const receipt = await loadReceipt(args.receipt, client);
+            await assertNotDeleted(client, expense_id);
+            return {
+                gate: {
+                    action: 'expense.attach_receipt',
+                    summary: `Attach receipt ${receipt.filename} to Splitwise expense ${expense_id} (replaces any existing receipt)`,
+                    ...SINGLE_ACCOUNT,
+                    target: expense_id,
+                    request: { method: 'POST', path: `/update_expense/${expense_id}`, body: previewBody({}, receipt) },
+                },
+                state: { expense_id, receipt },
+            };
+        },
+        execute: async ({ expense_id, receipt }) => withPostState(await explainForbidden(client, expense_id, () => sendExpenseWrite(client, `/update_expense/${expense_id}`, {}, receipt, expense_id))),
+        render: minifiedResult,
+    }));
+    registerWrite(server, defineWrite({
+        name: 'sw_delete_expense',
+        description: 'Soft-delete a Splitwise expense by id. Returns {success: true} on success. Use sw_undelete_expense to restore.',
         inputSchema: z.object({
             id: z.number().describe('Expense ID to delete'),
-            confirmToken: confirmTokenParam,
         }),
-    }, async (args, ctx) => {
-        const { id, confirmToken } = args;
-        const gate = await confirmWrite(ctx, {
-            tool: 'sw_delete_expense',
-            action: 'expense.delete',
-            summary: `Soft-delete Splitwise expense ${id}`,
-            method: 'POST',
-            path: `/delete_expense/${id}`,
-            target: id,
-            confirmToken,
-            args,
-        });
-        if (gate)
-            return gate;
-        const data = await client.request('POST', `/delete_expense/${id}`);
-        return minifiedResult(data);
-    });
-    server.registerTool('sw_undelete_expense', {
-        description: `Restore a soft-deleted Splitwise expense. This puts its charges back on every participant's balance and notifies them, so it is gated like the other writes. ${CONFIRM_NOTE}`,
+        plan: ({ id }) => ({
+            gate: {
+                action: 'expense.delete',
+                summary: `Soft-delete Splitwise expense ${id}`,
+                ...SINGLE_ACCOUNT,
+                target: id,
+                request: { method: 'POST', path: `/delete_expense/${id}` },
+            },
+            state: id,
+        }),
+        execute: (id) => client.request('POST', `/delete_expense/${id}`),
+        render: minifiedResult,
+    }));
+    registerWrite(server, defineWrite({
+        name: 'sw_undelete_expense',
+        description: 'Restore a soft-deleted Splitwise expense, then re-read it and return post_state {deleted_at, deleted_by, updated_at, updated_by}; if it is still (or again) deleted, the call fails naming who deleted it and when. This puts its charges back on every participant\'s balance and notifies them, so it is gated like the other writes.',
         // Destructive despite the delete tool being its record-level inverse:
         // the restore notifies every participant, and no later call un-sends that.
+        // Stated rather than left to registerWrite's default, because it is a
+        // decision about this tool, not a default it happens to share.
         annotations: { readOnlyHint: false, destructiveHint: true, openWorldHint: true },
         inputSchema: z.object({
             id: z.number().describe('Expense ID to restore'),
-            confirmToken: confirmTokenParam,
         }),
-    }, async (args, ctx) => {
-        const { id, confirmToken } = args;
-        const gate = await confirmWrite(ctx, {
-            tool: 'sw_undelete_expense',
-            action: 'expense.undelete',
-            summary: `Restore soft-deleted Splitwise expense ${id} — puts it back on balances and notifies its participants`,
-            method: 'POST',
-            path: `/undelete_expense/${id}`,
-            target: id,
-            confirmToken,
-            args,
-        });
-        if (gate)
-            return gate;
-        const data = await client.request('POST', `/undelete_expense/${id}`);
-        return minifiedResult(data);
-    });
+        plan: ({ id }) => ({
+            gate: {
+                action: 'expense.undelete',
+                summary: `Restore soft-deleted Splitwise expense ${id} — puts it back on balances and notifies its participants`,
+                ...SINGLE_ACCOUNT,
+                target: id,
+                request: { method: 'POST', path: `/undelete_expense/${id}` },
+            },
+            state: id,
+        }),
+        execute: async (id) => verifyRestored(client, id, await client.request('POST', `/undelete_expense/${id}`)),
+        render: minifiedResult,
+    }));
 }

package/dist/tools/uploads.js

@@ -0,0 +1,45 @@
+import { randomUUID } from 'crypto';
+import { z } from 'zod';
+import { minifiedResult } from '@chrischall/mcp-utils';
+import { blobStoreFromEnv } from '@chrischall/mcp-utils/export';
+import { canonicalReceiptMime, MAX_RECEIPT_BYTES, safeKeyName } from './_receipt.js';
+/** Long enough to run a curl in the same turn, short enough that a leaked link is soon dead. */
+export const UPLOAD_URL_TTL_MS = 10 * 60 * 1000;
+/**
+ * `sw_get_upload_url` — get a receipt's bytes to the server without passing
+ * them through the model. A hosted server cannot read the caller's files
+ * (receipt.path is off) and base64 costs ~1.37 bytes of context per byte of
+ * image; a signed PUT moves the original file with one curl. Always
+ * registered, so the tool list is the same everywhere; on a server with no
+ * blob store it says which receipt source to use instead.
+ */
+export function registerUploadTools(server, _client) {
+    server.registerTool('sw_get_upload_url', {
+        description: 'Get a short-lived (~10 min) signed URL to upload a receipt file (PNG, JPEG, GIF or PDF, up to 10 MiB) to this server WITHOUT putting its bytes in a tool call: run the returned curl command from a shell or sandbox that has the file and network access to the URL\'s host, then pass receipt: {upload_id, filename} to sw_attach_receipt, sw_create_expense or sw_update_expense. Send the original file — no need to shrink it. Only on the hosted server; locally use receipt.path. If you have no shell that can reach the URL, use receipt.base64 instead.',
+        annotations: { readOnlyHint: true, openWorldHint: true },
+        inputSchema: z.object({
+            filename: z.string().min(1).max(200).describe('Name of the file, e.g. "receipt.jpg"'),
+            content_type: z
+                .string()
+                .describe('The file\'s type: image/png, image/jpeg, image/gif or application/pdf. The upload must send exactly this Content-Type.'),
+        }),
+    }, async ({ filename, content_type }) => {
+        const store = blobStoreFromEnv();
+        if (!store) {
+            throw new Error('sw_get_upload_url only works on the hosted server (no blob store is configured here). Pass the file as receipt.path (a file inside SPLITWISE_INPUT_DIR) or receipt.base64 instead.');
+        }
+        const contentType = canonicalReceiptMime(content_type);
+        const key = `up/${randomUUID()}/${safeKeyName(filename)}`;
+        const { url: uploadUrl, expiresAtMs: exp } = store.signPutUrl(key, contentType, { ttlMs: UPLOAD_URL_TTL_MS });
+        return minifiedResult({
+            upload_id: key,
+            upload_url: uploadUrl,
+            method: 'PUT',
+            headers: { 'Content-Type': contentType },
+            max_bytes: MAX_RECEIPT_BYTES,
+            expires_at: new Date(exp).toISOString(),
+            curl: `curl -sS -f -X PUT -H "Content-Type: ${contentType}" --data-binary @<path-to-file> "${uploadUrl}"`,
+            next: `After the upload succeeds, pass receipt: {"upload_id": "${key}", "filename": "${safeKeyName(filename)}"} to sw_attach_receipt (or sw_create_expense / sw_update_expense).`,
+        });
+    });
+}