splitwise-mcp 2.0.7 → 2.0.9

package/dist/client.js

@@ -1,43 +1,27 @@
 import { dirname, join } from 'path';
 import { fileURLToPath } from 'url';
-// Load .env for local dev; silently skip if dotenv is unavailable (e.g. mcpb bundle)
-try {
-    const { config } = await import('dotenv');
-    const __dirname = dirname(fileURLToPath(import.meta.url));
-    config({ path: join(__dirname, '..', '.env'), override: false, quiet: true });
-}
-catch {
-    // not available — rely on process.env (mcpb sets credentials via mcp_config.env)
-}
-/**
- * Read an env var, trim whitespace, and treat as unset if blank or if the value
- * looks like an unsubstituted shell placeholder (e.g. `${FOO}`) — defends
- * against MCP hosts that pass .mcp.json env blocks through unexpanded.
- */
-function readVar(key) {
-    const raw = process.env[key];
-    if (typeof raw !== 'string')
-        return undefined;
-    const trimmed = raw.trim();
-    if (trimmed.length === 0)
-        return undefined;
-    if (trimmed === 'undefined' || trimmed === 'null')
-        return undefined;
-    if (/^\$\{[^}]*\}$/.test(trimmed))
-        return undefined;
-    return trimmed;
-}
+import { loadDotenvSafely, readEnvVar, createApiClient } from '@chrischall/mcp-utils';
+// Load .env for local dev; silently skip if dotenv is unavailable (e.g. mcpb
+// bundle). `loadDotenvSafely` swallows a missing dotenv module and never lets
+// .env override a host-provided value.
+const __dirname = dirname(fileURLToPath(import.meta.url));
+await loadDotenvSafely({ path: join(__dirname, '..', '.env'), override: false });
 const BASE_URL = 'https://secure.splitwise.com/api/v3.0';
+const SERVICE_NAME = 'Splitwise';
 export class SplitwiseClient {
     apiKey;
     configError;
+    api;
     /**
      * Defer the config error so the server can still start (and respond to the
      * host's install-time smoke test) when SPLITWISE_API_KEY isn't set yet.
      * Tool calls re-raise the error at request time.
      */
     constructor() {
-        const key = readVar('SPLITWISE_API_KEY');
+        // readEnvVar trims whitespace and treats blank/`undefined`/`null`/`${...}`
+        // placeholder values as unset — defends against MCP hosts that pass
+        // .mcp.json env blocks through unexpanded.
+        const key = readEnvVar('SPLITWISE_API_KEY');
         if (!key) {
             this.apiKey = null;
             this.configError = new Error('SPLITWISE_API_KEY environment variable is required');
@@ -46,6 +30,16 @@ export class SplitwiseClient {
             this.apiKey = key;
             this.configError = null;
         }
+        // `getToken` defers config errors to request time; on* handlers preserve Splitwise's documented 401/429 messages.
+        this.api = createApiClient({
+            baseUrl: BASE_URL,
+            getToken: () => this.requireKey(),
+            serviceName: SERVICE_NAME,
+            retry: { count: 1, delayMs: 2000 },
+            timeout: 30_000,
+            onUnauthorized: () => new Error('SPLITWISE_API_KEY is invalid or missing'),
+            onRateLimited: () => new Error('Rate limited by Splitwise API'),
+        });
     }
     requireKey() {
         if (this.configError)
@@ -53,32 +47,13 @@ export class SplitwiseClient {
         return this.apiKey;
     }
     async request(method, path, body) {
-        return this.doRequest(method, path, body, false);
-    }
-    async doRequest(method, path, body, isRetry) {
-        const headers = {
-            Authorization: `Bearer ${this.requireKey()}`,
-            'Content-Type': 'application/json',
-            Accept: 'application/json',
-        };
-        const response = await fetch(`${BASE_URL}${path}`, {
-            method,
-            headers,
-            ...(body !== undefined ? { body: JSON.stringify(body) } : {}),
-        });
-        if (response.status === 401) {
-            throw new Error('SPLITWISE_API_KEY is invalid or missing');
-        }
-        if (response.status === 429) {
-            if (!isRetry) {
-                await new Promise((r) => setTimeout(r, 2000));
-                return this.doRequest(method, path, body, true);
-            }
-            throw new Error('Rate limited by Splitwise API');
-        }
-        if (!response.ok) {
-            throw new Error(`Splitwise API error: ${response.status} ${response.statusText} for ${method} ${path}`);
-        }
-        return response.json();
+        return this.api.fetchJson(method, path, body !== undefined ? { body } : {});
     }
 }
+/**
+ * Module-level singleton shared by every tool module. Constructing it here (not
+ * in `index.ts`) keeps the deferred-config-error pattern: the server boots and
+ * answers the host's install-time tools/list smoke test even when the API key is
+ * absent — the error only surfaces on the first request.
+ */
+export const client = new SplitwiseClient();

package/dist/index.js

@@ -1,19 +1,24 @@
 #!/usr/bin/env node
-import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
-import { SplitwiseClient } from './client.js';
+import { runMcp } from '@chrischall/mcp-utils';
 import { registerUserTools } from './tools/user.js';
 import { registerGroupTools } from './tools/groups.js';
 import { registerFriendTools } from './tools/friends.js';
 import { registerExpenseTools } from './tools/expenses.js';
 import { registerUtilityTools } from './tools/utilities.js';
-const client = new SplitwiseClient();
-const server = new McpServer({ name: 'splitwise-mcp', version: '2.0.7' }); // x-release-please-version
-registerUserTools(server, client);
-registerGroupTools(server, client);
-registerFriendTools(server, client);
-registerExpenseTools(server, client);
-registerUtilityTools(server, client);
-console.error('[splitwise-mcp] This project was developed and is maintained by AI (Claude Sonnet 4.6). Use at your own discretion.');
-const transport = new StdioServerTransport();
-await server.connect(transport);
+// The Splitwise client is a module-level singleton (imported by each tool
+// module) that defers its config error to the first request. That preserves the
+// deferred-config-error pattern: the server boots and answers the host's
+// install-time tools/list smoke test even when SPLITWISE_API_KEY is absent —
+// the configuration error only surfaces on the first tool call.
+await runMcp({
+    name: 'splitwise-mcp',
+    version: '2.0.9', // x-release-please-version
+    banner: '[splitwise-mcp] This project was developed and is maintained by AI (Claude Sonnet 4.6). Use at your own discretion.',
+    tools: [
+        registerUserTools,
+        registerGroupTools,
+        registerFriendTools,
+        registerExpenseTools,
+        registerUtilityTools,
+    ],
+});

package/dist/tools/expenses.js

@@ -1,4 +1,6 @@
 import { z } from 'zod';
+import { textResult, buildQueryString } from '@chrischall/mcp-utils';
+import { client } from '../client.js';
 /** Flattens a users array into Splitwise's flat-param JSON format. */
 export function flattenUsers(users) {
     const flat = {};
@@ -28,7 +30,7 @@ const userShareSchema = z.object({
     paid_share: z.string().describe('Amount this user paid, e.g. "25.00"'),
     owed_share: z.string().describe('Amount this user owes, e.g. "12.50"'),
 });
-export function registerExpenseTools(server, client) {
+export function registerExpenseTools(server) {
     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.',
         annotations: { readOnlyHint: true },
@@ -43,16 +45,18 @@ export function registerExpenseTools(server, client) {
             offset: z.number().describe('Pagination offset').optional(),
         },
     }, async (args) => {
-        const params = new URLSearchParams();
-        const filters = ['group_id', 'friend_id', 'dated_after', 'dated_before', 'updated_after', 'updated_before', 'limit', 'offset'];
-        for (const key of filters) {
-            const val = args[key];
-            if (val !== undefined)
-                params.append(key, String(val));
-        }
-        const qs = params.toString();
-        const data = await client.request('GET', qs ? `/get_expenses?${qs}` : '/get_expenses');
-        return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
+        const qs = buildQueryString({
+            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 data = await client.request('GET', `/get_expenses${qs}`);
+        return textResult(data);
     });
     server.registerTool('sw_get_expense', {
         description: 'Get full details of a single Splitwise expense by id.',
@@ -62,7 +66,7 @@ export function registerExpenseTools(server, client) {
         },
     }, async ({ id }) => {
         const data = await client.request('GET', `/get_expense/${id}`);
-        return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
+        return textResult(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.',
@@ -80,7 +84,7 @@ export function registerExpenseTools(server, client) {
     }, async (args) => {
         const body = buildExpenseBody(args);
         const data = await client.request('POST', '/create_expense', body);
-        return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
+        return textResult(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).',
@@ -99,7 +103,7 @@ export function registerExpenseTools(server, client) {
         const { expense_id } = args;
         const body = buildExpenseBody(args);
         const data = await client.request('POST', `/update_expense/${expense_id}`, body);
-        return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
+        return textResult(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.',
@@ -109,7 +113,7 @@ export function registerExpenseTools(server, client) {
         },
     }, async ({ id }) => {
         const data = await client.request('POST', `/delete_expense/${id}`);
-        return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
+        return textResult(data);
     });
     server.registerTool('sw_undelete_expense', {
         description: 'Restore a soft-deleted Splitwise expense.',
@@ -118,6 +122,6 @@ export function registerExpenseTools(server, client) {
         },
     }, async ({ id }) => {
         const data = await client.request('POST', `/undelete_expense/${id}`);
-        return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
+        return textResult(data);
     });
 }

package/dist/tools/friends.js

@@ -1,11 +1,13 @@
 import { z } from 'zod';
-export function registerFriendTools(server, client) {
+import { textResult } from '@chrischall/mcp-utils';
+import { client } from '../client.js';
+export function registerFriendTools(server) {
     server.registerTool('sw_list_friends', {
         description: "List all Splitwise friends with their id, first_name, last_name, and email. Use this to resolve a friend's name to a user_id before adding them to a group or building a custom expense split.",
         annotations: { readOnlyHint: true },
     }, async () => {
         const data = await client.request('GET', '/get_friends');
-        return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
+        return textResult(data);
     });
     server.registerTool('sw_create_friend', {
         description: 'Add a Splitwise friend by email.',
@@ -21,7 +23,7 @@ export function registerFriendTools(server, client) {
         if (user_last_name !== undefined)
             body.user_last_name = user_last_name;
         const data = await client.request('POST', '/create_friend', body);
-        return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
+        return textResult(data);
     });
     server.registerTool('sw_delete_friend', {
         description: 'Remove a Splitwise friendship by user id.',
@@ -31,6 +33,6 @@ export function registerFriendTools(server, client) {
         },
     }, async ({ id }) => {
         const data = await client.request('POST', `/delete_friend/${id}`);
-        return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
+        return textResult(data);
     });
 }

package/dist/tools/groups.js

@@ -1,11 +1,13 @@
 import { z } from 'zod';
-export function registerGroupTools(server, client) {
+import { textResult } from '@chrischall/mcp-utils';
+import { client } from '../client.js';
+export function registerGroupTools(server) {
     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 },
     }, async () => {
         const data = await client.request('GET', '/get_groups');
-        return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
+        return textResult(data);
     });
     server.registerTool('sw_get_group', {
         description: 'Get details of a single Splitwise group including all members and balances.',
@@ -15,7 +17,7 @@ export function registerGroupTools(server, client) {
         },
     }, async ({ id }) => {
         const data = await client.request('GET', `/get_group/${id}`);
-        return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
+        return textResult(data);
     });
     server.registerTool('sw_create_group', {
         description: 'Create a new Splitwise group.',
@@ -31,7 +33,7 @@ export function registerGroupTools(server, client) {
         if (simplify_by_default !== undefined)
             body.simplify_by_default = simplify_by_default;
         const data = await client.request('POST', '/create_group', body);
-        return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
+        return textResult(data);
     });
     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.",
@@ -54,7 +56,7 @@ export function registerGroupTools(server, client) {
             body = { group_id, first_name, last_name, email };
         }
         const data = await client.request('POST', '/add_user_to_group', body);
-        return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
+        return textResult(data);
     });
     server.registerTool('sw_remove_user_from_group', {
         description: 'Remove a user from a Splitwise group.',
@@ -64,7 +66,7 @@ export function registerGroupTools(server, client) {
         },
     }, async ({ group_id, user_id }) => {
         const data = await client.request('POST', '/remove_user_from_group', { group_id, user_id });
-        return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
+        return textResult(data);
     });
     server.registerTool('sw_delete_group', {
         description: 'Soft-delete a Splitwise group.',
@@ -74,7 +76,7 @@ export function registerGroupTools(server, client) {
         },
     }, async ({ id }) => {
         const data = await client.request('POST', `/delete_group/${id}`);
-        return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
+        return textResult(data);
     });
     server.registerTool('sw_undelete_group', {
         description: 'Restore a soft-deleted Splitwise group.',
@@ -83,6 +85,6 @@ export function registerGroupTools(server, client) {
         },
     }, async ({ id }) => {
         const data = await client.request('POST', `/undelete_group/${id}`);
-        return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
+        return textResult(data);
     });
 }

package/dist/tools/user.js

@@ -1,11 +1,13 @@
 import { z } from 'zod';
-export function registerUserTools(server, client) {
+import { textResult } from '@chrischall/mcp-utils';
+import { client } from '../client.js';
+export function registerUserTools(server) {
     server.registerTool('sw_get_current_user', {
         description: "Get the authenticated Splitwise user's profile (id, first_name, last_name, email). Use the returned id when building custom expense splits.",
         annotations: { readOnlyHint: true },
     }, async () => {
         const data = await client.request('GET', '/get_current_user');
-        return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
+        return textResult(data);
     });
     server.registerTool('sw_get_user', {
         description: "Get another Splitwise user's profile by id.",
@@ -15,7 +17,7 @@ export function registerUserTools(server, client) {
         },
     }, async ({ id }) => {
         const data = await client.request('GET', `/get_user/${id}`);
-        return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
+        return textResult(data);
     });
     server.registerTool('sw_update_user', {
         description: "Update the current user's profile fields. id must be the current user's id.",
@@ -43,6 +45,6 @@ export function registerUserTools(server, client) {
         if (default_currency !== undefined)
             body.default_currency = default_currency;
         const data = await client.request('POST', `/update_user/${id}`, body);
-        return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
+        return textResult(data);
     });
 }

package/dist/tools/utilities.js

@@ -1,25 +1,27 @@
 import { z } from 'zod';
-export function registerUtilityTools(server, client) {
+import { textResult, buildQueryString } from '@chrischall/mcp-utils';
+import { client } from '../client.js';
+export function registerUtilityTools(server) {
     server.registerTool('sw_get_notifications', {
         description: 'Get recent Splitwise activity notifications for the current user.',
         annotations: { readOnlyHint: true },
     }, async () => {
         const data = await client.request('GET', '/get_notifications');
-        return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
+        return textResult(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 },
     }, async () => {
         const data = await client.request('GET', '/get_categories');
-        return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
+        return textResult(data);
     });
     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 },
     }, async () => {
         const data = await client.request('GET', '/get_currencies');
-        return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
+        return textResult(data);
     });
     server.registerTool('sw_get_comments', {
         description: 'Get all comments on a Splitwise expense.',
@@ -28,8 +30,10 @@ export function registerUtilityTools(server, client) {
             expense_id: z.number().describe('Expense ID to get comments for'),
         },
     }, async ({ expense_id }) => {
-        const data = await client.request('GET', `/get_comments?expense_id=${expense_id}`);
-        return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
+        // buildQueryString percent-encodes the value — defense-in-depth against
+        // query-param injection (already constrained to a number by the schema).
+        const data = await client.request('GET', `/get_comments${buildQueryString({ expense_id })}`);
+        return textResult(data);
     });
     server.registerTool('sw_create_comment', {
         description: 'Add a comment to a Splitwise expense.',
@@ -39,7 +43,7 @@ export function registerUtilityTools(server, client) {
         },
     }, async ({ expense_id, content }) => {
         const data = await client.request('POST', '/create_comment', { expense_id, content });
-        return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
+        return textResult(data);
     });
     server.registerTool('sw_delete_comment', {
         description: 'Delete a comment by id.',
@@ -49,6 +53,6 @@ export function registerUtilityTools(server, client) {
         },
     }, async ({ id }) => {
         const data = await client.request('POST', `/delete_comment/${id}`);
-        return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
+        return textResult(data);
     });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "splitwise-mcp",
-  "version": "2.0.7",
+  "version": "2.0.9",
   "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>",
@@ -43,6 +43,7 @@
     "test:coverage": "vitest run --coverage"
   },
   "dependencies": {
+    "@chrischall/mcp-utils": "^0.7.0",
     "@modelcontextprotocol/sdk": "^1.29.0",
     "dotenv": "^17.4.0",
     "zod": "^4.4.2"

package/server.json

@@ -6,12 +6,12 @@
     "url": "https://github.com/chrischall/splitwise-mcp",
     "source": "github"
   },
-  "version": "2.0.7",
+  "version": "2.0.9",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "splitwise-mcp",
-      "version": "2.0.7",
+      "version": "2.0.9",
       "transport": {
         "type": "stdio"
       },