@aura-payments/mcp-server 1.1.0 → 1.2.1

package/README.md

@@ -25,7 +25,7 @@ macOS, `~/.cursor/mcp.json` for Cursor):
     "aura": {
       "command": "aura-mcp",
       "env": {
-        "AURA_API_KEY": "pk_live_..."
+        "AURA_API_KEY": "sk_test_..."
       }
     }
   }
@@ -39,7 +39,7 @@ Get an API key at <https://getaura.sh>.
 | Variable                | Default                       | Purpose                                              |
 | ----------------------- | ----------------------------- | ---------------------------------------------------- |
 | `AURA_API_KEY`          | (required)                    | Your platform API key (`pk_live_*` or `pk_test_*`)   |
-| `AURA_BASE_URL`         | `https://tryaura.xyz/api`     | Override for self-hosted or staging deployments      |
+| `AURA_BASE_URL`         | `https://getaura.sh/api`      | Override for self-hosted or staging deployments      |
 | `AURA_AUTO_IDEMPOTENCY` | `true`                        | Auto-generate idempotency keys for POST/PUT requests |
 
 ## Tools

package/dist/bin.js

@@ -37,7 +37,7 @@ function resolveKeyMode(apiKey) {
 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.'
+      '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": "sk_test_..." } } } }. Get a key at https://getaura.sh.'
     );
     this.name = "MissingAuraApiKeyError";
   }
@@ -134,6 +134,22 @@ function registerEscrowResources(server) {
     }
   );
 }
+
+// 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",
@@ -220,6 +236,42 @@ function registerWalletResources(server) {
     }
   );
 }
+var COLLECTION_LIMIT3 = 50;
+var WithdrawalIdSchema = zod.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 mcp_js.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) {
@@ -419,7 +471,7 @@ function registerAgentTools(server) {
       amount: zod.z.string().describe("USDC amount as decimal string"),
       destination: zod.z.string().describe("Counterparty wallet (0x...) or merchant identifier"),
       destinationType: zod.z.enum(["address", "domain", "category", "entity_id"]).optional(),
-      reasoning: zod.z.string().optional(),
+      reasoning: zod.z.string().optional().describe("Why the agent wants this; shown to the operator. Required for a mandate to be created when approval is needed."),
       metadata: zod.z.record(zod.z.unknown()).optional()
     },
     // NOT read-only despite being a dry run: when the decision requires human
@@ -598,6 +650,118 @@ function registerEscrowTools(server) {
     "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: zod.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: zod.z.ZodIssueCode.custom,
+      path: ["end"],
+      message: "end must be at or after start"
+    });
+  }
+}
+
+// src/tools/insights.ts
+var PeriodSchema = zod.z.enum(["today", "7d", "30d", "90d", "custom"]);
+var DateTimeSchema = zod.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 = zod.z.object(overviewShape).superRefine(
+  (value, ctx) => addCustomRangeIssues(ctx, "period", value.period, value.start, value.end)
+);
+var auditShape = {
+  action: zod.z.string().min(1).optional().describe("Audit action name, e.g. escrow.released"),
+  actor: zod.z.enum(["user", "system", "api", "cron", "webhook"]).optional(),
+  resourceType: zod.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: zod.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: zod.z.number().int().min(1).optional().describe("1-based page number (default 1)"),
+  limit: zod.z.number().int().min(1).max(100).optional().describe("Page size, 1-100 (default 50)")
+};
+var InsightsAuditInput = zod.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: zod.z.enum([
+        "revenue",
+        "transaction_count",
+        "escrow_count",
+        "commission",
+        "avg_transaction_value"
+      ]),
+      algorithm: zod.z.enum([
+        "linear_regression",
+        "moving_average",
+        "exponential_smoothing",
+        "arima",
+        "prophet",
+        "ensemble"
+      ]).optional(),
+      period: zod.z.enum(["daily", "weekly", "monthly"]).optional().describe("Granularity of each projected point"),
+      horizon: zod.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: zod.z.boolean().optional().describe("Include the historical series alongside the projection"),
+      historyPeriods: zod.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(
     "aura_list_mandates",
@@ -666,6 +830,18 @@ function registerMandateTools(server) {
     "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 = zod.z.enum(["ARC", "ARB", "BASE"]);
 function walletCreateEnabled() {
   const v = (process.env.AURA_MCP_ALLOW_WALLET_CREATE ?? "").trim().toLowerCase();
@@ -801,10 +977,113 @@ function registerWebhookTools(server) {
     "aura_delete_webhook_config"
   ];
 }
+var ChainSchema3 = zod.z.enum(["ARC", "ETH", "BASE", "ARB", "MATIC"]);
+var AmountSchema = zod.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 = zod.z.string().regex(
+  /^0x[a-fA-F0-9]{40}$/,
+  "Must be an EVM address: 0x followed by 40 hexadecimal characters"
+);
+var ExchangeSchema = zod.z.enum(["binance", "coinbase", "kraken", "other"]);
+var FeeConfigSchema = zod.z.enum(["FREE", "GAS_ONLY", "STANDARD"]);
+var StatusSchema = zod.z.enum(["pending", "submitted", "confirmed", "failed", "cancelled"]);
+var WithdrawalIdSchema2 = zod.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: zod.z.string().min(1).describe("Source wallet id to debit"),
+  amount: AmountSchema.describe('USDC amount as a string, e.g. "100.00"'),
+  destinationType: zod.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 = zod.z.object(estimateShape).superRefine((value, ctx) => {
+  if (value.destinationType === "exchange" && value.exchange === void 0) {
+    ctx.addIssue({
+      code: zod.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: zod.z.number().int().min(1).max(100).optional().describe("Page size, 1-100 (default 50)"),
+      offset: zod.z.number().int().min(0).optional().describe("Rows to skip (default 0)"),
+      status: StatusSchema.optional(),
+      chain: ChainSchema3.optional(),
+      fromDate: zod.z.string().datetime().optional().describe("ISO 8601 datetime, inclusive lower bound"),
+      toDate: zod.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.1.0";
+var SERVER_VERSION = "1.2.1";
 var toolManifests = /* @__PURE__ */ new WeakMap();
 function getRegisteredToolNames(server) {
   return toolManifests.get(server) ?? [];
@@ -819,13 +1098,18 @@ function createServer(options = {}) {
     ...registerAgentTools(server),
     ...registerMandateTools(server),
     ...registerWalletTools(server),
-    ...registerWebhookTools(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;
 }