@airwallex/developer-mcp 0.3.0-beta.10 → 0.3.0-beta.12

package/README.md

@@ -9,7 +9,7 @@ The Airwallex Developer Model Context Protocol (MCP) server empowers AI coding a
 <details>
   <summary><strong>Cursor</strong></summary>
 
-[![Install Airwallex Developer MCP Server on Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en-US/install-mcp?name=airwallex-dev&config=eyJlbnYiOnsiQUlSV0FMTEVYX1NBTkRCT1hfQ0xJRU5UX0lEIjoiIiwiQUlSV0FMTEVYX1NBTkRCT1hfQVBJX0tFWSI6IiJ9LCJjb21tYW5kIjoibnB4IC15IEBhaXJ3YWxsZXgvZGV2ZWxvcGVyLW1jcEBsYXRlc3QifQ%3D%3D)
+[![Install Airwallex Developer MCP Server on Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en-US/install-mcp?name=airwallex-dev&config=eyJlbnYiOnsiQUlSV0FMTEVYX1NBTkRCT1hfQ0xJRU5UX0lEIjoiIiwiQUlSV0FMTEVYX1NBTkRCT1hfQVBJX0tFWSI6IiIsIkFJUldBTExFWF9TQU5EQk9YX0FDQ09VTlRfSUQiOiIifSwiY29tbWFuZCI6Im5weCAteSBAYWlyd2FsbGV4L2RldmVsb3Blci1tY3BAbGF0ZXN0In0%3D)
 
 ```json
 {
@@ -19,7 +19,8 @@ The Airwallex Developer Model Context Protocol (MCP) server empowers AI coding a
       "args": ["-y", "@airwallex/developer-mcp@latest"],
       "env": {
         "AIRWALLEX_SANDBOX_CLIENT_ID": "",
-        "AIRWALLEX_SANDBOX_API_KEY": ""
+        "AIRWALLEX_SANDBOX_API_KEY": "",
+        "AIRWALLEX_SANDBOX_ACCOUNT_ID": ""
       }
     }
   }
@@ -32,7 +33,7 @@ The Airwallex Developer Model Context Protocol (MCP) server empowers AI coding a
   <summary><strong>Claude Code</strong></summary>
 
 ```zsh
-claude mcp add-json airwallex-dev '{ "type": "stdio", "command":"npx", "args": ["-y", "@airwallex/developer-mcp@latest"], "env": { "AIRWALLEX_SANDBOX_CLIENT_ID": "", "AIRWALLEX_SANDBOX_API_KEY": "" } }'
+claude mcp add-json airwallex-dev '{ "type": "stdio", "command":"npx", "args": ["-y", "@airwallex/developer-mcp@latest"], "env": { "AIRWALLEX_SANDBOX_CLIENT_ID": "", "AIRWALLEX_SANDBOX_API_KEY": "", "AIRWALLEX_SANDBOX_ACCOUNT_ID": "" } }'
 ```
 
 </details>
@@ -48,7 +49,8 @@ claude mcp add-json airwallex-dev '{ "type": "stdio", "command":"npx", "args": [
       "args": ["-y", "@airwallex/developer-mcp@latest"],
       "env": {
         "AIRWALLEX_SANDBOX_CLIENT_ID": "",
-        "AIRWALLEX_SANDBOX_API_KEY": ""
+        "AIRWALLEX_SANDBOX_API_KEY": "",
+        "AIRWALLEX_SANDBOX_ACCOUNT_ID": ""
       }
     }
   }
@@ -68,6 +70,7 @@ args = ["-y", "@airwallex/developer-mcp@latest"]
 [mcp_servers.airwallex-dev.env]
 AIRWALLEX_SANDBOX_CLIENT_ID = ""
 AIRWALLEX_SANDBOX_API_KEY = ""
+AIRWALLEX_SANDBOX_ACCOUNT_ID = ""
 ```
 
 </details>
@@ -94,8 +97,9 @@ To access sandbox tools, ensure that your sandbox API credentials are set using
 
 | Name                          | Description                                                                                                                                                                                                                                                                                                                                  | Default | Required |
 | ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | -------- |
-| `AIRWALLEX_SANDBOX_API_KEY`   | The API key, either an admin key or a scoped key with limited permissions, generated in the sandbox environment.  Note that the sandbox tools work as expected only if the API key has the required permissions to access the underlying APIs.  Simulation APIs require an admin API key. | N/A     | No       |
+| `AIRWALLEX_SANDBOX_API_KEY`   | The API key, either an admin key or a scoped key with limited permissions, generated in the sandbox environment.  Note that the sandbox tools work as expected only if the API key has the required permissions to access the underlying APIs. | N/A     | No       |
 | `AIRWALLEX_SANDBOX_CLIENT_ID` | The client ID associated with the API key generated in the sandbox environment.                                                                                                                                                                                                                                                                 | N/A     | No       |
+| `AIRWALLEX_SANDBOX_ACCOUNT_ID` | Specifies the account ID for a scoped API key that can either access both organization & account resources or resources belonging to multiple accounts of an organization. Starts with `acct_`.                                                                                                                                                                                                                                                   | N/A     | No       |
 | `DISABLE_TELEMETRY`           | Set this variable to `true` to opt out of telemetry.                                                                                                                                                                                                                                                                                                                         | `0`     | No       |
 
 ---
@@ -129,7 +133,8 @@ All data retrieved and actions performed with the tools below are in the authent
 | `list_beneficiaries` | List available transfer recipients |
 | `simulate_transfer_result` | Simulate the status of a transfer |
 | `create_payment_link` | Create a new payment link |
-| `list_payment_links` | List created payment links |   
+| `list_payment_links` | List created payment links |
+| `get_default_api_version` | Get the default API version associated with the account or organization. |
 
 
 
@@ -145,4 +150,10 @@ This MCP server is developed and maintained by the Airwallex Developer Experienc
 
 ## Telemetry
 
-Telemetry is enabled by default. To disable telemetry, set the `DISABLE_TELEMETRY` environment variable to `true`. Only anonymous data about MCP tool usage is collected.
+Telemetry is enabled by default. To disable telemetry, set the `DISABLE_TELEMETRY` environment variable to `true`.
+
+Telemetry data includes:
+- MCP tool usage events
+- MCP client name & version (when available)
+- Stable device identifier and device OS
+- The `AIRWALLEX_SANDBOX_CLIENT_ID` if configured (defaults to `unknown` when not set)

package/dist/constants/config.js

@@ -1,8 +1,11 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.BASE_URLS = void 0;
+exports.HEADERS = exports.BASE_URLS = void 0;
 exports.BASE_URLS = {
     api: "https://api-demo.airwallex.com",
-    docsSearch: "https://demo.airwallex.com/docs/ai",
+    docsSearch: "https://mcp-demo.airwallex.com/docs/ai",
     telemetry: "https://o11y-demo.airwallex.com",
 };
+exports.HEADERS = {
+    ON_BEHALF_OF: "x-on-behalf-of",
+};

package/dist/constants/descriptions.js

@@ -26,6 +26,7 @@ EXAMPLES:
 PRESENTATION REQUIREMENT: When presenting the results to the user, you MUST format the balance data as a clear table showing each currency with its corresponding balance amounts. Create a table with columns for Currency, Available, Pending, Reserved, Total, and Prepayment amounts.
 
 RESPONSE: Amounts returned are NOT in minor units.`,
+    GET_DEFAULT_API_VERSION: `Get the default API version associated with the account or organization. The client can override this API version in their integration by setting the x-api-version header at an individual request level.`,
     GET_FX_QUOTE: `Get a foreign exchange quote for a currency conversion in the authenticated Sandbox account.`,
     LIST_BENEFICIARIES: `List all beneficiaries in the authenticated Sandbox account.`,
     LIST_BILLING_PRICES: `List billing prices in the authenticated Sandbox account.`,

package/dist/integration-best-practices.md

@@ -1,4 +1,4 @@
-# Airwallex Integration Best Practices
+# Airwallex Integration Best Practices for Agents
 
 ## General
 
@@ -6,10 +6,23 @@
 - Check how to initialise the Airwallex.js SDK using the `search_public_docs` MCP tool with a suitable `source` parameter. DO NOT hallucinate or assume.
 - Unless requested explicitly by the user, always use the most recent version of the API
 
+## Money & Rounding
+
+- In the Airwallex APIs & SDKs, request fields related to money are NOT represented in minor units by default unless explicitly specified.
+- While setting money-related fields in API requests, ensure that you round to the number of decimal places supported for the currency. Use the `search_public_docs` tool to find the number of supported decimal places for a given currency. 
+
+## Test Card Numbers
+
+- Test card numbers are useful for testing both Billing and Payment Acceptance integrations in the sandbox environment. Airwallex test card numbers are different from other payment platforms. When you need to suggest test card numbers to the user, use the `search_public_docs` tool to find test card numbers accepted by Airwallex and the test scenarios that they help simulate.
+
 ## Payments
 
-- In the Airwallex APIs & SDKs, request fields related to money are NOT represented in minor units by default unless explicitly specified
 - For the Javascript browser library, if the user prefers a direct integration with a CDN, use `https://static.airwallex.com/components/sdk/v1/index.js` and NOT `https://checkout.airwallex.com/assets/elements.bundle.min.js` unless explicitly requested by the user. The latter is a legacy library that is considered deprecated. When the user explicitly asks for it, advise them to consider migrating.
 - For the Javascript browser library, if the user prefers to use a package from the `npm` registry with `npm`, `yarn` or the `pnpm` CLI tools, use `@airwallex/components-sdk` instead of `airwallex-payment-elements` unless explicitly requested by the user. The latter is a legacy package that is considered deprecated. When the user explicitly asks for it, advise them to consider migrating.
 - For a robust and complete payments integration, always consider supporting setting up webhooks.
 - If the payment integration involves redirect-style payment methods, remember to configure a return URL in your payment intent and set up a URL handler on the server for the same. In the URL handler, retrieve the payment intent and check its status. If the status is non-terminal, repeat until a terminal status is observed and decide what to do next based on that. For Drop-in element integrations, you can consider doing this by default since multiple payment methods can be accepted through that integration.
+- Airwallex integrations can accept payments in different currencies. You do not need to perform a currency conversion on the application-side.
+
+### Drop-in Element
+
+- Mount the Drop-in element to the DOM BEFORE attaching event listeners. If you attach the event listeners before mounting the element, the event handlers may not be called.

package/dist/server.js

@@ -5,14 +5,23 @@ const node_sdk_1 = require("@airwallex/node-sdk");
 const mcp_js_1 = require("@modelcontextprotocol/sdk/server/mcp.js");
 const config_1 = require("./constants/config");
 const AirTrackerClient_1 = require("./services/AirTrackerClient");
+const createBillingCheckout_1 = require("./tools/createBillingCheckout");
 const createBillingPrice_1 = require("./tools/createBillingPrice");
+const createBillingProduct_1 = require("./tools/createBillingProduct");
 const createPaymentLink_1 = require("./tools/createPaymentLink");
 const createTransfer_1 = require("./tools/createTransfer");
+const getBalances_1 = require("./tools/getBalances");
+const getDefaultApiVersion_1 = require("./tools/getDefaultApiVersion");
 const getFxQuote_1 = require("./tools/getFxQuote");
-const index_1 = require("./tools/index");
 const listBeneficiaries_1 = require("./tools/listBeneficiaries");
+const listBillingPrices_1 = require("./tools/listBillingPrices");
+const listBillingProducts_1 = require("./tools/listBillingProducts");
+const listGlobalAccounts_1 = require("./tools/listGlobalAccounts");
 const listPaymentLinks_1 = require("./tools/listPaymentLinks");
 const listTransfers_1 = require("./tools/listTransfers");
+const readIntegrationBestPractices_1 = require("./tools/readIntegrationBestPractices");
+const retrieveDocs_1 = require("./tools/retrieveDocs");
+const simulateDeposit_1 = require("./tools/simulateDeposit");
 const simulateTransferResult_1 = require("./tools/simulateTransferResult");
 const withTelemetry_1 = require("./utils/withTelemetry");
 const awxEnv = "demo";
@@ -23,31 +32,33 @@ const buildServer = ({ appVersion, integrationBestPracticesContent, }) => {
         name: "Airwallex",
         version: appVersion,
     });
-    const airTrackerClient = new AirTrackerClient_1.AirTrackerClient(config_1.BASE_URLS.telemetry, awxEnv, appVersion);
-    server.registerTool(index_1.retrieveDocsToolConfig.name, index_1.retrieveDocsToolConfig, (0, withTelemetry_1.withToolTelemetry)(index_1.retrieveDocsToolConfig.name, async (args) => (0, index_1.executeRetrieveDocs)(args, appVersion), { disableTelemetry, telemetryClient: airTrackerClient }));
-    server.registerTool(index_1.readBestPracticesToolConfig.name, index_1.readBestPracticesToolConfig, (0, withTelemetry_1.withToolTelemetry)(index_1.readBestPracticesToolConfig.name, async () => (0, index_1.executeReadBestPractices)(integrationBestPracticesContent), { disableTelemetry, telemetryClient: airTrackerClient }));
+    const airTrackerClient = new AirTrackerClient_1.AirTrackerClient(config_1.BASE_URLS.telemetry, awxEnv, appVersion, server);
+    server.registerTool(retrieveDocs_1.retrieveDocsToolConfig.name, retrieveDocs_1.retrieveDocsToolConfig, (0, withTelemetry_1.withToolTelemetry)(retrieveDocs_1.retrieveDocsToolConfig.name, async (args) => (0, retrieveDocs_1.executeRetrieveDocs)(args, appVersion), { disableTelemetry, telemetryClient: airTrackerClient }));
+    server.registerTool(readIntegrationBestPractices_1.readBestPracticesToolConfig.name, readIntegrationBestPractices_1.readBestPracticesToolConfig, (0, withTelemetry_1.withToolTelemetry)(readIntegrationBestPractices_1.readBestPracticesToolConfig.name, async () => (0, readIntegrationBestPractices_1.executeReadBestPractices)(integrationBestPracticesContent), { disableTelemetry, telemetryClient: airTrackerClient }));
     if (process.env.AIRWALLEX_SANDBOX_CLIENT_ID &&
         process.env.AIRWALLEX_SANDBOX_API_KEY) {
         const airwallex = new node_sdk_1.Airwallex({
+            accountId: process.env.AIRWALLEX_SANDBOX_ACCOUNT_ID,
             apiKey: process.env.AIRWALLEX_SANDBOX_API_KEY,
             clientId: process.env.AIRWALLEX_SANDBOX_CLIENT_ID,
-            env: "demo",
+            env: awxEnv,
         });
-        server.registerTool(index_1.listGlobalAccountsToolConfig.name, index_1.listGlobalAccountsToolConfig, (0, withTelemetry_1.withToolTelemetry)(index_1.listGlobalAccountsToolConfig.name, async () => (0, index_1.executeListGlobalAccounts)(airwallex), { disableTelemetry, telemetryClient: airTrackerClient }));
-        server.registerTool(index_1.getAccountBalancesToolConfig.name, index_1.getAccountBalancesToolConfig, (0, withTelemetry_1.withToolTelemetry)(index_1.getAccountBalancesToolConfig.name, async () => (0, index_1.executeGetAccountBalances)(airwallex), { disableTelemetry, telemetryClient: airTrackerClient }));
-        server.registerTool(index_1.simulateDepositToolConfig.name, index_1.simulateDepositToolConfig, (0, withTelemetry_1.withToolTelemetry)(index_1.simulateDepositToolConfig.name, async (args) => (0, index_1.executeSimulateDeposit)(airwallex, args), { disableTelemetry, telemetryClient: airTrackerClient }));
-        server.registerTool(index_1.listBillingProductsToolConfig.name, index_1.listBillingProductsToolConfig, (0, withTelemetry_1.withToolTelemetry)(index_1.listBillingProductsToolConfig.name, async () => (0, index_1.executeListBillingProducts)(airwallex), { disableTelemetry, telemetryClient: airTrackerClient }));
-        server.registerTool(index_1.listBillingPricesToolConfig.name, index_1.listBillingPricesToolConfig, (0, withTelemetry_1.withToolTelemetry)(index_1.listBillingPricesToolConfig.name, async (args) => (0, index_1.executeListBillingPrices)(airwallex, args), { disableTelemetry, telemetryClient: airTrackerClient }));
-        server.registerTool(index_1.createBillingProductToolConfig.name, index_1.createBillingProductToolConfig, (0, withTelemetry_1.withToolTelemetry)(index_1.createBillingProductToolConfig.name, async (args) => (0, index_1.executeCreateBillingProduct)(airwallex, args), { disableTelemetry, telemetryClient: airTrackerClient }));
+        server.registerTool(listGlobalAccounts_1.listGlobalAccountsToolConfig.name, listGlobalAccounts_1.listGlobalAccountsToolConfig, (0, withTelemetry_1.withToolTelemetry)(listGlobalAccounts_1.listGlobalAccountsToolConfig.name, async (args) => (0, listGlobalAccounts_1.executeListGlobalAccounts)(airwallex, args), { disableTelemetry, telemetryClient: airTrackerClient }));
+        server.registerTool(getDefaultApiVersion_1.getDefaultApiVersionToolConfig.name, getDefaultApiVersion_1.getDefaultApiVersionToolConfig, (0, withTelemetry_1.withToolTelemetry)(getDefaultApiVersion_1.getDefaultApiVersionToolConfig.name, async () => (0, getDefaultApiVersion_1.executeGetDefaultApiVersion)(airwallex), { disableTelemetry, telemetryClient: airTrackerClient }));
+        server.registerTool(getBalances_1.getAccountBalancesToolConfig.name, getBalances_1.getAccountBalancesToolConfig, (0, withTelemetry_1.withToolTelemetry)(getBalances_1.getAccountBalancesToolConfig.name, async (args) => (0, getBalances_1.executeGetAccountBalances)(airwallex, args), { disableTelemetry, telemetryClient: airTrackerClient }));
+        server.registerTool(simulateDeposit_1.simulateDepositToolConfig.name, simulateDeposit_1.simulateDepositToolConfig, (0, withTelemetry_1.withToolTelemetry)(simulateDeposit_1.simulateDepositToolConfig.name, async (args) => (0, simulateDeposit_1.executeSimulateDeposit)(airwallex, args), { disableTelemetry, telemetryClient: airTrackerClient }));
+        server.registerTool(listBillingProducts_1.listBillingProductsToolConfig.name, listBillingProducts_1.listBillingProductsToolConfig, (0, withTelemetry_1.withToolTelemetry)(listBillingProducts_1.listBillingProductsToolConfig.name, async () => (0, listBillingProducts_1.executeListBillingProducts)(airwallex), { disableTelemetry, telemetryClient: airTrackerClient }));
+        server.registerTool(listBillingPrices_1.listBillingPricesToolConfig.name, listBillingPrices_1.listBillingPricesToolConfig, (0, withTelemetry_1.withToolTelemetry)(listBillingPrices_1.listBillingPricesToolConfig.name, async (args) => (0, listBillingPrices_1.executeListBillingPrices)(airwallex, args), { disableTelemetry, telemetryClient: airTrackerClient }));
+        server.registerTool(createBillingProduct_1.createBillingProductToolConfig.name, createBillingProduct_1.createBillingProductToolConfig, (0, withTelemetry_1.withToolTelemetry)(createBillingProduct_1.createBillingProductToolConfig.name, async (args) => (0, createBillingProduct_1.executeCreateBillingProduct)(airwallex, args), { disableTelemetry, telemetryClient: airTrackerClient }));
         server.registerTool(createBillingPrice_1.createBillingPriceToolConfig.name, createBillingPrice_1.createBillingPriceToolConfig, (0, withTelemetry_1.withToolTelemetry)(createBillingPrice_1.createBillingPriceToolConfig.name, async (args) => (0, createBillingPrice_1.executeCreateBillingPrice)(airwallex, args), { disableTelemetry, telemetryClient: airTrackerClient }));
-        server.registerTool(index_1.createBillingCheckoutToolConfig.name, index_1.createBillingCheckoutToolConfig, (0, withTelemetry_1.withToolTelemetry)(index_1.createBillingCheckoutToolConfig.name, async (args) => (0, index_1.executeCreateBillingCheckout)(airwallex, args), { disableTelemetry, telemetryClient: airTrackerClient }));
+        server.registerTool(createBillingCheckout_1.createBillingCheckoutToolConfig.name, createBillingCheckout_1.createBillingCheckoutToolConfig, (0, withTelemetry_1.withToolTelemetry)(createBillingCheckout_1.createBillingCheckoutToolConfig.name, async (args) => (0, createBillingCheckout_1.executeCreateBillingCheckout)(airwallex, args), { disableTelemetry, telemetryClient: airTrackerClient }));
         server.registerTool(getFxQuote_1.getFxQuoteToolConfig.name, getFxQuote_1.getFxQuoteToolConfig, (0, withTelemetry_1.withToolTelemetry)(getFxQuote_1.getFxQuoteToolConfig.name, async (args) => (0, getFxQuote_1.executeGetFxQuote)(airwallex, args), { disableTelemetry, telemetryClient: airTrackerClient }));
-        server.registerTool(listTransfers_1.listTransfersToolConfig.name, listTransfers_1.listTransfersToolConfig, (0, withTelemetry_1.withToolTelemetry)(listTransfers_1.listTransfersToolConfig.name, async () => (0, listTransfers_1.executeListTransfers)(airwallex), { disableTelemetry, telemetryClient: airTrackerClient }));
+        server.registerTool(listTransfers_1.listTransfersToolConfig.name, listTransfers_1.listTransfersToolConfig, (0, withTelemetry_1.withToolTelemetry)(listTransfers_1.listTransfersToolConfig.name, async (args) => (0, listTransfers_1.executeListTransfers)(airwallex, args), { disableTelemetry, telemetryClient: airTrackerClient }));
         server.registerTool(createTransfer_1.createTransferToolConfig.name, createTransfer_1.createTransferToolConfig, (0, withTelemetry_1.withToolTelemetry)(createTransfer_1.createTransferToolConfig.name, async (args) => (0, createTransfer_1.executeCreateTransfer)(airwallex, args), { disableTelemetry, telemetryClient: airTrackerClient }));
-        server.registerTool(listBeneficiaries_1.listBeneficiariesToolConfig.name, listBeneficiaries_1.listBeneficiariesToolConfig, (0, withTelemetry_1.withToolTelemetry)(listBeneficiaries_1.listBeneficiariesToolConfig.name, async () => (0, listBeneficiaries_1.executeListBeneficiaries)(airwallex), { disableTelemetry, telemetryClient: airTrackerClient }));
+        server.registerTool(listBeneficiaries_1.listBeneficiariesToolConfig.name, listBeneficiaries_1.listBeneficiariesToolConfig, (0, withTelemetry_1.withToolTelemetry)(listBeneficiaries_1.listBeneficiariesToolConfig.name, async (args) => (0, listBeneficiaries_1.executeListBeneficiaries)(airwallex, args), { disableTelemetry, telemetryClient: airTrackerClient }));
         server.registerTool(simulateTransferResult_1.simulateTransferUpdateToolConfig.name, simulateTransferResult_1.simulateTransferUpdateToolConfig, (0, withTelemetry_1.withToolTelemetry)(simulateTransferResult_1.simulateTransferUpdateToolConfig.name, async (args) => (0, simulateTransferResult_1.executeSimulateTransferUpdate)(airwallex, args), { disableTelemetry, telemetryClient: airTrackerClient }));
         server.registerTool(createPaymentLink_1.createPaymentLinkToolConfig.name, createPaymentLink_1.createPaymentLinkToolConfig, (0, withTelemetry_1.withToolTelemetry)(createPaymentLink_1.createPaymentLinkToolConfig.name, async (args) => (0, createPaymentLink_1.executeCreatePaymentLink)(airwallex, args), { disableTelemetry, telemetryClient: airTrackerClient }));
-        server.registerTool(listPaymentLinks_1.listPaymentLinksToolConfig.name, listPaymentLinks_1.listPaymentLinksToolConfig, (0, withTelemetry_1.withToolTelemetry)(listPaymentLinks_1.listPaymentLinksToolConfig.name, async () => (0, listPaymentLinks_1.executeListPaymentLinks)(airwallex), { disableTelemetry, telemetryClient: airTrackerClient }));
+        server.registerTool(listPaymentLinks_1.listPaymentLinksToolConfig.name, listPaymentLinks_1.listPaymentLinksToolConfig, (0, withTelemetry_1.withToolTelemetry)(listPaymentLinks_1.listPaymentLinksToolConfig.name, async (args) => (0, listPaymentLinks_1.executeListPaymentLinks)(airwallex, args), { disableTelemetry, telemetryClient: airTrackerClient }));
     }
     return server;
 };

package/dist/services/AirTrackerClient.js

@@ -16,15 +16,18 @@ const DEFAULT_COMMON_DATA = {
     env: "unknown",
     networkType: "unknown",
     platform: os_1.default.platform(),
+    sandboxApiClientId: process.env.AIRWALLEX_SANDBOX_CLIENT_ID?.trim().slice(0, 64) || "unknown",
     sessionId: (0, uuid_1.v4)(),
 };
 class AirTrackerClient {
     baseUrl;
     appVersion;
+    server;
     commonData;
-    constructor(baseUrl, awxEnv, appVersion) {
+    constructor(baseUrl, awxEnv, appVersion, server) {
         this.baseUrl = baseUrl;
         this.appVersion = appVersion;
+        this.server = server;
         this.commonData = {
             ...DEFAULT_COMMON_DATA,
             appVersion: this.appVersion,
@@ -32,13 +35,18 @@ class AirTrackerClient {
         };
     }
     logEvent(eventName, properties) {
+        const clientInfo = this.server.server.getClientVersion();
         const logData = {
             eventName,
             ...properties,
         };
         fetch(`${this.baseUrl}/airtracker/logs`, {
             body: JSON.stringify({
-                commonData: this.commonData,
+                commonData: {
+                    ...this.commonData,
+                    mcpClientName: clientInfo?.name,
+                    mcpClientVersion: clientInfo?.version,
+                },
                 data: [{ ...logData, severity: "info" }],
             }),
             headers: {

package/dist/tools/createBillingCheckout.js

@@ -5,6 +5,9 @@ exports.executeCreateBillingCheckout = executeCreateBillingCheckout;
 const uuid_1 = require("uuid");
 const zod_1 = require("zod");
 const descriptions_1 = require("../constants/descriptions");
+const index_1 = require("../types/index");
+const errorHandler_1 = require("../utils/errorHandler");
+const RESOURCE_CONTEXT_TYPE = index_1.ResourceContextType.Organization;
 exports.createBillingCheckoutSchema = zod_1.z.object({
     mode: zod_1.z.enum(["PAYMENT", "SUBSCRIPTION"], {
         errorMap: () => ({
@@ -54,9 +57,7 @@ async function executeCreateBillingCheckout(airwallex, args) {
         };
     }
     catch (error) {
-        const statusCode = error?.status || error?.statusCode || 500;
-        const errorMessage = error?.message || "Unknown error occurred";
-        throw new Error(`Failed to create billing checkout (${statusCode}): ${errorMessage}`);
+        throw (0, errorHandler_1.handleSdkError)(error, RESOURCE_CONTEXT_TYPE, airwallex, "create billing checkout");
     }
 }
 exports.createBillingCheckoutToolConfig = {

package/dist/tools/createBillingPrice.js

@@ -5,6 +5,9 @@ exports.executeCreateBillingPrice = executeCreateBillingPrice;
 const uuid_1 = require("uuid");
 const zod_1 = require("zod");
 const descriptions_1 = require("../constants/descriptions");
+const index_1 = require("../types/index");
+const errorHandler_1 = require("../utils/errorHandler");
+const RESOURCE_CONTEXT_TYPE = index_1.ResourceContextType.Organization;
 exports.createBillingPriceSchema = zod_1.z
     .object({
     amount: zod_1.z.number().positive("Amount must be positive"),
@@ -89,9 +92,7 @@ async function executeCreateBillingPrice(airwallex, args) {
         };
     }
     catch (error) {
-        const statusCode = error?.status || error?.statusCode || 500;
-        const errorMessage = error?.message || "Unknown error occurred";
-        throw new Error(`Failed to create billing price (${statusCode}): ${errorMessage}`);
+        throw (0, errorHandler_1.handleSdkError)(error, RESOURCE_CONTEXT_TYPE, airwallex, "create billing price");
     }
 }
 exports.createBillingPriceToolConfig = {

package/dist/tools/createBillingProduct.js

@@ -5,6 +5,9 @@ exports.executeCreateBillingProduct = executeCreateBillingProduct;
 const uuid_1 = require("uuid");
 const zod_1 = require("zod");
 const descriptions_1 = require("../constants/descriptions");
+const index_1 = require("../types/index");
+const errorHandler_1 = require("../utils/errorHandler");
+const RESOURCE_CONTEXT_TYPE = index_1.ResourceContextType.Organization;
 exports.createBillingProductSchema = zod_1.z.object({
     description: zod_1.z.string().optional(),
     name: zod_1.z.string().min(1, "Product name is required"),
@@ -32,9 +35,7 @@ async function executeCreateBillingProduct(airwallex, args) {
         };
     }
     catch (error) {
-        const statusCode = error?.status || error?.statusCode || 500;
-        const errorMessage = error?.message || "Unknown error occurred";
-        throw new Error(`Failed to create billing product (${statusCode}): ${errorMessage}`);
+        throw (0, errorHandler_1.handleSdkError)(error, RESOURCE_CONTEXT_TYPE, airwallex, "create billing product");
     }
 }
 exports.createBillingProductToolConfig = {

package/dist/tools/createPaymentLink.js

@@ -4,11 +4,19 @@ exports.createPaymentLinkToolConfig = exports.createPaymentLinkSchema = void 0;
 exports.executeCreatePaymentLink = executeCreatePaymentLink;
 const zod_1 = require("zod");
 const descriptions_1 = require("../constants/descriptions");
+const index_1 = require("../types/index");
+const errorHandler_1 = require("../utils/errorHandler");
+const RESOURCE_CONTEXT_TYPE = index_1.ResourceContextType.Account;
+const requestOptions_1 = require("../utils/requestOptions");
 exports.createPaymentLinkSchema = zod_1.z.object({
     amount: zod_1.z
         .number()
         .positive()
         .describe("The payment amount. For Fixed pricing only."),
+    connected_account_id: zod_1.z
+        .string()
+        .startsWith("acct_", "Connected account ID must start with 'acct_'")
+        .optional(),
     currency: zod_1.z
         .string()
         .length(3)
@@ -39,9 +47,10 @@ async function executeCreatePaymentLink(airwallex, args) {
         if (args.description) {
             createPayload.description = args.description;
         }
-        const response = (await airwallex.post("/api/v1/pa/payment_links/create", createPayload));
+        const requestOptions = (0, requestOptions_1.buildOnBehalfOfOptions)(args.connected_account_id);
+        const response = (await airwallex.post("/api/v1/pa/payment_links/create", createPayload, requestOptions));
         if (args.shopper_email) {
-            await airwallex.post(`/api/v1/pa/payment_links/${response.id}/notify_shopper`, { shopper_email: args.shopper_email });
+            await airwallex.post(`/api/v1/pa/payment_links/${response.id}/notify_shopper`, { shopper_email: args.shopper_email }, requestOptions);
         }
         return {
             content: [
@@ -53,9 +62,7 @@ async function executeCreatePaymentLink(airwallex, args) {
         };
     }
     catch (error) {
-        const statusCode = error?.status || error?.statusCode || 500;
-        const errorMessage = error?.message || "Unknown error occurred";
-        throw new Error(`Failed to create payment link (${statusCode}): ${errorMessage}`);
+        throw (0, errorHandler_1.handleSdkError)(error, RESOURCE_CONTEXT_TYPE, airwallex, "create payment link");
     }
 }
 exports.createPaymentLinkToolConfig = {

package/dist/tools/createTransfer.js

@@ -5,12 +5,20 @@ exports.executeCreateTransfer = executeCreateTransfer;
 const uuid_1 = require("uuid");
 const zod_1 = require("zod");
 const descriptions_1 = require("../constants/descriptions");
+const index_1 = require("../types/index");
+const errorHandler_1 = require("../utils/errorHandler");
+const RESOURCE_CONTEXT_TYPE = index_1.ResourceContextType.Account;
+const requestOptions_1 = require("../utils/requestOptions");
 exports.createTransferSchema = zod_1.z
     .object({
     beneficiary_id: zod_1.z
         .string()
         .min(1)
         .describe("The ID of the beneficiary to send the transfer to."),
+    connected_account_id: zod_1.z
+        .string()
+        .startsWith("acct_", "Connected account ID must start with 'acct_'")
+        .optional(),
     reason: zod_1.z.string().min(1),
     reference: zod_1.z.string().min(1),
     source_amount: zod_1.z
@@ -55,7 +63,8 @@ async function executeCreateTransfer(airwallex, args) {
             transfer_currency: args.transfer_currency,
             transfer_method: args.transfer_method,
         };
-        const response = (await airwallex.post("/api/v1/transfers/create", requestBody));
+        const requestOptions = (0, requestOptions_1.buildOnBehalfOfOptions)(args.connected_account_id);
+        const response = (await airwallex.post("/api/v1/transfers/create", requestBody, requestOptions));
         return {
             content: [
                 {
@@ -66,9 +75,7 @@ async function executeCreateTransfer(airwallex, args) {
         };
     }
     catch (error) {
-        const statusCode = error?.status || error?.statusCode || 500;
-        const errorMessage = error?.message || "Unknown error occurred";
-        throw new Error(`Failed to create transfer (${statusCode}): ${errorMessage}`);
+        throw (0, errorHandler_1.handleSdkError)(error, RESOURCE_CONTEXT_TYPE, airwallex, "create transfer");
     }
 }
 exports.createTransferToolConfig = {

package/dist/tools/getBalances.js

@@ -4,10 +4,20 @@ exports.getAccountBalancesToolConfig = exports.getAccountBalancesSchema = void 0
 exports.executeGetAccountBalances = executeGetAccountBalances;
 const zod_1 = require("zod");
 const descriptions_1 = require("../constants/descriptions");
-exports.getAccountBalancesSchema = zod_1.z.object({});
-async function executeGetAccountBalances(airwallex) {
+const index_1 = require("../types/index");
+const errorHandler_1 = require("../utils/errorHandler");
+const RESOURCE_CONTEXT_TYPE = index_1.ResourceContextType.Account;
+const requestOptions_1 = require("../utils/requestOptions");
+exports.getAccountBalancesSchema = zod_1.z.object({
+    connected_account_id: zod_1.z
+        .string()
+        .startsWith("acct_", "Connected account ID must start with 'acct_'")
+        .optional(),
+});
+async function executeGetAccountBalances(airwallex, args) {
     try {
-        const response = (await airwallex.get("/api/v1/balances/current"));
+        const requestOptions = (0, requestOptions_1.buildOnBehalfOfOptions)(args.connected_account_id);
+        const response = (await airwallex.get("/api/v1/balances/current", requestOptions));
         return {
             content: [
                 {
@@ -18,9 +28,7 @@ async function executeGetAccountBalances(airwallex) {
         };
     }
     catch (error) {
-        const statusCode = error?.status || error?.statusCode || 500;
-        const errorMessage = error?.message || "Unknown error occurred";
-        throw new Error(`Failed to get account balances (${statusCode}): ${errorMessage}`);
+        throw (0, errorHandler_1.handleSdkError)(error, RESOURCE_CONTEXT_TYPE, airwallex, "get account balances");
     }
 }
 exports.getAccountBalancesToolConfig = {

package/dist/tools/getDefaultApiVersion.js

@@ -0,0 +1,49 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getDefaultApiVersionToolConfig = exports.getDefaultApiVersionSchema = void 0;
+exports.executeGetDefaultApiVersion = executeGetDefaultApiVersion;
+const zod_1 = require("zod");
+const descriptions_1 = require("../constants/descriptions");
+const index_1 = require("../types/index");
+const tokenInspector_1 = require("../utils/tokenInspector");
+exports.getDefaultApiVersionSchema = zod_1.z.object({});
+async function executeGetDefaultApiVersion(airwallex) {
+    try {
+        await airwallex.login();
+        const token = airwallex.token;
+        if (!token) {
+            throw new Error("Failed to retrieve token after login");
+        }
+        const tokenInspector = new tokenInspector_1.JWTTokenInspector(token);
+        const resourceContextType = tokenInspector.isOrgOnlyToken()
+            ? index_1.ResourceContextType.Organization
+            : index_1.ResourceContextType.Account;
+        const response = {
+            api_version: tokenInspector.getPayload().api_version,
+            resource_context_type: resourceContextType,
+        };
+        return {
+            content: [
+                {
+                    text: JSON.stringify(response, null, 2),
+                    type: "text",
+                },
+            ],
+        };
+    }
+    catch (error) {
+        const statusCode = error?.status || error?.statusCode || 500;
+        const errorMessage = error?.message || "Unknown error occurred";
+        throw new Error(`Failed to get default API version (${statusCode}): ${errorMessage}`);
+    }
+}
+exports.getDefaultApiVersionToolConfig = {
+    annotations: {
+        openWorldHint: true,
+        readOnlyHint: true,
+        title: "Get default API version",
+    },
+    description: descriptions_1.TOOL_DESCRIPTIONS.GET_DEFAULT_API_VERSION,
+    inputSchema: exports.getDefaultApiVersionSchema,
+    name: "get_default_api_version",
+};

package/dist/tools/getFxQuote.js

@@ -4,6 +4,10 @@ exports.getFxQuoteToolConfig = exports.getFxQuoteSchema = void 0;
 exports.executeGetFxQuote = executeGetFxQuote;
 const zod_1 = require("zod");
 const descriptions_1 = require("../constants/descriptions");
+const index_1 = require("../types/index");
+const errorHandler_1 = require("../utils/errorHandler");
+const RESOURCE_CONTEXT_TYPE = index_1.ResourceContextType.Account;
+const requestOptions_1 = require("../utils/requestOptions");
 exports.getFxQuoteSchema = zod_1.z
     .object({
     buy_amount: zod_1.z
@@ -12,6 +16,10 @@ exports.getFxQuoteSchema = zod_1.z
         .describe("The amount to buy. Skip this if you are setting sell_amount")
         .optional(),
     buy_currency: zod_1.z.string().length(3).describe("The currency to buy"),
+    connected_account_id: zod_1.z
+        .string()
+        .startsWith("acct_", "Connected account ID must start with 'acct_'")
+        .optional(),
     sell_amount: zod_1.z
         .number()
         .positive()
@@ -29,13 +37,14 @@ exports.getFxQuoteSchema = zod_1.z
 });
 async function executeGetFxQuote(airwallex, args) {
     try {
+        const requestOptions = (0, requestOptions_1.buildOnBehalfOfOptions)(args.connected_account_id);
         const response = (await airwallex.post("/api/v1/fx/quotes/create", {
             buy_amount: args.buy_amount,
             buy_currency: args.buy_currency,
             sell_amount: args.sell_amount,
             sell_currency: args.sell_currency,
             validity: args.validity,
-        }));
+        }, requestOptions));
         return {
             content: [
                 {
@@ -46,9 +55,7 @@ async function executeGetFxQuote(airwallex, args) {
         };
     }
     catch (error) {
-        const statusCode = error?.status || error?.statusCode || 500;
-        const errorMessage = error?.message || "Unknown error occurred";
-        throw new Error(`Failed to get FX quote (${statusCode}): ${errorMessage}`);
+        throw (0, errorHandler_1.handleSdkError)(error, RESOURCE_CONTEXT_TYPE, airwallex, "get FX quote");
     }
 }
 exports.getFxQuoteToolConfig = {

package/dist/tools/listBeneficiaries.js

@@ -4,13 +4,23 @@ exports.listBeneficiariesToolConfig = exports.listBeneficiariesSchema = void 0;
 exports.executeListBeneficiaries = executeListBeneficiaries;
 const zod_1 = require("zod");
 const descriptions_1 = require("../constants/descriptions");
-exports.listBeneficiariesSchema = zod_1.z.object({});
-async function executeListBeneficiaries(airwallex) {
+const index_1 = require("../types/index");
+const errorHandler_1 = require("../utils/errorHandler");
+const RESOURCE_CONTEXT_TYPE = index_1.ResourceContextType.Account;
+const requestOptions_1 = require("../utils/requestOptions");
+exports.listBeneficiariesSchema = zod_1.z.object({
+    connected_account_id: zod_1.z
+        .string()
+        .startsWith("acct_", "Connected account ID must start with 'acct_'")
+        .optional(),
+});
+async function executeListBeneficiaries(airwallex, args) {
     try {
+        const requestOptions = (0, requestOptions_1.buildOnBehalfOfOptions)(args.connected_account_id);
         const queryParams = new URLSearchParams();
         queryParams.append("page_size", "100");
         const url = `/api/v1/beneficiaries${queryParams.toString() ? `?${queryParams.toString()}` : ""}`;
-        const response = (await airwallex.get(url));
+        const response = (await airwallex.get(url, requestOptions));
         return {
             content: [
                 {
@@ -21,9 +31,7 @@ async function executeListBeneficiaries(airwallex) {
         };
     }
     catch (error) {
-        const statusCode = error?.status || error?.statusCode || 500;
-        const errorMessage = error?.message || "Unknown error occurred";
-        throw new Error(`Failed to list beneficiaries (${statusCode}): ${errorMessage}`);
+        throw (0, errorHandler_1.handleSdkError)(error, RESOURCE_CONTEXT_TYPE, airwallex, "list beneficiaries");
     }
 }
 exports.listBeneficiariesToolConfig = {

package/dist/tools/listBillingPrices.js

@@ -4,6 +4,9 @@ exports.listBillingPricesToolConfig = exports.listBillingPricesSchema = void 0;
 exports.executeListBillingPrices = executeListBillingPrices;
 const zod_1 = require("zod");
 const descriptions_1 = require("../constants/descriptions");
+const index_1 = require("../types/index");
+const errorHandler_1 = require("../utils/errorHandler");
+const RESOURCE_CONTEXT_TYPE = index_1.ResourceContextType.Organization;
 exports.listBillingPricesSchema = zod_1.z.object({
     product_id: zod_1.z
         .string()
@@ -29,9 +32,7 @@ async function executeListBillingPrices(airwallex, args) {
         };
     }
     catch (error) {
-        const statusCode = error?.status || error?.statusCode || 500;
-        const errorMessage = error?.message || "Unknown error occurred";
-        throw new Error(`Failed to list billing prices (${statusCode}): ${errorMessage}`);
+        throw (0, errorHandler_1.handleSdkError)(error, RESOURCE_CONTEXT_TYPE, airwallex, "list billing prices");
     }
 }
 exports.listBillingPricesToolConfig = {

package/dist/tools/listBillingProducts.js

@@ -4,6 +4,9 @@ exports.listBillingProductsToolConfig = exports.listBillingProductsSchema = void
 exports.executeListBillingProducts = executeListBillingProducts;
 const zod_1 = require("zod");
 const descriptions_1 = require("../constants/descriptions");
+const index_1 = require("../types/index");
+const errorHandler_1 = require("../utils/errorHandler");
+const RESOURCE_CONTEXT_TYPE = index_1.ResourceContextType.Organization;
 exports.listBillingProductsSchema = zod_1.z.object({});
 async function executeListBillingProducts(airwallex) {
     try {
@@ -21,9 +24,7 @@ async function executeListBillingProducts(airwallex) {
         };
     }
     catch (error) {
-        const statusCode = error?.status || error?.statusCode || 500;
-        const errorMessage = error?.message || "Unknown error occurred";
-        throw new Error(`Failed to list billing products (${statusCode}): ${errorMessage}`);
+        throw (0, errorHandler_1.handleSdkError)(error, RESOURCE_CONTEXT_TYPE, airwallex, "list billing products");
     }
 }
 exports.listBillingProductsToolConfig = {

package/dist/tools/listGlobalAccounts.js

@@ -4,10 +4,20 @@ exports.listGlobalAccountsToolConfig = exports.listGlobalAccountsSchema = void 0
 exports.executeListGlobalAccounts = executeListGlobalAccounts;
 const zod_1 = require("zod");
 const descriptions_1 = require("../constants/descriptions");
-exports.listGlobalAccountsSchema = zod_1.z.object({});
-async function executeListGlobalAccounts(airwallex) {
+const index_1 = require("../types/index");
+const errorHandler_1 = require("../utils/errorHandler");
+const RESOURCE_CONTEXT_TYPE = index_1.ResourceContextType.Account;
+const requestOptions_1 = require("../utils/requestOptions");
+exports.listGlobalAccountsSchema = zod_1.z.object({
+    connected_account_id: zod_1.z
+        .string()
+        .startsWith("acct_", "Connected account ID must start with 'acct_'")
+        .optional(),
+});
+async function executeListGlobalAccounts(airwallex, args) {
     try {
-        const response = (await airwallex.get("/api/v1/global_accounts"));
+        const requestOptions = (0, requestOptions_1.buildOnBehalfOfOptions)(args.connected_account_id);
+        const response = (await airwallex.get("/api/v1/global_accounts", requestOptions));
         return {
             content: [
                 {
@@ -18,10 +28,7 @@ async function executeListGlobalAccounts(airwallex) {
         };
     }
     catch (error) {
-        // Simplified error handling
-        const statusCode = error?.status || error?.statusCode || 500;
-        const errorMessage = error?.message || "Unknown error occurred";
-        throw new Error(`Failed to list global accounts (${statusCode}): ${errorMessage}`);
+        throw (0, errorHandler_1.handleSdkError)(error, RESOURCE_CONTEXT_TYPE, airwallex, "list global accounts");
     }
 }
 exports.listGlobalAccountsToolConfig = {

package/dist/tools/listPaymentLinks.js

@@ -4,13 +4,23 @@ exports.listPaymentLinksToolConfig = exports.listPaymentLinksSchema = void 0;
 exports.executeListPaymentLinks = executeListPaymentLinks;
 const zod_1 = require("zod");
 const descriptions_1 = require("../constants/descriptions");
-exports.listPaymentLinksSchema = zod_1.z.object({});
-async function executeListPaymentLinks(airwallex) {
+const index_1 = require("../types/index");
+const errorHandler_1 = require("../utils/errorHandler");
+const RESOURCE_CONTEXT_TYPE = index_1.ResourceContextType.Account;
+const requestOptions_1 = require("../utils/requestOptions");
+exports.listPaymentLinksSchema = zod_1.z.object({
+    connected_account_id: zod_1.z
+        .string()
+        .startsWith("acct_", "Connected account ID must start with 'acct_'")
+        .optional(),
+});
+async function executeListPaymentLinks(airwallex, args) {
     try {
+        const requestOptions = (0, requestOptions_1.buildOnBehalfOfOptions)(args.connected_account_id);
         const queryParams = new URLSearchParams();
         queryParams.append("page_size", "100");
         const url = `/api/v1/pa/payment_links${queryParams.toString() ? `?${queryParams.toString()}` : ""}`;
-        const response = (await airwallex.get(url));
+        const response = (await airwallex.get(url, requestOptions));
         return {
             content: [
                 {
@@ -21,9 +31,7 @@ async function executeListPaymentLinks(airwallex) {
         };
     }
     catch (error) {
-        const statusCode = error?.status || error?.statusCode || 500;
-        const errorMessage = error?.message || "Unknown error occurred";
-        throw new Error(`Failed to list payment links (${statusCode}): ${errorMessage}`);
+        throw (0, errorHandler_1.handleSdkError)(error, RESOURCE_CONTEXT_TYPE, airwallex, "list payment links");
     }
 }
 exports.listPaymentLinksToolConfig = {

package/dist/tools/listTransfers.js

@@ -4,10 +4,20 @@ exports.listTransfersToolConfig = exports.listTransfersSchema = void 0;
 exports.executeListTransfers = executeListTransfers;
 const zod_1 = require("zod");
 const descriptions_1 = require("../constants/descriptions");
-exports.listTransfersSchema = zod_1.z.object({});
-async function executeListTransfers(airwallex) {
+const index_1 = require("../types/index");
+const errorHandler_1 = require("../utils/errorHandler");
+const RESOURCE_CONTEXT_TYPE = index_1.ResourceContextType.Account;
+const requestOptions_1 = require("../utils/requestOptions");
+exports.listTransfersSchema = zod_1.z.object({
+    connected_account_id: zod_1.z
+        .string()
+        .startsWith("acct_", "Connected account ID must start with 'acct_'")
+        .optional(),
+});
+async function executeListTransfers(airwallex, args) {
     try {
-        const response = (await airwallex.get("/api/v1/transfers"));
+        const requestOptions = (0, requestOptions_1.buildOnBehalfOfOptions)(args.connected_account_id);
+        const response = (await airwallex.get("/api/v1/transfers", requestOptions));
         return {
             content: [
                 {
@@ -18,9 +28,7 @@ async function executeListTransfers(airwallex) {
         };
     }
     catch (error) {
-        const statusCode = error?.status || error?.statusCode || 500;
-        const errorMessage = error?.message || "Unknown error occurred";
-        throw new Error(`Failed to list transfers (${statusCode}): ${errorMessage}`);
+        throw (0, errorHandler_1.handleSdkError)(error, RESOURCE_CONTEXT_TYPE, airwallex, "list transfers");
     }
 }
 exports.listTransfersToolConfig = {

package/dist/tools/readIntegrationBestPractices.js

@@ -4,6 +4,7 @@ exports.readBestPracticesToolConfig = exports.readBestPracticesSchema = void 0;
 exports.executeReadBestPractices = executeReadBestPractices;
 const zod_1 = require("zod");
 const descriptions_1 = require("../constants/descriptions");
+const index_1 = require("../types/index");
 exports.readBestPracticesSchema = zod_1.z.object({});
 async function executeReadBestPractices(integrationBestPracticesContent) {
     try {
@@ -17,7 +18,7 @@ async function executeReadBestPractices(integrationBestPracticesContent) {
         };
     }
     catch (error) {
-        throw new Error(`Failed to read the integration best practices file: ${error instanceof Error ? error.message : String(error)}`);
+        throw new index_1.ToolError(`Failed to read the integration best practices file: ${error instanceof Error ? error.message : String(error)}`, 500);
     }
 }
 exports.readBestPracticesToolConfig = {

package/dist/tools/retrieveDocs.js

@@ -5,6 +5,7 @@ exports.executeRetrieveDocs = executeRetrieveDocs;
 const zod_1 = require("zod");
 const config_1 = require("../constants/config");
 const descriptions_1 = require("../constants/descriptions");
+const index_1 = require("../types/index");
 exports.retrieveDocsSchema = zod_1.z.object({
     question: zod_1.z
         .string()
@@ -35,7 +36,7 @@ async function executeRetrieveDocs(args, version) {
         method: "POST",
     });
     if (!response.ok) {
-        throw new Error(`HTTP error! status: ${response.status}`);
+        throw new index_1.ToolError(`HTTP error! status: ${response.status}`, response.status);
     }
     const data = (await response.json());
     const results = data.results.map((entry) => ({
@@ -43,12 +44,15 @@ async function executeRetrieveDocs(args, version) {
         source_url: entry.source_url,
     }));
     return {
-        content: [
-            {
-                text: JSON.stringify(results.map((result) => result.content), null, 2),
-                type: "text",
-            },
-        ],
+        result: {
+            content: [
+                {
+                    text: JSON.stringify(results.map((result) => result.content), null, 2),
+                    type: "text",
+                },
+            ],
+        },
+        telemetryMeta: { httpStatusCode: response.status },
     };
 }
 exports.retrieveDocsToolConfig = {

package/dist/tools/simulateDeposit.js

@@ -4,11 +4,19 @@ exports.simulateDepositToolConfig = exports.simulateDepositSchema = void 0;
 exports.executeSimulateDeposit = executeSimulateDeposit;
 const zod_1 = require("zod");
 const descriptions_1 = require("../constants/descriptions");
+const index_1 = require("../types/index");
+const errorHandler_1 = require("../utils/errorHandler");
+const RESOURCE_CONTEXT_TYPE = index_1.ResourceContextType.Account;
+const requestOptions_1 = require("../utils/requestOptions");
 exports.simulateDepositSchema = zod_1.z.object({
     amount: zod_1.z
         .number()
         .positive()
         .describe("The amount to deposit into the global account (in the account's base currency, not minor units)"),
+    connected_account_id: zod_1.z
+        .string()
+        .startsWith("acct_", "Connected account ID must start with 'acct_'")
+        .optional(),
     globalAccountId: zod_1.z
         .string()
         .min(1)
@@ -16,10 +24,11 @@ exports.simulateDepositSchema = zod_1.z.object({
 });
 async function executeSimulateDeposit(airwallex, args) {
     try {
+        const requestOptions = (0, requestOptions_1.buildOnBehalfOfOptions)(args.connected_account_id);
         const response = await airwallex.post("/api/v1/simulation/deposit/create", {
             amount: args.amount,
             global_account_id: args.globalAccountId,
-        });
+        }, requestOptions);
         const result = {
             amount: response.amount,
             created_at: response.create_time,
@@ -37,9 +46,7 @@ async function executeSimulateDeposit(airwallex, args) {
         };
     }
     catch (error) {
-        const statusCode = error?.status || error?.statusCode || 500;
-        const errorMessage = error?.message || "Unknown error occurred";
-        throw new Error(`Deposit simulation failed (${statusCode}): ${errorMessage}`);
+        throw (0, errorHandler_1.handleSdkError)(error, RESOURCE_CONTEXT_TYPE, airwallex, "simulate deposit");
     }
 }
 exports.simulateDepositToolConfig = {

package/dist/tools/simulateTransferResult.js

@@ -4,7 +4,15 @@ exports.simulateTransferUpdateToolConfig = exports.simulateTransferUpdateSchema
 exports.executeSimulateTransferUpdate = executeSimulateTransferUpdate;
 const zod_1 = require("zod");
 const descriptions_1 = require("../constants/descriptions");
+const index_1 = require("../types/index");
+const errorHandler_1 = require("../utils/errorHandler");
+const RESOURCE_CONTEXT_TYPE = index_1.ResourceContextType.Account;
+const requestOptions_1 = require("../utils/requestOptions");
 exports.simulateTransferUpdateSchema = zod_1.z.object({
+    connected_account_id: zod_1.z
+        .string()
+        .startsWith("acct_", "Connected account ID must start with 'acct_'")
+        .optional(),
     next_status: zod_1.z
         .enum(["OVERDUE", "PROCESSING", "SENT", "PAID", "FAILED", "CANCELLED"])
         .describe("The next status of the transfer. One of the following: OVERDUE, PROCESSING, SENT, PAID, FAILED, CANCELLED."),
@@ -12,9 +20,10 @@ exports.simulateTransferUpdateSchema = zod_1.z.object({
 });
 async function executeSimulateTransferUpdate(airwallex, args) {
     try {
+        const requestOptions = (0, requestOptions_1.buildOnBehalfOfOptions)(args.connected_account_id);
         const response = (await airwallex.post(`/api/v1/simulation/transfers/${args.transfer_id}/transition`, {
             next_status: args.next_status,
-        }));
+        }, requestOptions));
         return {
             content: [
                 {
@@ -25,9 +34,7 @@ async function executeSimulateTransferUpdate(airwallex, args) {
         };
     }
     catch (error) {
-        const statusCode = error?.status || error?.statusCode || 500;
-        const errorMessage = error?.message || "Unknown error occurred";
-        throw new Error(`Failed to simulate transfer update (${statusCode}): ${errorMessage}`);
+        throw (0, errorHandler_1.handleSdkError)(error, RESOURCE_CONTEXT_TYPE, airwallex, "simulate transfer update");
     }
 }
 exports.simulateTransferUpdateToolConfig = {

package/dist/types/index.js

@@ -1,2 +1,21 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.ToolError = exports.ResourceContextType = void 0;
+var ResourceContextType;
+(function (ResourceContextType) {
+    ResourceContextType["Account"] = "account";
+    ResourceContextType["Organization"] = "organization";
+})(ResourceContextType || (exports.ResourceContextType = ResourceContextType = {}));
+/**
+ * Custom error class that preserves HTTP status code for telemetry.
+ * Use this instead of plain Error when throwing errors from tool executors.
+ */
+class ToolError extends Error {
+    httpStatusCode;
+    constructor(message, httpStatusCode) {
+        super(message);
+        this.httpStatusCode = httpStatusCode;
+        this.name = "ToolError";
+    }
+}
+exports.ToolError = ToolError;

package/dist/utils/errorHandler.js

@@ -0,0 +1,41 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.handleSdkError = handleSdkError;
+const index_1 = require("../types/index");
+const tokenInspector_1 = require("./tokenInspector");
+function handleSdkError(error, resourceContextType, airwallex, operationName) {
+    const statusCode = error?.status || error?.statusCode || 500;
+    const errorMessage = error?.message || "Unknown error occurred";
+    // Check for 401 errors and provide context-aware messages
+    if (statusCode === 401) {
+        const contextHint = getContextMismatchHint(resourceContextType, airwallex);
+        if (contextHint) {
+            return new index_1.ToolError(`Failed to ${operationName} (${statusCode}): ${errorMessage}. ${contextHint}`, statusCode);
+        }
+    }
+    return new index_1.ToolError(`Failed to ${operationName} (${statusCode}): ${errorMessage}`, statusCode);
+}
+function getContextMismatchHint(resourceContextType, airwallex) {
+    const token = airwallex.token;
+    if (!token) {
+        return null;
+    }
+    try {
+        const tokenInspector = new tokenInspector_1.JWTTokenInspector(token);
+        // Account-only token trying to access Organization resource
+        if (tokenInspector.isAccountOnlyToken() &&
+            resourceContextType === index_1.ResourceContextType.Organization) {
+            return "This operation requires organization-level access, but the API key is scoped to account-level only.";
+        }
+        // Org-only token trying to access Account resource
+        if (tokenInspector.isOrgOnlyToken() &&
+            resourceContextType === index_1.ResourceContextType.Account) {
+            return "This operation requires account-level access, but the API key is scoped to organization-level only.";
+        }
+    }
+    catch {
+        // If token parsing fails, don't add a hint
+        return null;
+    }
+    return null;
+}

package/dist/utils/requestOptions.js

@@ -0,0 +1,12 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildOnBehalfOfOptions = buildOnBehalfOfOptions;
+const config_1 = require("../constants/config");
+/**
+ * Build request options with on-behalf-of header for connected accounts
+ */
+function buildOnBehalfOfOptions(connectedAccountId) {
+    return connectedAccountId
+        ? { headers: { [config_1.HEADERS.ON_BEHALF_OF]: connectedAccountId } }
+        : undefined;
+}

package/dist/utils/tokenInspector.js

@@ -0,0 +1,34 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.JWTTokenInspector = void 0;
+class JWTTokenInspector {
+    tokenPayload;
+    constructor(tokenStr) {
+        this.tokenPayload = this.parseToken(tokenStr).payload;
+    }
+    getPayload() {
+        return this.tokenPayload;
+    }
+    isAccountOnlyToken() {
+        return (this.tokenPayload.account_id !== undefined &&
+            this.tokenPayload.org_id === undefined);
+    }
+    isMixedToken() {
+        return (this.tokenPayload.org_id !== undefined &&
+            this.tokenPayload.account_id !== undefined);
+    }
+    isOrgOnlyToken() {
+        return (this.tokenPayload.org_id !== undefined &&
+            this.tokenPayload.account_id === undefined);
+    }
+    parseToken(tokenStr) {
+        const [, payload] = tokenStr.split(".");
+        return {
+            payload: JSON.parse(decodeBase64Url(payload)),
+        };
+    }
+}
+exports.JWTTokenInspector = JWTTokenInspector;
+function decodeBase64Url(base64Url) {
+    return Buffer.from(base64Url, "base64url").toString("utf-8");
+}

package/dist/utils/withTelemetry.js

@@ -1,16 +1,56 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.withToolTelemetry = withToolTelemetry;
+const types_1 = require("../types");
 const TOOL_INVOKED_EVENT_NAME = "TOOL_INVOKED";
 // Middleware that wraps around a MCP tool's execute function and logs the event using the telemetry client
 function withToolTelemetry(toolName, toolExecutor, { disableTelemetry, telemetryClient, }) {
     return async (args) => {
         if (disableTelemetry) {
-            return await toolExecutor(args);
+            const response = await toolExecutor(args);
+            return isToolExecutorResponse(response) ? response.result : response;
+        }
+        let result;
+        let telemetryMeta;
+        const startTime = Date.now();
+        try {
+            const response = await toolExecutor(args);
+            if (isToolExecutorResponse(response)) {
+                result = response.result;
+                telemetryMeta = response.telemetryMeta;
+            }
+            else {
+                result = response;
+            }
+            telemetryClient.logEvent(TOOL_INVOKED_EVENT_NAME, {
+                httpStatusCode: telemetryMeta?.httpStatusCode ?? 200,
+                latencyInMs: Date.now() - startTime,
+                success: true,
+                toolName: toolName,
+            });
+            return result;
+        }
+        catch (error) {
+            // Extract status code from ToolError, or fallback to error properties, or default to 500
+            const statusCode = error instanceof types_1.ToolError
+                ? error.httpStatusCode
+                : error?.status || error?.statusCode || 500;
+            telemetryClient.logEvent(TOOL_INVOKED_EVENT_NAME, {
+                httpStatusCode: statusCode,
+                latencyInMs: Date.now() - startTime,
+                success: false,
+                toolName: toolName,
+            });
+            throw error;
         }
-        telemetryClient.logEvent(TOOL_INVOKED_EVENT_NAME, {
-            toolName: toolName,
-        });
-        return await toolExecutor(args);
     };
 }
+// Type guard to check if response is ToolExecutorResponse (has result property)
+function isToolExecutorResponse(response) {
+    return (response !== null &&
+        typeof response === "object" &&
+        "result" in response &&
+        response.result !== null &&
+        typeof response.result === "object" &&
+        "content" in response.result);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@airwallex/developer-mcp",
-  "version": "v0.3.0-beta.10",
+  "version": "0.3.0-beta.12",
   "description": "MCP server for AI agents that assist developers integrating with the Airwallex platform",
   "bin": {
     "awx-developer-mcp": "dist/index.js"
@@ -11,6 +11,7 @@
   ],
   "scripts": {
     "build": "tsc && cp src/*.md dist/",
+    "update-manifest": "node --experimental-strip-types scripts/update-manifest.ts",
     "lint": "prettier --check . && eslint . && tsc --noEmit",
     "test": "vitest run",
     "test:unit": "vitest run --project unit",
@@ -25,7 +26,7 @@
   "author": "Developer Experience Team <developer.support@airwallex.com>",
   "license": "MIT",
   "dependencies": {
-    "@airwallex/node-sdk": "2.0.0-beta.4",
+    "@airwallex/node-sdk": "2.1.0-beta.5",
     "@modelcontextprotocol/sdk": "1.22.0",
     "node-machine-id": "1.1.12",
     "uuid": "11",
@@ -40,6 +41,7 @@
     "airwallex"
   ],
   "devDependencies": {
+    "@anthropic-ai/mcpb": "^2.1.2",
     "@eslint/js": "^9.26.0",
     "@semantic-release/changelog": "^6.0.3",
     "@semantic-release/commit-analyzer": "^13.0.1",

package/dist/tools/index.js

@@ -1,25 +0,0 @@
-"use strict";
-var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    var desc = Object.getOwnPropertyDescriptor(m, k);
-    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
-      desc = { enumerable: true, get: function() { return m[k]; } };
-    }
-    Object.defineProperty(o, k2, desc);
-}) : (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    o[k2] = m[k];
-}));
-var __exportStar = (this && this.__exportStar) || function(m, exports) {
-    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-__exportStar(require("./createBillingCheckout"), exports);
-__exportStar(require("./createBillingProduct"), exports);
-__exportStar(require("./getBalances"), exports);
-__exportStar(require("./listBillingPrices"), exports);
-__exportStar(require("./listBillingProducts"), exports);
-__exportStar(require("./listGlobalAccounts"), exports);
-__exportStar(require("./readIntegrationBestPractices"), exports);
-__exportStar(require("./retrieveDocs"), exports);
-__exportStar(require("./simulateDeposit"), exports);