@aura-payments/mcp-server 1.0.0

package/README.md

@@ -0,0 +1,121 @@
+# `@aura-payments/mcp-server`
+
+Model Context Protocol server for Aura Payments. Drop it into Claude
+Desktop, Cursor, Continue, or any other MCP host and your AI agent can
+create escrows, manage agents, approve mandates, and check wallet
+balances natively, without writing HTTP boilerplate.
+
+## Install
+
+```bash
+npm install -g @aura-payments/mcp-server
+# or invoke directly via npx (no install)
+npx @aura-payments/mcp-server
+```
+
+## Configure (Claude Desktop / Cursor / any MCP client)
+
+Add this to your `mcp.json` (paths vary by host, e.g.
+`~/Library/Application Support/Claude/mcp.json` for Claude Desktop on
+macOS, `~/.cursor/mcp.json` for Cursor):
+
+```json
+{
+  "mcpServers": {
+    "aura": {
+      "command": "aura-mcp",
+      "env": {
+        "AURA_API_KEY": "pk_live_..."
+      }
+    }
+  }
+}
+```
+
+Get an API key at <https://getaura.sh>.
+
+### Optional env
+
+| 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_AUTO_IDEMPOTENCY` | `true`                        | Auto-generate idempotency keys for POST/PUT requests |
+
+## Tools
+
+| Tool                       | What it does                                                                                                            |
+| -------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
+| `aura_create_escrow`       | Create a new escrow with payment splits across vendor/platform/seller wallets                                           |
+| `aura_get_escrow`          | Get the current state of an escrow                                                                                      |
+| `aura_list_escrows`        | List escrows with state/sort/search filters                                                                             |
+| `aura_fund_escrow`         | Fund an escrow from the buyer wallet                                                                                    |
+| `aura_release_escrow`      | Release a funded escrow to recipients per the splits                                                                    |
+| `aura_refund_escrow`       | Refund a funded escrow back to the buyer                                                                                |
+| `aura_create_agent`        | Create a new AI agent with a dedicated wallet and optional initial spending policy                                      |
+| `aura_list_agents`         | List agents (filter by status/type, paginated)                                                                          |
+| `aura_get_agent`           | Get a single agent by id                                                                                                |
+| `aura_get_agent_balance`   | Get an agent's current USDC wallet balance (on-chain)                                                                   |
+| `aura_freeze_agent`        | Kill switch — pause the agent and cascade-reject every pending mandate it has in flight                                 |
+| `aura_unfreeze_agent`      | Resume a frozen agent                                                                                                   |
+| `aura_evaluate_policy`     | Run a hypothetical transaction through the policy engine without executing it                                           |
+| `aura_list_mandates`       | List operator mandates (defaults to status=pending — the inbox)                                                         |
+| `aura_get_mandate`         | Get a single mandate by id                                                                                              |
+| `aura_approve_mandate`     | Approve a pending mandate. Requires a precomputed HMAC decision signature (the LLM never sees the secret).              |
+| `aura_reject_mandate`      | Reject a pending mandate. Same signature scheme.                                                                        |
+| `aura_get_wallet_balance`  | Get any wallet's USDC balance                                                                                           |
+
+## Resources
+
+| URI                              | Returns                                                |
+| -------------------------------- | ------------------------------------------------------ |
+| `aura://agents/{id}`             | Full agent record (status, wallet, type, etc.)         |
+| `aura://agents/{id}/balance`     | Current on-chain USDC balance                          |
+| `aura://mandates/pending`        | The operator's inbox (50 most-urgent pending mandates) |
+| `aura://mandates/{id}`           | Full mandate record (intent, status, decision history) |
+
+## Try it
+
+Once configured, ask your AI agent:
+
+> "Using Aura, create a $50 USDC escrow on ARC, splitting 80% to vendor wallet
+> `<vendor-uuid>` and 20% to platform wallet `<platform-uuid>`."
+
+The agent should call `aura_create_escrow` and return the new escrow id.
+
+> "List all my pending mandates."
+
+The agent should call `aura_list_mandates` (defaults to pending) and show the
+inbox.
+
+## Approving mandates from an LLM
+
+`aura_approve_mandate` requires a precomputed HMAC-SHA256 signature over
+`${mandateId}:approve:${decidedAt}`. The LLM should NOT compute this — the
+secret stays out of model context. Instead, use the Aura CLI (`aura mandates
+approve <id>`) or the mobile app to approve, and the LLM can confirm via
+`aura_get_mandate` that the decision landed.
+
+If you want LLM-driven approval (e.g., for a fully autonomous ops agent),
+run a thin trusted shim alongside the MCP server that holds the secret and
+exposes a non-MCP signing endpoint. That's deliberately not bundled here.
+
+## Errors
+
+Every tool catches errors and returns them as structured `isError: true`
+results so the LLM can read the message. The `errorCode` line tells the LLM
+what kind of error it is:
+
+| `errorCode`         | What it means                                                          |
+| ------------------- | ---------------------------------------------------------------------- |
+| `CONFIG_ERROR`      | `AURA_API_KEY` missing or unreadable                                   |
+| `AUTH_ERROR`        | Key is invalid, revoked, or unauthorized for the requested resource    |
+| `NOT_FOUND`         | The escrow / agent / mandate doesn't exist (or isn't yours)            |
+| `VALIDATION_ERROR`  | Request body failed server-side validation                             |
+| `RATE_LIMITED`      | Too many requests. Includes `retryAfter` when available                |
+| `TIMEOUT`           | Request exceeded the SDK timeout (default 30s)                         |
+| `API_ERROR_<code>`  | Generic platform error (5xx etc.)                                      |
+
+## License
+
+MIT.

package/dist/bin.js

@@ -0,0 +1,570 @@
+#!/usr/bin/env node
+'use strict';
+
+var stdio_js = require('@modelcontextprotocol/sdk/server/stdio.js');
+var mcp_js = require('@modelcontextprotocol/sdk/server/mcp.js');
+var sdk = require('@aura-payments/sdk');
+var zod = require('zod');
+
+var cached = null;
+function getClient() {
+  if (cached) return cached;
+  const apiKey = process.env.AURA_API_KEY;
+  if (!apiKey) {
+    throw new MissingAuraApiKeyError();
+  }
+  cached = new sdk.AuraClient({
+    apiKey,
+    baseUrl: process.env.AURA_BASE_URL,
+    // Honor caller's preference; default to SDK default (auto on POST/PUT)
+    autoIdempotency: process.env.AURA_AUTO_IDEMPOTENCY !== "false"
+  });
+  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) {
+  server.resource(
+    "agent",
+    new mcp_js.ResourceTemplate("aura://agents/{id}", { list: void 0 }),
+    async (uri, { id }) => {
+      const client = getClient();
+      const agent = await client.agents.get(String(id));
+      return {
+        contents: [
+          {
+            uri: uri.href,
+            mimeType: "application/json",
+            text: JSON.stringify(agent, null, 2)
+          }
+        ]
+      };
+    }
+  );
+  server.resource(
+    "agent-balance",
+    new mcp_js.ResourceTemplate("aura://agents/{id}/balance", { list: void 0 }),
+    async (uri, { id }) => {
+      const client = getClient();
+      const balance = await client.agents.getBalance(String(id));
+      return {
+        contents: [
+          {
+            uri: uri.href,
+            mimeType: "application/json",
+            text: JSON.stringify(balance, null, 2)
+          }
+        ]
+      };
+    }
+  );
+}
+function registerMandateResources(server) {
+  server.resource(
+    "mandates-pending",
+    "aura://mandates/pending",
+    async (uri) => {
+      const client = getClient();
+      const page = await client.mandates.listPending({ limit: 50 });
+      return {
+        contents: [
+          {
+            uri: uri.href,
+            mimeType: "application/json",
+            text: JSON.stringify(page, null, 2)
+          }
+        ]
+      };
+    }
+  );
+  server.resource(
+    "mandate",
+    new mcp_js.ResourceTemplate("aura://mandates/{id}", { list: void 0 }),
+    async (uri, { id }) => {
+      const client = getClient();
+      const mandate = await client.mandates.get(String(id));
+      return {
+        contents: [
+          {
+            uri: uri.href,
+            mimeType: "application/json",
+            text: JSON.stringify(mandate, null, 2)
+          }
+        ]
+      };
+    }
+  );
+}
+async function withToolErrorHandling(body, successFormatter = defaultJsonFormatter) {
+  try {
+    const result = await body();
+    return {
+      content: [{ type: "text", text: successFormatter(result) }]
+    };
+  } catch (err) {
+    return formatError(err);
+  }
+}
+function defaultJsonFormatter(data) {
+  return JSON.stringify(data, null, 2);
+}
+function formatError(err) {
+  if (err instanceof MissingAuraApiKeyError) {
+    return errorResult("CONFIG_ERROR", err.message);
+  }
+  if (err instanceof sdk.AuraAuthenticationError) {
+    return errorResult(
+      "AUTH_ERROR",
+      `Authentication failed: ${err.message}. Check that AURA_API_KEY is correct and not revoked.`
+    );
+  }
+  if (err instanceof sdk.AuraNotFoundError) {
+    return errorResult("NOT_FOUND", err.message);
+  }
+  if (err instanceof sdk.AuraValidationError) {
+    return errorResult("VALIDATION_ERROR", err.message);
+  }
+  if (err instanceof sdk.AuraRateLimitError) {
+    return errorResult(
+      "RATE_LIMITED",
+      `Rate limited. ${err.retryAfter ? `Retry after ${err.retryAfter}s.` : "Back off and retry."}`
+    );
+  }
+  if (err instanceof sdk.AuraTimeoutError) {
+    return errorResult("TIMEOUT", err.message);
+  }
+  if (err instanceof sdk.AuraAPIError) {
+    return errorResult(`API_ERROR_${err.statusCode}`, err.message);
+  }
+  if (err instanceof sdk.AuraError) {
+    return errorResult(err.code || "AURA_ERROR", err.message);
+  }
+  if (err instanceof Error) {
+    return errorResult("UNKNOWN_ERROR", err.message);
+  }
+  return errorResult("UNKNOWN_ERROR", String(err));
+}
+function errorResult(code, message) {
+  return {
+    isError: true,
+    content: [
+      {
+        type: "text",
+        text: `errorCode: ${code}
+message: ${message}`
+      }
+    ]
+  };
+}
+function toolError(code, message) {
+  return errorResult(code, message);
+}
+
+// src/tools/agents.ts
+var ChainSchema = zod.z.enum(["ARC", "ARB", "BASE", "ETH", "MATIC"]);
+var SpendingLimitSchema = zod.z.object({
+  limitType: zod.z.enum([
+    "per_transaction",
+    "daily",
+    "weekly",
+    "monthly",
+    "lifetime"
+  ]),
+  maxAmount: zod.z.string().describe("Whole-number USDC amount as a string"),
+  currency: zod.z.string().optional().default("USDC")
+});
+var MerchantRuleSchema = zod.z.object({
+  ruleType: zod.z.enum(["allowlist", "blocklist"]),
+  destinationType: zod.z.enum(["address", "domain", "category", "entity_id"]),
+  destinationValue: zod.z.string().min(1)
+});
+function registerAgentTools(server) {
+  server.tool(
+    "aura_create_agent",
+    "Create a new AI agent with a dedicated wallet and optional initial spending policy. The wallet is provisioned on-chain during this call (a few seconds latency).",
+    {
+      name: zod.z.string().min(1).max(100),
+      description: zod.z.string().max(500).optional(),
+      type: zod.z.enum(["treasury", "payment", "trading", "custom"]),
+      chain: ChainSchema.optional().default("ARC"),
+      metadata: zod.z.record(zod.z.unknown()).optional(),
+      initialPolicy: zod.z.object({
+        name: zod.z.string().optional(),
+        description: zod.z.string().optional(),
+        spendingLimits: zod.z.array(SpendingLimitSchema).optional(),
+        merchantRules: zod.z.array(MerchantRuleSchema).optional(),
+        requiresApprovalAbove: zod.z.string().optional(),
+        autoApproveBelow: zod.z.string().optional()
+      }).optional()
+    },
+    async (args) => withToolErrorHandling(async () => {
+      const client = getClient();
+      return client.agents.create(args);
+    })
+  );
+  server.tool(
+    "aura_list_agents",
+    "List agents for the authenticated account, paginated. Filter by status or type.",
+    {
+      status: zod.z.enum(["active", "paused", "archived"]).optional(),
+      type: zod.z.enum(["treasury", "payment", "trading", "custom"]).optional(),
+      limit: zod.z.number().int().min(1).max(200).optional(),
+      offset: zod.z.number().int().min(0).optional()
+    },
+    async (args) => withToolErrorHandling(async () => {
+      const client = getClient();
+      return client.agents.list(args);
+    })
+  );
+  server.tool(
+    "aura_get_agent",
+    "Get a single agent by id with its current status, wallet, and recent activity.",
+    {
+      agentId: zod.z.string().uuid()
+    },
+    async ({ agentId }) => withToolErrorHandling(async () => {
+      const client = getClient();
+      return client.agents.get(agentId);
+    })
+  );
+  server.tool(
+    "aura_get_agent_balance",
+    "Get the current USDC balance of an agent's wallet (on-chain at request time).",
+    {
+      agentId: zod.z.string().uuid()
+    },
+    async ({ agentId }) => withToolErrorHandling(async () => {
+      const client = getClient();
+      return client.agents.getBalance(agentId);
+    })
+  );
+  server.tool(
+    "aura_freeze_agent",
+    "Kill switch \u2014 halt all autonomous activity for an agent. Sets status=paused AND auto-rejects every pending mandate the agent has in flight. Idempotent.",
+    {
+      agentId: zod.z.string().uuid(),
+      reason: zod.z.string().max(500).optional().describe("Surfaced in activity event metadata for audit trail")
+    },
+    async (args) => withToolErrorHandling(async () => {
+      const client = getClient();
+      return client.agents.freeze(args);
+    })
+  );
+  server.tool(
+    "aura_unfreeze_agent",
+    "Resume autonomous activity for a frozen agent (status -> active). Previously cascade-rejected mandates are NOT restored \u2014 the agent re-creates them on its next loop.",
+    {
+      agentId: zod.z.string().uuid()
+    },
+    async (args) => withToolErrorHandling(async () => {
+      const client = getClient();
+      return client.agents.unfreeze(args);
+    })
+  );
+  server.tool(
+    "aura_evaluate_policy",
+    "Run a hypothetical transaction through the policy engine WITHOUT executing it. Returns the decision (auto_approve / auto_deny / requires_human_approval) and which rules matched. When the decision requires human approval, a mandate row is created and its id is returned.",
+    {
+      agentId: zod.z.string().uuid(),
+      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(),
+      metadata: zod.z.record(zod.z.unknown()).optional()
+    },
+    async (args) => withToolErrorHandling(async () => {
+      const client = getClient();
+      return client.agents.evaluate(args);
+    })
+  );
+}
+var ChainSchema2 = zod.z.enum(["ARC", "ARB", "BASE", "ETH", "MATIC"]);
+var SplitInputSchema = zod.z.object({
+  ownerType: zod.z.enum([
+    "buyer",
+    "seller",
+    "platform",
+    "vendor",
+    "creator",
+    "affiliate",
+    "logistics",
+    "tax"
+  ]),
+  ownerId: zod.z.string().uuid(),
+  role: zod.z.enum([
+    "seller",
+    "platform",
+    "vendor",
+    "creator",
+    "affiliate",
+    "logistics",
+    "tax"
+  ]),
+  percentage: zod.z.number().min(0).max(100)
+});
+function registerEscrowTools(server) {
+  server.tool(
+    "aura_create_escrow",
+    "Create a new escrow with payment splits across vendor/platform/seller wallets. Default chain is ARC. Async by default \u2014 returns an escrowId immediately while contract deployment continues in background.",
+    {
+      orderId: zod.z.string().describe("Caller-provided order id, unique per account"),
+      buyerOwnerId: zod.z.string().uuid().describe("UUID of the buyer in the platform"),
+      amount: zod.z.string().describe('Whole-number USDC amount as a string (e.g. "100" for $100)'),
+      chain: ChainSchema2.optional().describe("Target chain. Defaults to ARC"),
+      splits: zod.z.array(SplitInputSchema).min(1).describe("Payment splits. Percentages must sum to 100.")
+    },
+    async (args) => withToolErrorHandling(async () => {
+      const client = getClient();
+      return client.escrows.create(args);
+    })
+  );
+  server.tool(
+    "aura_get_escrow",
+    "Get the current state of an escrow by id, including splits and on-chain deployment status.",
+    {
+      escrowId: zod.z.string().uuid()
+    },
+    async ({ escrowId }) => withToolErrorHandling(async () => {
+      const client = getClient();
+      return client.escrows.get(escrowId);
+    })
+  );
+  server.tool(
+    "aura_list_escrows",
+    "List escrows for the authenticated account, optionally filtered by state. Returns paginated results.",
+    {
+      state: zod.z.enum([
+        "initiated",
+        "deployed",
+        "funded",
+        "locked",
+        "released",
+        "refunded",
+        "disputed",
+        "all"
+      ]).optional(),
+      sortBy: zod.z.enum(["created_desc", "created_asc", "amount_desc", "amount_asc"]).optional(),
+      search: zod.z.string().optional(),
+      limit: zod.z.number().int().min(1).max(200).optional(),
+      offset: zod.z.number().int().min(0).optional()
+    },
+    async (args) => withToolErrorHandling(async () => {
+      const client = getClient();
+      return client.escrows.list(args);
+    })
+  );
+  server.tool(
+    "aura_fund_escrow",
+    "Fund an existing escrow from the buyer wallet. Once funded, the escrow can be released (after unlock conditions) or refunded.",
+    {
+      escrowId: zod.z.string().uuid(),
+      buyerWalletId: zod.z.string().uuid(),
+      amount: zod.z.string().describe("USDC amount to fund (whole-number string)"),
+      correlationId: zod.z.string().optional()
+    },
+    async (args) => withToolErrorHandling(async () => {
+      const client = getClient();
+      return client.escrows.fund(args);
+    })
+  );
+  server.tool(
+    "aura_release_escrow",
+    "Release a funded escrow to the recipients per the original splits. Requires the unlock conditions to be met (or manual override with actorId).",
+    {
+      escrowId: zod.z.string().uuid(),
+      actorId: zod.z.string().uuid().describe("UUID of the user/agent performing the release"),
+      reason: zod.z.string().optional(),
+      correlationId: zod.z.string().optional()
+    },
+    async (args) => withToolErrorHandling(async () => {
+      const client = getClient();
+      return client.escrows.release(args);
+    })
+  );
+  server.tool(
+    "aura_refund_escrow",
+    "Refund a funded escrow back to the buyer. Requires a reason (audit trail).",
+    {
+      escrowId: zod.z.string().uuid(),
+      reason: zod.z.string().min(10),
+      actorId: zod.z.string().uuid()
+    },
+    async (args) => withToolErrorHandling(async () => {
+      const client = getClient();
+      return client.escrows.refund(args);
+    })
+  );
+  server.tool(
+    "aura_receive_and_split",
+    'Receive USDC and split it to recipients in ONE call \u2014 composes escrow create\u2192fund\u2192release. The payer (payerOwnerId) may be the agent itself (splitting funds it holds) or a counterparty; funds move from that party\'s Aura wallet. Returns a `stage` (created|deployed|funded|released): if it stops at "deployed" with `fundingRequired`, fund that wallet (e.g. aura_request_testnet_funds) and retry. Testnet only.',
+    {
+      orderId: zod.z.string().describe("Caller-provided order id, unique per account"),
+      payerOwnerId: zod.z.string().describe("Entity that funds the escrow (the agent itself or a counterparty)"),
+      amount: zod.z.string().describe('Whole-number USDC amount as a string (e.g. "50"). Each split must net \u2265 $1 after fees.'),
+      splits: zod.z.array(SplitInputSchema).min(1).describe("Payment splits. Percentages must sum to 100."),
+      chain: zod.z.enum(["ARC", "ARB", "BASE"]).optional().describe("Testnet chain. Defaults to ARC."),
+      actorId: zod.z.string().optional().describe("Actor recorded on release. Defaults to payerOwnerId."),
+      autoRelease: zod.z.boolean().optional().describe("Release immediately after funding. Default true."),
+      waitForDeploymentMs: zod.z.number().int().min(0).optional().describe("Max ms to wait for on-chain deployment. Default 60000."),
+      waitForFundingMs: zod.z.number().int().min(0).optional().describe("Max ms to wait for funds to settle (funded/locked) before releasing. Default 60000.")
+    },
+    async (args) => withToolErrorHandling(async () => {
+      const client = getClient();
+      return client.escrows.receiveAndSplit(args);
+    })
+  );
+}
+function registerMandateTools(server) {
+  server.tool(
+    "aura_list_mandates",
+    "List mandates for the authenticated account. Defaults to status=pending so it acts as the operator's inbox by default. Most-urgent (soonest-expiring) first.",
+    {
+      status: zod.z.enum(["pending", "approved", "rejected", "cancelled"]).optional().default("pending"),
+      agentId: zod.z.string().uuid().optional(),
+      limit: zod.z.number().int().min(1).max(200).optional(),
+      cursor: zod.z.string().uuid().optional().describe("Last mandate id from the previous page")
+    },
+    async (args) => withToolErrorHandling(async () => {
+      const client = getClient();
+      return client.mandates.list(args);
+    })
+  );
+  server.tool(
+    "aura_get_mandate",
+    "Get a single mandate by id, including its full intent payload (the action the agent wants to take), expiry, and decision history.",
+    {
+      mandateId: zod.z.string().uuid()
+    },
+    async ({ mandateId }) => withToolErrorHandling(async () => {
+      const client = getClient();
+      return client.mandates.get(mandateId);
+    })
+  );
+  server.tool(
+    "aura_approve_mandate",
+    "Approve a pending mandate. The decisionSignature MUST be precomputed by the caller (HMAC-SHA256 over `${mandateId}:approve:${decidedAt}`) \u2014 the LLM should never see the HMAC secret. Use the CLI or mobile app to compute it. Idempotent: re-approving an already-approved mandate returns the existing decision.",
+    {
+      mandateId: zod.z.string().uuid(),
+      decisionMethod: zod.z.enum(["biometric", "passcode", "manual"]),
+      decisionSignature: zod.z.string().min(16).describe("HMAC-SHA256 hex digest, computed by the caller"),
+      decidedAt: zod.z.string().datetime().optional().describe('ISO-8601 timestamp the signature commits to. Defaults to "now" server-side.')
+    },
+    async (args) => withToolErrorHandling(async () => {
+      const client = getClient();
+      return client.mandates.approve(args);
+    })
+  );
+  server.tool(
+    "aura_reject_mandate",
+    "Reject a pending mandate. Same signature scheme as approve \u2014 caller computes it, LLM forwards.",
+    {
+      mandateId: zod.z.string().uuid(),
+      decisionMethod: zod.z.enum(["biometric", "passcode", "manual"]),
+      decisionSignature: zod.z.string().min(16),
+      decidedAt: zod.z.string().datetime().optional(),
+      reason: zod.z.string().optional().describe("Human-readable reason logged to the activity feed")
+    },
+    async (args) => withToolErrorHandling(async () => {
+      const client = getClient();
+      return client.mandates.reject(args);
+    })
+  );
+}
+var TestnetChainSchema = zod.z.enum(["ARC", "ARB", "BASE"]);
+function walletCreateEnabled() {
+  const v = (process.env.AURA_MCP_ALLOW_WALLET_CREATE ?? "").trim().toLowerCase();
+  return v === "1" || v === "true" || v === "yes";
+}
+function registerWalletTools(server) {
+  server.tool(
+    "aura_get_wallet_balance",
+    "Get a wallet's current USDC balance (on-chain at request time).",
+    {
+      walletId: zod.z.string().uuid()
+    },
+    async ({ walletId }) => withToolErrorHandling(async () => {
+      const client = getClient();
+      return client.wallets.getBalance(walletId);
+    })
+  );
+  server.tool(
+    "aura_create_wallet",
+    "Provision (create-or-get) a wallet to RECEIVE USDC into. Idempotent and moves no money. Testnet only. Disabled unless the host sets AURA_MCP_ALLOW_WALLET_CREATE=1.",
+    {
+      entityId: zod.z.string().min(1).describe("Your unique identifier for the wallet owner (e.g. the agent id)"),
+      chain: TestnetChainSchema.optional().describe("Testnet chain. Defaults to ARC."),
+      type: zod.z.enum([
+        "BUSINESS",
+        "buyer",
+        "seller",
+        "platform",
+        "vendor",
+        "creator",
+        "affiliate",
+        "logistics",
+        "tax"
+      ]).optional().describe("Wallet owner type. Defaults to BUSINESS.")
+    },
+    async ({ entityId, chain, type }) => {
+      if (!walletCreateEnabled()) {
+        return toolError(
+          "WALLET_CREATE_DISABLED",
+          "Wallet creation is disabled on this MCP host. Set AURA_MCP_ALLOW_WALLET_CREATE=1 in the server env to enable it, or create the wallet via the Aura CLI (`aura wallet create`) or SDK."
+        );
+      }
+      return withToolErrorHandling(async () => {
+        const client = getClient();
+        return client.wallets.create({ entityId, chain, type });
+      });
+    }
+  );
+  server.tool(
+    "aura_request_testnet_funds",
+    "Request testnet USDC for a wallet from the platform faucet (testnet only). Drips are async \u2014 balance reflects after a few seconds. Returns FAUCET_UNAVAILABLE if the deployment has no faucet enabled.",
+    {
+      walletId: zod.z.string().uuid(),
+      token: zod.z.string().optional().describe("Token to drip. Defaults to 'USDC'."),
+      chain: TestnetChainSchema.optional().describe("Override the wallet's chain.")
+    },
+    async ({ walletId, token, chain }) => withToolErrorHandling(async () => {
+      const client = getClient();
+      return client.wallets.requestTestnetFunds(walletId, { token, chain });
+    })
+  );
+}
+
+// src/index.ts
+function createServer(options = {}) {
+  const server = new mcp_js.McpServer({
+    name: options.name ?? "aura-payments",
+    version: options.version ?? "1.0.0"
+  });
+  registerEscrowTools(server);
+  registerAgentTools(server);
+  registerMandateTools(server);
+  registerWalletTools(server);
+  registerAgentResources(server);
+  registerMandateResources(server);
+  return server;
+}
+
+// src/bin.ts
+async function main() {
+  const server = createServer();
+  const transport = new stdio_js.StdioServerTransport();
+  await server.connect(transport);
+}
+main().catch((err) => {
+  console.error("aura-mcp: fatal error:", err);
+  process.exit(1);
+});
+//# sourceMappingURL=bin.js.map
+//# sourceMappingURL=bin.js.map