@aura-payments/mcp-server 1.0.1 → 1.1.0

package/dist/bin.js

@@ -6,13 +6,55 @@ var mcp_js = require('@modelcontextprotocol/sdk/server/mcp.js');
 var sdk = require('@aura-payments/sdk');
 var zod = require('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 sdk.AuraClient({
     apiKey,
     baseUrl: process.env.AURA_BASE_URL,
@@ -21,14 +63,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) {
@@ -67,6 +101,39 @@ 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 mcp_js.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)
+          }
+        ]
+      };
+    }
+  );
+}
 function registerMandateResources(server) {
   server.resource(
     "mandates-pending",
@@ -103,6 +170,72 @@ 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 mcp_js.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 mcp_js.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)
+          }
+        ]
+      };
+    }
+  );
+}
+
+// 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();
@@ -117,7 +250,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 sdk.AuraAuthenticationError) {
@@ -205,6 +338,8 @@ function registerAgentTools(server) {
         autoApproveBelow: zod.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);
@@ -219,6 +354,7 @@ function registerAgentTools(server) {
       limit: zod.z.number().int().min(1).max(200).optional(),
       offset: zod.z.number().int().min(0).optional()
     },
+    readOnly("List Agents"),
     async (args) => withToolErrorHandling(async () => {
       const client = getClient();
       return client.agents.list(args);
@@ -230,6 +366,7 @@ function registerAgentTools(server) {
     {
       agentId: zod.z.string().uuid()
     },
+    readOnly("Get Agent"),
     async ({ agentId }) => withToolErrorHandling(async () => {
       const client = getClient();
       return client.agents.get(agentId);
@@ -241,6 +378,7 @@ function registerAgentTools(server) {
     {
       agentId: zod.z.string().uuid()
     },
+    readOnly("Get Agent Balance"),
     async ({ agentId }) => withToolErrorHandling(async () => {
       const client = getClient();
       return client.agents.getBalance(agentId);
@@ -253,6 +391,8 @@ function registerAgentTools(server) {
       agentId: zod.z.string().uuid(),
       reason: zod.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);
@@ -264,6 +404,8 @@ function registerAgentTools(server) {
     {
       agentId: zod.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);
@@ -280,11 +422,24 @@ function registerAgentTools(server) {
       reasoning: zod.z.string().optional(),
       metadata: zod.z.record(zod.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 = zod.z.enum(["ARC", "ARB", "BASE", "ETH", "MATIC"]);
 var SplitInputSchema = zod.z.object({
@@ -321,6 +476,8 @@ function registerEscrowTools(server) {
       chain: ChainSchema2.optional().describe("Target chain. Defaults to ARC"),
       splits: zod.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);
@@ -332,6 +489,7 @@ function registerEscrowTools(server) {
     {
       escrowId: zod.z.string().uuid()
     },
+    readOnly("Get Escrow"),
     async ({ escrowId }) => withToolErrorHandling(async () => {
       const client = getClient();
       return client.escrows.get(escrowId);
@@ -356,6 +514,7 @@ function registerEscrowTools(server) {
       limit: zod.z.number().int().min(1).max(200).optional(),
       offset: zod.z.number().int().min(0).optional()
     },
+    readOnly("List Escrows"),
     async (args) => withToolErrorHandling(async () => {
       const client = getClient();
       return client.escrows.list(args);
@@ -370,6 +529,8 @@ function registerEscrowTools(server) {
       amount: zod.z.string().describe("USDC amount to fund (whole-number string)"),
       correlationId: zod.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);
@@ -384,6 +545,8 @@ function registerEscrowTools(server) {
       reason: zod.z.string().optional(),
       correlationId: zod.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);
@@ -397,6 +560,8 @@ function registerEscrowTools(server) {
       reason: zod.z.string().min(10),
       actorId: zod.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);
@@ -416,11 +581,22 @@ function registerEscrowTools(server) {
       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.")
     },
+    // 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 registerMandateTools(server) {
   server.tool(
@@ -432,6 +608,7 @@ function registerMandateTools(server) {
       limit: zod.z.number().int().min(1).max(200).optional(),
       cursor: zod.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);
@@ -443,6 +620,7 @@ function registerMandateTools(server) {
     {
       mandateId: zod.z.string().uuid()
     },
+    readOnly("Get Mandate"),
     async ({ mandateId }) => withToolErrorHandling(async () => {
       const client = getClient();
       return client.mandates.get(mandateId);
@@ -457,6 +635,8 @@ function registerMandateTools(server) {
       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.')
     },
+    // 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);
@@ -472,11 +652,19 @@ function registerMandateTools(server) {
       decidedAt: zod.z.string().datetime().optional(),
       reason: zod.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"
+  ];
 }
 var TestnetChainSchema = zod.z.enum(["ARC", "ARB", "BASE"]);
 function walletCreateEnabled() {
@@ -490,6 +678,7 @@ function registerWalletTools(server) {
     {
       walletId: zod.z.string().uuid()
     },
+    readOnly("Get Wallet Balance"),
     async ({ walletId }) => withToolErrorHandling(async () => {
       const client = getClient();
       return client.wallets.getBalance(walletId);
@@ -513,6 +702,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(
@@ -534,31 +725,131 @@ function registerWalletTools(server) {
       token: zod.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 = zod.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: zod.z.string().url().describe("HTTPS endpoint that will receive event POSTs"),
+      events: zod.z.array(WebhookEventTypeSchema).min(1).optional().describe(
+        "Event types to subscribe to. Omit to subscribe to all events, or pass ['*'] explicitly."
+      ),
+      description: zod.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"
+  ];
 }
 
 // src/index.ts
+var SERVER_NAME = "aura-payments";
+var SERVER_VERSION = "1.1.0";
+var toolManifests = /* @__PURE__ */ new WeakMap();
+function getRegisteredToolNames(server) {
+  return toolManifests.get(server) ?? [];
+}
 function createServer(options = {}) {
   const server = new mcp_js.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)
+  ];
+  toolManifests.set(server, Object.freeze(toolNames));
   registerAgentResources(server);
   registerMandateResources(server);
+  registerEscrowResources(server);
+  registerWalletResources(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 stdio_js.StdioServerTransport();
   await server.connect(transport);
 }