@aura-payments/mcp-server 1.0.1 → 1.2.0

package/dist/bin.mjs

@@ -4,13 +4,55 @@ import { McpServer, ResourceTemplate } from '@modelcontextprotocol/sdk/server/mc
 import { AuraClient, AuraAuthenticationError, AuraNotFoundError, AuraValidationError, AuraRateLimitError, AuraTimeoutError, AuraAPIError, AuraError } from '@aura-payments/sdk';
 import { z } from 'zod';
 
+// src/api-key.ts
+var API_KEY_PREFIXES = [
+  "sk_test_",
+  "sk_live_",
+  "pk_test_",
+  "pk_live_"
+];
+function maskApiKey(apiKey) {
+  const revealed = Math.min(8, Math.floor(apiKey.length / 2));
+  return `${apiKey.slice(0, revealed)}\u2026(${apiKey.length} chars)`;
+}
+function parseApiKey(apiKey) {
+  if (!apiKey || apiKey.trim() === "") {
+    throw new MissingAuraApiKeyError();
+  }
+  const prefix = API_KEY_PREFIXES.find((p) => apiKey.startsWith(p));
+  if (!prefix) {
+    throw new MalformedAuraApiKeyError(apiKey);
+  }
+  return { prefix, mode: prefix.includes("_test_") ? "test" : "live" };
+}
+function resolveKeyMode(apiKey) {
+  try {
+    return parseApiKey(apiKey).mode;
+  } catch (err) {
+    return err instanceof MissingAuraApiKeyError ? "unconfigured" : "invalid";
+  }
+}
+var MissingAuraApiKeyError = class extends Error {
+  constructor() {
+    super(
+      'AURA_API_KEY not set. Configure it in your MCP client config \u2014 for example in mcp.json: { "mcpServers": { "aura": { "command": "aura-mcp", "env": { "AURA_API_KEY": "pk_live_..." } } } }. Get a key at https://getaura.sh.'
+    );
+    this.name = "MissingAuraApiKeyError";
+  }
+};
+var MalformedAuraApiKeyError = class extends Error {
+  constructor(apiKey) {
+    super(
+      `AURA_API_KEY is malformed (got ${maskApiKey(apiKey)}). An Aura API key must start with one of: ${API_KEY_PREFIXES.join(", ")}. Check for a truncated copy/paste, a shell-quoting problem, or a key from a different service. Issue a new key at https://getaura.sh.`
+    );
+    this.name = "MalformedAuraApiKeyError";
+  }
+};
 var cached = null;
 function getClient() {
   if (cached) return cached;
   const apiKey = process.env.AURA_API_KEY;
-  if (!apiKey) {
-    throw new MissingAuraApiKeyError();
-  }
+  parseApiKey(apiKey);
   cached = new AuraClient({
     apiKey,
     baseUrl: process.env.AURA_BASE_URL,
@@ -19,14 +61,6 @@ function getClient() {
   });
   return cached;
 }
-var MissingAuraApiKeyError = class extends Error {
-  constructor() {
-    super(
-      'AURA_API_KEY not set. Configure it in your MCP client config \u2014 for example in mcp.json: { "mcpServers": { "aura": { "command": "aura-mcp", "env": { "AURA_API_KEY": "pk_live_..." } } } }. Get a key at https://getaura.sh.'
-    );
-    this.name = "MissingAuraApiKeyError";
-  }
-};
 
 // src/resources/agents.ts
 function registerAgentResources(server) {
@@ -65,6 +99,55 @@ function registerAgentResources(server) {
     }
   );
 }
+var COLLECTION_LIMIT = 50;
+function registerEscrowResources(server) {
+  server.resource("escrows", "aura://escrows", async (uri) => {
+    const client = getClient();
+    const page = await client.escrows.list({ limit: COLLECTION_LIMIT });
+    return {
+      contents: [
+        {
+          uri: uri.href,
+          mimeType: "application/json",
+          text: JSON.stringify(page, null, 2)
+        }
+      ]
+    };
+  });
+  server.resource(
+    "escrow",
+    new ResourceTemplate("aura://escrows/{id}", { list: void 0 }),
+    async (uri, { id }) => {
+      const client = getClient();
+      const escrow = await client.escrows.get(String(id));
+      return {
+        contents: [
+          {
+            uri: uri.href,
+            mimeType: "application/json",
+            text: JSON.stringify(escrow, null, 2)
+          }
+        ]
+      };
+    }
+  );
+}
+
+// src/resources/insights.ts
+function registerInsightsResources(server, clientFactory = getClient) {
+  server.resource("insights-overview", "aura://insights/overview", async (uri) => {
+    const overview = await clientFactory().insights.overview();
+    return {
+      contents: [
+        {
+          uri: uri.href,
+          mimeType: "application/json",
+          text: JSON.stringify(overview, null, 2)
+        }
+      ]
+    };
+  });
+}
 function registerMandateResources(server) {
   server.resource(
     "mandates-pending",
@@ -101,6 +184,108 @@ function registerMandateResources(server) {
     }
   );
 }
+var COLLECTION_LIMIT2 = 50;
+function registerWalletResources(server) {
+  server.resource("wallets", "aura://wallets", async (uri) => {
+    const client = getClient();
+    const page = await client.wallets.list({ limit: COLLECTION_LIMIT2 });
+    return {
+      contents: [
+        {
+          uri: uri.href,
+          mimeType: "application/json",
+          text: JSON.stringify(page, null, 2)
+        }
+      ]
+    };
+  });
+  server.resource(
+    "wallet",
+    new ResourceTemplate("aura://wallets/{id}", { list: void 0 }),
+    async (uri, { id }) => {
+      const client = getClient();
+      const wallet = await client.wallets.get(String(id));
+      return {
+        contents: [
+          {
+            uri: uri.href,
+            mimeType: "application/json",
+            text: JSON.stringify(wallet, null, 2)
+          }
+        ]
+      };
+    }
+  );
+  server.resource(
+    "wallet-balance",
+    new ResourceTemplate("aura://wallets/{id}/balance", { list: void 0 }),
+    async (uri, { id }) => {
+      const client = getClient();
+      const balance = await client.wallets.getBalance(String(id));
+      return {
+        contents: [
+          {
+            uri: uri.href,
+            mimeType: "application/json",
+            text: JSON.stringify(balance, null, 2)
+          }
+        ]
+      };
+    }
+  );
+}
+var COLLECTION_LIMIT3 = 50;
+var WithdrawalIdSchema = z.string().uuid();
+function registerWithdrawalResources(server, clientFactory = getClient) {
+  server.resource("withdrawals", "aura://withdrawals", async (uri) => {
+    const page = await clientFactory().withdrawals.list({ limit: COLLECTION_LIMIT3 });
+    return {
+      contents: [
+        {
+          uri: uri.href,
+          mimeType: "application/json",
+          text: JSON.stringify(page, null, 2)
+        }
+      ]
+    };
+  });
+  server.resource(
+    "withdrawal",
+    new ResourceTemplate("aura://withdrawals/{id}", { list: void 0 }),
+    async (uri, { id }) => {
+      const parsed = WithdrawalIdSchema.safeParse(Array.isArray(id) ? id[0] : id);
+      if (!parsed.success) {
+        throw new Error(`Invalid withdrawal id in ${uri.href}: expected a UUID`);
+      }
+      const withdrawal = await clientFactory().withdrawals.get(parsed.data);
+      return {
+        contents: [
+          {
+            uri: uri.href,
+            mimeType: "application/json",
+            text: JSON.stringify(withdrawal, null, 2)
+          }
+        ]
+      };
+    }
+  );
+}
+
+// src/annotations.ts
+function readOnly(title) {
+  return { title, readOnlyHint: true };
+}
+function write(title, idempotent = false) {
+  return {
+    title,
+    readOnlyHint: false,
+    destructiveHint: false,
+    ...idempotent ? { idempotentHint: true } : {}
+  };
+}
+function destructive(title) {
+  return { title, readOnlyHint: false, destructiveHint: true };
+}
 async function withToolErrorHandling(body, successFormatter = defaultJsonFormatter) {
   try {
     const result = await body();
@@ -115,7 +300,7 @@ function defaultJsonFormatter(data) {
   return JSON.stringify(data, null, 2);
 }
 function formatError(err) {
-  if (err instanceof MissingAuraApiKeyError) {
+  if (err instanceof MissingAuraApiKeyError || err instanceof MalformedAuraApiKeyError) {
     return errorResult("CONFIG_ERROR", err.message);
   }
   if (err instanceof AuraAuthenticationError) {
@@ -203,6 +388,8 @@ function registerAgentTools(server) {
         autoApproveBelow: z.string().optional()
       }).optional()
     },
+    // Additive: provisions a new agent and its wallet. No funds move.
+    write("Create Agent"),
     async (args) => withToolErrorHandling(async () => {
       const client = getClient();
       return client.agents.create(args);
@@ -217,6 +404,7 @@ function registerAgentTools(server) {
       limit: z.number().int().min(1).max(200).optional(),
       offset: z.number().int().min(0).optional()
     },
+    readOnly("List Agents"),
     async (args) => withToolErrorHandling(async () => {
       const client = getClient();
       return client.agents.list(args);
@@ -228,6 +416,7 @@ function registerAgentTools(server) {
     {
       agentId: z.string().uuid()
     },
+    readOnly("Get Agent"),
     async ({ agentId }) => withToolErrorHandling(async () => {
       const client = getClient();
       return client.agents.get(agentId);
@@ -239,6 +428,7 @@ function registerAgentTools(server) {
     {
       agentId: z.string().uuid()
     },
+    readOnly("Get Agent Balance"),
     async ({ agentId }) => withToolErrorHandling(async () => {
       const client = getClient();
       return client.agents.getBalance(agentId);
@@ -251,6 +441,8 @@ function registerAgentTools(server) {
       agentId: z.string().uuid(),
       reason: z.string().max(500).optional().describe("Surfaced in activity event metadata for audit trail")
     },
+    // Halts an existing agent AND cascade-rejects its in-flight mandates.
+    destructive("Freeze Agent (kill switch)"),
     async (args) => withToolErrorHandling(async () => {
       const client = getClient();
       return client.agents.freeze(args);
@@ -262,6 +454,8 @@ function registerAgentTools(server) {
     {
       agentId: z.string().uuid()
     },
+    // Re-enables autonomous spending on an existing agent.
+    destructive("Unfreeze Agent (resumes autonomous spending)"),
     async (args) => withToolErrorHandling(async () => {
       const client = getClient();
       return client.agents.unfreeze(args);
@@ -278,11 +472,24 @@ function registerAgentTools(server) {
       reasoning: z.string().optional(),
       metadata: z.record(z.unknown()).optional()
     },
+    // NOT read-only despite being a dry run: when the decision requires human
+    // approval the engine persists a new mandate row. Additive, never
+    // destructive — it cannot execute the transaction it evaluates.
+    write("Evaluate Policy (dry run, may create a mandate)"),
     async (args) => withToolErrorHandling(async () => {
       const client = getClient();
       return client.agents.evaluate(args);
     })
   );
+  return [
+    "aura_create_agent",
+    "aura_list_agents",
+    "aura_get_agent",
+    "aura_get_agent_balance",
+    "aura_freeze_agent",
+    "aura_unfreeze_agent",
+    "aura_evaluate_policy"
+  ];
 }
 var ChainSchema2 = z.enum(["ARC", "ARB", "BASE", "ETH", "MATIC"]);
 var SplitInputSchema = z.object({
@@ -319,6 +526,8 @@ function registerEscrowTools(server) {
       chain: ChainSchema2.optional().describe("Target chain. Defaults to ARC"),
       splits: z.array(SplitInputSchema).min(1).describe("Payment splits. Percentages must sum to 100.")
     },
+    // Additive: creates a new escrow record. No funds move until `fund`.
+    write("Create Escrow"),
     async (args) => withToolErrorHandling(async () => {
       const client = getClient();
       return client.escrows.create(args);
@@ -330,6 +539,7 @@ function registerEscrowTools(server) {
     {
       escrowId: z.string().uuid()
     },
+    readOnly("Get Escrow"),
     async ({ escrowId }) => withToolErrorHandling(async () => {
       const client = getClient();
       return client.escrows.get(escrowId);
@@ -354,6 +564,7 @@ function registerEscrowTools(server) {
       limit: z.number().int().min(1).max(200).optional(),
       offset: z.number().int().min(0).optional()
     },
+    readOnly("List Escrows"),
     async (args) => withToolErrorHandling(async () => {
       const client = getClient();
       return client.escrows.list(args);
@@ -368,6 +579,8 @@ function registerEscrowTools(server) {
       amount: z.string().describe("USDC amount to fund (whole-number string)"),
       correlationId: z.string().optional()
     },
+    // Moves USDC out of the buyer wallet.
+    destructive("Fund Escrow (moves USDC)"),
     async (args) => withToolErrorHandling(async () => {
       const client = getClient();
       return client.escrows.fund(args);
@@ -382,6 +595,8 @@ function registerEscrowTools(server) {
       reason: z.string().optional(),
       correlationId: z.string().optional()
     },
+    // Irreversible payout to the split recipients.
+    destructive("Release Escrow (pays out USDC)"),
     async (args) => withToolErrorHandling(async () => {
       const client = getClient();
       return client.escrows.release(args);
@@ -395,6 +610,8 @@ function registerEscrowTools(server) {
       reason: z.string().min(10),
       actorId: z.string().uuid()
     },
+    // Irreversible return of funds to the buyer.
+    destructive("Refund Escrow (returns USDC to buyer)"),
     async (args) => withToolErrorHandling(async () => {
       const client = getClient();
       return client.escrows.refund(args);
@@ -414,11 +631,134 @@ function registerEscrowTools(server) {
       waitForDeploymentMs: z.number().int().min(0).optional().describe("Max ms to wait for on-chain deployment. Default 60000."),
       waitForFundingMs: z.number().int().min(0).optional().describe("Max ms to wait for funds to settle (funded/locked) before releasing. Default 60000.")
     },
+    // Composes create -> fund -> release: money moves and is paid out.
+    destructive("Receive and Split (moves and pays out USDC)"),
     async (args) => withToolErrorHandling(async () => {
       const client = getClient();
       return client.escrows.receiveAndSplit(args);
     })
   );
+  return [
+    "aura_create_escrow",
+    "aura_get_escrow",
+    "aura_list_escrows",
+    "aura_fund_escrow",
+    "aura_release_escrow",
+    "aura_refund_escrow",
+    "aura_receive_and_split"
+  ];
+}
+function validationError(error) {
+  const detail = error.issues.map((issue) => `${issue.path.join(".") || "(input)"}: ${issue.message}`).join("; ");
+  return toolError("VALIDATION_ERROR", detail);
+}
+function addCustomRangeIssues(ctx, field, selector, start, end) {
+  if (selector === "custom" && (start === void 0 || end === void 0)) {
+    ctx.addIssue({
+      code: z.ZodIssueCode.custom,
+      path: [start === void 0 ? "start" : "end"],
+      message: `start and end are both required when ${field} is 'custom'`
+    });
+  }
+  if (start !== void 0 && end !== void 0 && Date.parse(start) > Date.parse(end)) {
+    ctx.addIssue({
+      code: z.ZodIssueCode.custom,
+      path: ["end"],
+      message: "end must be at or after start"
+    });
+  }
+}
+
+// src/tools/insights.ts
+var PeriodSchema = z.enum(["today", "7d", "30d", "90d", "custom"]);
+var DateTimeSchema = z.string().datetime();
+var overviewShape = {
+  period: PeriodSchema.optional().describe(
+    "Window to report on (default 7d). 'custom' requires start and end."
+  ),
+  start: DateTimeSchema.optional().describe("ISO 8601 datetime; required when period is custom"),
+  end: DateTimeSchema.optional().describe("ISO 8601 datetime; required when period is custom")
+};
+var InsightsOverviewInput = z.object(overviewShape).superRefine(
+  (value, ctx) => addCustomRangeIssues(ctx, "period", value.period, value.start, value.end)
+);
+var auditShape = {
+  action: z.string().min(1).optional().describe("Audit action name, e.g. escrow.released"),
+  actor: z.enum(["user", "system", "api", "cron", "webhook"]).optional(),
+  resourceType: z.string().min(1).optional().describe("Resource kind, e.g. escrow"),
+  // `.min(1)`, not `.uuid()`: the route accepts any string here
+  // (`resourceId: z.string().optional()`, insights/audit/route.ts:26) and the
+  // audit log records ids from several subsystems, not all of them UUIDs.
+  resourceId: z.string().min(1).optional().describe("Id of the audited resource"),
+  range: PeriodSchema.optional().describe(
+    "Window to query (default 30d). 'custom' requires start and end."
+  ),
+  start: DateTimeSchema.optional().describe("ISO 8601 datetime; required when range is custom"),
+  end: DateTimeSchema.optional().describe("ISO 8601 datetime; required when range is custom"),
+  page: z.number().int().min(1).optional().describe("1-based page number (default 1)"),
+  limit: z.number().int().min(1).max(100).optional().describe("Page size, 1-100 (default 50)")
+};
+var InsightsAuditInput = z.object(auditShape).superRefine(
+  (value, ctx) => addCustomRangeIssues(ctx, "range", value.range, value.start, value.end)
+);
+function registerInsightsTools(server, clientFactory = getClient) {
+  server.tool(
+    "aura_insights_overview",
+    "Revenue, transaction count, active escrows and commissions for a period, each with its change against the previous period, plus sparkline and success-rate charts.",
+    overviewShape,
+    readOnly("Insights Overview"),
+    async (args) => {
+      const parsed = InsightsOverviewInput.safeParse(args);
+      if (!parsed.success) return validationError(parsed.error);
+      const { period, start, end } = parsed.data;
+      return withToolErrorHandling(
+        async () => clientFactory().insights.overview(period, start, end)
+      );
+    }
+  );
+  server.tool(
+    "aura_insights_forecast",
+    "Project a metric forward over a horizon using the requested algorithm. Requires a Growth or higher plan \u2014 lower tiers return feature_not_available.",
+    {
+      metric: z.enum([
+        "revenue",
+        "transaction_count",
+        "escrow_count",
+        "commission",
+        "avg_transaction_value"
+      ]),
+      algorithm: z.enum([
+        "linear_regression",
+        "moving_average",
+        "exponential_smoothing",
+        "arima",
+        "prophet",
+        "ensemble"
+      ]).optional(),
+      period: z.enum(["daily", "weekly", "monthly"]).optional().describe("Granularity of each projected point"),
+      horizon: z.number().int().min(1).max(365).optional().describe("Number of periods to project"),
+      // Known platform quirk: the route parses this with `z.coerce.boolean()`
+      // on a query string, where any non-empty value — including "false" —
+      // coerces to true. Passing false therefore does not currently suppress
+      // history; that is a platform-side fix, not one to paper over here.
+      includeHistory: z.boolean().optional().describe("Include the historical series alongside the projection"),
+      historyPeriods: z.number().int().min(1).max(365).optional()
+    },
+    readOnly("Insights Forecast"),
+    async (args) => withToolErrorHandling(async () => clientFactory().insights.forecast(args))
+  );
+  server.tool(
+    "aura_insights_audit",
+    "Query the account audit log by action, actor, resource and date range. Paginated, most recent first.",
+    auditShape,
+    readOnly("Insights Audit"),
+    async (args) => {
+      const parsed = InsightsAuditInput.safeParse(args);
+      if (!parsed.success) return validationError(parsed.error);
+      return withToolErrorHandling(async () => clientFactory().insights.audit(parsed.data));
+    }
+  );
+  return ["aura_insights_overview", "aura_insights_forecast", "aura_insights_audit"];
 }
 function registerMandateTools(server) {
   server.tool(
@@ -430,6 +770,7 @@ function registerMandateTools(server) {
       limit: z.number().int().min(1).max(200).optional(),
       cursor: z.string().uuid().optional().describe("Last mandate id from the previous page")
     },
+    readOnly("List Mandates (approval inbox)"),
     async (args) => withToolErrorHandling(async () => {
       const client = getClient();
       return client.mandates.list(args);
@@ -441,6 +782,7 @@ function registerMandateTools(server) {
     {
       mandateId: z.string().uuid()
     },
+    readOnly("Get Mandate"),
     async ({ mandateId }) => withToolErrorHandling(async () => {
       const client = getClient();
       return client.mandates.get(mandateId);
@@ -455,6 +797,8 @@ function registerMandateTools(server) {
       decisionSignature: z.string().min(16).describe("HMAC-SHA256 hex digest, computed by the caller"),
       decidedAt: z.string().datetime().optional().describe('ISO-8601 timestamp the signature commits to. Defaults to "now" server-side.')
     },
+    // Authorizes the agent's intended payment — the money-moving decision.
+    destructive("Approve Mandate (authorizes payment)"),
     async (args) => withToolErrorHandling(async () => {
       const client = getClient();
       return client.mandates.approve(args);
@@ -470,11 +814,31 @@ function registerMandateTools(server) {
       decidedAt: z.string().datetime().optional(),
       reason: z.string().optional().describe("Human-readable reason logged to the activity feed")
     },
+    // Terminal decision on an existing mandate — the agent cannot resume it.
+    destructive("Reject Mandate"),
     async (args) => withToolErrorHandling(async () => {
       const client = getClient();
       return client.mandates.reject(args);
     })
   );
+  return [
+    "aura_list_mandates",
+    "aura_get_mandate",
+    "aura_approve_mandate",
+    "aura_reject_mandate"
+  ];
+}
+
+// src/tools/treasury.ts
+function registerTreasuryTools(server, clientFactory = getClient) {
+  server.tool(
+    "aura_treasury_optimize",
+    "Analyze treasury balances, active escrows and pending payouts, and return an AI recommendation on how to rebalance. Read-only: it recommends, it does not move funds. Requires a Growth or higher plan \u2014 lower tiers return feature_not_available.",
+    {},
+    readOnly("Treasury Optimize"),
+    async () => withToolErrorHandling(async () => clientFactory().treasury.optimize())
+  );
+  return ["aura_treasury_optimize"];
 }
 var TestnetChainSchema = z.enum(["ARC", "ARB", "BASE"]);
 function walletCreateEnabled() {
@@ -488,6 +852,7 @@ function registerWalletTools(server) {
     {
       walletId: z.string().uuid()
     },
+    readOnly("Get Wallet Balance"),
     async ({ walletId }) => withToolErrorHandling(async () => {
       const client = getClient();
       return client.wallets.getBalance(walletId);
@@ -511,6 +876,8 @@ function registerWalletTools(server) {
         "tax"
       ]).optional().describe("Wallet owner type. Defaults to BUSINESS.")
     },
+    // Additive and create-or-get: provisions a receive address, moves no money.
+    write("Create Wallet (receive address)", true),
     async ({ entityId, chain, type }) => {
       if (!walletCreateEnabled()) {
         return toolError(
@@ -532,31 +899,239 @@ function registerWalletTools(server) {
       token: z.string().optional().describe("Token to drip. Defaults to 'USDC'."),
       chain: TestnetChainSchema.optional().describe("Override the wallet's chain.")
     },
+    // Additive: testnet-only drip that adds play funds, destroys nothing.
+    write("Request Testnet Funds"),
     async ({ walletId, token, chain }) => withToolErrorHandling(async () => {
       const client = getClient();
       return client.wallets.requestTestnetFunds(walletId, { token, chain });
     })
   );
+  return [
+    "aura_get_wallet_balance",
+    "aura_create_wallet",
+    "aura_request_testnet_funds"
+  ];
+}
+var WebhookEventTypeSchema = z.enum([
+  "*",
+  "escrow.created",
+  "escrow.funded",
+  "escrow.locked",
+  "escrow.released",
+  "escrow.refunded",
+  "escrow.disputed",
+  "transfer.completed",
+  "transfer.failed",
+  "withdrawal.created",
+  "withdrawal.processing",
+  "withdrawal.completed",
+  "withdrawal.failed",
+  "account.kyc_approved",
+  "account.kyc_rejected",
+  "account.tier_upgraded",
+  "security.api_key_created",
+  "security.api_key_revoked"
+]);
+function registerWebhookTools(server) {
+  server.tool(
+    "aura_get_webhook_config",
+    "Get the current webhook configuration for the authenticated account: delivery URL, subscribed event types, and status. The signing secret is never returned by this endpoint.",
+    {},
+    readOnly("Get Webhook Config"),
+    async () => withToolErrorHandling(async () => {
+      const client = getClient();
+      return client.webhooks.getConfig();
+    })
+  );
+  server.tool(
+    "aura_set_webhook_config",
+    "Set the webhook delivery endpoint for the account. An account has ONE configuration, so this REPLACES any existing one \u2014 events stop going to the previous URL. Must be an https:// URL you control. Returns the signing secret; store it, it is shown only on initial configuration.",
+    {
+      url: z.string().url().describe("HTTPS endpoint that will receive event POSTs"),
+      events: z.array(WebhookEventTypeSchema).min(1).optional().describe(
+        "Event types to subscribe to. Omit to subscribe to all events, or pass ['*'] explicitly."
+      ),
+      description: z.string().optional().describe("Optional human-readable label")
+    },
+    destructive("Set Webhook Config (replaces existing)"),
+    async (args) => withToolErrorHandling(async () => {
+      const client = getClient();
+      return client.webhooks.configure(args);
+    })
+  );
+  server.tool(
+    "aura_delete_webhook_config",
+    "Delete the account webhook configuration. Event delivery stops immediately and the signing secret is invalidated \u2014 reconfiguring issues a new secret.",
+    {},
+    destructive("Delete Webhook Config"),
+    async () => withToolErrorHandling(async () => {
+      const client = getClient();
+      return client.webhooks.delete();
+    })
+  );
+  return [
+    "aura_get_webhook_config",
+    "aura_set_webhook_config",
+    "aura_delete_webhook_config"
+  ];
+}
+var ChainSchema3 = z.enum(["ARC", "ETH", "BASE", "ARB", "MATIC"]);
+var AmountSchema = z.string().regex(
+  /^\d+(\.\d{1,6})?$/,
+  'Amount must be a number string with up to 6 decimal places, e.g. "100.00"'
+);
+var EvmAddressSchema = z.string().regex(
+  /^0x[a-fA-F0-9]{40}$/,
+  "Must be an EVM address: 0x followed by 40 hexadecimal characters"
+);
+var ExchangeSchema = z.enum(["binance", "coinbase", "kraken", "other"]);
+var FeeConfigSchema = z.enum(["FREE", "GAS_ONLY", "STANDARD"]);
+var StatusSchema = z.enum(["pending", "submitted", "confirmed", "failed", "cancelled"]);
+var WithdrawalIdSchema2 = z.string().uuid("Withdrawal id must be a UUID");
+var estimateShape = {
+  // `.min(1)`, not `.uuid()`: the route accepts any non-empty string here
+  // (`walletId: z.string().min(1)`, estimate/route.ts:56). Requiring a UUID
+  // would make this tool reject wallet ids the platform itself accepts.
+  walletId: z.string().min(1).describe("Source wallet id to debit"),
+  amount: AmountSchema.describe('USDC amount as a string, e.g. "100.00"'),
+  destinationType: z.enum(["exchange", "wallet"]).describe("Where the funds land. 'exchange' also requires `exchange`."),
+  destinationAddress: EvmAddressSchema.describe("Destination EVM address"),
+  chain: ChainSchema3.describe("Chain the funds are delivered on"),
+  exchange: ExchangeSchema.optional().describe(
+    "Required when destinationType is 'exchange'"
+  ),
+  sourceChain: ChainSchema3.optional().describe(
+    "Chain the funds start on. Differs from `chain` for a bridged withdrawal; defaults to ARC."
+  ),
+  feeConfig: FeeConfigSchema.optional()
+};
+var EstimateWithdrawalInput = z.object(estimateShape).superRefine((value, ctx) => {
+  if (value.destinationType === "exchange" && value.exchange === void 0) {
+    ctx.addIssue({
+      code: z.ZodIssueCode.custom,
+      path: ["exchange"],
+      message: "exchange is required when destinationType is 'exchange'"
+    });
+  }
+});
+function registerWithdrawalTools(server, clientFactory = getClient) {
+  server.tool(
+    "aura_get_withdrawal",
+    "Get a single withdrawal by id: status, amount, fees, destination, chain and transaction hash.",
+    { withdrawalId: WithdrawalIdSchema2.describe("The withdrawal id (UUID)") },
+    readOnly("Get Withdrawal"),
+    async ({ withdrawalId }) => withToolErrorHandling(async () => clientFactory().withdrawals.get(withdrawalId))
+  );
+  server.tool(
+    "aura_list_withdrawals",
+    "List withdrawals for the account, most recent first. Filter by status, chain and date range.",
+    {
+      limit: z.number().int().min(1).max(100).optional().describe("Page size, 1-100 (default 50)"),
+      offset: z.number().int().min(0).optional().describe("Rows to skip (default 0)"),
+      status: StatusSchema.optional(),
+      chain: ChainSchema3.optional(),
+      fromDate: z.string().datetime().optional().describe("ISO 8601 datetime, inclusive lower bound"),
+      toDate: z.string().datetime().optional().describe("ISO 8601 datetime, inclusive upper bound")
+    },
+    readOnly("List Withdrawals"),
+    async (args) => withToolErrorHandling(async () => clientFactory().withdrawals.list(args))
+  );
+  server.tool(
+    "aura_estimate_withdrawal",
+    "Preview the fees, net amount and confirmation time for a withdrawal WITHOUT creating it. Moves no funds. Use this before quoting a payout to a user.",
+    estimateShape,
+    readOnly("Estimate Withdrawal"),
+    async (args) => {
+      const parsed = EstimateWithdrawalInput.safeParse(args);
+      if (!parsed.success) return validationError(parsed.error);
+      return withToolErrorHandling(
+        async () => clientFactory().withdrawals.estimate(parsed.data)
+      );
+    }
+  );
+  server.tool(
+    "aura_get_withdrawal_limits",
+    "Get the account KYC-tier withdrawal limits and how much of the daily and monthly allowance is still available.",
+    {},
+    readOnly("Get Withdrawal Limits"),
+    async () => withToolErrorHandling(async () => clientFactory().withdrawals.limits())
+  );
+  server.tool(
+    "aura_validate_withdrawal_address",
+    "Check that a destination address is well-formed and usable on a chain, and preview the fee when an amount is given. Moves no funds.",
+    {
+      address: EvmAddressSchema.describe("Destination EVM address to check"),
+      chain: ChainSchema3,
+      amount: AmountSchema.optional().describe(
+        "Optional \u2014 when supplied the response includes a fee preview"
+      ),
+      feeConfig: FeeConfigSchema.optional()
+    },
+    readOnly("Validate Withdrawal Address"),
+    async (args) => withToolErrorHandling(async () => clientFactory().withdrawals.validate(args))
+  );
+  return [
+    "aura_get_withdrawal",
+    "aura_list_withdrawals",
+    "aura_estimate_withdrawal",
+    "aura_get_withdrawal_limits",
+    "aura_validate_withdrawal_address"
+  ];
 }
 
 // src/index.ts
+var SERVER_NAME = "aura-payments";
+var SERVER_VERSION = "1.2.0";
+var toolManifests = /* @__PURE__ */ new WeakMap();
+function getRegisteredToolNames(server) {
+  return toolManifests.get(server) ?? [];
+}
 function createServer(options = {}) {
   const server = new McpServer({
-    name: options.name ?? "aura-payments",
-    version: options.version ?? "1.0.1"
+    name: options.name ?? SERVER_NAME,
+    version: options.version ?? SERVER_VERSION
   });
-  registerEscrowTools(server);
-  registerAgentTools(server);
-  registerMandateTools(server);
-  registerWalletTools(server);
+  const toolNames = [
+    ...registerEscrowTools(server),
+    ...registerAgentTools(server),
+    ...registerMandateTools(server),
+    ...registerWalletTools(server),
+    ...registerWebhookTools(server),
+    ...registerWithdrawalTools(server),
+    ...registerTreasuryTools(server),
+    ...registerInsightsTools(server)
+  ];
+  toolManifests.set(server, Object.freeze(toolNames));
   registerAgentResources(server);
   registerMandateResources(server);
+  registerEscrowResources(server);
+  registerWalletResources(server);
+  registerWithdrawalResources(server);
+  registerInsightsResources(server);
   return server;
 }
 
 // src/bin.ts
+var DEFAULT_BASE_URL = "https://getaura.sh/api";
+function emitBanner(toolCount) {
+  const mode = resolveKeyMode(process.env.AURA_API_KEY);
+  const baseUrl = process.env.AURA_BASE_URL || DEFAULT_BASE_URL;
+  console.error(
+    `${SERVER_NAME} v${SERVER_VERSION} | mode=${mode} | baseUrl=${baseUrl} | tools=${toolCount}`
+  );
+  if (mode === "unconfigured") {
+    console.error(
+      `${SERVER_NAME}: AURA_API_KEY is not set \u2014 tool calls will fail until you add it to the \`env\` block of your MCP client config.`
+    );
+  } else if (mode === "invalid") {
+    console.error(
+      `${SERVER_NAME}: AURA_API_KEY is malformed \u2014 expected an sk_test_ / sk_live_ / pk_test_ / pk_live_ prefix. Tool calls will fail until it is corrected.`
+    );
+  }
+}
 async function main() {
   const server = createServer();
+  emitBanner(getRegisteredToolNames(server).length);
   const transport = new StdioServerTransport();
   await server.connect(transport);
 }