splitwise-mcp 2.2.2 → 2.3.0

package/.claude-plugin/marketplace.json

@@ -7,7 +7,7 @@
   },
   "metadata": {
     "description": "MCP server for Splitwise — natural-language expense and group management via the Splitwise API",
-    "version": "2.2.2"
+    "version": "2.3.0"
   },
   "plugins": [
     {
@@ -15,7 +15,7 @@
       "displayName": "Splitwise",
       "source": "./",
       "description": "MCP server for Splitwise — manage expenses, groups, and friends via natural language",
-      "version": "2.2.2",
+      "version": "2.3.0",
       "author": {
         "name": "Chris Hall"
       },

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "splitwise-mcp",
   "displayName": "Splitwise",
-  "version": "2.2.2",
+  "version": "2.3.0",
   "description": "MCP server for Splitwise — natural-language expense and group management via the Splitwise API",
   "author": {
     "name": "Chris Hall",

package/README.md

@@ -124,6 +124,7 @@ Add to Claude Desktop config:
 | Tool | What it does |
 |------|-------------|
 | `sw_get_current_user` | Get the authenticated user's profile |
+| `sw_healthcheck` | Verify the API key and Splitwise reachability; says which of the two failed |
 | `sw_get_user` | Get another user's profile by ID |
 | `sw_update_user` | Update the current user's profile fields |
 
@@ -202,6 +203,7 @@ src/
   index.ts          MCP server entry point
   tools/
     user.ts         sw_get_current_user, sw_get_user
+    healthcheck.ts  sw_healthcheck
     groups.ts       group CRUD and membership
     friends.ts      friend list and management
     expenses.ts     expense CRUD

package/dist/bundle.js

@@ -70944,6 +70944,11 @@ function truncateErrorMessage(text, max = DEFAULT_ERROR_MESSAGE_MAX) {
     return redacted;
   return `${redacted.slice(0, max)}\u2026 [truncated]`;
 }
+function messageOf(err) {
+  if (err instanceof Error)
+    return err.message;
+  return String(err);
+}
 
 // node_modules/@chrischall/mcp-utils/dist/response/index.js
 function textResult(data) {
@@ -71380,6 +71385,8 @@ function redactAssetQuery(err, search) {
 }
 var SplitwiseClient = class {
   apiKey;
+  /** Which source supplied the API key — a LABEL, never the value. */
+  credentialSource;
   configError;
   api;
   /** Per-origin clients for asset hosts, built on first use by `fetchAsset`. */
@@ -71395,7 +71402,9 @@ var SplitwiseClient = class {
    * byte-for-byte identical behaviour.
    */
   constructor(opts) {
-    const key = opts?.apiKey ?? readEnvVar("SPLITWISE_API_KEY");
+    const injected = opts?.apiKey;
+    const key = injected ?? readEnvVar("SPLITWISE_API_KEY");
+    this.credentialSource = !key ? null : injected !== void 0 ? "injected" : "env";
     if (!key) {
       this.apiKey = null;
       this.configError = new Error("SPLITWISE_API_KEY environment variable is required");
@@ -71405,6 +71414,14 @@ var SplitwiseClient = class {
     }
     this.api = this.buildApiClient(BASE_URL, true);
   }
+  /**
+   * Which source supplied the API key, for `sw_healthcheck`. Returns a LABEL
+   * or `null` — deliberately never the key, since the healthcheck result is
+   * the thing people paste into a chat when something is broken.
+   */
+  describeCredential() {
+    return { source: this.credentialSource };
+  }
   /**
    * One API client per origin, sharing the fleet's retry/timeout/error policy.
    * `authenticated` decides whether the API key is attached: `getToken` defers
@@ -71514,6 +71531,134 @@ function registerUserTools(server, client2) {
   });
 }
 
+// node_modules/@chrischall/mcp-utils/dist/healthcheck/index.js
+function statusOf(err) {
+  if (typeof err !== "object" || err === null)
+    return void 0;
+  const s2 = err.status ?? err.statusCode;
+  return typeof s2 === "number" ? s2 : void 0;
+}
+function credentialHint(arm, prefix, hostLabel, source) {
+  switch (arm) {
+    case "ok":
+      return `Credential from '${source}' works: ${hostLabel} accepted an authenticated request. If a real tool still fails, the problem is that tool, not auth.`;
+    case "no_credential":
+      return `No credential resolved. Nothing was available to authenticate with \u2014 sign in and reconnect the connector so ${prefix} receives a token, or set the documented environment variable.`;
+    case "credential_rejected":
+      return `${hostLabel} rejected the credential from '${source}'. It is present but no longer valid \u2014 most often expired or revoked upstream. Re-authenticate and reconnect; retrying will not fix it.`;
+    case "timeout":
+      return `The credential from '${source}' resolved, but ${hostLabel} did not answer in time. Usually transient \u2014 retry. If it persists, ${hostLabel} is slow or unreachable from here.`;
+    case "http":
+      return `${hostLabel} answered with an error status that is not an auth rejection. That is USUALLY a ${hostLabel}-side problem rather than an auth one \u2014 but a 404 here more often means the probe path is wrong than that ${hostLabel} is broken, so check error.message and probe.url before concluding anything about the credential.`;
+    case "transport":
+      return `Could not reach ${hostLabel} at all. Check network egress; the credential itself was never judged.`;
+    default:
+      return `Unexpected failure \u2014 see error.message.`;
+  }
+}
+function registerCredentialHealthcheckTool(args) {
+  const { server, prefix, hostLabel, probePath, resolveCredential, probeFn, classifyThrown, hints } = args;
+  const probeUrl = probePath ? `https://${hostLabel}${probePath}` : void 0;
+  server.registerTool(`${prefix}_healthcheck`, {
+    title: "Verify credentials and upstream reachability",
+    description: `Resolves the credential the way real tools do, then makes one authenticated request to ${hostLabel}. Reports which source supplied the credential, whether ${hostLabel} accepted it, the round-trip time, and a plain-English hint distinguishing 'no credential' from 'credential rejected' from 'a ${hostLabel}-side problem'. Call this when a real tool fails and you want to know which hop broke. Read-only; never returns the credential itself.`,
+    annotations: {
+      title: "Verify credentials and upstream reachability",
+      readOnlyHint: true,
+      idempotentHint: true,
+      openWorldHint: true
+    },
+    inputSchema: {}
+  }, async () => {
+    let probeStarted = 0;
+    let state;
+    try {
+      state = await resolveCredential();
+    } catch (e2) {
+      const result2 = {
+        ok: false,
+        credential: { source: null, resolved: false },
+        // No `url`: nothing was probed, and naming one implies it was tried.
+        probe: { elapsed_ms: 0 },
+        error: { kind: "no_credential", message: truncateErrorMessage(messageOf(e2)) },
+        hint: hints?.no_credential ?? credentialHint("no_credential", prefix, hostLabel, null)
+      };
+      return { content: [{ type: "text", text: JSON.stringify(result2, null, 2) }] };
+    }
+    const credential = {
+      source: state.source,
+      resolved: state.source !== null,
+      ...state.detail !== void 0 ? { detail: state.detail } : {}
+    };
+    if (!credential.resolved) {
+      const result2 = {
+        ok: false,
+        credential,
+        probe: { elapsed_ms: 0 },
+        error: { kind: "no_credential", message: "no credential source resolved" },
+        hint: hints?.no_credential ?? credentialHint("no_credential", prefix, hostLabel, null)
+      };
+      return { content: [{ type: "text", text: JSON.stringify(result2, null, 2) }] };
+    }
+    let arm = "ok";
+    let error51;
+    let status;
+    let customHint;
+    probeStarted = Date.now();
+    try {
+      await probeFn();
+    } catch (e2) {
+      status = statusOf(e2);
+      const aborted2 = e2 instanceof Error && e2.name === "AbortError";
+      arm = status === 401 || status === 403 ? "credential_rejected" : status !== void 0 ? "http" : aborted2 || /timeout|timed out|ETIMEDOUT/i.test(messageOf(e2)) ? "timeout" : /fetch failed|ENOTFOUND|ECONNREFUSED|ECONNRESET|network/i.test(messageOf(e2)) ? "transport" : "unknown";
+      let kind = arm;
+      let detail;
+      const custom2 = classifyThrown?.(e2);
+      if (custom2) {
+        kind = custom2.kind;
+        customHint = custom2.hint;
+        detail = custom2.detail;
+      }
+      error51 = {
+        kind,
+        // Redacted AND bounded before it reaches the result: an upstream
+        // failure routinely quotes what it was sent, and a healthcheck is
+        // the tool people paste into a chat when something is broken.
+        message: truncateErrorMessage(messageOf(e2)),
+        ...detail !== void 0 ? { detail } : {}
+      };
+    }
+    const result = {
+      ok: error51 === void 0,
+      credential,
+      probe: {
+        ...probeUrl ? { url: probeUrl } : {},
+        elapsed_ms: Date.now() - probeStarted,
+        ...status !== void 0 ? { status } : {}
+      },
+      ...error51 ? { error: error51 } : {},
+      hint: customHint ?? hints?.[arm] ?? credentialHint(arm, prefix, hostLabel, state.source)
+    };
+    return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+  });
+}
+
+// src/tools/healthcheck.ts
+function registerHealthcheckTools(server, client2) {
+  registerCredentialHealthcheckTool({
+    server,
+    prefix: "sw",
+    hostLabel: "secure.splitwise.com",
+    probePath: "/api/v3.0/get_current_user",
+    resolveCredential: async () => client2.describeCredential(),
+    probeFn: () => client2.request("GET", "/get_current_user"),
+    hints: {
+      no_credential: "No Splitwise API key resolved. Set SPLITWISE_API_KEY, or reconnect the connector so it supplies one.",
+      credential_rejected: "Splitwise rejected the API key. Generate a new one at https://secure.splitwise.com/apps and update SPLITWISE_API_KEY (or reconnect the connector)."
+    }
+  });
+}
+
 // src/tools/groups.ts
 function registerGroupTools(server, client2) {
   server.registerTool("sw_list_groups", {
@@ -72010,12 +72155,13 @@ function registerUtilityTools(server, client2) {
 // src/index.ts
 await runMcp({
   name: "splitwise-mcp",
-  version: "2.2.2",
+  version: "2.3.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: [
     registerUserTools,
+    registerHealthcheckTools,
     registerGroupTools,
     registerFriendTools,
     registerExpenseTools,

package/dist/client.js

@@ -61,6 +61,8 @@ function redactAssetQuery(err, search) {
 }
 export class SplitwiseClient {
     apiKey;
+    /** Which source supplied the API key — a LABEL, never the value. */
+    credentialSource;
     configError;
     api;
     /** Per-origin clients for asset hosts, built on first use by `fetchAsset`. */
@@ -80,7 +82,16 @@ export class SplitwiseClient {
         // back to the env var. 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 = opts?.apiKey ?? readEnvVar('SPLITWISE_API_KEY');
+        const injected = opts?.apiKey;
+        const key = injected ?? readEnvVar('SPLITWISE_API_KEY');
+        // Which source supplied it, for `sw_healthcheck`. Derived from the SAME
+        // `key` and `injected` bindings the resolution above uses, so the two
+        // cannot disagree. An earlier version re-tested `opts?.apiKey` for
+        // TRUTHINESS while the resolution used `??`: an injected empty string is
+        // not nullish, so `key` became `''` and the client reported a config error
+        // while the source said `env` — the healthcheck naming a source the client
+        // had not used.
+        this.credentialSource = !key ? null : injected !== undefined ? 'injected' : 'env';
         if (!key) {
             this.apiKey = null;
             this.configError = new Error('SPLITWISE_API_KEY environment variable is required');
@@ -91,6 +102,14 @@ export class SplitwiseClient {
         }
         this.api = this.buildApiClient(BASE_URL, true);
     }
+    /**
+     * Which source supplied the API key, for `sw_healthcheck`. Returns a LABEL
+     * or `null` — deliberately never the key, since the healthcheck result is
+     * the thing people paste into a chat when something is broken.
+     */
+    describeCredential() {
+        return { source: this.credentialSource };
+    }
     /**
      * One API client per origin, sharing the fleet's retry/timeout/error policy.
      * `authenticated` decides whether the API key is attached: `getToken` defers

package/dist/index.js

@@ -2,6 +2,7 @@
 import { runMcp } from '@chrischall/mcp-utils';
 import { client } from './client.js';
 import { registerUserTools } from './tools/user.js';
+import { registerHealthcheckTools } from './tools/healthcheck.js';
 import { registerGroupTools } from './tools/groups.js';
 import { registerFriendTools } from './tools/friends.js';
 import { registerExpenseTools } from './tools/expenses.js';
@@ -18,11 +19,12 @@ import { registerUtilityTools } from './tools/utilities.js';
 // client into the same registrars instead of this singleton.
 await runMcp({
     name: 'splitwise-mcp',
-    version: '2.2.2', // x-release-please-version
+    version: '2.3.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: [
         registerUserTools,
+        registerHealthcheckTools,
         registerGroupTools,
         registerFriendTools,
         registerExpenseTools,

package/dist/tools/healthcheck.js

@@ -0,0 +1,28 @@
+import { registerCredentialHealthcheckTool } from '@chrischall/mcp-utils/healthcheck';
+/**
+ * Register `sw_healthcheck` — resolves the API key the way real tools do, then
+ * makes one authenticated call to `/get_current_user`.
+ *
+ * Splitwise has no browser bridge, so "health" here is entirely about the
+ * credential: whether one resolved at all, and whether Splitwise still accepts
+ * it. Those are different problems with different fixes and, without this,
+ * both surface as the same opaque tool error.
+ *
+ * `/get_current_user` is the probe because it is the cheapest endpoint that
+ * REQUIRES auth — an unauthenticated endpoint would pass while the key was
+ * expired, which is the failure most worth catching.
+ */
+export function registerHealthcheckTools(server, client) {
+    registerCredentialHealthcheckTool({
+        server,
+        prefix: 'sw',
+        hostLabel: 'secure.splitwise.com',
+        probePath: '/api/v3.0/get_current_user',
+        resolveCredential: async () => client.describeCredential(),
+        probeFn: () => client.request('GET', '/get_current_user'),
+        hints: {
+            no_credential: 'No Splitwise API key resolved. Set SPLITWISE_API_KEY, or reconnect the connector so it supplies one.',
+            credential_rejected: 'Splitwise rejected the API key. Generate a new one at https://secure.splitwise.com/apps and update SPLITWISE_API_KEY (or reconnect the connector).',
+        },
+    });
+}

package/mint.yaml

@@ -13,6 +13,15 @@ env:
       https://secure.splitwise.com/apps/register and copy its API key.
 egress:
   allow:
-    # The Splitwise REST API (https://secure.splitwise.com/api/v3.0) — the only
-    # host this server contacts.
+    # Only hosts the SERVER process actually fetches. Hosts that appear
+    # solely in a URL this server BUILDS and returns are excluded.
+    #
+    # The Splitwise REST API (https://secure.splitwise.com/api/v3.0) — every
+    # tool but sw_get_receipt talks only to this host.
     - secure.splitwise.com
+    # sw_get_receipt fetches the receipt URL the API hands back, which lives at
+    # https://www.splitwise.com/api/v4.0/expenses/{id}/receipt (checked live
+    # 2026-08-28) and 302s to the presigned S3 object below. The child's fetch
+    # follows that redirect, so each hop is its own CONNECT and must be listed.
+    - www.splitwise.com
+    - splitwise.s3.amazonaws.com

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "splitwise-mcp",
-  "version": "2.2.2",
+  "version": "2.3.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,7 +45,7 @@
     "typecheck": "tsc -p tsconfig.json --noEmit"
   },
   "dependencies": {
-    "@chrischall/mcp-utils": "^0.15.0",
+    "@chrischall/mcp-utils": "^0.19.2",
     "@modelcontextprotocol/sdk": "^1.29.0",
     "dotenv": "^17.4.0",
     "unpdf": "^1.8.1",

package/server.json

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