splitwise-mcp 3.5.1 → 3.7.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.1', // x-release-please-version
+    version: '3.7.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

@@ -33,7 +33,7 @@ export const receiptSchema = z
     upload_id: z
         .string()
         .min(1)
-        .describe('The upload_id from sw_get_upload_url, after the file was PUT to its upload_url. The way to send a full-size file to the hosted server without base64.')
+        .describe('The upload_id from sw_get_upload_url, after the file was PUT to its upload_url. The way to send a full-size file to the hosted server without base64. Single use: the upload is deleted once Splitwise has the receipt (the reply says upload_deleted); a failed or declined write keeps it, so the same upload_id can be retried.')
         .optional(),
     filename: z.string().min(1).max(200).describe('Name to store the file under, e.g. "receipt.pdf".'),
     mime_type: z
@@ -146,7 +146,7 @@ async function readUpload(uploadId, client) {
     }
     catch (err) {
         if (err instanceof ApiError && (err.status === 404 || err.status === 403)) {
-            throw new Error(`No upload found for receipt.upload_id ${uploadId} — the PUT may not have run, failed, or the upload expired. Get a fresh link with sw_get_upload_url and upload the file again.`);
+            throw new Error(`No upload found for receipt.upload_id ${uploadId} — the PUT may not have run, failed, the upload expired, or it was already used (an upload is deleted once its receipt is attached). Get a fresh link with sw_get_upload_url and upload the file again.`);
         }
         if (err.kind === 'too_large') {
             throw new Error(`The uploaded receipt is over the ${LIMIT_LABEL} limit (${MAX_RECEIPT_BYTES} bytes)`);
@@ -198,8 +198,40 @@ export async function loadReceipt(input, client) {
         filename,
         mimeType: type.mime,
         summary: { filename, mime_type: type.mime, bytes: bytes.length, sha256 },
+        ...(input.upload_id !== undefined ? { uploadId: input.upload_id } : {}),
     };
 }
+/** A delete is housekeeping after a write that already landed: never let it hold the reply for long. */
+const UPLOAD_DELETE_TIMEOUT_MS = 10_000;
+/**
+ * Delete the blob-store copy of a receipt Splitwise now holds. Call it only
+ * after the write SUCCEEDED (and the file was verified stored): the preview may
+ * still be declined, and a failed write must leave the upload_id retryable.
+ *
+ * Never throws. The expense is already written, so an error here would read as
+ * a failed write and invite a duplicate; a delete that fails is reported, and
+ * the store's retention prune reclaims the object. A 404 means it is already
+ * gone (e.g. two ops in one batch used the same upload), which is the goal.
+ * Not `BlobStore.consume`: the read happens in `plan` (before the gate) and
+ * the write in `execute`, possibly calls apart, so there is no one callback
+ * to wrap.
+ */
+export async function releaseUpload(receipt) {
+    if (receipt.uploadId === undefined)
+        return {};
+    try {
+        const store = blobStoreFromEnv();
+        if (!store)
+            throw new Error('no blob store is configured on this server');
+        await store.delete(receipt.uploadId, { timeoutMs: UPLOAD_DELETE_TIMEOUT_MS });
+        return { upload_deleted: true };
+    }
+    catch (err) {
+        if (err.status === 404)
+            return { upload_deleted: true };
+        return { upload_deleted: false, upload_delete_error: err instanceof Error ? err.message : String(err) };
+    }
+}
 /**
  * Build the multipart body Splitwise takes when an expense carries a file:
  * every expense field as a form field (the same flat `users__N__*` keys the

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

@@ -2,10 +2,11 @@ import { z } from 'zod';
 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 { buildReceiptForm, loadReceipt, receiptParam, receiptSchema, releaseUpload, 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';
+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 = {};
@@ -62,13 +63,18 @@ function buildExpenseBody(args) {
  * Send a create/update. With a receipt the whole expense goes as multipart
  * (Splitwise only takes a file that way) and the response must show the file
  * stored; without one it stays JSON and the response passes through, exactly
- * as before.
+ * as before. A receipt that came from `upload_id` is deleted from the blob
+ * store once Splitwise has it (`upload_deleted`), here in `execute` — so a
+ * direct call, `sw_confirm` and `sw_batch` all clean up, and the preview never
+ * does.
  */
 async function sendExpenseWrite(client, path, body, receipt, expenseId) {
     if (!receipt)
         return client.request('POST', path, body);
     const data = await client.requestMultipart('POST', path, buildReceiptForm(body, receipt));
-    return verifyReceiptStored(data, expenseId);
+    // Only past verification: a dropped file keeps the upload for sw_attach_receipt.
+    const stored = verifyReceiptStored(data, expenseId);
+    return { ...stored, ...(await releaseUpload(receipt)) };
 }
 /** The body the confirmation preview shows: the fields, plus the file's identity in place of its bytes. */
 function previewBody(body, receipt) {
@@ -83,6 +89,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 +196,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 +207,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 +308,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,10 +345,10 @@ 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.',
+        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. An upload_id is deleted from the upload store once the file is stored (upload_deleted in the reply).',
         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'),
@@ -363,8 +371,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 +390,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 +414,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

@@ -3,6 +3,7 @@ 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';
+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;
 /**
@@ -15,8 +16,9 @@ export const UPLOAD_URL_TTL_MS = 10 * 60 * 1000;
  */
 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.',
+        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. The upload is deleted from this server once the receipt is attached (a failed write keeps it for a retry), so each upload_id is used once. 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

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,
-    }));
+    })));
 }