@aura-payments/mcp-server 1.0.0

package/dist/bin.mjs

@@ -0,0 +1,568 @@
+#!/usr/bin/env node
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { McpServer, ResourceTemplate } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { AuraClient, AuraAuthenticationError, AuraNotFoundError, AuraValidationError, AuraRateLimitError, AuraTimeoutError, AuraAPIError, AuraError } from '@aura-payments/sdk';
+import { z } from 'zod';
+
+var cached = null;
+function getClient() {
+  if (cached) return cached;
+  const apiKey = process.env.AURA_API_KEY;
+  if (!apiKey) {
+    throw new MissingAuraApiKeyError();
+  }
+  cached = new 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 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 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 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 AuraAuthenticationError) {
+    return errorResult(
+      "AUTH_ERROR",
+      `Authentication failed: ${err.message}. Check that AURA_API_KEY is correct and not revoked.`
+    );
+  }
+  if (err instanceof AuraNotFoundError) {
+    return errorResult("NOT_FOUND", err.message);
+  }
+  if (err instanceof AuraValidationError) {
+    return errorResult("VALIDATION_ERROR", err.message);
+  }
+  if (err instanceof AuraRateLimitError) {
+    return errorResult(
+      "RATE_LIMITED",
+      `Rate limited. ${err.retryAfter ? `Retry after ${err.retryAfter}s.` : "Back off and retry."}`
+    );
+  }
+  if (err instanceof AuraTimeoutError) {
+    return errorResult("TIMEOUT", err.message);
+  }
+  if (err instanceof AuraAPIError) {
+    return errorResult(`API_ERROR_${err.statusCode}`, err.message);
+  }
+  if (err instanceof 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 = z.enum(["ARC", "ARB", "BASE", "ETH", "MATIC"]);
+var SpendingLimitSchema = z.object({
+  limitType: z.enum([
+    "per_transaction",
+    "daily",
+    "weekly",
+    "monthly",
+    "lifetime"
+  ]),
+  maxAmount: z.string().describe("Whole-number USDC amount as a string"),
+  currency: z.string().optional().default("USDC")
+});
+var MerchantRuleSchema = z.object({
+  ruleType: z.enum(["allowlist", "blocklist"]),
+  destinationType: z.enum(["address", "domain", "category", "entity_id"]),
+  destinationValue: 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: z.string().min(1).max(100),
+      description: z.string().max(500).optional(),
+      type: z.enum(["treasury", "payment", "trading", "custom"]),
+      chain: ChainSchema.optional().default("ARC"),
+      metadata: z.record(z.unknown()).optional(),
+      initialPolicy: z.object({
+        name: z.string().optional(),
+        description: z.string().optional(),
+        spendingLimits: z.array(SpendingLimitSchema).optional(),
+        merchantRules: z.array(MerchantRuleSchema).optional(),
+        requiresApprovalAbove: z.string().optional(),
+        autoApproveBelow: 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: z.enum(["active", "paused", "archived"]).optional(),
+      type: z.enum(["treasury", "payment", "trading", "custom"]).optional(),
+      limit: z.number().int().min(1).max(200).optional(),
+      offset: 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: 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: 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: z.string().uuid(),
+      reason: 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: 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: z.string().uuid(),
+      amount: z.string().describe("USDC amount as decimal string"),
+      destination: z.string().describe("Counterparty wallet (0x...) or merchant identifier"),
+      destinationType: z.enum(["address", "domain", "category", "entity_id"]).optional(),
+      reasoning: z.string().optional(),
+      metadata: z.record(z.unknown()).optional()
+    },
+    async (args) => withToolErrorHandling(async () => {
+      const client = getClient();
+      return client.agents.evaluate(args);
+    })
+  );
+}
+var ChainSchema2 = z.enum(["ARC", "ARB", "BASE", "ETH", "MATIC"]);
+var SplitInputSchema = z.object({
+  ownerType: z.enum([
+    "buyer",
+    "seller",
+    "platform",
+    "vendor",
+    "creator",
+    "affiliate",
+    "logistics",
+    "tax"
+  ]),
+  ownerId: z.string().uuid(),
+  role: z.enum([
+    "seller",
+    "platform",
+    "vendor",
+    "creator",
+    "affiliate",
+    "logistics",
+    "tax"
+  ]),
+  percentage: 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: z.string().describe("Caller-provided order id, unique per account"),
+      buyerOwnerId: z.string().uuid().describe("UUID of the buyer in the platform"),
+      amount: 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: 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: 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: z.enum([
+        "initiated",
+        "deployed",
+        "funded",
+        "locked",
+        "released",
+        "refunded",
+        "disputed",
+        "all"
+      ]).optional(),
+      sortBy: z.enum(["created_desc", "created_asc", "amount_desc", "amount_asc"]).optional(),
+      search: z.string().optional(),
+      limit: z.number().int().min(1).max(200).optional(),
+      offset: 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: z.string().uuid(),
+      buyerWalletId: z.string().uuid(),
+      amount: z.string().describe("USDC amount to fund (whole-number string)"),
+      correlationId: 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: z.string().uuid(),
+      actorId: z.string().uuid().describe("UUID of the user/agent performing the release"),
+      reason: z.string().optional(),
+      correlationId: 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: z.string().uuid(),
+      reason: z.string().min(10),
+      actorId: 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: z.string().describe("Caller-provided order id, unique per account"),
+      payerOwnerId: z.string().describe("Entity that funds the escrow (the agent itself or a counterparty)"),
+      amount: z.string().describe('Whole-number USDC amount as a string (e.g. "50"). Each split must net \u2265 $1 after fees.'),
+      splits: z.array(SplitInputSchema).min(1).describe("Payment splits. Percentages must sum to 100."),
+      chain: z.enum(["ARC", "ARB", "BASE"]).optional().describe("Testnet chain. Defaults to ARC."),
+      actorId: z.string().optional().describe("Actor recorded on release. Defaults to payerOwnerId."),
+      autoRelease: z.boolean().optional().describe("Release immediately after funding. Default true."),
+      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.")
+    },
+    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: z.enum(["pending", "approved", "rejected", "cancelled"]).optional().default("pending"),
+      agentId: z.string().uuid().optional(),
+      limit: z.number().int().min(1).max(200).optional(),
+      cursor: 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: 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: z.string().uuid(),
+      decisionMethod: z.enum(["biometric", "passcode", "manual"]),
+      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.')
+    },
+    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: z.string().uuid(),
+      decisionMethod: z.enum(["biometric", "passcode", "manual"]),
+      decisionSignature: z.string().min(16),
+      decidedAt: z.string().datetime().optional(),
+      reason: 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 = 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: 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: 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: 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: z.string().uuid(),
+      token: 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 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 StdioServerTransport();
+  await server.connect(transport);
+}
+main().catch((err) => {
+  console.error("aura-mcp: fatal error:", err);
+  process.exit(1);
+});
+//# sourceMappingURL=bin.mjs.map
+//# sourceMappingURL=bin.mjs.map