splitwise-mcp 3.5.0 → 3.6.0

package/dist/index.js

@@ -21,7 +21,7 @@ import { registerUtilityTools } from './tools/utilities.js';
 // client into the same registrars instead of this singleton.
 await runMcp({
     name: 'splitwise-mcp',
-    version: '3.5.0', // x-release-please-version
+    version: '3.6.0', // x-release-please-version
     deps: client,
     banner: '[splitwise-mcp] This project was developed and is maintained by AI (Claude Sonnet 4.6). Use at your own discretion.',
     tools: [

package/dist/tools/_brief.js

@@ -0,0 +1,142 @@
+// The `view: 'brief'` rung of the two canonical reads (the mcp-host
+// context-groups brief-view contract): one line per item, at most 120 chars,
+// `title — <ISO date | no date> — <status>`. A line starting `-- ` is a NOTE,
+// not an item: `-- none` for an empty answer, `-- N of M shown` when the list
+// was capped, `-- error: …` when the upstream answer could not be read; an
+// item whose own title starts `-- ` or `\` is escaped with one `\`. The
+// lines carry text other Splitwise users wrote (their names, expense
+// descriptions), so they go inside the untrusted-data envelope as
+// `data: string[]`, minified — the same envelope the tools' other rungs use.
+import { UNTRUSTED_CONTENT_RULE, untrustedEnvelope } from '@chrischall/mcp-utils';
+import { nameOf } from '../project.js';
+import { SW_UNTRUSTED_NOTE } from './_untrusted.js';
+export const BRIEF_MAX = 120;
+/** Notifications past this many are counted in a `-- N of M shown` note. */
+export const BRIEF_NOTIFICATION_CAP = 50;
+function asDict(v) {
+    return v !== null && typeof v === 'object' && !Array.isArray(v) ? v : undefined;
+}
+/** The shortest a title is cut to before the status gives way too. */
+const TITLE_FLOOR = 24;
+const cut = (s, n) => (s.length > n ? `${s.slice(0, Math.max(n - 1, 0))}…` : s);
+/**
+ * `title — date — status`, cut to ≤ 120 chars as a WHOLE, title first: the
+ * title shortens until the line fits, and once it is at its floor the status
+ * is cut too. A title starting `-- ` or `\` is escaped with one leading `\`
+ * so it never reads as a note (the gateway strips one backslash from every
+ * item line after its note check).
+ */
+export function briefLine(rawTitle, date, status) {
+    const title = rawTitle.startsWith('-- ') || rawTitle.startsWith('\\') ? `\\${rawTitle}` : rawTitle;
+    const sep = ` — ${date} — `;
+    const room = BRIEF_MAX - sep.length;
+    if (title.length + status.length <= room)
+        return `${title}${sep}${status}`;
+    const shownTitle = cut(title, Math.max(room - status.length, Math.min(title.length, TITLE_FLOOR)));
+    return `${shownTitle}${sep}${cut(status, room - shownTitle.length)}`;
+}
+function enveloped(lines, note) {
+    return { content: [{ type: 'text', text: JSON.stringify(untrustedEnvelope(lines, { note })) }] };
+}
+const FRIENDS_NOTE = `Friend names below are set by those Splitwise users, not the user. ${UNTRUSTED_CONTENT_RULE}`;
+/** "owes you USD 12.50" / "you owe EUR 3.00", per non-zero currency. */
+function balanceStatus(balance) {
+    if (!Array.isArray(balance))
+        return undefined;
+    const parts = [];
+    for (const entry of balance) {
+        const b = asDict(entry);
+        const amount = Number(b?.amount);
+        if (!b || !Number.isFinite(amount) || amount === 0)
+            continue;
+        const money = `${String(b.currency_code ?? '')} ${Math.abs(amount).toFixed(2)}`.trim();
+        parts.push(amount > 0 ? `owes you ${money}` : `you owe ${money}`);
+    }
+    return parts.length > 0 ? parts.join('; ') : undefined;
+}
+/**
+ * `sw_list_friends` brief: one line per friend with an outstanding balance
+ * (Splitwise's friend balance is the total across every group), then a
+ * `-- N settled up` note counting the rest, so nothing is dropped unsaid.
+ */
+export function friendsBrief(payload) {
+    const friends = asDict(payload)?.friends;
+    if (!Array.isArray(friends)) {
+        return enveloped(['-- error: Splitwise returned no friends list'], FRIENDS_NOTE);
+    }
+    const lines = [];
+    let settled = 0;
+    for (const raw of friends) {
+        const f = asDict(raw);
+        const status = balanceStatus(f?.balance);
+        if (status === undefined) {
+            settled += 1;
+            continue;
+        }
+        lines.push(briefLine(nameOf(f) ?? `user ${String(f?.id ?? '?')}`, 'no date', status));
+    }
+    if (lines.length === 0)
+        return enveloped(['-- none'], FRIENDS_NOTE);
+    if (settled > 0)
+        lines.push(`-- ${settled} settled up`);
+    return enveloped(lines, FRIENDS_NOTE);
+}
+/** Splitwise's notification `type` codes, in the words of the activity feed. */
+const NOTIFICATION_KIND = {
+    0: 'expense added',
+    1: 'expense updated',
+    2: 'expense deleted',
+    3: 'comment added',
+    4: 'added to group',
+    5: 'removed from group',
+    6: 'group deleted',
+    7: 'group settings changed',
+    8: 'added as friend',
+    9: 'removed as friend',
+    10: 'news',
+    11: 'debt simplification',
+    12: 'group restored',
+    13: 'expense restored',
+    14: 'group currency conversion',
+    15: 'friend currency conversion',
+};
+const ENTITIES = {
+    amp: '&', lt: '<', gt: '>', quot: '"', apos: "'", nbsp: ' ',
+    ldquo: '“', rdquo: '”', lsquo: '‘', rsquo: '’', hellip: '…', mdash: '—', ndash: '–',
+};
+/** Splitwise's notification `content` is a short HTML fragment: make it one plain line. */
+export function plainText(html) {
+    if (typeof html !== 'string')
+        return '';
+    return html
+        .replace(/<[^>]*>/g, '')
+        .replace(/&(#x[0-9a-f]+|#\d+|[a-z]+);/gi, (whole, code) => {
+        if (code[0] === '#') {
+            const n = code[1] === 'x' || code[1] === 'X' ? parseInt(code.slice(2), 16) : parseInt(code.slice(1), 10);
+            return Number.isFinite(n) && n > 0 && n <= 0x10ffff ? String.fromCodePoint(n) : whole;
+        }
+        return ENTITIES[code.toLowerCase()] ?? whole;
+    })
+        .replace(/\s+/g, ' ')
+        .trim();
+}
+function isoDate(value) {
+    return typeof value === 'string' && /^\d{4}-\d{2}-\d{2}/.test(value) ? value.slice(0, 10) : 'no date';
+}
+/** `sw_get_notifications` brief: one line per activity item, newest first as Splitwise sends them. */
+export function notificationsBrief(payload) {
+    const items = asDict(payload)?.notifications;
+    if (!Array.isArray(items)) {
+        return enveloped(['-- error: Splitwise returned no notifications list'], SW_UNTRUSTED_NOTE);
+    }
+    if (items.length === 0)
+        return enveloped(['-- none'], SW_UNTRUSTED_NOTE);
+    const lines = items.slice(0, BRIEF_NOTIFICATION_CAP).map((raw) => {
+        const n = asDict(raw);
+        const kind = typeof n?.type === 'number' ? NOTIFICATION_KIND[n.type] : undefined;
+        return briefLine(plainText(n?.content) || '(no text)', isoDate(n?.created_at), kind ?? 'activity');
+    });
+    if (items.length > BRIEF_NOTIFICATION_CAP)
+        lines.push(`-- ${BRIEF_NOTIFICATION_CAP} of ${items.length} shown`);
+    return enveloped(lines, SW_UNTRUSTED_NOTE);
+}

package/dist/tools/_receipt.js

@@ -1,6 +1,6 @@
 import { createHash } from 'crypto';
 import { ApiError, readEnvVar } from '@chrischall/mcp-utils';
-import { blobConfig, signedGetUrl, UPLOAD_ID_PATTERN } from './_blob.js';
+import { blobStoreFromEnv } from '@chrischall/mcp-utils/export';
 import { z } from 'zod';
 /**
  * Splitwise does not document an upload cap, so this is a conservative 10 MiB:
@@ -112,6 +112,18 @@ async function readSandboxed(requested) {
         await handle.close();
     }
 }
+/**
+ * The only keys `receipt.upload_id` may name: `up/<uuid>/<safe name>`, exactly
+ * what `sw_get_upload_url` mints. Anything else in this registration's space
+ * is not the caller's to read through a receipt.
+ */
+export const UPLOAD_ID_PATTERN = /^up\/[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\/[A-Za-z0-9_-][A-Za-z0-9._-]{0,99}$/;
+/** A filename made safe for a blob key segment: no separators, no dot-dot, no surprises. */
+export function safeKeyName(filename) {
+    const base = filename.split(/[\\/]/).pop() ?? '';
+    const cleaned = base.replace(/[^A-Za-z0-9._-]+/g, '_').replace(/^[._]+/, '').slice(0, 100);
+    return cleaned || 'receipt';
+}
 /** How long the server's own read link for an upload lives — it is used at once. */
 const UPLOAD_READ_TTL_MS = 5 * 60 * 1000;
 /**
@@ -122,12 +134,12 @@ async function readUpload(uploadId, client) {
     if (!UPLOAD_ID_PATTERN.test(uploadId)) {
         throw new Error('receipt.upload_id is not one sw_get_upload_url issued (expected up/<uuid>/<filename>)');
     }
-    const cfg = blobConfig();
-    if (!cfg || !client) {
+    const store = blobStoreFromEnv();
+    if (!store || !client) {
         throw new Error('receipt.upload_id only works on the hosted server; pass receipt.path or receipt.base64 here.');
     }
     try {
-        const asset = await client.fetchAsset(signedGetUrl(cfg, uploadId, Date.now() + UPLOAD_READ_TTL_MS), {
+        const asset = await client.fetchAsset(store.signGetUrl(uploadId, { ttlMs: UPLOAD_READ_TTL_MS }).url, {
             maxBytes: MAX_RECEIPT_BYTES,
         });
         return Uint8Array.from(asset.bytes);

package/dist/tools/batch.js

@@ -1,4 +1,5 @@
 import { registerBatchTool, registerConfirmTool } from '@chrischall/mcp-utils';
+import { EXPENSE_WRITE_ALIASES, moneyMeta, withToolMeta } from './hints.js';
 /**
  * `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).
@@ -14,9 +15,9 @@ import { registerBatchTool, registerConfirmTool } from '@chrischall/mcp-utils';
  * Registered LAST: the batch tool lists the writes registered before it.
  */
 export function registerBatchTools(server, _client) {
-    registerConfirmTool(server, { name: 'sw_confirm' });
-    registerBatchTool(server, {
+    withToolMeta(server, moneyMeta('other'), () => registerConfirmTool(server, { name: 'sw_confirm' }));
+    withToolMeta(server, moneyMeta('change', { aliases: EXPENSE_WRITE_ALIASES }), () => 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

@@ -6,6 +6,7 @@ import { buildReceiptForm, loadReceipt, receiptParam, receiptSchema, verifyRecei
 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';
+import { moneyMeta, withToolMeta, EXPENSE_WRITE_ALIASES } from './hints.js';
 /** Flattens a users array into Splitwise's flat-param JSON format. */
 export function flattenUsers(users) {
     const flat = {};
@@ -83,6 +84,7 @@ export function registerExpenseTools(server, client) {
     server.registerTool('sw_list_expenses', {
         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 },
+        _meta: moneyMeta('lookup', { aliases: ['expenses', 'shared expenses', 'what did we spend', 'bills'] }),
         inputSchema: z.object({
             view: z
                 .enum(EXPENSE_LIST_VIEWS)
@@ -189,6 +191,7 @@ export function registerExpenseTools(server, client) {
     server.registerTool('sw_get_expense', {
         description: `Get full details of a single Splitwise expense by id. ${UNTRUSTED_DESCRIPTION_SUFFIX}`,
         annotations: { readOnlyHint: true, openWorldHint: true },
+        _meta: moneyMeta('lookup'),
         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.',
@@ -199,7 +202,7 @@ export function registerExpenseTools(server, client) {
         const data = await client.request('GET', `/get_expense/${id}`);
         return swUntrustedResult(viewExpense(resolveView(view, SW_VIEWS), data));
     });
-    registerWrite(server, defineWrite({
+    withToolMeta(server, moneyMeta('change', { aliases: EXPENSE_WRITE_ALIASES }), () => 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({
@@ -300,8 +303,8 @@ export function registerExpenseTools(server, client) {
         execute: async ({ body, receipt }) => withPostState(await sendExpenseWrite(client, '/create_expense', body, receipt)),
         render: minifiedResult,
         produces: { expense_id: (result) => createdExpenseId(result) },
-    }));
-    registerWrite(server, defineWrite({
+    })));
+    withToolMeta(server, moneyMeta('change'), () => 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({
@@ -337,8 +340,8 @@ export function registerExpenseTools(server, client) {
         },
         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({
+    })));
+    withToolMeta(server, moneyMeta('change'), () => 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 },
@@ -363,8 +366,8 @@ export function registerExpenseTools(server, client) {
         },
         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({
+    })));
+    withToolMeta(server, moneyMeta('change'), () => 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({
@@ -382,8 +385,8 @@ export function registerExpenseTools(server, client) {
         }),
         execute: (id) => client.request('POST', `/delete_expense/${id}`),
         render: minifiedResult,
-    }));
-    registerWrite(server, defineWrite({
+    })));
+    withToolMeta(server, moneyMeta('change'), () => 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:
@@ -406,5 +409,5 @@ export function registerExpenseTools(server, client) {
         }),
         execute: async (id) => verifyRestored(client, id, await client.request('POST', `/undelete_expense/${id}`)),
         render: minifiedResult,
-    }));
+    })));
 }

package/dist/tools/friends.js

@@ -1,21 +1,33 @@
 import { z } from 'zod';
 import { PERSON_VIEW_NOTE, SW_VIEWS, viewFriends } from '../project.js';
-import { minifiedResult, pruneUndefined, resolveView, viewParam } from '@chrischall/mcp-utils';
+import { minifiedResult, pruneUndefined, resolveView } from '@chrischall/mcp-utils';
 import { CONFIRM_NOTE, confirmTokenParam, confirmWrite } from './_confirm.js';
+import { moneyMeta } from './hints.js';
+import { friendsBrief } from './_brief.js';
 export function registerFriendTools(server, client) {
     server.registerTool('sw_list_friends', {
         description: "List all Splitwise friends. Use this to resolve a friend's name to a user_id before adding them to a group or building a custom expense split. The compact default returns id, name (first_name + last_name joined), email, registration_status and any non-empty balance per friend; pass view:'full' for Splitwise's raw records, which keep first_name and last_name separate.",
         annotations: { readOnlyHint: true, openWorldHint: true },
+        _meta: moneyMeta('whats-due', {
+            canonical: true,
+            aliases: ['what do i owe', 'who owes me', 'balances', 'owe', 'settle up', 'splitwise', 'iou', 'debts'],
+        }),
         inputSchema: z.object({
-            view: viewParam(SW_VIEWS, { note: PERSON_VIEW_NOTE }),
+            view: z
+                .enum([...SW_VIEWS, 'brief'])
+                .describe(`Response shape. ${PERSON_VIEW_NOTE} "brief" answers "what do I owe / who owes me": one line per friend with an outstanding balance (name — no date — "owes you <amount>" or "you owe <amount>"), inside the untrusted-data envelope, then a "-- N settled up" note; "-- none" when nothing is owed either way.`)
+                .optional(),
         }),
     }, async ({ view }) => {
         const data = await client.request('GET', '/get_friends');
+        if (view === 'brief')
+            return friendsBrief(data);
         return minifiedResult(viewFriends(resolveView(view, SW_VIEWS), data));
     });
     server.registerTool('sw_create_friend', {
         description: `Add a Splitwise friend by email (sends them an invite). ${CONFIRM_NOTE}`,
         annotations: { readOnlyHint: false, destructiveHint: true, openWorldHint: true },
+        _meta: moneyMeta('change'),
         inputSchema: z.object({
             user_email: z.string().describe('Email of the user to add as a friend'),
             user_first_name: z.string().describe('First name of the user').optional(),
@@ -44,6 +56,7 @@ export function registerFriendTools(server, client) {
     server.registerTool('sw_delete_friend', {
         description: `Remove a Splitwise friendship by user id. ${CONFIRM_NOTE}`,
         annotations: { readOnlyHint: false, destructiveHint: true, openWorldHint: true },
+        _meta: moneyMeta('change'),
         inputSchema: z.object({
             id: z.number().describe('User ID of the friend to remove'),
             confirmToken: confirmTokenParam,

package/dist/tools/groups.js

@@ -2,10 +2,12 @@ import { z } from 'zod';
 import { SW_VIEWS, viewGroup, viewGroups } from '../project.js';
 import { minifiedResult, pruneUndefined, resolveView, viewParam } from '@chrischall/mcp-utils';
 import { CONFIRM_NOTE, confirmTokenParam, confirmWrite } from './_confirm.js';
+import { moneyMeta } from './hints.js';
 export function registerGroupTools(server, client) {
     server.registerTool('sw_list_groups', {
         description: 'List all Splitwise groups the current user belongs to. Returns id, name, and members for each group. Use this to resolve a group name to its id.',
         annotations: { readOnlyHint: true, openWorldHint: true },
+        _meta: moneyMeta('lookup', { aliases: ['splitwise groups', 'shared groups', 'house', 'trip'] }),
         inputSchema: z.object({
             view: viewParam(SW_VIEWS, {
                 note: 'compact drops the avatar/cover-photo URLs (60% of a live 51-group response, which does not fit in a tool result at all) and the whiteboard/reminder settings; "full" returns Splitwise\'s whole records.',
@@ -18,6 +20,7 @@ export function registerGroupTools(server, client) {
     server.registerTool('sw_get_group', {
         description: 'Get details of a single Splitwise group including all members and balances.',
         annotations: { readOnlyHint: true, openWorldHint: true },
+        _meta: moneyMeta('lookup', { aliases: ['group balance', 'who owes whom'] }),
         inputSchema: z.object({
             view: viewParam(SW_VIEWS, {
                 note: 'compact drops the avatar/cover-photo URLs (60% of a live 51-group response, which does not fit in a tool result at all) and the whiteboard/reminder settings; "full" returns Splitwise\'s whole records.',
@@ -31,6 +34,7 @@ export function registerGroupTools(server, client) {
     server.registerTool('sw_create_group', {
         description: `Create a new Splitwise group. ${CONFIRM_NOTE}`,
         annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: true },
+        _meta: moneyMeta('change'),
         inputSchema: z.object({
             name: z.string().describe('Group name'),
             group_type: z
@@ -65,6 +69,7 @@ export function registerGroupTools(server, client) {
     server.registerTool('sw_add_user_to_group', {
         description: `Add a user to a Splitwise group. Provide user_id (preferred, use sw_list_friends to resolve a name) or first_name + last_name + email to invite by email. ${CONFIRM_NOTE}`,
         annotations: { readOnlyHint: false, destructiveHint: true, openWorldHint: true },
+        _meta: moneyMeta('change'),
         inputSchema: z.object({
             group_id: z.number().describe('Group ID'),
             user_id: z.number().describe('User ID (preferred)').optional(),
@@ -104,6 +109,7 @@ export function registerGroupTools(server, client) {
     server.registerTool('sw_remove_user_from_group', {
         description: `Remove a user from a Splitwise group. ${CONFIRM_NOTE}`,
         annotations: { readOnlyHint: false, destructiveHint: true, openWorldHint: true },
+        _meta: moneyMeta('change'),
         inputSchema: z.object({
             group_id: z.number().describe('Group ID'),
             user_id: z.number().describe('User ID to remove'),
@@ -130,6 +136,7 @@ export function registerGroupTools(server, client) {
     server.registerTool('sw_delete_group', {
         description: `Soft-delete a Splitwise group. ${CONFIRM_NOTE}`,
         annotations: { readOnlyHint: false, destructiveHint: true, openWorldHint: true },
+        _meta: moneyMeta('change'),
         inputSchema: z.object({
             id: z.number().describe('Group ID to delete'),
             confirmToken: confirmTokenParam,
@@ -156,6 +163,7 @@ export function registerGroupTools(server, client) {
         // Destructive despite the delete tool being its record-level inverse:
         // the restore notifies every participant, and no later call un-sends that.
         annotations: { readOnlyHint: false, destructiveHint: true, openWorldHint: true },
+        _meta: moneyMeta('change'),
         inputSchema: z.object({
             id: z.number().describe('Group ID to restore'),
             confirmToken: confirmTokenParam,

package/dist/tools/hints.js

@@ -0,0 +1,40 @@
+// Context-group hints, published on each tool as `_meta.mint` (the mcp-host
+// context-groups contract, `mintHintSchema`). Inert data: a host that does not
+// read them sees an extra `_meta` key and nothing else. The shape is restated
+// here rather than imported — this server takes no dependency on mcp-host.
+//
+// `subject` and `when` name THIS tool's own argument names (the host fills
+// them), never values; `aliases` are the words a person says — lowercase, at
+// most 8, each at most 40 chars. Splitwise names no `subject` anywhere: one API
+// key is one account, and nothing here is a set of subjects a person would
+// name (friends and groups are counterparties, not whose-question-is-this).
+/** `_meta` for a Splitwise tool: every tool here is in the `money` group. */
+export function moneyMeta(intent, extra = {}) {
+    return { mint: { domain: 'money', intent, ...extra } };
+}
+/**
+ * Run `register` with `_meta` added to every tool it registers.
+ *
+ * For mcp-utils' `registerWrite`, `registerConfirmTool` and `registerBatchTool`,
+ * which build the `registerTool` config themselves and take no `_meta`. The SAME
+ * server object is patched (not a proxy), so registerWrite's per-server write
+ * registry — what `sw_batch` reads — still keys on the real server; the original
+ * `registerTool` is restored afterwards, even when `register` throws.
+ */
+export function withToolMeta(server, meta, register) {
+    const target = server;
+    const hadOwn = Object.prototype.hasOwnProperty.call(target, 'registerTool');
+    const original = target.registerTool;
+    target.registerTool = (name, config, ...rest) => original.call(server, name, { ...config, _meta: meta }, ...rest);
+    try {
+        register();
+    }
+    finally {
+        if (hadOwn)
+            target.registerTool = original;
+        else
+            delete target.registerTool;
+    }
+}
+/** The words a person says about a write that puts a charge on someone. */
+export const EXPENSE_WRITE_ALIASES = ['split a bill', 'add an expense', 'log an expense', 'split the cost', 'i paid for'];

package/dist/tools/receipts.js

@@ -1,6 +1,7 @@
 import { z } from 'zod';
 import { minifiedResult, imageResult, readEnvVar, resolveOutputDir, writeBinaryOutput, sniffMimeBytes, extensionForMime, } from '@chrischall/mcp-utils';
 import { UNTRUSTED_DESCRIPTION_SUFFIX, swUntrustedEnvelope } from './_untrusted.js';
+import { moneyMeta } from './hints.js';
 /** 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. */
@@ -80,6 +81,7 @@ export function registerReceiptTools(server, client) {
         // 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, openWorldHint: true },
+        _meta: moneyMeta('other', { aliases: ['receipt'] }),
         inputSchema: z.object({
             id: z.number().describe('Expense ID (the same id sw_get_expense takes)'),
             size: z

package/dist/tools/uploads.js

@@ -1,8 +1,9 @@
 import { randomUUID } from 'crypto';
 import { z } from 'zod';
 import { minifiedResult } from '@chrischall/mcp-utils';
-import { blobConfig, safeKeyName, signedPutUrl } from './_blob.js';
-import { canonicalReceiptMime, MAX_RECEIPT_BYTES } from './_receipt.js';
+import { blobStoreFromEnv } from '@chrischall/mcp-utils/export';
+import { canonicalReceiptMime, MAX_RECEIPT_BYTES, safeKeyName } from './_receipt.js';
+import { moneyMeta } from './hints.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;
 /**
@@ -17,6 +18,7 @@ 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 },
+        _meta: moneyMeta('other'),
         inputSchema: z.object({
             filename: z.string().min(1).max(200).describe('Name of the file, e.g. "receipt.jpg"'),
             content_type: z
@@ -24,14 +26,13 @@ export function registerUploadTools(server, _client) {
                 .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 cfg = blobConfig();
-        if (!cfg) {
+        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 exp = Date.now() + UPLOAD_URL_TTL_MS;
-        const uploadUrl = signedPutUrl(cfg, key, contentType, exp);
+        const { url: uploadUrl, expiresAtMs: exp } = store.signPutUrl(key, contentType, { ttlMs: UPLOAD_URL_TTL_MS });
         return minifiedResult({
             upload_id: key,
             upload_url: uploadUrl,

package/dist/tools/user.js

@@ -2,10 +2,12 @@ import { z } from 'zod';
 import { PERSON_VIEW_NOTE, SW_VIEWS, viewUser } from '../project.js';
 import { minifiedResult, pruneUndefined, resolveView, viewParam } from '@chrischall/mcp-utils';
 import { CONFIRM_NOTE, confirmTokenParam, confirmWrite } from './_confirm.js';
+import { moneyMeta } from './hints.js';
 export function registerUserTools(server, client) {
     server.registerTool('sw_get_current_user', {
         description: "Get the authenticated Splitwise user's profile. Use the returned id when building custom expense splits. The compact default returns id, name (first_name + last_name joined), email and registration_status; pass view:'full' for Splitwise's raw record, which keeps first_name and last_name separate — the form sw_update_user takes.",
         annotations: { readOnlyHint: true, openWorldHint: true },
+        _meta: moneyMeta('lookup'),
         inputSchema: z.object({
             view: viewParam(SW_VIEWS, { note: PERSON_VIEW_NOTE }),
         }),
@@ -16,6 +18,7 @@ export function registerUserTools(server, client) {
     server.registerTool('sw_get_user', {
         description: "Get another Splitwise user's profile by id. Same shape as sw_get_current_user: the compact default merges first_name/last_name into name, and view:'full' keeps them separate.",
         annotations: { readOnlyHint: true, openWorldHint: true },
+        _meta: moneyMeta('lookup'),
         inputSchema: z.object({
             view: viewParam(SW_VIEWS, { note: PERSON_VIEW_NOTE }),
             id: z.number().describe('User ID'),
@@ -27,6 +30,7 @@ export function registerUserTools(server, client) {
     server.registerTool('sw_update_user', {
         description: "Update the current user's profile fields: name, locale and default currency. id must be the current user's id. The login email and password are deliberately not settable here — account credentials are changed in the Splitwise app, not by an assistant. " + CONFIRM_NOTE,
         annotations: { readOnlyHint: false, destructiveHint: true, openWorldHint: true },
+        _meta: moneyMeta('change'),
         // No `email` / `password`: changing the login email is an account
         // takeover primitive (a password reset to the new address follows), and
         // the only gate would be a model-driven confirmation that injected text from

package/dist/tools/utilities.js

@@ -3,22 +3,32 @@ import { SW_VIEWS, viewGeneric } from '../project.js';
 import { buildQueryString, defineWrite, minifiedResult, registerWrite, resolveView, viewParam, } from '@chrischall/mcp-utils';
 import { UNTRUSTED_DESCRIPTION_SUFFIX, swUntrustedResult } from './_untrusted.js';
 import { assertNotDeleted, explainForbidden } from './_expense-state.js';
+import { moneyMeta, withToolMeta } from './hints.js';
+import { BRIEF_NOTIFICATION_CAP, notificationsBrief } from './_brief.js';
 export function registerUtilityTools(server, client) {
     server.registerTool('sw_get_notifications', {
         description: `Get recent Splitwise activity notifications for the current user. ${UNTRUSTED_DESCRIPTION_SUFFIX}`,
         annotations: { readOnlyHint: true, openWorldHint: true },
+        _meta: moneyMeta('whats-new', {
+            canonical: true,
+            aliases: ['splitwise', 'anything new', 'recent activity', 'activity', 'new expenses'],
+        }),
         inputSchema: z.object({
-            view: viewParam(SW_VIEWS, {
-                note: 'compact drops the avatar URLs; "full" returns Splitwise\'s whole record.',
-            }),
+            view: z
+                .enum([...SW_VIEWS, 'brief'])
+                .describe(`Response shape. compact (default) drops the avatar URLs; "full" returns Splitwise's whole record; "brief" is one line per notification (text — ISO date — kind, e.g. "expense added"), at most ${BRIEF_NOTIFICATION_CAP} with a "-- N of M shown" note past that, "-- none" when there is no activity.`)
+                .optional(),
         }),
     }, async ({ view }) => {
         const data = await client.request('GET', '/get_notifications');
+        if (view === 'brief')
+            return notificationsBrief(data);
         return swUntrustedResult(viewGeneric(resolveView(view, SW_VIEWS), data));
     });
     server.registerTool('sw_get_categories', {
         description: 'Get the hierarchical list of Splitwise expense categories. Use the returned id as category_id when creating expenses.',
         annotations: { readOnlyHint: true, openWorldHint: true },
+        _meta: moneyMeta('lookup'),
     }, async () => {
         const data = await client.request('GET', '/get_categories');
         return minifiedResult(data);
@@ -26,6 +36,7 @@ export function registerUtilityTools(server, client) {
     server.registerTool('sw_get_currencies', {
         description: 'Get all Splitwise-supported currency codes and units. Use the currency_code value when creating expenses in non-default currencies.',
         annotations: { readOnlyHint: true, openWorldHint: true },
+        _meta: moneyMeta('lookup'),
     }, async () => {
         const data = await client.request('GET', '/get_currencies');
         return minifiedResult(data);
@@ -33,6 +44,7 @@ export function registerUtilityTools(server, client) {
     server.registerTool('sw_get_comments', {
         description: `Get all comments on a Splitwise expense. ${UNTRUSTED_DESCRIPTION_SUFFIX}`,
         annotations: { readOnlyHint: true, openWorldHint: true },
+        _meta: moneyMeta('lookup'),
         inputSchema: z.object({
             view: viewParam(SW_VIEWS, {
                 note: 'compact drops the avatar URLs; "full" returns Splitwise\'s whole record.',
@@ -45,7 +57,7 @@ export function registerUtilityTools(server, client) {
         const data = await client.request('GET', `/get_comments${buildQueryString({ expense_id })}`);
         return swUntrustedResult(viewGeneric(resolveView(view, SW_VIEWS), data));
     });
-    registerWrite(server, defineWrite({
+    withToolMeta(server, moneyMeta('send', { aliases: ['comment on an expense'] }), () => registerWrite(server, defineWrite({
         name: 'sw_create_comment',
         description: 'Add a comment to a Splitwise expense (visible to other participants). Refused up front, naming who deleted it, if the expense is deleted — restore it with sw_undelete_expense first.',
         inputSchema: z.object({
@@ -68,8 +80,8 @@ export function registerUtilityTools(server, client) {
         },
         execute: ({ expense_id, content }) => explainForbidden(client, expense_id, () => client.request('POST', '/create_comment', { expense_id, content })),
         render: minifiedResult,
-    }));
-    registerWrite(server, defineWrite({
+    })));
+    withToolMeta(server, moneyMeta('change'), () => registerWrite(server, defineWrite({
         name: 'sw_delete_comment',
         description: 'Delete a comment by id.',
         inputSchema: z.object({
@@ -87,5 +99,5 @@ export function registerUtilityTools(server, client) {
         }),
         execute: (id) => client.request('POST', `/delete_comment/${id}`),
         render: minifiedResult,
-    }));
+    })));
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "splitwise-mcp",
-  "version": "3.5.0",
+  "version": "3.6.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>",
@@ -45,10 +45,10 @@
     "typecheck": "tsc -p tsconfig.json --noEmit"
   },
   "dependencies": {
-    "@chrischall/mcp-utils": "^3.2.0",
+    "@chrischall/mcp-utils": "^3.3.0",
     "@modelcontextprotocol/server": "^2.3.0",
     "dotenv": "^18.0.2",
-    "unpdf": "^1.8.1",
+    "unpdf": "^2.0.0",
     "zod": "^4.6.5"
   },
   "devDependencies": {