@blanketbyte/wise-mcp 1.1.0 → 1.1.1

package/dist/schemas.js

@@ -0,0 +1,146 @@
+import { z } from "zod";
+/**
+ * Output schemas: the shape of each tool's structuredContent. They're loose on purpose (extra keys allowed, values
+ * that come from Wise may be missing), so a new field in Wise's API can never make a tool call fail validation.
+ */
+const id = z.union([z.number(), z.string()]);
+const num = z.number().nullish();
+const str = z.string().nullish();
+const money = z.looseObject({ amount: num, currency: str });
+const profileRef = z.looseObject({ id, type: z.string() });
+const profile = z.looseObject({ id, type: z.string(), name: str });
+const recipient = z.looseObject({
+    id,
+    name: str,
+    currency: str,
+    type: str,
+    account: str.describe("Account number or IBAN, as Wise shows it"),
+    details: str,
+    owned_by_me: z.boolean().nullish(),
+    profile_id: id.nullish(),
+    active: z.boolean().nullish(),
+    profile: profileRef.optional(),
+});
+const transferShape = {
+    id,
+    created: str,
+    status: str.describe("Wise transfer status, e.g. incoming_payment_waiting, outgoing_payment_sent, cancelled"),
+    reference: str,
+    source: money.describe("Amount converted, in the source currency (excludes the fee)"),
+    target: money.describe("Amount the recipient gets"),
+    recipient_id: id.nullish(),
+};
+const quote = z.looseObject({
+    id: z.string(),
+    source: money.describe("What you pay"),
+    target: money.describe("What the recipient gets, when paid from the Wise balance"),
+    rate: num,
+    rate_type: str,
+    rate_expires: str,
+    fee: money.optional(),
+    pay_in: str,
+    pay_out: str,
+    estimated_delivery: str,
+    delivery: str,
+    notices: z.array(z.string()).optional(),
+    pay_in_options: z
+        .array(z.looseObject({ pay_in: z.string(), fee: num, target_amount: num }))
+        .optional()
+        .describe("Price per payment method, cheapest first (methods with the same price merged)"),
+});
+const pending = {
+    status: z.string().describe("awaiting_user_confirmation"),
+    summary: z.string().describe("Show this to the user before confirming"),
+    confirmation_code: z.string(),
+    expires_at: z.string(),
+};
+export const outputs = {
+    list_profiles: { profiles: z.array(profile) },
+    list_balances: {
+        balances: z.array(z.looseObject({
+            id,
+            profile: profileRef,
+            kind: z.string().describe("balance or jar"),
+            name: str,
+            currency: str,
+            amount: num.describe("Available to spend or send now; reserved money is already taken out of it"),
+            reserved: num.describe("Held for pending transactions (mostly card payments not settled yet). Already deducted from amount: not extra money"),
+            total_worth: num.describe("Only when it differs from amount, e.g. invested balances"),
+            note: str,
+        })),
+    },
+    get_transactions: {
+        profile,
+        count: z.number(),
+        transactions: z.array(z.looseObject({
+            id,
+            date: str,
+            type: str,
+            status: str,
+            title: str.describe("Merchant or counterparty"),
+            description: str,
+            direction: str.describe("in, out or neutral (between your own balances)"),
+            amount: num,
+            currency: str,
+            amount_text: str,
+            secondary_amount: money.optional(),
+            secondary_text: str,
+            resource: z.looseObject({ type: str, id: id.nullish() }).optional(),
+        })),
+        next_cursor: str,
+    },
+    list_transfers: {
+        profile,
+        total: z.number(),
+        transfers: z.array(z.looseObject({ ...transferShape, recipient_name: str })),
+        truncated: z.boolean().optional(),
+    },
+    get_transfer: {
+        ...transferShape,
+        recipient: recipient.optional(),
+        rate: num,
+        quote_id: str,
+        has_active_issues: z.boolean().nullish(),
+        raw_status: str,
+        note: str,
+    },
+    list_recipients: { count: z.number(), recipients: z.array(recipient) },
+    get_exchange_rate: { source: str, target: str, rate: num, time: str },
+    get_quote: quote.shape,
+    get_recipient_requirements: {
+        options: z.array(z.looseObject({
+            type: z.string().describe("Pass as `type` to prepare_recipient"),
+            title: str,
+            usage: str,
+            fields: z.array(z.looseObject({
+                key: z.string(),
+                name: str,
+                required: z.boolean(),
+                type: str,
+                example: str,
+                pattern: str,
+                allowed: z.array(z.looseObject({ key: id, name: str })).optional(),
+                refresh_on_change: z.boolean().optional(),
+            })),
+        })),
+    },
+    prepare_recipient: pending,
+    prepare_transfer: {
+        ...pending,
+        quote,
+        balance_check: z.string(),
+        next_step: z.string(),
+    },
+    prepare_cancel_transfer: pending,
+    confirm_action: {
+        status: z.string().describe("created_awaiting_payment, recipient_created or cancelled"),
+        summary: z.string(),
+        transfer_id: id.optional(),
+        wise_status: str,
+        recipient: recipient.optional(),
+        wise_shows_until_paid: z.string().optional(),
+        note: z.string().optional(),
+        next_step: z.string().optional(),
+    },
+    discard_action: { status: z.string().describe("discarded or not_found"), message: z.string() },
+};

package/dist/tools.js

@@ -6,8 +6,11 @@ import { config } from "./config.js";
 import { ACTIVITY_TYPES, UNPAID_PRICE_NOTE } from "./wise/service.js";
 import { WiseAccessRevokedError } from "./wise/client.js";
 import { storePending, takePending, discardPending } from "./pending.js";
+import { outputs } from "./schemas.js";
+/** Every tool returns an object: as text (for older clients) and as structuredContent matching its output schema. */
 const ok = (data) => ({
-    content: [{ type: "text", text: typeof data === "string" ? data : JSON.stringify(data, null, 2) }],
+    content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
+    structuredContent: data,
 });
 const fail = (message) => ({ content: [{ type: "text", text: message }], isError: true });
 const date = z
@@ -43,18 +46,20 @@ export function registerTools(server, wise, { sessionKey, connectionId, onRevoke
         title: "List Wise profiles",
         description: "List the Wise profiles (personal and business) this token can access, with id, type and name.",
         inputSchema: {},
+        outputSchema: outputs.list_profiles,
         annotations: READ,
-    }, async () => safe(async () => ok(await wise.listProfiles())));
+    }, async () => safe(async () => ok({ profiles: await wise.listProfiles() })));
     server.registerTool("list_balances", {
         title: "List Wise balances",
-        description: "Current balances in every currency plus Jars (savings), with amounts. Default: all profiles. " +
+        description: "Current balances in every currency plus Jars (savings). `amount` is what's available now; `reserved` (pending card payments) is already deducted from it, not extra money. Default: all profiles. " +
             "Empty balances are hidden unless include_empty is true.",
         inputSchema: {
             profile: profileArg.describe('Profile id, "personal", "business", part of the name, or "all" (default)'),
             include_empty: z.boolean().optional().describe("Also list balances with 0"),
         },
+        outputSchema: outputs.list_balances,
         annotations: READ,
-    }, async ({ profile, include_empty }) => safe(async () => ok(await wise.listBalances(await wise.resolveProfiles(profile), include_empty ?? false))));
+    }, async ({ profile, include_empty }) => safe(async () => ok({ balances: await wise.listBalances(await wise.resolveProfiles(profile), include_empty ?? false) })));
     server.registerTool("get_transactions", {
         title: "Get Wise transactions",
         description: "List activity on a Wise profile, newest first: card payments, transfers, conversions, cashback, direct debits. " +
@@ -68,7 +73,10 @@ export function registerTools(server, wise, { sessionKey, connectionId, onRevoke
                 .string()
                 .optional()
                 .describe(`One of ${Object.keys(ACTIVITY_TYPES).join(", ")}, or a raw Wise monetaryResourceType (e.g. CARD_TRANSACTION)`),
-            status: z.enum(["COMPLETED", "IN_PROGRESS", "UPCOMING", "REQUIRES_ATTENTION", "CANCELLED"]).optional(),
+            status: z
+                .enum(["COMPLETED", "IN_PROGRESS", "UPCOMING", "REQUIRES_ATTENTION", "CANCELLED"])
+                .optional()
+                .describe("Only activity in this state, e.g. UPCOMING for pending card payments"),
             since: date.optional().describe("Only on/after this date (YYYY-MM-DD or ISO timestamp)"),
             until: date.optional().describe("Only on/before this date (YYYY-MM-DD or ISO timestamp)"),
             search: z
@@ -78,6 +86,7 @@ export function registerTools(server, wise, { sessionKey, connectionId, onRevoke
             limit: z.number().int().min(1).max(500).optional().describe("Max items (default 50)"),
             cursor: z.string().optional().describe("next_cursor from a previous call"),
         },
+        outputSchema: outputs.get_transactions,
         annotations: READ,
     }, async (args) => safe(async () => {
         const profile = await wise.resolveProfile(args.profile);
@@ -100,12 +109,13 @@ export function registerTools(server, wise, { sessionKey, connectionId, onRevoke
             "Filter by date (YYYY-MM-DD), status (e.g. outgoing_payment_sent, processing, cancelled) or search (reference/recipient). Default profile: personal.",
         inputSchema: {
             profile: profileArg,
-            since: date.optional(),
-            until: date.optional(),
+            since: date.optional().describe("Only transfers created on/after this date (YYYY-MM-DD or ISO timestamp)"),
+            until: date.optional().describe("Only transfers created on/before this date (YYYY-MM-DD or ISO timestamp)"),
             status: z.string().optional().describe("Wise transfer status, e.g. outgoing_payment_sent"),
             search: z.string().optional().describe("Case-insensitive match on reference or recipient name"),
             limit: z.number().int().min(1).max(200).optional().describe("Max transfers (default 25)"),
         },
+        outputSchema: outputs.list_transfers,
         annotations: READ,
     }, async (args) => safe(async () => {
         const profile = await wise.resolveProfile(args.profile);
@@ -116,6 +126,7 @@ export function registerTools(server, wise, { sessionKey, connectionId, onRevoke
         title: "Get a Wise transfer",
         description: "Details of one transfer: amounts in both currencies, rate, reference, status, created date and recipient.",
         inputSchema: { id: z.coerce.number().int().describe("Transfer id (from list_transfers or a TRANSFER activity's resource.id)") },
+        outputSchema: outputs.get_transfer,
         annotations: READ,
     }, async ({ id }) => safe(async () => ok(await wise.getTransfer(id))));
     server.registerTool("list_recipients", {
@@ -126,6 +137,7 @@ export function registerTools(server, wise, { sessionKey, connectionId, onRevoke
             currency: currency.optional().describe("Only recipients in this currency, e.g. EUR"),
             search: z.string().optional().describe("Case-insensitive match on name or account"),
         },
+        outputSchema: outputs.list_recipients,
         annotations: READ,
     }, async ({ profile, currency, search }) => safe(async () => {
         const s = search?.trim().toLowerCase();
@@ -141,6 +153,7 @@ export function registerTools(server, wise, { sessionKey, connectionId, onRevoke
             target: currency.describe("Target currency, e.g. RON"),
             at: date.optional().describe("Historic rate at this date/time (default: now)"),
         },
+        outputSchema: outputs.get_exchange_rate,
         annotations: READ,
     }, async ({ source, target, at }) => safe(async () => ok(await wise.getRate(source, target, at))));
     if (config.WRITES_ENABLED)
@@ -159,13 +172,14 @@ function registerWriteTools(server, wise, { sessionKey, connectionId }, safe) {
         description: "Price a transfer or conversion: rate, fee, amount received and estimated delivery. Creates nothing the user sees and moves no money. " +
             "Give either send_amount (in source_currency) or receive_amount (in target_currency).",
         inputSchema: {
-            source_currency: currency,
-            target_currency: currency,
-            send_amount: z.number().positive().optional(),
-            receive_amount: z.number().positive().optional(),
+            source_currency: currency.describe("Currency you send, e.g. EUR"),
+            target_currency: currency.describe("Currency the recipient gets, e.g. RON (same as source_currency for a same-currency transfer)"),
+            send_amount: z.number().positive().optional().describe("Amount to send, in source_currency (give this or receive_amount)"),
+            receive_amount: z.number().positive().optional().describe("Amount the recipient should get, in target_currency (give this or send_amount)"),
             recipient_id: z.number().int().optional().describe("Saved recipient, for an exact price and delivery time"),
             profile: profileArg,
         },
+        outputSchema: outputs.get_quote,
         annotations: { readOnlyHint: true, openWorldHint: true },
     }, async (a) => safe(async () => {
         if (!!a.send_amount === !!a.receive_amount)
@@ -189,16 +203,17 @@ function registerWriteTools(server, wise, { sessionKey, connectionId }, safe) {
             amount: z.number().positive().optional().describe("Typical amount (default 100); some routes depend on it"),
             profile: profileArg,
         },
+        outputSchema: outputs.get_recipient_requirements,
         annotations: { readOnlyHint: true, openWorldHint: true },
     }, async (a) => safe(async () => {
         const profile = await wise.resolveProfile(a.profile);
-        return ok(await wise.recipientRequirements(profile, a.source_currency ?? a.currency, a.currency, a.amount ?? 100));
+        return ok({ options: await wise.recipientRequirements(profile, a.source_currency ?? a.currency, a.currency, a.amount ?? 100) });
     }));
     server.registerTool("prepare_recipient", {
         title: "Prepare a new Wise recipient",
         description: `Step 1 of 2 to save a new recipient. Use get_recipient_requirements first for the right \`type\` and \`details\` keys. ${TWO_STEP}`,
         inputSchema: {
-            currency,
+            currency: currency.describe("Currency of the recipient's account, e.g. EUR"),
             type: z.string().min(1).describe("Requirement type, e.g. iban, sort_code, aba"),
             account_holder_name: z.string().min(2).describe("Recipient's full name or business name"),
             details: z
@@ -207,6 +222,7 @@ function registerWriteTools(server, wise, { sessionKey, connectionId }, safe) {
             owned_by_me: z.boolean().optional().describe("True if this is the user's own account elsewhere"),
             profile: profileArg,
         },
+        outputSchema: outputs.prepare_recipient,
         annotations: { readOnlyHint: true, openWorldHint: false },
     }, async (a) => safe(async () => {
         const profile = await wise.resolveProfile(a.profile);
@@ -235,6 +251,7 @@ function registerWriteTools(server, wise, { sessionKey, connectionId }, safe) {
                 .describe("Extra fields Wise requires on some routes, e.g. transferPurpose, sourceOfFunds (a previous attempt lists them)"),
             profile: profileArg.describe("Default: the profile the recipient belongs to"),
         },
+        outputSchema: outputs.prepare_transfer,
         annotations: { readOnlyHint: true, openWorldHint: true },
     }, async (a) => safe(async () => {
         if (!!a.send_amount === !!a.receive_amount)
@@ -301,7 +318,8 @@ function registerWriteTools(server, wise, { sessionKey, connectionId }, safe) {
     server.registerTool("prepare_cancel_transfer", {
         title: "Prepare cancelling a Wise transfer",
         description: `Step 1 of 2 to cancel a transfer that hasn't been paid yet (status incoming_payment_waiting). ${TWO_STEP}`,
-        inputSchema: { transfer_id: z.coerce.number().int() },
+        inputSchema: { transfer_id: z.coerce.number().int().describe("Id of the unpaid transfer (from list_transfers or prepare_transfer's confirmation)") },
+        outputSchema: outputs.prepare_cancel_transfer,
         annotations: { readOnlyHint: true, openWorldHint: false },
     }, async ({ transfer_id }) => safe(async () => {
         const t = await wise.getTransfer(transfer_id);
@@ -309,7 +327,7 @@ function registerWriteTools(server, wise, { sessionKey, connectionId }, safe) {
             return fail(`Transfer ${transfer_id} is "${t.status}"; Wise only allows cancelling unpaid transfers (incoming_payment_waiting) via API.`);
         }
         const summary = `Cancel transfer ${t.id}: ${money(t.source.amount, t.source.currency)} → ${t.recipient?.name ?? `recipient ${t.recipient_id}`} ` +
-            `(${money(t.target.amount, t.target.currency)})${t.reference ? `, reference "${t.reference}"` : ""}, created ${t.created}`;
+            `(${money(t.target.amount, t.target.currency)}, Wise's price until paid)${t.reference ? `, reference "${t.reference}"` : ""}, created ${t.created}`;
         const { code, expiresAt } = storePending(sessionKey, { kind: "cancel_transfer", transferId: t.id }, summary);
         await log("cancel_prepared", { code, summary });
         return ok({ status: "awaiting_user_confirmation", summary, confirmation_code: code, expires_at: expiresAt.toISOString() });
@@ -320,6 +338,7 @@ function registerWriteTools(server, wise, { sessionKey, connectionId }, safe) {
             "explicitly approved that exact summary in their latest message. Codes are single-use and expire after 10 minutes. " +
             "Transfers are created unpaid: the user pays them in the Wise app.",
         inputSchema: { confirmation_code: z.string().describe("Code from a prepare_* tool, e.g. TX-1A2B3C4D") },
+        outputSchema: outputs.confirm_action,
         annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: true },
     }, async ({ confirmation_code }) => safe(async () => {
         const p = takePending(sessionKey, confirmation_code);
@@ -385,13 +404,16 @@ function registerWriteTools(server, wise, { sessionKey, connectionId }, safe) {
     server.registerTool("discard_action", {
         title: "Discard a prepared Wise action",
         description: "Throw away an action prepared with a prepare_* tool, before it's confirmed.",
-        inputSchema: { confirmation_code: z.string() },
+        inputSchema: { confirmation_code: z.string().describe("Code from a prepare_* tool to throw away, e.g. TX-1A2B3C4D") },
+        outputSchema: outputs.discard_action,
         annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: false },
     }, async ({ confirmation_code }) => {
         const removed = discardPending(sessionKey, confirmation_code);
         if (removed)
             await log("action_discarded", { code: confirmation_code });
-        return ok(removed ? "Discarded. Nothing was sent to Wise." : "No pending action with that code.");
+        return ok(removed
+            ? { status: "discarded", message: "Discarded. Nothing was sent to Wise." }
+            : { status: "not_found", message: "No pending action with that code." });
     });
 }
 const stripHtml = (s) => s.replace(/<[^>]*>/g, "").trim();

package/dist/wise/service.js

@@ -122,6 +122,11 @@ export class WiseService {
                 amount: b.amount?.value,
                 reserved: b.reservedAmount?.value || undefined,
                 total_worth: b.totalWorth?.value !== b.amount?.value ? b.totalWorth?.value : undefined,
+                // Stated in the data itself: assistants read values more reliably than schema descriptions.
+                note: b.reservedAmount?.value
+                    ? `${b.reservedAmount.value} ${b.currency} is held for pending payments and already deducted from amount: ` +
+                        `${b.amount?.value} ${b.currency} is available now. Don't add the reserved amount to the total.`
+                    : undefined,
             }));
         }));
         return perProfile.flat().filter((b) => includeEmpty || Number(b.amount) !== 0 || Number(b.reserved ?? 0) !== 0);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blanketbyte/wise-mcp",
-  "version": "1.1.0",
+  "version": "1.1.1",
   "description": "MCP server for Wise: read balances, card payments, transfers and recipients, and prepare transfers you approve twice. Runs locally (npx, for Claude, Codex, Cursor…) or as a remote connector for Claude and ChatGPT.",
   "mcpName": "io.github.BlanketByte/wise-mcp",
   "keywords": [